DeepSeek Harness 接入本地模型完整指南：Ollama / vLLM / 自定义 API 三种方案

发布日期：2026-10-21 | 话题：DeepSeek Harness 本地模型 / dsh 自定义端点 / Ollama vLLM 接入

DeepSeek Harness（dsh）是 DeepSeek 官方于 2026 年 8 月开源的 Agent 执行框架，MIT 许可，GitHub Star 数超过 25 万，采用"一切皆插件"架构，通过 Cordis 插件内核实现模型层、工具层、存储层解耦。除官方 DeepSeek API 外，dsh 支持通过「Custom model API」接入任意 OpenAI 兼容端点，覆盖 Ollama、vLLM、以及任何兼容 OpenAI Chat Completions / Responses / Anthropic Messages 格式的本地或内网推理服务。本文完整梳理三种接入路径的操作步骤：Web UI 可视化配置、cordis.patch.yml 直接编辑、以及常见报错的排查方法，并说明如何处理推理模式（thinking mode）在第三方网关上的兼容性问题。

DeepSeek Harness 本地模型接入原理

dsh 的模型接入层由插件 dsh-llm-pi-ai 负责，它将"provider（提供商）"抽象为一个独立配置单元，每个 provider 包含：

  • Provider ID：永久标识符，用于请求路由和凭据引用
  • Base URL：推理服务端点地址
  • API protocol：接口协议，三选一——openai-completions、openai-responses、anthropic-messages
  • Credential：API Key 或环境变量引用
  • Models：该 provider 下可用的模型列表

配置生效无需重启服务，修改后下一次请求立即生效。凭据写入 $DSH_HOME/.credentials.yaml，配置写入 $DSH_HOME/profiles/<profile>/cordis.patch.yml（Web UI 启动时 profile 名为 web）。

方案一：Web UI 可视化配置（推荐新手）

启动 dsh

# 从 npm 直接运行（推荐，无需克隆仓库）
npx @deepseek-ai/dsh web
# 默认在 http://127.0.0.1:3080 启动并自动打开浏览器

添加本地模型 Provider

  1. 打开 Settings → Models
  2. 点击页面底部的 Add model provider
  3. 将卡片切换到 Custom model API（默认显示的是 Third-party model provider）
  4. 填写以下字段：
字段 填写内容（以 Ollama 为例）
Provider ID local-ollama（小写字母，永久不可改）
Display name 本地 Ollama
Base URL http://127.0.0.1:11434/v1
API protocol OpenAI Chat Completions
API key 留空（Ollama 本地无需鉴权）
  1. 点击 Fetch available models 让 dsh 自动拉取 Ollama 已安装的模型列表，从弹窗中勾选所需模型，点击 Add selected
  2. 点击 Save，配置立即生效

注意：Provider ID 保存后永久不可更改，因为历史会话日志使用它作为模型标识。如需改名，需新建 provider 并删除旧的。

方案二：cordis.patch.yml 直接编辑（推荐高级用户）

Web UI 写入的内容最终存储在 $DSH_HOME/profiles/web/cordis.patch.yml。直接编辑该文件效率更高，且支持 Web UI 未暴露的高级字段（如 compat、reasoningEfforts、headers）。

Ollama 接入示例

- id: llm-pi-ai
  config:
    providers:
      local-ollama:
        api: openai-completions
        baseURL: http://127.0.0.1:11434/v1
        models:
          - id: qwen3:8b
          - id: deepseek-r1:7b
          - id: llama3.3:70b

vLLM 接入示例

vLLM 默认启动时使用 OpenAI 兼容接口：

# 先启动 vLLM 服务（以 DeepSeek-V4.1-Flash 为例）
vllm serve deepseek-ai/DeepSeek-V4.1-Flash-1017 \
  --port 8000 \
  --api-key your-vllm-key

然后在 cordis.patch.yml 中添加：

- id: llm-pi-ai
  config:
    providers:
      local-vllm:
        api: openai-completions
        baseURL: http://127.0.0.1:8000/v1
        apiKeyEnv: VLLM_API_KEY
        models:
          - id: deepseek-ai/DeepSeek-V4.1-Flash-1017

七牛云 Token Plan 等兼容 OpenAI 格式的第三方网关

对于兼容 OpenAI 格式的统一推理平台，配置方式与自托管完全相同，只需替换 Base URL 和 API Key：

- id: llm-pi-ai
  config:
    providers:
      qiniu-gateway:
        api: openai-completions
        baseURL: https://api.qnaigc.com/v1
        apiKeyEnv: QINIU_API_KEY
        models:
          - id: deepseek-v4.1-flash
          - id: deepseek-v4-pro
          - id: kimi-k3

通过这种方式，七牛云 Token Plan 收录的 50+ 模型（DeepSeek、Kimi、GLM、Qwen 等）均可在 dsh 中统一管理，单 API Key 切换模型只需在会话中重新选择，历史会话的模型记录不受影响。

方案三：处理推理模式兼容性问题

接入第三方网关时最常见的问题是 推理模式（thinking mode）兼容性，dsh 对声明了推理等级的模型会以 role: "developer" 发送系统提示词，并用 max_completion_tokens 字段控制输出上限——这两点大多数非 OpenAI 官方网关都不支持。

