输入关键词搜索

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

  1. DeepSeek Harness 依赖 Node.js 运行环境,安装前请确认已安装 Node.js 18 或更高版本:

    bashnode --version
    
  2. 启动 Web UI(首次运行会自动拉取工具包):

    bashnpx @deepseek-ai/dsh web
    
  3. 启动成功后,默认访问地址为 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。两种方式等价。

  1. 在 ~/.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
    
  2. 在终端中导出访问令牌,然后重启 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。

验证配置

  1. 验证 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"}]
      }'
    
  2. 在 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 控制台查看请求日志中的上游错误码与错误信息,据此判断是鉴权、模型授权还是路由问题。
此文档是否对你有帮助?
有帮助
去反馈
  • 安装 DeepSeek Harness
  • 配置接入凭证
  • 验证配置
  • 常见问题