摘要:DeepSeek Harness 可以通过“自定义模型 API”连接 API易 等网关。开发者为每种协议单独配置提供商、填写网关实际支持的模型 ID,并按任务需要另外接入联网搜索工具。
DeepSeek Harness 支持把第三方 API 网关添加为自定义模型提供商,提供 OpenAI Chat Completions、OpenAI Responses、Anthropic Messages、Gemini API 四种协议可选。因此,一个 Harness 实例可以通过 API易 apiyi.com 这类统一网关同时调用多家厂商的模型。接入是否成功取决于四件事:协议与 Base URL 匹配、模型 ID 与网关一致、推理和输出参数兼容、联网工具单独规划。
下文先说明 Harness 的模型适配机制和网关在其中的位置,再按设置界面逐项完成一次自定义提供商配置,并给出 API易 的配置文件模板。随后整理接口能连通但调用失败时最常见的兼容问题与错误码,再区分 DeepSeek 服务端内置搜索和 API易 独立 Search / Fetch 两条联网路线,最后给出多模型 Agent 的分层设计与部署建议。

To Know:DeepSeek Harness 多模型接入术语
| 术语 | 解释 |
|---|---|
| Harness | Agent 的运行框架,负责模型接入、工具调用、上下文、会话和任务执行循环 |
| API Gateway | 统一转发和管理多个模型 API 请求的网关,对外提供一个入口 |
| Base URL | API 请求的基础地址,协议不同,地址的路径前缀也不同 |
| Provider | Harness 中配置的一个模型服务提供商,对应一套地址、协议和密钥 |
| Model ID | 请求中指定模型的标识,必须与网关实际提供的名称一致 |
| Chat Completions | OpenAI 风格的对话补全接口,兼容网关最常用的协议 |
| Responses API | OpenAI 的结构化响应接口,面向工具调用和多轮交互 |
| Anthropic Messages | Anthropic 风格的消息接口,Claude 系列模型的原生协议 |
| Reasoning Effort | 模型思考等级参数,如 off、low、medium、high、max |
| Tool Calling | 模型或 Agent 决定调用外部工具,并把结果用于后续推理 |
| Search / Fetch | Search 负责网页搜索并返回结果列表,Fetch 负责抓取指定网页正文 |
| API Key | 身份认证凭据,决定请求能访问哪些模型和接口 |
1 DeepSeek Harness 为什么适合多模型 API 接入
1.1 DeepSeek Harness 的模型提供商机制
DeepSeek Harness 于 2026 年 8 月 13 日以开发者预览版开源,采用 MIT 协议,核心架构是“Everything is a Plugin”。模型适配器、工具、Skills、存储和会话管理都是可替换的插件,模型接入因此成为一个开放的配置项,而非写死在产品里的厂商绑定。
在模型层,Harness 允许用户添加多个提供商,并在会话中切换模型。每个提供商可配置 API Key、Base URL、模型名称、API 协议、上下文长度、最大输出 Token、图片输入能力和推理等级。中转站、公司内部网关和自建模型服务都可以作为独立的提供商接入。
需要注意的是,Harness 目前仍处于开发者预览阶段,官方提示未来版本可能出现破坏性变更。生产环境使用前,建议固定版本并备份配置。
1.2 API 网关在 DeepSeek Harness 中的角色
在 Harness 看来,一个网关就是一个 Provider。四个字段决定了一次请求的去向:Base URL 指向网关地址,协议决定请求和响应的格式,API Key 证明调用者身份,Model ID 告诉网关要把请求转发给哪个模型。
以 API易 apiyi.com 为例,平台用一个 API Key 提供 OpenAI、Claude、Gemini、DeepSeek 等模型,并开放 OpenAI 兼容、Anthropic 原生和 Gemini 三种协议入口。在 Harness 中只需按协议建立对应的提供商,模型切换就变成了修改 Model ID,不需要为每家厂商单独申请账号和维护密钥。

