llmfit 运行时 Provider 集成详解：Ollama、llama.cpp、MLX、Docker Model Runner 与 LM Studio 的检测与下载机制

本篇指南基于 docs/providers.md 与核心实现 llmfit-core/src/providers.rs，系统讲解 llmfit 如何自动探测本机已安装的推理运行时、识别每个 provider 中已装的模型，并在 TUI 中一键拉取新模型；读完后你可以掌握全部 provider 的接入前提、远程实例配置（环境变量）、模型名映射规则，以及源码层面的探测与下载实现细节。

统一抽象：ModelProvider 特性

llmfit 支持多个本地运行时 provider：

• Ollama（基于守护进程/API 的拉取）
• llama.cpp（从 Hugging Face 直接下载 GGUF + 本地缓存检测）
• MLX（Apple Silicon / mlx-community 模型缓存 + 可选 server）——MLX 下载对应 HuggingFace 上的 mlx-community/* 仓库，而非原始模型发布方
• Docker Model Runner（Docker Desktop 内置的模型服务功能）
• LM Studio（带 REST API 的本地模型服务器，支持模型管理与下载）

这些 provider 在源码中共享同一个最小接口——ModelProvider 特性（providers.rs#L15-L29）：

pub trait ModelProvider {
    fn name(&self) -> &str;              // UI 中显示的名字
    fn is_available(&self) -> bool;      // 服务当前是否可达
    fn installed_models(&self) -> HashSet<String>; // 已安装模型名集合（小写归一化）
    fn start_pull(&self, model_tag: &str) -> Result<PullHandle, String>;
}

start_pull 立即返回一个 PullHandle（内部是一个 mpsc::Receiver<PullEvent>），TUI 在后台线程轮询它，接收 Progress { status, percent } / Done / Error 事件（providers.rs#L31-L46）。这正是 TUI 中“按下 d 后该行高亮并显示动画进度条”的底层机制。

TUI 启动时会为每个网络型 provider 各起一个后台探测线程，通过 mpsc 通道把检测结果送回复主界面（见 tui_app.rs 中的 provider_detection_rx 初始化）。当某个模型有多个兼容 provider 可用时，在 TUI 中按 d 会弹出 provider 选择器（DownloadProvider 枚举与 download_provider_options，见 tui_app.rs#L764 和 tui_app.rs#L927-L929），让你选择用哪个运行时下载。

Ollama 集成

llmfit 与 Ollama 集成，用于检测你已经安装了哪些模型，并直接从 TUI 下载新模型。

前提条件

• Ollama 必须已安装并运行（ollama serve 或 Ollama 桌面应用）
• llmfit 连接 http://localhost:11434（Ollama 默认 API 端口）
• 无需任何配置——只要 Ollama 在运行，llmfit 会自动探测到它

远程 Ollama 实例

要连接运行在其他机器或端口上的 Ollama，设置 OLLAMA_HOST 环境变量：

# 连接到指定 IP 和端口的 Ollama
OLLAMA_HOST="http://192.168.1.100:11434" llmfit

# 通过主机名连接
OLLAMA_HOST="http://ollama-server:666" llmfit

# 对所有 TUI 和 CLI 命令均有效
OLLAMA_HOST="http://192.168.1.100:11434" llmfit --cli
OLLAMA_HOST="http://192.168.1.100:11434" llmfit fit --perfect -n 5

适用场景：

• 在一台机器上运行 llmfit，Ollama 在另一台机器上服务（例如 GPU 服务器 + 笔记本客户端）
• 连接运行在自定义端口 Docker 容器中的 Ollama
• Ollama 位于反向代理或负载均衡器之后

工作原理

启动时，llmfit 查询 GET /api/tags 列出已安装的 Ollama 模型。每个已安装模型在 TUI 的 Inst 列显示绿色 ✓，系统栏显示 Ollama: ✓ (N installed)。对某模型按 d 时，llmfit 向 Ollama 发送 POST /api/pull 下载它，该行会高亮并实时显示下载进度；完成后模型立即可用于 Ollama。若 Ollama 未运行，Ollama 相关操作会被跳过；TUI 仍可继续使用 llama.cpp 等其他可用 provider。

源码级细节

OllamaProvider 的构造逻辑（providers.rs#L105-L141）有几个值得注意的健壮性设计：

1. 地址归一化：normalize_ollama_host 接受 host:port（自动补 http://）或完整 URL；无法解析（如 ftp://）时打印警告并回退到默认值。
2. 通配绑定地址防护：如果你以 OLLAMA_HOST=0.0.0.0 启动 Ollama，该值会泄漏进客户端环境，而 0.0.0.0 / [::] 是监听地址、不能作为连接目标。is_wildcard_bind_address（providers.rs#L83-L103）会识别这种情况并回退到 localhost。
3. IPv4/IPv6 回退：默认先尝试 http://localhost:11434；如果 localhost 在你的系统上解析为 IPv6 回环 ::1 而 Ollama 只监听 IPv4，探测失败后自动改用 http://127.0.0.1:11434，并把成功的那个地址采纳为后续所有请求（pull、show 等）的 base URL。整个流程在 detect_with_installed 中一次完成（providers.rs#L185-L222），避免重复调用 /api/tags。

已安装集合的构建规则（build_installed_set，providers.rs#L333-L356）直接决定了 TUI 里哪些行打勾：

• 云端托管模型被完全跳过：Ollama 对云模型使用 -cloud 标签后缀且本地 size 为 0；若把其 family 前缀（如 qwen3-coder）插入集合，会把无关模型误标为已安装。
• 带尺寸的标签（如 qwen3:8b）只贡献自身：它已经精确说明了磁盘上的权重。
• 无标签 / :latest 安装（尺寸确实未知时）额外贡献 family 前缀，以及由 Ollama 报告的参数量推导出的尺寸别名——例如 qwen3:latest 报告 "8.2B"，会生成 8b / 8.2b 两个 token，从而精确匹配 Qwen/Qwen3-8B（size_tokens_from_parameter_size，providers.rs#L303-L318）。

拉取实现：start_pull 发送 {"model": tag, "stream": true} 到 /api/pull，在后台线程逐行解析 NDJSON 进度（completed/total 换算百分比），遇到 status == "success" 发送 Done；若流结束却没有 success（常见于 tag 在 Ollama registry 中不存在），会给出明确错误（providers.rs#L389-L451）。此外还有一个 has_remote_tag 方法，通过本地 Ollama 守护进程的 /api/show 解析路径做“该 tag 是否存在于远程 registry”的尽力检查（providers.rs#L244-L252）。

llama.cpp 集成

llmfit 将 llama.cpp 作为 TUI 和 CLI 两种模式下的运行时/下载 provider。

前提条件：

• llama-cli 或 llama-server 位于 PATH 中（用于运行时检测）
• 可访问 Hugging Face 以下载 GGUF

工作原理：

• llmfit 将 HF 模型映射到已知的 GGUF 仓库（带启发式回退）
• 将 GGUF 文件下载到本地 llama.cpp 模型缓存
• 本地存在匹配的 GGUF 文件时标记模型为已安装

环境变量

变量	默认值	说明
LLAMA_CPP_PATH	(无)	包含 llama.cpp 二进制（llama-cli、llama-server）的目录。优先于 PATH 查找。
LLAMA_SERVER_PORT	8080	探测正在运行的 llama-server 健康端点（用于运行时检测）所用的端口。

如果 llama.cpp 安装在非标准位置，设置 LLAMA_CPP_PATH 让 llmfit 无需 PATH 即可找到它。

源码级细节

二进制查找顺序（find_binary，providers.rs#L1716-L1752）共四级：

1. CLI 参数 --llama-cpp-path 设置的进程级 override（OnceLock，仅首次调用生效）
2. LLAMA_CPP_PATH 环境变量目录
3. 常见安装位置：/usr/local/bin、/opt/llama.cpp/build/bin、~/.local/bin
4. 系统 PATH（通过 which crate，跨平台，不 shell 出去）

如果两个二进制都找不到，还会对 http://localhost:$LLAMA_SERVER_PORT/health 做一次 curl -sf --max-time 2 探测（probe_llama_server，providers.rs#L1756-L1765），识别出“没有本地二进制但 server 已在跑”的场景，此时 detection_hint() 会返回 "server detected" 而非提示设置 LLAMA_CPP_PATH。

模型缓存目录由 llamacpp_models_dir 决定（providers.rs#L1682-L1690）：优先 LLMFIT_MODELS_DIR，否则为系统缓存目录下的 llmfit/models（macOS 为 ~/Library/Caches/llmfit/models，Linux 为 ~/.cache/llmfit/models）。扫描深度上限为 3 层（GGUF_SCAN_MAX_DEPTH，providers.rs#L1584）——注释中说明了原因：LM Studio 按 publisher/repo/model.gguf 三级存放，3 层足以覆盖这类布局同时避免对大型模型库做全量爬取；符号链接的模型文件会被解析，但目录级符号链接故意不跟随。

GGUF 仓库映射分两层：

1. 静态映射表 LLAMACPP_GGUF_MAPPINGS（数百条 HF 仓库名 → GGUF 仓库条目，lookup_gguf_repo，providers.rs#L3770-L3780），例如 qwen3-8b → bartowski/Qwen3-8B-GGUF、deepseek-r1 → bartowski/DeepSeek-R1-GGUF。
2. 启发式回退 hf_name_to_gguf_candidates（providers.rs#L3783-L3796）：按 bartowski/{name}-GGUF、ggml-org/{name}-GGUF、TheBloke/{name}-GGUF 三个常见命名模式逐个生成候选，并用 HF API GET /api/models/{repo_id} 验证仓库真实存在（hf_repo_exists），避免凭空编造不存在的仓库。

文件选择与下载：

• select_best_gguf（providers.rs#L1120-L1147）在给定内存预算内按量化优先级挑选文件：Q8 > Q6 > Q5 > Q4 > Q3 > Q2（完整顺序见源码注释），找不到就取预算内最大的候选。分片模型（model-00001-of-00003.gguf）被折叠为单个候选：路径取首个分片，大小取全组分片之和，下载时再展开为完整分片集合顺序下载（parse_shard_info / collect_shard_set，providers.rs#L1427-L1482）。
• 下载走 https://huggingface.co/{repo}/resolve/main/{file}。安全性处理值得注意：文件名必须通过 validate_gguf_filename（拒绝路径分隔符、绝对路径、非 .gguf 后缀），并做规范化后的“必须仍位于 models_dir 内”检查；写入使用 .gguf.part 临时文件 + create_new（O_EXCL，防止预置符号链接劫持写入目标），完成后校验“实际下载字节 < Content-Length”即判定截断并删除临时文件，最后 rename 原子落盘（providers.rs#L1275-L1364）。进度事件以 200ms 节流发送。
• 已安装判定 is_model_installed_llamacpp（providers.rs#L3804-L3830）刻意避免子串匹配：单个 gemma-3.gguf 不能把数据库里所有 gemma-3-* 模型都标为已安装；匹配基于文件 stem 全等，或剥离 -instruct/-chat/-hf/-it 后缀后的全等。

MLX 集成（Apple Silicon）

文档层面，MLX 的定位是“mlx-community 模型缓存 + 可选 server”，且明确提示：MLX 下载对应 HuggingFace 上的 mlx-community/* 仓库，而不是原始模型发布方。

源码中 MlxProvider（providers.rs#L585-L610）的行为：

• 平台限定：detect_with_installed 在非 macOS 上跳过网络检查，直接报告 available=false，但仍会扫描 HF 缓存目录（providers.rs#L661-L679）。
• 服务器探测：默认 http://localhost:8080，可用 MLX_LM_HOST 覆盖（必须是 http/https URL，否则警告并忽略）；还会尝试 oMLX 默认端口 127.0.0.1:8000。探测时通过响应 Server: llama.cpp 头或模型列表中的 owned_by 字段识别端点身份，防止把 llama.cpp/llama-swap 服务的模型列表误当作 MLX 模型导入（classify_openai_endpoint，providers.rs#L485-L514）。
• 本地缓存扫描：scan_hf_cache_for_mlx 遍历 ~/.cache/huggingface/hub（以及 macOS 的 ~/Library/Caches；HF_HOME 优先）中的 models--mlx-community--* 目录，并按 -mlx- / -mlx 命名特征识别其他 mlx 仓库（providers.rs#L728-L759）。
• 下载：start_pull 调用 Hugging Face CLI 执行 hf download -- <repo>（-- 用于防止以 - 开头的仓库 ID 被误解析为 CLI 参数）。仓库解析函数 resolve_mlx_fallback_repo（providers.rs#L4099-L4126）会拒绝为 AWQ/GPTQ/AutoRound 等预量化非 MLX 格式猜测 mlx-community 等价仓库，并在猜测前先验证仓库真实存在，避免“Model not found”式失败。拉取标签选择 mlx_pull_tag 优先 -4bit 变体以减小下载量（providers.rs#L4066-L4085）。
• 兜底可用性判断还会执行 python3 -c "import mlx_lm"（结果用 OnceLock 缓存）。

Docker Model Runner 集成

llmfit 与 Docker Model Runner（Docker Desktop 内置的模型服务功能）集成。

前提条件：

• 启用 Model Runner 的 Docker Desktop
• 默认端点：http://localhost:12434

工作原理：

• llmfit 查询 GET /engines 列出 Docker Model Runner 中可用的模型（源码注释如此描述；实现中 detect_with_installed 实际探测的是 OpenAI 兼容的 {base}/v1/models 接口，两种路径返回相同的模型列表结构）
• 模型通过 Ollama 风格的标签映射匹配到 HF 数据库（Docker Model Runner 使用 ai/<tag> 命名）
• 在 TUI 中按 d 通过 docker model pull 拉取

远程 Docker Model Runner 实例

连接其他主机或端口的 Docker Model Runner，设置 DOCKER_MODEL_RUNNER_HOST：

DOCKER_MODEL_RUNNER_HOST="http://192.168.1.100:12434" llmfit

源码级细节

DockerModelRunnerProvider（providers.rs#L1861-L2022）的标签归一化做得比较细：对每个模型 ID（如 ai/llama3.1:8B-Q4_K_M，小写化后）同时插入三个变体——完整 ID、ai/ 命名空间后的部分（llama3.1:8b-q4_k_m）、以及剥离量化标签后的基础名（llama3.1），最大化与目录中 HF 名称的命中面。

两个环境适配点：

• Linux 短路：Linux 上先检查 Docker Desktop 是否运行（/run/docker-desktop/docker.sock 或 ~/.docker/desktop/docker.sock 存在，或显式设置了 DOCKER_MODEL_RUNNER_HOST），否则跳过 HTTP 探测，避免每次启动白等约 800ms 超时（providers.rs#L1868-L1885）。TUI 侧还会用 docker_desktop_installed()（检查各平台的安装路径）区分“已安装但未运行”和“未检测到”。
• 拉取实现：在后台线程执行 docker model pull -- <tag>，-- 防止以 - 开头的 tag 注入 docker CLI 参数（providers.rs#L2054-L2093）。

LM Studio 集成

llmfit 将 LM Studio 作为带内置下载能力的本地模型服务器集成。

前提条件：

• LM Studio 正在运行且已启用本地服务器
• 默认端点：http://127.0.0.1:1234

工作原理：

• llmfit 查询 GET /v1/models 列出 LM Studio 中可用的模型
• 在 TUI 中按 d 通过 POST /api/v1/models/download 触发下载
• 下载进度从 POST 响应流式返回；当 LM Studio 返回 job id 时，改为通过 GET /api/v1/models/download/status/:job_id 跟踪进度
• LM Studio 直接接受 HuggingFace 模型名，因此无需名称映射

远程 LM Studio 实例

连接其他主机或端口的 LM Studio，设置 LMSTUDIO_HOST：

LMSTUDIO_HOST="http://192.168.1.100:1234" llmfit

API 认证

如果你的 LM Studio 实例启用了 Require API Key（MCP server 访问所必需），设置 LMSTUDIO_API_KEY 环境变量，所有请求都会附带 Bearer token：

export LMSTUDIO_API_KEY="your-api-key-here"
llmfit

源码中 LmStudioProvider 在构造时读取 LMSTUDIO_HOST 与 LMSTUDIO_API_KEY（providers.rs#L2286-L2307），并在 GET /v1/models、下载与状态轮询的每一处请求上注入 Authorization: Bearer <key> 头。

源码级细节

下载标签解析：LM Studio 的下载 API 只接受 HuggingFace 仓库 URL 形式。lmstudio_pull_tag（providers.rs#L2908-L2927）的注释记录了针对 LM Studio 0.4.20 的实测结论：直接给 .gguf 文件链接会被 HTTP 400 拒绝（"Invalid HuggingFace model URL format"），而社区模型的裸 owner/repo ID 也会被拒绝。因此 llmfit 会先验证该仓库确实带有可下载的 GGUF 权重——优先查静态 GGUF 映射表，再用 bartowski/、ggml-org/、TheBloke/ 启发式候选，并以“系统内存 × 0.85”为预算调用 select_best_gguf 确认存在合适的量化文件——最后才把 resolve URL 反转为 API 接受的仓库 URL 形式（lmstudio_pull_tag 内部调用 lmstudio_find_gguf_url，providers.rs#L2854-L2883）。

进度跟踪的两级回退（start_pull，providers.rs#L2593-L2775）：

1. LM Studio 可能以 NDJSON/SSE 从 POST 响应流式推送进度，也可能只确认请求后关流、在后台继续下载（0.4.20 甚至会返回跨多行的美化 JSON，代码先整体按一个 JSON 文档解析，再回退到逐行解析）；
2. 若流中没有完成事件但拿到了 job_id，则轮询 GET /api/v1/models/download/status/{job_id}（3 秒间隔、最多 600 次即 30 分钟；completed/already_downloaded 视为完成，failed 视为失败，连续 3 次空状态则放弃该路径）；
3. 最终兜底是周期性地重新 GET /v1/models，检查候选名称是否已出现在已加载列表里（poll_lmstudio_installed_models，providers.rs#L2511-L2570）。

已安装判定分 API 与磁盘两条路径：HTTP API 只报告当前 已加载 的模型（13 个模型装库、只加载 1 个，API 只报 1 个），所以 scan_lmstudio_models_dir（providers.rs#L2184-L2235）直接扫描 ~/.lmstudio/models 下的 GGUF 文件作为“完整画像”——mmproj-* 视觉投影器文件不计入模型数，LM Studio 追加的 -GGUF 仓库后缀会被剥掉；磁盘路径刻意使用全等匹配（而非 API ID 的子串匹配），防止一个已安装的 base 模型把同名 IT 变体也标为已安装。

模型名映射

llmfit 的数据库使用 HuggingFace 模型名（如 Qwen/Qwen2.5-Coder-14B-Instruct），而 Ollama 有自己的命名体系（如 qwen2.5-coder:14b）。llmfit 维护两者之间的精确映射表，使安装检测和拉取都解析到正确的模型。每条映射都是精确的——qwen2.5-coder:14b 对应 Coder 模型，而不是基础模型 qwen2.5:14b。

从源码看，这张表就是 OLLAMA_MAPPINGS 常量（providers.rs#L4135-L4297），约 150 条 HF 仓库名（小写、斜杠后部分）到 Ollama tag 的条目，例如：

("llama-3.1-8b-instruct", "llama3.1:8b"),
("qwen2.5-coder-14b-instruct", "qwen2.5-coder:14b"),
("qwen3-8b", "qwen3:8b"),
("deepseek-r1-distill-qwen-32b", "deepseek-r1:32b"),

源码注释写得很直白：“只有在此表中列出的模型才有已知的 Ollama registry 条目；不在表中的模型无法从 Ollama 拉取”——即映射表同时充当“Ollama 可拉取性”的白名单。反向匹配（判断某个 Ollama tag 是否对应目录里的 HF 模型）由 tag_matches_model（providers.rs#L4505）完成，TUI 用它把 provider 返回的 tag 与 HF 风格模型名对齐（tui_app.rs#L365-L373）。

除 Ollama 外，其他 provider 也各有映射策略，形成一套完整的命名体系：

Provider	命名空间	映射/匹配策略（源码位置）
Ollama	family:tag	精确映射表 OLLAMA_MAPPINGS + 已安装集合的 family stem/尺寸别名
llama.cpp	GGUF 仓库名	静态表 LLAMACPP_GGUF_MAPPINGS + bartowski/ggml-org/TheBloke 启发式（providers.rs#L3783）
MLX	mlx-community/{name}-{quant}bit	显式映射 + -4bit/-8bit/-mlx-* 变体展开（providers.rs#L3909），拉取优先 4bit
Docker Model Runner	ai/<tag>	剥命名空间 + 剥量化标签的多变体插入
LM Studio	HF 原名	直接使用 HF 名称；匹配时剥离 -instruct/-chat/-hf/-it 后缀（hf_name_to_lmstudio_candidates，providers.rs#L2784-L2804）

值得注意的是 vLLM：虽然 docs/providers.md 的主体聚焦上述五个 provider，源码中还存在 VllmProvider（providers.rs#L2951-L3086）——默认探测 http://localhost:8000（可用 VLLM_HOST 覆盖），通过 GET /v1/models 列出已加载模型，但不支持运行时下载（start_pull 返回提示：vLLM 没有 pull 端点，模型在服务启动时经 HuggingFace 加载，需要 vllm serve <model> 重启）。它同样通过 oMLX 状态端点做身份甄别，避免与 oMLX 服务混淆。

环境变量速查

变量	默认值	作用
OLLAMA_HOST	http://localhost:11434（回退 127.0.0.1:11434）	指定 Ollama 实例地址
LLAMA_CPP_PATH	(无)	llama.cpp 二进制目录，优先于 PATH
LLAMA_SERVER_PORT	8080	探测运行中 llama-server 的 /health 端点端口
LLMFIT_MODELS_DIR	系统缓存目录/llmfit/models	GGUF 模型缓存目录
MLX_LM_HOST	http://localhost:8080	MLX 兼容 server 地址（须为 http/https URL；仅 macOS 做网络探测）
HF_HOME	(无)	覆盖 HuggingFace 缓存根目录（扫描 MLX/GGUF 缓存时优先）
DOCKER_MODEL_RUNNER_HOST	http://localhost:12434	Docker Model Runner 端点
LMSTUDIO_HOST	http://127.0.0.1:1234	LM Studio 本地服务器端点
LMSTUDIO_API_KEY	(无)	LM Studio 启用 Require API Key 时的 Bearer token
VLLM_HOST	http://localhost:8000	vLLM server 端点（仅列举，不支持下载）

所有 host 类变量都接受 host:port 或 http(s)://host:port 两种写法（各 provider 的 normalize_*_host 函数统一处理，格式非法时打印警告并回退默认值），因此远程实例接入的命令形式一致：<VAR>="http://<host>:<port>" llmfit [子命令]，对 TUI 与 llmfit fit 等 CLI 命令均生效。

小结

llmfit 的 provider 层用一个四方法特性抽象了“探测、列装、下载、进度”四件事，把每个运行时的差异（Ollama 的 tag 注册表、llama.cpp 的 GGUF 缓存与量化选择、MLX 的 mlx-community 仓库、Docker Model Runner 的 ai/<tag> 命名、LM Studio 的 job 状态机）都收敛在 llmfit-core/src/providers.rs 各自的实现内；TUI 则以后台线程探测 + 事件通道的方式把这些异步能力呈现为“绿色 ✓ 标记 + 按 d 一键下载 + 实时进度”。理解了这套映射表与探测顺序，你就能解释 llmfit 界面上任何一个 ✓ 的由来，也能按自己的部署（远程 GPU 服务器、Docker 容器、带 API Key 的 LM Studio）用一张环境变量表完成接入。