Khoj 接入 LM Studio：基于 OpenAI 兼容 API 的本地大模型配置全解与当前兼容性边界

本篇技术指南以 Khoj 官方文档 LM Studio 集成说明 为主体，讲清两件事：一是如何通过 LM Studio 的 OpenAI 兼容本地服务，把本地开源大模型变成 Khoj 的聊天模型（含 Admin 面板的完整字段配置）；二是 Khoj 为何明确标注 LM Studio "不再受支持"——这背后是 Khoj 对结构化输出（structured output / JSON mode）的深度依赖。读完后，你可以判断 LM Studio 是否仍适合你的自托管场景，并掌握可复制的替代方案（Ollama、LiteLLM、vLLM 等 OpenAI 兼容服务）。

需要预先说明适用前提：本文全部内容仅适用于自托管 Khoj 用户。官方文档明确提示，如果使用的是 Khoj Cloud 服务，只能使用其第一方支持的模型，本地模型集成能力不开放。

一、当前状态：为什么 Khoj 标注 LM Studio 为"Unsupported"

LM Studio 集成文档 开篇即给出一个官方警告（warning 级别提示块）：

Khoj does not work with LM Studio anymore. Khoj leverages json mode extensively but LMStudio's API seems to have dropped support for json mode.

翻译过来：Khoj 已经无法与 LM Studio 正常配合工作，原因是 Khoj 大量依赖 OpenAI 的 JSON mode / 结构化输出能力，而 LM Studio 的本地 API 据官方判断已放弃对该能力的支持。

这不是文档的一句空话，而是可以从源码中直接印证的。Khoj 在与 OpenAI 兼容模型交互时，结构化输出是核心链路：

1. 对话主入口：gpt.py 中的 openai_send_message_to_model 负责向模型发送消息。它在构造请求参数时会先调用 get_structured_output_support(model, api_base_url) 判断目标服务端支持哪一档结构化输出，然后：

   • 若请求携带工具（tools）且服务端支持 TOOL 档，则把工具定义转换成 OpenAI tools 格式下发；
   • 若需要按 Pydantic schema 返回结构化结果（response_schema 非空）且服务端支持不低于 SCHEMA 档，则通过 response_format={"type": "json_schema", ...} 下发严格 schema（非 OpenAI 原生 Responses API 时走这一分支）；
   • 仅当请求是 json_object 类型且服务端只支持 OBJECT 档时，才退化为 response_format={"type": "json_object"}。

2. 能力档位定义：结构化输出能力在 utils.py 中定义为一个四级枚举：

   class StructuredOutputSupport(int, Enum):
       NONE = 0      # 完全不支持
       OBJECT = 1    # 仅支持 response_format: json_object
       SCHEMA = 2    # 支持 json_schema 严格 schema
       TOOL = 3      # 支持 tools / function calling 形式的结构化输出
   

3. 默认判定逻辑：从 get_structured_output_support 的实现 看，除少数特例（Azure OpenAI 与 DeepInfra 被识别为 OBJECT 档、deepseek-reasoner 前缀被识别为 NONE）外，其余所有服务端（包括本地兼容服务）默认按最高档 TOOL 处理——即 Khoj 会直接下发 tools 或 json_schema 请求。如果 LM Studio 的本地服务已经不支持 JSON mode，这些请求就无法得到合规的结构化响应，Khoj 依赖结构化输出实现的智能体工具调用、自动化任务解析等能力就会失效。这就是文档中"Unsupported"结论的技术根源。

因此本文的实操章节应理解为：文档保留的完整接入路径 + 官方已声明的兼容性风险。LM Studio 仍是 OpenAI 兼容服务端，Khoj 的配置通路对它是开放的，但结构化输出缺失意味着部分智能体能力可能不可用。

二、LM Studio 在 Khoj 架构中的位置

文档对两者的关系给出了一段准确定位：

• LM Studio 是一个桌面应用，通过图形界面在本地机器上与开源大模型对话，适合偏好 GUI 的用户；
• 它能在本地暴露一个 OpenAI API 兼容服务（默认监听 http://localhost:1234/v1/），这正是 Khoj 可以"接住"它的接口。

文档还给出两条关键背景信息（均为 info 提示块）：

1. 自托管用户才能受益于此集成；Khoj Cloud 用户限定使用第一方模型；
2. Khoj 原生支持以 GGUF 格式从 HuggingFace 获取的本地大模型，使用 OpenAI API 代理（LM Studio 属于此类）更多是为了：降低接入门槛、方便快速试用新模型、或经由 API 使用商业 LLM。

