DeepSeek Harness（简称 dsh）是 DeepSeek‑AI 推出的 Agent 运行底座，它的核心设计思想是模型能力不属于框架内核，而是以插件形式实现扩展。框架内置两套模型适配插件：dsh‑llm‑deepseek 负责对接 DeepSeek 官方服务；dsh‑llm‑pi‑ai 作为通用适配层，兼容 OpenAI 协议的各类模型服务。开发者借助这套通用插件，可以接入 Anthropic、Google、Azure、Mistral、本地 Ollama、自建 vLLM 等各类大模型后端，无需修改 Harness 核心源码。
很多开发者初次接入第三方模型时，会遇到鉴权报错、协议不兼容、多模态图像失效、上下文窗口参数异常、网关返回格式不匹配等问题。本文梳理三种接入模式：Web UI 目录提供商接入、Web UI 自定义提供商接入、直接编辑 settings.yaml 文件，同时讲解兼容开关、多模态配置、本地模型调参、排错对照表，帮助工程团队完成多模型混合部署。在多模型路由场景下，Treerouter 这类 API 网关可以统一管理不同厂商模型的流量与密钥，降低多服务商维护成本。
DeepSeek Harness 的模型层架构
Harness 将模型能力拆分为两套相互独立的插件，两套插件可以同时加载运行。
| 插件名称 | 路由命名 | 核心职责 | 默认模型列表 |
|---|---|---|---|
| dsh‑llm‑deepseek | deepseek‑official | 对接 DeepSeek 官方对话接口，支持长上下文、文件上传能力 | deepseek‑v4‑flash、deepseek‑v4‑pro |
| dsh‑llm‑pi‑ai | 用户自定义命名 | 通用兼容层，对接各类 OpenAI 协议后端，支持目录/自定义网关 | 取决于配置文件 |
dsh‑llm‑pi‑ai 的设计理念十分关键：OpenAI 兼容网关或者私有化推理服务，只靠配置即可完成接入，不需要修改代码。整个配置结构本质是 providers 字典，字典内每一个键代表一条模型路由，请求会读取 provider 字段匹配对应路由配置。
在开始配置前，先理清三个基础概念：
- 目录提供商：插件内置预置端点、协议、模型清单的服务商，例如 OpenAI、Anthropic、Google、Mistral。开发者只需要填入 API Key，其余端点地址、模型列表由目录自动补齐。
- 自定义提供商：目录中不存在的服务，例如私有化推理集群、自建网关、本地 Ollama，需要手动填写基础 URL、协议类型、模型 ID 清单。
- 凭据引用：配置文件不建议明文填写密钥，优先使用环境变量
apiKeyEnv；WebUI 填写的密钥会加密保存在$DSH_HOME/credentials.yaml，配置文件只做引用，避免密钥明文泄露。
方式一：Web UI 添加目录提供商
目录提供商适用于 Anthropic、OpenAI 这类主流公有云模型服务商，不需要手动填写接口地址，仅补充密钥即可完成接入。
操作步骤：
- 启动 DeepSeek Harness，执行命令
npx @deepseek‑ai/dsh web，默认访问地址http://127.0.0.1:3080，打开设置‑模型页面。 - 点击「添加提供商」，从下拉列表选中目标目录服务商。
- 在输入框填入对应 API Key，保存配置。保存之后不会立刻弹窗刷新，配置会在下一次模型请求生效。
- 返回对话界面，模型选择器会加载该服务商全部模型，选中后就作为当前会话默认模型。
> 重要注意事项
> - 部分目录提供商不能只填 API Key：Bedrock、Vertex、Azure、Codex，还需要补充地域、ADC 项目、api‑version、OAuth 凭据，仅填写密钥会持续鉴权失败。
> - Codex 支持授权登录流程，凭据会保存在 llm‑pi‑ai 的 provider 记录，登录状态自动持久化，退出登录会清除存储凭据。
方式二：Web UI 添加自定义提供商
当对接私有化部署、本地 vLLM、Ollama，或者 Treerouter 这类中转网关时，需要新建自定义提供商，一共需要填写五项核心字段，至少配置一条模型 ID。
| 字段 | 填写说明 | 注意事项 |
|---|---|---|
| Provider ID | 小写字母数字标识符，例如 my‑gateway | 一旦创建不可修改，会话历史、凭据绑定都依赖该 ID，修改只能新建 |
| 显示名称 | 前端下拉框展示别名 | 可随时修改，仅影响 UI 展示 |
| 基础 URL | 网关/vLLM 接口地址，示例 https://gateway.example.com/v1 | 指向服务的 v1 根路径 |
| API 协议 | 三选一：openai‑completions / openai‑responses / anthropic‑messages | 一条路由只能绑定一类协议 |
| 凭据 | API Key | 会存入凭据存储，不会明文写进 settings.yaml |
| 模型 | 至少填写一个模型 ID | 点击获取可用模型会调用 /models 接口自动拉取；网关不支持 models 接口就手动录入 |
点击「获取可用模型」会发起网络请求读取模型列表，如果网关返回 401，代表密钥错误；网关没有实现 /models 端点，则必须手动录入模型 ID。全部配置保存完成后，修改不会立即生效，下一次模型请求加载新配置。图片模态、推理等级、兼容开关这类高级参数，Web UI 无法覆盖，需要使用第三种方式修改 yaml。
方式三：直接编写 settings.yaml 完整配置
$DSH_HOME/settings.yaml 下的 llm‑pi‑ai 节点是全部模型路由的完整数据源，Web UI 的配置本质是对这份 yaml 的可视化编辑。一份自定义网关路由完整示例：
llm‑pi‑ai:
providers:
my‑gateway:
displayName: "My Custom Gateway"
apiKeyEnv: "GATEWAY_API_KEY"
api: openai‑completions
baseURL: "https://gateway.example.com/v1"
defaultContextWindow: 262144
defaultMaxTokens: 32768
models:
- "model‑a"
- "model‑b"核心字段释义
| 字段 | 默认值 | 作用说明 |
|---|---|---|
| apiKey / apiKeyEnv | 无 | apiKeyEnv 读取环境变量；apiKey 为明文密钥，生产环境不推荐 |
| baseURL | 目录内置 | 路由统一接口地址，所有该路由下模型共用 |
| models | 读取目录 | 完整替换路由的模型清单 |
| modelOverrides | 无 | 局部修改目录内个别模型参数，不替换全部模型，不能和 models 字段同时使用 |
| compat | 自动检测 | 请求格式兼容开关，适配不标准的第三方网关 |
| defaultContextWindow | 262144 | 未声明上下文窗口的模型，使用该回退值 |
| defaultMaxTokens | 32768 | 未声明最大输出长度模型的回退参数 |
| defaultInput | [text] | 模型默认支持输入模态，多模态模型需要改为 [text,image] |
| headers | 无 | 自定义附加请求头，用于私有网关鉴权逻辑 |
| retryPolicy | nominal 5次 | 接口报错重试策略配置 |
> 配置修改无需重启服务，变更会在下一轮请求加载；但是桌面版 Harness 客户端，插件层面修改需要重启客户端，模型配置不需要重启。
compat 兼容开关：解决网关格式不兼容
很多自建网关、推理服务不完全遵循 OpenAI 原始报文规范，直接调用会被拒绝请求。compat 节点用来开关各类请求兼容适配，规避字段不兼容问题。
compat:
supportsDeveloperRole: false
maxTokensField: max_tokens常用开关说明：
supportsDeveloperRole：关闭时，框架不会向网关传递developer角色消息，很多国内推理服务不支持该字段，会直接报错。maxTokensField：切换输出上限字段名，部分服务只识别max_tokens，不识别max_completion_tokens。supportsReasoningEffort：控制是否传递推理强度参数，不支持思考链模型需要关闭。thinkingFormat：适配思考内容传输格式，针对 DeepSeek、vLLM chat‑template 系列服务。
> 配置规则：开关归属于对应协议；openai‑completions 的开关配置放到对应 provider 下，放到 anthropic‑messages 路由不会生效。优先在单个 provider 下配置 compat，不建议全局统一修改，避免影响其他正常服务商。
多模态图像模型配置
自定义接入的模型默认只识别文本输入，图片消息会被直接丢弃。想要启用图像输入能力，需要显式声明 defaultInput。
单条模型单独开启模态：
models:
- id: vision‑preview
input: ["text","image"]整条路由全部模型支持图像：
my‑gateway:
defaultInput: ["text","image"]注意：声明模态不等于后端服务真的支持图片。如果网关本身没有图像能力，即便配置 image，请求依旧会失败，此时要从模型列表移除图像能力标记。DeepSeek 官方适配插件 dsh‑llm‑deepseek 的图像逻辑走 Files API，不受这套 input 参数控制。
本地 Ollama、vLLM 接入实操
本地推理服务全部走自定义提供商，协议选择 openai‑completions。本地服务一般不需要密钥，鉴权字段可以留空。
local‑vllm:
displayName: "Local vLLM Service"
api: openai‑completions
baseURL: "http://127.0.0.1:8000/v1"
apiKeyEnv: "LOCAL_PLACEHOLDER_KEY"
defaultContextWindow: 32768
compat:
supportsDeveloperRole: false
supportsThinkingTokenBudget: true本地部署务必调整 defaultContextWindow，不要直接沿用默认 262144，要和真实模型上下文大小匹配，否则会出现截断、推理异常。
models 与 modelOverrides 的区别
models：完整覆盖整条路由的模型列表，路由只会使用填写的模型 ID。适合对接网关，网关模型集合完全不同于官方目录。modelOverrides：只修改目录内个别模型参数，其余沿用目录原有配置。适合修改目录中某一个模型的上下文窗口、模态配置，不改动全部模型。
> 禁止 models 和 modelOverrides 写在同一个 provider，配置会直接报错。
常见故障排查对照表
| 现象 | 根因 | 处理方案 |
|---|---|---|
| MISSING_CREDENTIALS | 密钥引用为空 | 补充 apiKey 或者环境变量 apiKeyEnv |
| INVALID_CREDENTIAL | 鉴权失败 | 核对密钥、凭据存储，公有云检查密钥权限 |
| UNKNOWN_MODEL | 模型ID不在路由清单 | 把模型ID补入 models 列表 |
| 获取可用模型返回401 | 网关鉴权拒绝 | 核对密钥，网关无 /models 接口手动录入模型ID |
| 密钥地址正确，全部请求被拒绝 | 报文格式和 OpenAI 存在差异 | 调整 compat，关闭 supportsDeveloperRole |
| 只有思考链相关调用报错 | 服务不支持 reasoning_effort | 关闭 supportsReasoningEffort 开关 |
| 图片消息发送被拒绝 | 没有声明 image 输入模态 | 配置 input: ["text","image"] |
| UNSTORABLE_PROVIDER_ID | Provider ID包含大写字符 | ID全部改为小写字母数字 |
高频问题解答
Q：可以同时运行 DeepSeek 官方插件和 pi‑ai 通用插件吗？
A：支持。两套插件相互独立，模型下拉选择器可以自由切换两套体系的模型，互不冲突。
Q：一条 provider 路由能不能同时使用 openai 和 anthropic 两套协议？
A：不可以。单条路由只能绑定一类协议。如果一个网关同时兼容两套协议，需要新建两条不同 provider ID 的路由分开配置。
Q：修改 settings.yaml 是否需要重启 Harness？
A：服务端不需要重启，新请求自动加载配置；桌面客户端版本，插件变更要重启客户端，单纯模型配置修改无需重启。
Q：模型目录会自动同步服务商新增模型吗？
A：不会。目录提供商不会自动拉取服务商新增模型，新版本模型需要手动添加到 models 配置。
总结
DeepSeek Harness 通过 dsh‑llm‑pi‑ai 插件实现模型层完全解耦，框架本身不绑定任何一家大模型厂商。开发者可以根据业务复杂度选择 Web UI 可视化配置，或者直接维护 settings.yaml 完成批量路由管理。目录提供商适合快速接入公有云；自定义提供商面向私有化推理、自建网关场景；yaml 文件适合批量运维、CI 交付。
接入过程中绝大多数报错来源于协议字段不兼容、模态标记缺失、上下文窗口参数配置错误，优先调整 compat 兼容开关，配合排错对照表可以快速定位问题。混合多模型集群运维时，借助统一网关能力可以简化多服务商接入流程。
了解更多：https://treerouter.com