2 DeepSeek Harness 从零配置自定义模型提供商
2.1 打开 DeepSeek Harness 模型配置界面
本地启动 Harness 最快的方式是官方 npm 命令,需要预先安装 Node.js:
npx @deepseek-ai/dsh web
# 默认打开本地 Web UI:http://127.0.0.1:3080
进入界面后,依次点击 设置 → 模型 → 添加模型提供商 → 自定义模型 API,即可看到提供商配置表单。官方桌面版提供 macOS Apple Silicon 和 Windows 64 位安装包,配置路径相同。
2.2 填写 DeepSeek Harness 提供商信息
| 设置项 | 作用 | 填写要点 |
|---|---|---|
| Provider ID | 提供商唯一标识 | 必须小写,创建后无法重命名,如 apiyi |
| 显示名称 | 模型菜单中显示的名称 | 可写成“API易 OpenAI 兼容” |
| API 协议 | 请求与响应的格式 | 与 Base URL 对应,见 2.3 |
| Base URL | API 服务地址 | 注意版本前缀,见 2.4 |
| API Key | 身份认证凭据 | 存入凭据文件,界面仅显示脱敏预览 |
| Model ID | 实际调用的模型名称 | 与网关模型列表完全一致 |
| Context Window / Max Output Tokens | 上下文与最大输出长度 | 按模型实际规格填写 |
| Input Type | 文本或图片输入 | 仅视觉模型勾选图片 |
| Reasoning Effort | 思考等级与参数映射 | 只添加模型真实支持的档位 |
Provider ID 不能重命名,是因为模型配置、历史会话和凭据引用都会指向这个 ID。需要更换时,先创建新提供商,再删除旧的。
表单中的“获取可用模型”按钮会尝试从网关读取模型列表。若网关不提供标准模型列表,或返回格式不在 Harness 识别范围内,手动添加 Model ID 即可,效果相同。
2.3 选择 DeepSeek Harness 的 API 协议
Harness 自定义模型 API 支持四种协议:OpenAI Chat Completions、OpenAI Responses、Anthropic Messages 和 Gemini API。一个提供商只能绑定一种协议,同一个网关若开放了三种协议入口,就需要建立三个提供商。
协议的选择跟随模型家族。GPT、DeepSeek 以及大多数国产模型走 OpenAI Chat Completions 最稳妥;Claude 系列可选 Anthropic Messages 以保留原生特性;Gemini 系列使用 Gemini API。Responses 协议适合需要结构化响应和工具调用的场景,前提是网关与目标模型都支持该接口。
2.4 使用 API易 配置 DeepSeek Harness 实例
API易 官方给出的协议与 Base URL 对应关系如下:
| 协议 | API易 Base URL | 适用模型 | 可用平台 |
|---|---|---|---|
| OpenAI 兼容(Chat Completions) | https://api.apiyi.com/v1 |
GPT、DeepSeek 等 | API易 apiyi.com、各厂商官方 API |
| Anthropic 原生 | https://api.apiyi.com |
Claude 系列 | API易、Anthropic 官方 |
| Gemini | https://api.apiyi.com/v1beta |
Gemini 系列 | API易、Google 官方 |
Anthropic 协议使用根域名,适配器会自行拼接后续路径。若在根域名后多写了 /v1,就可能出现路径重复,返回 404。Responses 协议的接入方式可参照 API易 Responses API 文档确认后再填写。
除了界面配置,Harness 也支持手工编辑配置文件,位置是 $DSH_HOME/profiles/web/cordis.patch.yml。下面是按官方配置结构编写的 API易 OpenAI 兼容提供商模板:
- id: llm-pi-ai
config:
providers:
apiyi:
apiKeyEnv: APIYI_API_KEY # 从环境变量读取密钥
api: openai-completions # OpenAI Chat Completions 协议
baseURL: https://api.apiyi.com/v1 # API易 OpenAI 兼容入口
models:
- id: MODEL_ID_FROM_APIYI # 替换为账户实际可用的模型 ID
使用步骤如下:
- 设置环境变量
APIYI_API_KEY; - 把
MODEL_ID_FROM_APIYI替换为 API易 控制台中实际可用的模型名称; - 保存配置,在 Harness 模型选择器中选择
apiyi提供商和对应模型; - 发起一次简单对话,确认接口工作正常。
该模板展示的是官方配置结构,模型名称请以自己账户中可调用的列表为准。模型配置变化一般在下一次请求时生效,无需重启 Web UI。界面配置适合日常添加模型和修改密钥,配置文件适合调整兼容参数、推理模式、超时和重试等高级设置。
在接入 Harness 之前,建议先用脚本单独验证 Key 和 Model ID,把“网关可用”和“Harness 配置正确”两个问题拆开排查:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["APIYI_API_KEY"],
base_url="https://api.apiyi.com/v1" # API易 apiyi.com OpenAI 兼容入口
)
resp = client.chat.completions.create(
model="MODEL_ID_FROM_APIYI", # 与 Harness 中填写的 Model ID 保持一致
messages=[{"role": "user", "content": "用一句话介绍你自己"}],
max_tokens=100
)
print(resp.choices[0].message.content)
🚀 快速上手建议:新用户可以在 API易 apiyi.com 注册后领取免费测试额度,先用上面的脚本确认模型 ID 可用,再写入 Harness 配置,整体排错时间会短很多。
3 DeepSeek Harness 接口能连接,模型为何仍会调用失败
Harness 官方文档明确指出:API 地址和密钥都正确时,网关仍可能拒绝请求。原因在于不同兼容接口对消息角色、输出长度和思考参数的要求不同。以下三个 compat 参数用于解决这类问题,应根据接口实际返回的错误按需启用。
3.1 Developer 角色兼容
新版 OpenAI 规范引入了 role: developer,部分兼容网关只认 system。如果出现“所有请求都失败”或“只有推理模型失败”的情况,可以关闭 developer 角色:
compat:
supportsDeveloperRole: false
开启该选项后,适配器会调整请求中的角色处理方式,使请求符合网关可接受的格式。
3.2 最大输出参数兼容
OpenAI 新接口使用 max_completion_tokens 表示最大输出,而部分网关只接受传统的 max_tokens。两者含义相同,字段名不一致就会导致参数校验失败。对应设置为:
compat:
maxTokensField: max_tokens
3.3 DeepSeek 思考模式兼容
部分 DeepSeek 模型默认开启思考。在 Harness 中把推理等级设为 off 时,部分兼容协议只会省略推理参数,模型便按默认行为继续思考,造成“off 关不掉”。官方为此提供 DeepSeek 专用的思考格式:
compat:
thinkingFormat: deepseek
启用后,关闭思考时适配器会显式发送 {"thinking": {"type": "disabled"}},开启时发送 {"thinking": {"type": "enabled"}}。官方示例针对的是 OpenAI 兼容网关后的 DeepSeek V4 模型。多模型网关中可以只为 DeepSeek 模型单独设置该参数,GPT、Claude 等模型保持默认。
推理等级方面,Harness 允许把界面上的 off、low、medium、high、max 映射为 API 实际接受的参数值。只把模型真实支持的档位加入配置,可以避免用户选中无效档位后请求报错。三个兼容参数合并后的完整示例如下:
- id: llm-pi-ai
config:
providers:
apiyi:
apiKeyEnv: APIYI_API_KEY
api: openai-completions
baseURL: https://api.apiyi.com/v1
compat:
supportsDeveloperRole: false
maxTokensField: max_tokens
models:
- id: MODEL_ID_FROM_APIYI
3.4 DeepSeek Harness 常见错误快速排查
| 错误或现象 | 可能原因 | 处理方式 |
|---|---|---|
| MISSING_CREDENTIAL | 密钥未配置 | 检查 API Key 与环境变量名 |
| UNKNOWN_MODEL | 模型 ID 未登记 | 在提供商下添加正确的模型 ID |
| HTTP 401 | 密钥无效或权限不足 | 核对密钥内容及所属分组 |
| HTTP 404 | Base URL 路径错误 | 核对协议与版本前缀(/v1、根域名、/v1beta) |
| 模型列表为空 | 网关不支持标准模型列表接口 | 手动添加模型 ID |
| 所有请求均失败 | 角色或参数格式冲突 | 检查 compat 兼容参数 |
| 只有推理模型失败 | Developer 角色不兼容 | 设置 supportsDeveloperRole: false |
| off 无法关闭思考 | 模型默认启用思考 | 设置 thinkingFormat: deepseek |
| 搜索接口返回 503 | 令牌分组无工具权限 | 更换 default 或 svip 分组令牌 |
| 对话正常、联网不可用 | 搜索工具未集成或协议不支持 | 检查工具能力和客户端配置 |
前八项依据 Harness 官方配置文档,分组相关问题来自 API易 官方文档。排查顺序建议从上往下:先确认凭据,再确认模型 ID,然后是路径,最后才是参数兼容。
4 给 DeepSeek Harness 增加联网搜索能力
4.1 区分模型内置搜索与独立搜索 API
普通对话调用成功,只能证明 API Key 可用、模型 ID 正确、对话协议基本兼容。联网能力还需要模型支持对应工具、请求正确声明工具、API 服务支持该工具协议、Harness 能处理工具响应,或者由开发者在应用侧单独集成搜索。因此,聊天成功与联网成功属于两个独立的验证步骤。
DeepSeek 体系下的联网能力有两条技术路线:

| 维度 | 路线 A:模型内置服务端工具 | 路线 B:独立 Search / Fetch API |
|---|---|---|
| 调用方式 | 对话请求中声明 deepseek_web_search、deepseek_read_url |
程序主动请求 /v1/tools/search、/v1/tools/fetch |
| 谁决定搜索 | 模型自主判断 | 开发者或 Agent 工具逻辑 |
| 工具执行 | DeepSeek 服务端完成搜索与上下文拼接 | 客户端拿到结果后自行处理 |
| 模型范围 | 官方公告明确针对 deepseek-flash |
与模型无关,任意模型可复用结果 |
| 计费口径 | 按实际搜索词条数、抓取网页数等计费 | 按成功请求次数计费,不消耗模型 Token |
| 当前可用渠道 | DeepSeek 官方 API | DeepSeek 官方 API、API易 |
4.2 模型内置搜索的工作方式
2026 年 11 月 13 日,DeepSeek 开放了 App 背后的多项应用能力,其中联网搜索和阅读链接以服务端工具的形式提供。在请求的工具列表中声明即可:
[
{"type": "deepseek_web_search", "name": "deepseek_web_search"},
{"type": "deepseek_read_url", "name": "deepseek_read_url"}
]
声明后,模型会自行判断是否需要联网、生成搜索词,由 DeepSeek 服务端执行搜索并返回带来源引用的回答。开启思考模式后,搜索升级为多步骤流程,模型可以搜索多个关键词、打开网页、页内查找并交叉核实,官方文档显示最多约 20 次工具调用后作答。deepseek_read_url 只识别最后一条用户消息中的 URL,最多考虑 10 个不同链接。
开发者仍需处理返回的内容块、引用信息、流式事件和多轮历史。根据官方公告,这套完整的对话级工具集成由 deepseek-flash(DeepSeek-V4.1-Flash)承载。据 API易 文档说明,通过 Harness、Claude Code 等客户端经网关调用这类内置搜索的兼容工作仍在后续规划中,目前要使用路线 A,应直接连接 DeepSeek 官方 API。
4.3 API易 独立 Search / Fetch 接入
API易 于 2026 年 10 月 21 日上线了 DeepSeek Search & Fetch 独立工具接口,对应 deepseek-search 与 deepseek-fetch。Search 返回结构化搜索结果,Fetch 抓取指定网页并返回 Markdown 正文。请求无需传入模型 ID,也不消耗模型 Token,按成功调用次数计费。
以下示例先搜索,再抓取排名第一的网页:
import os
import requests
BASE = "https://api.apiyi.com/v1/tools" # API易 独立工具接口
headers = {"Authorization": f"Bearer {os.environ['APIYI_API_KEY']}"}
search = requests.post(
f"{BASE}/search",
headers=headers,
json={"query": "DeepSeek Harness 插件", "count": 5},
timeout=60,
)
search.raise_for_status()
results = search.json()["results"]
if results:
url = results[0]["url"]
fetch = requests.post(
f"{BASE}/fetch",
headers=headers,
json={"url": url},
timeout=60,
)
if fetch.ok:
print(fetch.json()["content"])
令牌分组需要特别注意:default 和 svip 分组可以调用这两个接口,ClaudeCode 分组令牌无法直接调用,文档记录过返回 503 的情况。API易 文档中的自测显示,Search 返回 5 条结果约 1.8 秒,20 个并发请求全部返回 200;Fetch 访问不可达页面时返回失败且不扣费。这些数据来自平台自身测试,实际表现受网络与目标站点影响。价格方面,文档列出站内价为每 1000 次 $0.90,叠加充值加赠后实付更低,具体以控制台为准。
要让 Harness 中的 Agent 自主使用这段逻辑,需要把它封装为工具插件。Harness 插件以 TypeScript 编写,通过上下文对象 ctx 注册工具,插件卸载时框架会自动清理注册的工具和事件。封装时建议把 search 和 fetch 注册为两个独立工具,让模型先拿到结果列表,再决定抓取哪几个页面。
💡 技术建议:独立 Search / Fetch 与模型解耦,同一份检索结果可以交给 GPT、Claude、DeepSeek 等不同模型处理。通过 API易 apiyi.com 用一个 Key 同时管理模型调用和搜索工具,便于在 Harness 中对比不同模型基于相同资料的回答质量。
5 DeepSeek Harness 多模型 Agent 应该如何设计
5.1 根据任务选择不同模型
多模型接入的价值在于按任务分配模型。编程 Agent 可以选用擅长代码的模型,文档整理、摘要改写这类高频任务适合成本较低的模型,截图分析和图表理解则必须选择支持图片输入的视觉模型,并在 Input Type 中勾选图片。
以 DeepSeek 官方模型为例,DeepSeek-V4.1-Flash 支持图像理解,DeepSeek-V4-Pro 不支持,两者价格也相差数倍。在 Harness 中把它们配成同一提供商下的两个 Model ID,按任务在会话中切换,就能兼顾效果和成本。
5.2 将 DeepSeek Harness 模型调用与搜索能力分层管理