这一"代理层"定位在仓库的其他文档中也是一致的：使用 OpenAI 代理 一文指出 Khoj 可以使用任何 OpenAI API 兼容服务，包括本地的 Ollama、LMStudio、LiteLLM 与商业供应商，而 setup 文档 与 admin 文档 也多次把 LMStudio 列为 OPENAI_BASE_URL / Api base url 的适用场景。

三、完整接入步骤（继承原文档的五步流程）

以下五个步骤完整继承自 LM Studio 集成文档，并结合仓库数据模型补充了每个字段的含义与依据。所有 Admin 面板地址中的端口 42110 与仓库 docker-compose.yml 中 server 服务的端口映射 42110:42110 一致。

步骤 1：安装 LM Studio 并下载聊天模型

安装 LM Studio，并通过其图形界面下载你需要的 Chat Model（开源模型）。此步发生在 Khoj 之外，与仓库代码无关，唯一要求是模型为"可对话"的 chat 模型。

步骤 2：启动 LM Studio 本地服务

在 LM Studio 的 Server 选项卡中，选中你准备好的 Chat Model，点击绿色的 Start Server 按钮。启动后，LM Studio 会在本机提供 OpenAI 兼容端点，文档给出的默认地址为：

http://localhost:1234/v1/

步骤 3：在 Khoj Admin 面板创建 AI Model API

打开 Admin 面板的 AI Model API 新增页（http://localhost:42110/server/admin/database/aimodelapi/add/），填入三个字段：

字段	取值	说明
Name	lmstudio	命名随意，仅用于 Admin 面板内识别，建议体现提供方
Api Key	any string	任意字符串即可。LM Studio 本地服务不校验 key，该字段必填（数据库层面为非空字段）
Api Base Url	http://localhost:1234/v1/	LM Studio 本地服务的默认地址

这三个字段与 Khoj 的数据模型一一对应：AiModelApi 模型 定义了 name（200 字符）、api_key（4000 字符，必填）与 api_base_url（URL 字段，可为空，为空时直连 OpenAI）。admin 文档 也对 Api base url 字段做了同样的说明：仅当使用 Ollama、LMStudio 等其他 OpenAI 兼容代理服务时才需要设置。

步骤 4：创建 Chat Model

打开 Chat Model 新增页（http://localhost:42110/server/admin/database/chatmodel/add），按如下方式填写：

字段	取值	说明
Name	llama3.1	替换为你在 LM Studio 中实际加载的模型名，必须与服务端 /v1/models 返回的模型 ID 一致
Model Type	Openai	走 OpenAI 兼容协议
Ai Model API	步骤 3 创建的 lmstudio	外键关联，指向本地的 LM Studio 端点
Max prompt size	20000	替换为你所选模型的实际上下文/提示长度上限
Tokenizer	不设置	文档明确：OpenAI、mistral、llama3 系模型不要配置 Tokenizer

这些字段对应 ChatModel 模型 的数据库定义：name、max_prompt_size（整型，可空）、tokenizer（字符串，默认空）、model_type（枚举仅含 openai / anthropic / google 三档，本地兼容服务一律选 openai）、ai_model_api（指向 AiModelApi 的外键）。从字段结构看，max_prompt_size 是 Khoj 组装提示词时的截断依据，填得过大可能导致上游服务端报错，填得过小会提前裁剪上下文；tokenizer 留空则走默认的字符估算逻辑——这也是文档要求 OpenAI/llama3/mistral 系模型不设置 Tokenizer 的原因。

步骤 5：在个人配置页启用该模型

打开配置页（http://localhost:42110/settings），在 Chat Model 下拉框中选择步骤 4 刚创建的模型。此后你的 Khoj 聊天、智能体与自动化将经由 LM Studio 本地服务调用该模型。

再次强调：官方文档已标注该集成当前不受支持（见第一节），若启用后出现智能体/工具调用类功能异常，应优先怀疑 LM Studio 侧的结构化输出支持问题，而不是配置问题。

四、另一条轻量路径：用 OPENAI_BASE_URL 在首次启动时自动注册模型

除了 Admin 面板的手工配置，Khoj 还有一条首次启动（first-run）自动集成路径：在启动 Khoj 之前设置 OPENAI_BASE_URL 环境变量指向 OpenAI 兼容服务，Khoj 会自动拉取该服务的全部可用模型并注册为 OpenAI 类型的 ChatModel。

源码依据在 initialization.py 的 _create_chat_configuration：

