Zed 本地模型接入实战：llama.cpp、Ollama 与 LM Studio 的完整配置指南

本文基于 Zed 官方文档 Use a Local Model，系统讲解如何在本机或自有基础设施上运行大模型并将其接入 Zed 的 Agent、Inline Assistant 等 AI 功能。你将掌握 llama.cpp、Ollama、LM Studio 三条本地推理路径的安装与服务启动步骤、settings.json 中 language_models 配置的各参数含义（api_url、auto_discover、available_models、context_window 等），并理解 Zed 源码中模型自动发现、上下文长度协商与能力探测（tools/vision/thinking）的底层实现。

本地模型的适用场景与总体路线

当你希望模型运行在自己控制的机器上（不经过云端）时，就走“本地模型”这条路。Zed 支持的本地接入方式及各路径覆盖的功能如下（引自原文档的能力矩阵）：

本地路径	Zed AI 功能	External Agents	Terminal Threads	说明
llama.cpp	支持	需单独配置	需单独配置	为 Zed AI 功能配置 llama.cpp 服务器
LM Studio	支持	需单独配置	需单独配置	为 Zed AI 功能配置 LM Studio
Ollama	支持	需单独配置	需单独配置	为 Zed AI 功能配置 Ollama
本地 OpenAI 兼容服务	支持	需单独配置	需单独配置	配置 base URL、模型，必要时配置 key
本地/自托管 Edit Prediction	仅 Edit Prediction	不支持	不支持	使用 Edit Prediction 的独立配置

需要注意的边界：外部 Agent（External Agents）与终端 CLI 的本地模型配置是独立体系，需要在对应 agent 或 CLI 侧自行配置，本文只覆盖在 Zed 内配置的本地模型。

Zed 通过一组独立的 crate 与各本地推理服务通信，核心文件为：

• llama.cpp 客户端：对接 llama.cpp 内置服务器；
• Ollama 客户端：对接 Ollama HTTP API；
• LM Studio 客户端：对接 LM Studio 的 OpenAI 风格 API；
• 设置内容定义：定义 language_models 各 provider 的 JSON 设置结构。

llama.cpp：使用其内置服务器

llama.cpp 自带 HTTP 服务器，可直接为 Zed Agent、Inline Assistant 等模型驱动功能提供服务。步骤：

1. 从 llama.app 安装 llama.cpp；
2. 以 router 模式启动内置服务器：

llama serve

router 模式下，模型按需求从 llama.cpp 缓存中加载。若想一步完成“下载并运行某个模型”，可传入 -hf 参数直接拉取 Hugging Face 上的 GGUF：

llama serve -hf unsloth/gemma-4-26B-A4B-it-GGUF:BF16

3. 在 Zed 的模型下拉框中选择该 llama.cpp 模型即可。

模型自动发现与手动声明

Zed 会自动发现 llama.cpp 正在服务的模型及其上下文长度、tools/vision 能力。在 router 模式下，当某个模型实际加载后，Zed 会通过服务器的 /models/sse 事件流再次精化这些能力信息（需要较新的 llama.cpp 构建才提供该端点）。

如果你不想依赖自动发现（例如想固定展示某个模型、或服务器版本过旧），把 auto_discover 设为 false 并手动列出模型：

{
  "language_models": {
    "llama.cpp": {
      "api_url": "http://localhost:8080",
      "auto_discover": false,
      "available_models": [
        {
          "name": "gemma-4-12b-it-GGUF:BF16",
          "display_name": "gemma-4-12b-it-GGUF:BF16",
          "max_tokens": 32768,
          "supports_tools": true,
          "supports_images": false
        }
      ]
    }
  }
}

结合源码看各参数的作用：

• api_url：llama.cpp 客户端的默认地址在 llama_cpp.rs 中硬编码为 http://localhost:8080，与示例一致；远程服务器则改成对应端点；
• auto_discover：对应 设置定义 中 LlamaCppSettingsContent.auto_discover，注释明确“默认 true，即自动发现服务器提供的模型”；
• available_models 每项字段（name、display_name、max_tokens、supports_tools、supports_images、supports_thinking）与 LlamaCppAvailableModel 结构一一对应。其中 name 是服务器报告的模型 id（即 --alias 或模型文件路径），max_tokens 即上下文长度（n_ctx）。