推荐的结构分为三层。执行层由 Harness 负责任务循环、上下文压缩、插件加载和权限控制;模型层由 API 网关负责协议转换、模型路由和计费;工具层由独立的 Search / Fetch 等接口提供外部信息。三层各自可替换:更换模型只改 Model ID,更换搜索服务只改工具插件,执行逻辑保持不变。
分层还带来安全上的好处。腾讯朱雀实验室针对 Harness 的受控评估显示,网页、文件、Skills 等不可信内容可能通过间接提示词注入影响 Agent 行为。工具层与执行层分开后,可以在搜索结果进入上下文、敏感工具执行之前加入统一的过滤与确认环节。
5.3 DeepSeek Harness 实际部署建议
- 模型配置:一种协议对应一个提供商,Provider ID 用小写且一次定好;模型 ID 一律从网关控制台复制。
- 密钥管理:Harness 把密钥存放在
$DSH_HOME/.credentials.yaml,配置文件只引用环境变量,避免明文 Key 进入共享配置或代码仓库。 - 兼容性测试:每接入一个新模型,依次验证普通对话、关闭思考、长输出和图片输入,再按报错启用
compat参数。 - 工具调用:控制插件数量。社区反馈显示,安装十几个以上插件后可能出现上下文溢出和 Token 消耗上升,搜索工具保持精简描述更稳定。
- 成本记录:模型 Token 与工具调用分别计费,建议在网关后台分别统计。API易 apiyi.com 控制台可以按 Key 查看用量,适合为不同 Agent 分配独立 Key 做成本归属。
此外,升级 Harness 前先备份 $DSH_HOME 下的配置。社区曾记录过一次版本升级后第三方插件配置丢失、恢复耗时数小时的案例。
常见问题 FAQ
Q1:DeepSeek Harness 只能使用 DeepSeek 模型吗?
Harness 支持通过自定义模型 API 接入任意兼容四种协议之一的服务,包括 OpenAI、Claude、Gemini 系列以及各类 API 网关和自建模型服务。DeepSeek 官方模型只是其中一个选项。
Q2:同一个网关为什么要建多个提供商?
Harness 规定一个提供商只绑定一种协议。API易 同时开放 OpenAI 兼容、Anthropic 和 Gemini 三种入口,若要分别以原生协议调用 GPT、Claude 和 Gemini,就需要建三个提供商,Base URL 分别为 `/v1`、根域名和 `/v1beta`。
Q3:如何确认自己该填写哪个模型 ID?
先试用“获取可用模型”功能;读取不到时,在 API易 apiyi.com 控制台的模型列表中复制准确名称手动添加。模型 ID 区分大小写和版本后缀,任何差异都会触发 UNKNOWN_MODEL 或网关报错。
Q4:通过 API易 接入后,能直接使用 deepseek_web_search 吗?
目前 API易 已支持 DeepSeek 独立 Search / Fetch 接口,经 Harness 等客户端调用模型内置搜索的兼容工作仍在规划中。现阶段推荐用 API易 的 `/v1/tools/search` 与 `/v1/tools/fetch` 封装为 Agent 工具;需要内置搜索时直接连接 DeepSeek 官方 API。
Q5:搜索接口返回 503,但对话完全正常,原因是什么?
最常见的原因是令牌分组。ClaudeCode 分组令牌无法直接调用独立工具接口,换用 default 或 svip 分组的 Key 即可。可以在 API易 apiyi.com 后台为搜索工具单独创建一个对应分组的令牌,与模型调用的 Key 分开管理。
Q6:DeepSeek Harness 多模型接入有哪些限制?
Harness 仍是开发者预览版,配置结构可能随版本变化;各家网关对 Responses、推理参数和工具协议的透传程度不同,需要逐个模型验证。插件过多会推高上下文与 Token 成本,复杂任务的交付质量也取决于插件配置和执行过程管理。
总结
DeepSeek Harness 的开放模型适配机制,让一个 Agent 框架可以通过统一网关调用多家厂商的模型。落地时把握以下几点:
- 协议定提供商:一种协议建一个 Provider,Base URL 的版本前缀与协议严格对应;
- 模型 ID 照抄网关:从控制台复制,读不到列表就手动添加;
- 兼容参数按错启用:developer 角色、
max_tokens字段和 DeepSeek 思考格式三项覆盖了大多数“能连不能用”的问题; - 联网能力单独规划:内置搜索走 DeepSeek 官方 API,独立 Search / Fetch 可经网关调用并封装为工具;
- 分层与治理:执行层、模型层、工具层分开,密钥、版本和成本分别管理。
建议先用一个模型跑通“脚本验证 → Harness 配置 → 简单对话”,再逐步加入更多模型和搜索工具。推荐通过 API易 apiyi.com 领取免费测试额度,用一个 Key 完成多模型与 Search / Fetch 的整体验证。
📚 参考资料
- DeepSeek Harness 配置模型文档:自定义提供商字段与 compat 兼容参数
- 链接:
deepseek-harness.github.io/deepseek-harness/guide/providers -
说明: supportsDeveloperRole、maxTokensField、thinkingFormat 的官方说明
-
DeepSeek Harness GitHub 仓库:源码、Releases 与启动方式
- 链接:
github.com/deepseek-ai/deepseek-harness -
说明: 版本更新与开发者预览阶段说明
-
DeepSeek 联网工具文档:deepseek_web_search 与 deepseek_read_url
- 链接:
api-docs.deepseek.com/zh-cn/guides/web_tools/ -
说明: 内置搜索的声明方式、限制与计费口径
-
API易 Base URL 配置指南:三种协议路径说明
- 链接:
help.apiyi.com/apiyi-base-url-v1-claude-gemini-endpoint-config-guide.html -
说明:
/v1、根域名、/v1beta的使用场景 -
API易 DeepSeek Search & Fetch 文档:独立工具接口与分组要求
- 链接:
docs.apiyi.com/api-capabilities/deepseek-search-fetch/overview - 说明: 请求参数、令牌分组与计费说明
作者: APIYI 技术团队
技术交流: 配置过程中遇到问题,欢迎通过 API易 apiyi.com 首页联系我们,更多接口说明可查阅 docs.apiyi.com 文档中心