openai_base_url = os.getenv("OPENAI_BASE_URL") or None
provider = "Ollama" if openai_base_url and openai_base_url.endswith(":11434/v1/") else "OpenAI"
...
if openai_base_url:
    # Get available chat models from OpenAI compatible API
    openai_client = openai.OpenAI(api_key=openai_api_key, base_url=openai_base_url)
    available_chat_models = [model.id for model in openai_client.models.list()]

这段逻辑印证了三个事实：

1. 只要设置 OPENAI_BASE_URL（LM Studio 即 http://localhost:1234/v1/，Ollama 为 http://localhost:11434/v1/），Khoj 就会调用远端的 models.list() 接口，把已知默认模型排前、其余可用模型排后，批量创建 ChatModel 记录；
2. 拉取失败时只记录 warning 并回退到默认模型列表，不会阻断启动；
3. 从 :11434/v1/ 后缀识别 Ollama，LM Studio 的地址会被归入通用的 "OpenAI" 兼容分支——即 LM Studio 完全复用 OpenAI 兼容通路，没有专门适配代码，这也解释了为什么它的兼容性完全取决于 LM Studio 服务端对 OpenAI 协议（含结构化输出）的忠实度。

仓库 docker-compose.yml 中为 Docker 用户预留了对应注释，明确把 LMStudio 列为适用该变量的兼容提供方之一：

# Uncomment line below to use with Ollama running on your local machine at localhost:11434.
# Change URL to use with other OpenAI API compatible providers like VLLM, LMStudio, DeepInfra, DeepSeek etc.
# - OPENAI_BASE_URL=http://host.docker.internal:11434/v1/
# - KHOJ_DEFAULT_CHAT_MODEL=qwen3

注意 Docker 网络细节：compose 文件通过 extra_hosts: host.docker.internal:host-gateway 让容器内的 host.docker.internal 指向宿主机，因此容器化部署时 LM Studio 地址应写成 http://host.docker.internal:1234/v1/ 而非 localhost，否则容器内会解析到自身网络命名空间。

此外，若同时设置 KHOJ_DEFAULT_CHAT_MODEL（compose 中示例为 qwen3），Khoj 会在 初始化逻辑 中把它设为默认聊天模型，省去步骤 5 的手动选择。与 Ollama 文档 的提示一致：首次运行或更新配置后需重启 Khoj 服务，确保设置生效。

五、结构化输出依赖缺失时的替代方案

若你评估后认为当前 LM Studio 版本的 JSON mode 支持不满足需求，仓库文档给出了三条可落地的替代路径：

1. Khoj 原生 GGUF 本地模型：官方文档（LM Studio 页、Ollama 页、OpenAI 代理页的 info 提示块一致表述）指出 Khoj 原生支持 HuggingFace 上 GGUF 格式的本地大模型，不经过任何 OpenAI 兼容中间层；
2. 切换到其他 OpenAI 兼容提供方：docker-compose.yml 注释明确列出的候选包括 VLLM、DeepInfra、DeepSeek，以及文档族中的 Ollama 与 LiteLLM；Ollama 同样暴露 OpenAI 兼容端点（/v1/），且 Khoj 对其有专门识别分支（OPENAI_BASE_URL 以 :11434/v1/ 结尾时 provider 标记为 Ollama）；
3. 保留配置通路、等待 LM Studio 恢复支持：Khoj 侧的接入面（AiModelApi + ChatModel 两条记录 + 配置页选择）是通用的 OpenAI 兼容通路，一旦 LM Studio 重新提供 JSON mode / 结构化输出，同一套配置无需改动即可恢复完整能力。

六、适用前提与边界说明

• 本文所有 Admin 面板步骤（端口 42110、/server/admin/... 路径）基于仓库 docker-compose.yml 的默认端口映射；若自定义了宿主机端口，需相应替换；
• Api Key 填"任意字符串"的前提是使用 LM Studio 本地服务；换成商业 OpenAI 兼容服务时须填真实密钥（数据库字段上限 4000 字符）；
• Max prompt size 示例值 20000 来自原文档，实际应替换为你所选模型的提示长度上限；
• "Khoj 不再与 LM Studio 兼容"的结论来自当前仓库官方文档（documentation/docs/advanced/lmstudio.md）的警告提示块，其归因（LM Studio 放弃 JSON mode 支持）同样出自该文档；本文对"缺失结构化输出会导致智能体能力异常"的推断基于 gpt.py 与 结构化输出档位判定 的源码行为，属于从源码结构可证实的机制描述，而非针对 LM Studio 实测的结论；
• 使用 Khoj Cloud 的用户不适用本文任何步骤。