DeepSeek Harness 如何接入多模型 API?API易 等网关的 4 种协议配置与使用逻辑

DeepSeek Harness 如何接入多模型 API?API易 等网关的 4 种协议配置与使用逻辑

摘要: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 的分层设计与部署建议。

deepseek-harness-multi-model-api-gateway-config-image-0

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,不需要为每家厂商单独申请账号和维护密钥。

deepseek-harness-multi-model-api-gateway-config-image-1


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

使用步骤如下:

  1. 设置环境变量 APIYI_API_KEY;
  2. 把 MODEL_ID_FROM_APIYI 替换为 API易 控制台中实际可用的模型名称;
  3. 保存配置,在 Harness 模型选择器中选择 apiyi 提供商和对应模型;
  4. 发起一次简单对话,确认接口工作正常。

该模板展示的是官方配置结构,模型名称请以自己账户中可调用的列表为准。模型配置变化一般在下一次请求时生效,无需重启 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 体系下的联网能力有两条技术路线:

deepseek-harness-multi-model-api-gateway-config-image-2

维度 路线 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 模型调用与搜索能力分层管理

deepseek-harness-multi-model-api-gateway-config-image-3

推荐的结构分为三层。执行层由 Harness 负责任务循环、上下文压缩、插件加载和权限控制;模型层由 API 网关负责协议转换、模型路由和计费;工具层由独立的 Search / Fetch 等接口提供外部信息。三层各自可替换:更换模型只改 Model ID,更换搜索服务只改工具插件,执行逻辑保持不变。

分层还带来安全上的好处。腾讯朱雀实验室针对 Harness 的受控评估显示,网页、文件、Skills 等不可信内容可能通过间接提示词注入影响 Agent 行为。工具层与执行层分开后,可以在搜索结果进入上下文、敏感工具执行之前加入统一的过滤与确认环节。

5.3 DeepSeek Harness 实际部署建议

  1. 模型配置:一种协议对应一个提供商,Provider ID 用小写且一次定好;模型 ID 一律从网关控制台复制。
  2. 密钥管理:Harness 把密钥存放在 $DSH_HOME/.credentials.yaml,配置文件只引用环境变量,避免明文 Key 进入共享配置或代码仓库。
  3. 兼容性测试:每接入一个新模型,依次验证普通对话、关闭思考、长输出和图片输入,再按报错启用 compat 参数。
  4. 工具调用:控制插件数量。社区反馈显示,安装十几个以上插件后可能出现上下文溢出和 Token 消耗上升,搜索工具保持精简描述更稳定。
  5. 成本记录:模型 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 框架可以通过统一网关调用多家厂商的模型。落地时把握以下几点:

  1. 协议定提供商:一种协议建一个 Provider,Base URL 的版本前缀与协议严格对应;
  2. 模型 ID 照抄网关:从控制台复制,读不到列表就手动添加;
  3. 兼容参数按错启用:developer 角色、max_tokens 字段和 DeepSeek 思考格式三项覆盖了大多数“能连不能用”的问题;
  4. 联网能力单独规划:内置搜索走 DeepSeek 官方 API,独立 Search / Fetch 可经网关调用并封装为工具;
  5. 分层与治理:执行层、模型层、工具层分开,密钥、版本和成本分别管理。

建议先用一个模型跑通“脚本验证 → Harness 配置 → 简单对话”,再逐步加入更多模型和搜索工具。推荐通过 API易 apiyi.com 领取免费测试额度,用一个 Key 完成多模型与 Search / Fetch 的整体验证。


📚 参考资料

  1. DeepSeek Harness 配置模型文档:自定义提供商字段与 compat 兼容参数
  2. 链接: deepseek-harness.github.io/deepseek-harness/guide/providers
  3. 说明: supportsDeveloperRole、maxTokensField、thinkingFormat 的官方说明

  4. DeepSeek Harness GitHub 仓库:源码、Releases 与启动方式

  5. 链接: github.com/deepseek-ai/deepseek-harness
  6. 说明: 版本更新与开发者预览阶段说明

  7. DeepSeek 联网工具文档:deepseek_web_search 与 deepseek_read_url

  8. 链接: api-docs.deepseek.com/zh-cn/guides/web_tools/
  9. 说明: 内置搜索的声明方式、限制与计费口径

  10. API易 Base URL 配置指南:三种协议路径说明

  11. 链接: help.apiyi.com/apiyi-base-url-v1-claude-gemini-endpoint-config-guide.html
  12. 说明: /v1、根域名、/v1beta 的使用场景

  13. API易 DeepSeek Search & Fetch 文档:独立工具接口与分组要求

  14. 链接: docs.apiyi.com/api-capabilities/deepseek-search-fetch/overview
  15. 说明: 请求参数、令牌分组与计费说明

作者: APIYI 技术团队
技术交流: 配置过程中遇到问题,欢迎通过 API易 apiyi.com 首页联系我们,更多接口说明可查阅 docs.apiyi.com 文档中心

延伸阅读

类似文章