DeepSeek Harness 接入
更新时间: 2026/11/12 17:34:30
DeepSeek Harness(命令行工具 dsh)是 DeepSeek 开源的 AI Agent 框架,提供 Web UI 和命令行两种模式。接入云信大模型 API 平台(简称 AIHub)时,可通过自定义 provider 将 Base URL 指向 AIHub 的 OpenAI Chat Completions 兼容入口。
安装 DeepSeek Harness
-
DeepSeek Harness 依赖 Node.js 运行环境,安装前请确认已安装 Node.js 18 或更高版本:
bash
node --version -
启动 Web UI(首次运行会自动拉取工具包):
bash
npx @deepseek-ai/dsh web -
启动成功后,默认访问地址为
http://127.0.0.1:3080。本文以 Web UI 模式为例配置。DeepSeek Harness 通过
~/.dsh/settings.yaml保存模型配置,首次配置前请确认~/.dsh/目录已生成;也可以先在 Web UI 中完成一次初始化,再编辑配置文件。
配置接入凭证
可以在 Web UI 的 Settings → Models → Add a custom provider 中填写,也可以直接编辑 ~/.dsh/settings.yaml。两种方式等价。
-
在
~/.dsh/settings.yaml中增加 AIHub provider,并将默认模型指向它:yamlagent-default-model: provider: aihub model: your-logical-model llm-pi-ai: providers: aihub: api: openai-completions baseURL: https://ai.yunxinapi.com/hub/v1 apiKeyEnv: AIHUB_TOKEN models: - id: your-logical-model -
在终端中导出访问令牌,然后重启 DeepSeek Harness,使进程读取到该环境变量:
bashexport AIHUB_TOKEN="sk-..."
配置项说明:
| 配置项 | 说明 |
|---|---|
agent-default-model.provider |
默认使用的 provider 名称,需与 llm-pi-ai.providers 下的 key 一致 |
agent-default-model.model |
AIHub 逻辑模型名称 |
api |
固定为 openai-completions,即 OpenAI Chat Completions 兼容协议 |
baseURL |
AIHub 根地址 + /v1,例如 https://ai.yunxinapi.com/hub/v1 |
apiKeyEnv |
令牌来源的环境变量名,填写 AIHUB_TOKEN(AIHub 访问令牌);也可在 Web UI 中直接填写 API Key |
models[].id |
需要在模型选择器中出现的 AIHub 逻辑模型名称 |
- 如需配置多个模型,在
models下继续追加- id:条目即可。 - 如果
apiKeyEnv指向的环境变量未生效,可在 Web UI 的 Settings → Models 中直接填写 API Key。
验证配置
-
验证 AIHub Chat Completions 端点(
$AIHUB_BASE_URL、$AIHUB_TOKEN、$AIHUB_MODEL分别为 AIHub 根地址、访问令牌和逻辑模型名)。bashcurl "$AIHUB_BASE_URL/v1/chat/completions" \ -H "Authorization: Bearer $AIHUB_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model": "'"$AIHUB_MODEL"'", "messages": [{"role": "user", "content": "只回复 OK"}] }' -
在 Web UI 的模型选择器中选择刚配置的模型,发送一条最小对话。
如果模型正常返回内容,说明配置已生效。
常见问题
| 现象 | 排查方向 |
|---|---|
报错 MISSING_CREDENTIAL |
AIHUB_TOKEN 未导出,或导出后未重启 DeepSeek Harness;也可在 Settings → Models 中直接填写并保存 API Key。 |
| 配置后仍使用默认 provider | agent-default-model.provider 与 llm-pi-ai.providers 下的 provider 名称不一致。 |
401/unauthorized |
API Key 未正确填写 AIHub 访问令牌,或令牌已禁用。 |
404 |
baseURL 缺少 /hub/v1,或误写成了完整的 /chat/completions 地址。 |
| 找不到模型 | models[].id 与 AIHub 逻辑模型名不一致;可调用 /v1/models 获取当前令牌可见的模型列表。 |
| Web UI 中获取模型列表失败 | 先用 GET $AIHUB_BASE_URL/v1/models 确认令牌与模型授权,再核对 baseURL;若仍失败,直接在 Model catalog 中手动输入 AIHub 逻辑模型 ID。 |
model not allowed/no candidate |
当前访问令牌未授权该模型,或模型无可用路由。 |
| 协议不匹配报错 | api 字段必须为 openai-completions;如需 Responses 或 Anthropic Messages 协议,请改用支持对应协议的工具接入。 |
| 其他报错 | 在 AIHub 控制台查看请求日志中的上游错误码与错误信息,据此判断是鉴权、模型授权还是路由问题。 |