修复"每次请求都被拒绝"

在 cordis.patch.yml 的 provider 配置里加入 compat 字段：

- id: llm-pi-ai
  config:
    providers:
      my-gateway:
        api: openai-completions
        baseURL: https://gateway.example/v1
        apiKeyEnv: GATEWAY_API_KEY
        compat:
          supportsDeveloperRole: false   # 改用 system role 发送系统提示词
          maxTokensField: max_tokens     # 改用旧字段名
        models:
          - id: my-model

修复"推理模型关不掉思考"

部分网关的 DeepSeek 模型默认开启推理，off 等级若不发送任何参数则无法关闭。添加 thinkingFormat: deepseek：

        models:
          - id: deepseek-v4-pro
            compat:
              thinkingFormat: deepseek
            reasoningEfforts:
              off:
              high: high
              max: max

thinkingFormat: deepseek 会让 off 等级发送 thinking: {type: disabled}，让其他等级发送 thinking: {type: enabled}，与 DeepSeek 原生接口行为一致。

为手动添加的模型启用 Effort 菜单

手动输入模型 ID 时，dsh 不知道该模型是否支持推理，因此不显示 Effort 菜单。在 cordis.patch.yml 中加入 reasoningEfforts 声明即可：

        models:
          - id: my-reasoner
            reasoningEfforts:
              off:
              high: high
              max: max

常见报错排查

报错 原因 解决方案
MISSING_CREDENTIAL Provider Key 未配置 在 Models 页面填入 Key，或设置对应环境变量
UNKNOWN_MODEL 模型 ID 未在 provider 的 models 列表中 在 Custom model API 中添加该模型 ID
Fetch models 返回 401 API Key 错误 检查 Key，或手动填写模型 ID
网关拒绝所有请求 developer role 或 max_completion_tokens 不兼容 添加 compat.supportsDeveloperRole: false 和 compat.maxTokensField: max_tokens
只有推理模型失败 系统提示词用了 developer role 添加 compat.supportsDeveloperRole: false
off 无法关闭思考 网关 DeepSeek 模型默认开启推理 添加 compat.thinkingFormat: deepseek
Effort 菜单不显示 模型未声明推理等级 在 cordis.patch.yml 中添加 reasoningEfforts

常见问题

Q：Ollama 接入 dsh 时 Fetch available models 一直失败，怎么排查？

Ollama 默认只监听 127.0.0.1:11434，且模型发现走 GET /v1/models 接口。检查三点：① Ollama 已启动且有已安装模型（ollama list 确认）；② Base URL 填写的是 http://127.0.0.1:11434/v1（带 /v1 后缀）；③ 若 dsh 运行在 Docker 容器内需将 127.0.0.1 替换为宿主机 IP 或 host.docker.internal。Fetch 失败不影响手动填写模型 ID，两种方式效果相同。

Q：cordis.patch.yml 是否可以定义多个 provider？

可以。同一个 llm-pi-ai 插件的 config.providers 下可以同时配置多个 provider，每个 provider 有独立的 ID、Base URL 和模型列表。会话发起时在模型选择器中选择对应 provider 下的模型即可，不同 provider 互不干扰。

Q：接入本地模型后，dsh 的 Agent 任务（文件读写、命令执行）是否仍然可用？

完全可用。dsh 的 Agent 能力由工具插件层实现，与模型接入层解耦。只要本地模型支持工具调用（function calling）格式，Agent 的文件读写、终端执行、代码沙箱等能力均正常工作。不支持工具调用的模型只能做普通对话，无法触发 Agent 工具循环。

Q：$DSH_HOME 默认在哪个目录？

macOS / Linux 下默认为 ~/.dsh，Windows 下为 %APPDATA%\dsh。可通过环境变量 DSH_HOME 自定义路径。凭据文件 .credentials.yaml 和所有 profile 配置均在此目录下。

Q：自定义 provider 能否设置请求超时和重试？

可以，但需直接编辑 cordis.patch.yml。在 provider 配置中添加 timeout（毫秒）和 retries（重试次数）字段。Web UI 当前不暴露这两个字段，需手动编辑配置文件，修改后无需重启，下一次请求生效。

结语

DeepSeek Harness 的「Custom model API」将本地模型接入标准化为三个要素：Base URL、协议类型、模型 ID。Ollama 和 vLLM 的接入均在五分钟内可完成，核心障碍往往不在接入本身，而在第三方网关的兼容性细节——developer role 和 max_completion_tokens 这两个字段解决了 80% 的拒绝请求问题。对于需要在 dsh 中统一管理多家厂商模型的团队，通过兼容 OpenAI 格式的聚合网关（如七牛云 Token Plan，支持 50+ 模型、单 API Key 管理）配置为一个 Custom provider，可以在保持 dsh 接入方式不变的前提下随时切换底层模型。

本文数据来源：DeepSeek Harness 官方 GitHub 仓库（deepseek-ai/deepseek-harness）providers 文档，MIT 许可，截至 2026 年 10 月 21 日数据，框架处于 developer preview 阶段，接口可能有不兼容更新，建议关注官方 Changelog。

延伸资源

posted @ 2026-10-21 10:35  vibecoding患者  阅读(22)  评论(0)    收藏  举报