发现机制的底层流程：

1. 客户端通过 GET {api_url}/v1/models 列出模型（单模型模式返回 1 条带 meta.n_ctx 的记录；router 模式返回全部已知模型并带 status/architecture 字段，见 get_models 实现）；
2. 通过 GET /props 读取已加载模型的 default_generation_settings.n_ctx（运行时上下文）、modalities.vision（是否支持图像）与 chat_template_caps（是否支持 tool calls / reasoning，见 get_props 与 Props 解析）。router 模式下该接口用 URL 编码的 ?model= 查询参数选择实例，因为模型 id 中含 / 和 :；
3. router 模式下客户端持续订阅 /models/sse 事件流，仅当出现 loaded/unloaded/models_reload/model_remove 等终态事件时触发重新发现，中间态的加载进度（loading + 分阶段 progress）则用于在模型选择器中展示 “Loading weights 42%” 之类的进度标签，实现见 ModelEvent 与 LoadProgress，并有配套单测覆盖加载进度、加载失败（非零 exit_code）等边界场景。

llama.cpp 的上下文长度

Zed 默认使用服务器报告的上下文长度（/props 中的 n_ctx）。两个覆盖方式：

• 对所有模型统一覆盖：context_window；
• 对单个模型覆盖：available_models 中的 max_tokens。

{
  "language_models": {
    "llama.cpp": {
      "context_window": 8192
    }
  }
}

若未做任何配置，源码中的兜底默认值是 DEFAULT_CONTEXT_LENGTH = 4096（llama_cpp.rs#L17），也就是服务器未报告时按 4096 token 处理。

llama.cpp 鉴权

如果 llama.cpp 服务器要求 key，在 provider UI 中输入，或设置环境变量 LLAMACPP_API_KEY。远程服务器的做法是把 api_url 指向其端点并提供 key（服务器侧用 --api-key 设置）。从源码看，key 会以 Authorization: Bearer {key} 头附加到 /v1/models、/props、/models/sse 和 /v1/chat/completions 全部请求上。

Ollama：最常用的本地模型管理器

使用 Ollama 为 Zed Agent、Inline Assistant 等功能提供本地模型：

1. 从 ollama.com/download 下载安装 Ollama；
2. 拉取一个模型：

ollama pull mistral

3. 确保 Ollama 服务在运行。macOS 上打开 Ollama.app；Linux 或 shell 中执行：

ollama serve

4. 在 Zed 的模型下拉框中选择该 Ollama 模型。

Zed 会自动发现 Ollama 已拉取的模型。要关闭自动发现并手动列出模型，配置 auto_discover：

{
  "language_models": {
    "ollama": {
      "api_url": "http://localhost:11434",
      "auto_discover": false,
      "available_models": [
        {
          "name": "qwen2.5-coder",
          "display_name": "qwen 2.5 coder",
          "max_tokens": 32768,
          "supports_tools": true,
          "supports_thinking": true,
          "supports_images": true
        }
      ]
    }
  }
}

参数说明（结合 设置定义）：

• api_url：默认 http://localhost:11434（ollama.rs#L12），远程 Ollama（如 Ollama Turbo）指向远端端点即可；
• available_models 每项还支持 keep_alive 字段：可写秒数（5）或时长字符串（"5m"、"1h"）。从源码看，未显式指定时 Zed 对自动发现的模型默认使用 KeepAlive::indefinite()（即 keep_alive: -1），模型会一直驻留内存直到加载新模型或 Ollama 退出（见 Model::new）。手动声明的模型可按需缩短保活时间以释放显存；
• supports_tools/supports_images/supports_thinking 均为可选字段，手动声明时用于告知 Zed 该模型的能力；自动发现时则由 POST /api/show 返回的 capabilities 数组（含 "tools"、"vision"、"thinking" 时判定为支持）得出（ModelShow）。

Ollama 的上下文长度（num_ctx）

发往 Ollama 的请求把上下文长度作为 num_ctx 参数传递，默认使用 4096 token（get_max_tokens 的默认值，ollama.rs#L27-L30）。

对所有 Ollama 模型统一设置上下文长度：

{
  "language_models": {
    "ollama": {
      "context_window": 8192
    }
  }
}

也可以像上文一样用 available_models 中的 max_tokens 按模型单独设置。从实现看，num_ctx 会进入 ChatRequest.options（ChatOptions），随 POST /api/chat 一起发送；单测 test_chat_options_serialization 还验证了“stop 未设置时不出现在请求 JSON 中，让 Ollama 使用模型自带的默认 stop token”这一细节。

Ollama 鉴权

服务器需要 key 时，在 provider UI 输入或设置 OLLAMA_API_KEY；远程 Ollama 服务（如 Ollama Turbo）同样是指定 api_url + 提供 API key。

LM Studio：开箱即用的本地推理 GUI

LM Studio 提供图形界面与命令行两种模型管理方式：

1. 下载并安装 LM Studio；
2. 在 LM Studio 中下载至少一个模型，或使用其 CLI：

lms get qwen2.5-coder-7b

3. 启动 LM Studio 的 API 服务器：

lms server start

4. 在 Zed 的模型下拉框中选择该 LM Studio 模型。

若 LM Studio 服务器要求 key，在 provider UI 输入或设置环境变量 LMSTUDIO_API_KEY。

源码侧要点（lmstudio.rs）：

• 默认端点是 http://localhost:1234/api/v0，与 LM Studio 内置 OpenAI 风格 API 对应；
• LM Studio 的设置项包含 api_url、api_key、available_models、custom_headers（LmStudioSettingsContent）；
• 手动声明模型时字段为 name、display_name、max_tokens、supports_tool_calls、supports_images；未指定 max_tokens 时源码默认 2048（Model::new），因此建议在 available_models 中显式写大一些。

本地 OpenAI 兼容服务

任何暴露 OpenAI 兼容 API 的本地或自托管服务器，都可以走 Zed 的 OpenAI 兼容接入方式（配置 base URL、模型列表与 key），详见 Use API Access 中 OpenAI-compatible 一节。这类服务器（包括各种自托管网关）无需 Zed 内置 provider，直接复用 openai_compatible 设置即可。

本地 Edit Prediction

Zed 的 Edit Prediction（编辑预测/自动补全建议）有独立的 provider 体系，不走上述 language_models 配置。本地与自托管的 Edit Prediction 选项（如本地 OpenAI 兼容端点等）请见 Edit Prediction。它只服务 Edit Prediction 功能，不用于 Agent 或 Terminal Threads。

验证配置是否生效的实操建议

• 先在模型下拉框里确认本地模型出现：llama.cpp/Ollama 走自动发现时，模型列表会随服务器状态变化（router 模式下模型加载完成后能力信息会被精化）；
• 上下文不匹配时优先检查 context_window 与服务器实际 n_ctx/num_ctx 是否一致——Zed 会按声明的窗口管理提示词，而服务器端实际容量不同可能导致请求被截断或拒绝；
• 自动发现不可用时，回退到 auto_discover: false + 手写 available_models，并逐项核对 name（必须是服务器 API 中真实的模型 id/路径/别名）、max_tokens 与能力开关；
• 各 provider 的 api_url 默认值（llama.cpp 8080 端口、Ollama 11434 端口、LM Studio 1234 端口）均来自源码常量，远程部署时改 api_url 并配合对应环境变量（LLAMACPP_API_KEY、OLLAMA_API_KEY、LMSTUDIO_API_KEY）提供鉴权即可。

以上配置全部写入 settings.json 的 language_models 节点，设置结构定义可进一步参考 crates/settings_content/src/language_model.rs 与 crates/language_models/src/settings.rs。