模型提供方、适配器与模型选择
DeepSeek Harness 20 天实战(08):模型提供方、适配器与模型选择
本文是「DeepSeek Harness 20 天实战」的第 8 篇。上一篇介绍了启动配置的组合方式;这一次,我们看看 Agent 如何通过模型适配层连接不同的模型服务。
本文基于截至 2026 年 11 月的公开资料。DeepSeek Harness 仍处于开发者预览阶段,界面、配置和接口可能随版本变化。
同一个 Agent,为什么更换模型服务后,有时能正常回答,却不能调用工具?为什么填好了 API Key,仍然可能出现请求失败?
要回答这些问题,需要区分模型提供方、模型和适配器。它们共同决定一次模型请求会被发送到哪里、使用什么协议,以及结果如何返回。
一、先区分 Provider、Model 和 Adapter
| 概念 | 作用 |
|---|---|
| Provider | 标识一条模型服务路由及其相关配置 |
| Model | 标识该路由下要使用的具体模型 |
| Adapter | 在 Harness 内部协议与提供方接口之间转换请求和响应 |
例如,一个团队可以配置一条名为 team-gateway 的自定义路由,并在其中添加某个实际可用的模型 ID。这里的路由名和模型 ID 分别回答两个问题:请求走哪条路,调用哪个模型。
team-gateway 只是用于说明的示例名称,并不是 DeepSeek Harness 内置的提供方。
适配器则负责处理协议细节。Agent Loop 使用 Harness 的模型接口发起请求,适配器再把消息、工具说明等转换为目标服务可接受的形式,并把返回结果转换回 Harness 使用的格式。
二、一次模型请求会经过什么?
结合前面介绍的 Agent Loop,可以把一次常见请求简化为:
- 根据会话当前选择,确定 Provider 和 Model。
- 准备消息历史、工具说明和本次请求参数。
- 通过模型运行时选择负责该 Provider 路由的适配器。
- 适配器调用对应的模型服务,并转换流式响应。
- Harness 接收文本、工具调用或错误等结果,继续当前任务。
这是帮助理解的简化流程。实际流程还包括模型能力解析、请求准备、取消处理和插件扩展点;具体可用能力取决于所选路由和模型。
在代码层面,ctx.llm 是 Harness 的模型服务。适配器可以通过 ctx.llm.registerAdapter() 注册一个或多个 Provider 路由;请求中的 provider 用于选择路由,model 则交给相应适配器解释。
同一个 Provider 路由不能被重复注册到不同适配器;遇到重复注册错误时,应先检查当前 Profile 和补丁是否重复加载了提供相同路由的插件。
三、内置适配器与自定义路由
DeepSeek Harness 的源码中有不同适配器实现。例如:
dsh-llm-deepseek:对接 DeepSeek 相关路由的适配器实现。dsh-llm-pi-ai:通过通用模型库支持多种提供方和自定义路由。
使用时,并不总需要自己编写适配器。对于受支持的提供方或兼容接口,可以先通过 Web 界面配置模型服务;只有现有适配器不能满足需求时,才需要进一步研究扩展实现。
需要注意,“接口兼容”不等于所有功能都一致。不同服务对工具调用、图像输入、推理参数、输出上限和错误格式的支持可能不同。
因此,模型能返回一句文本,并不能单独证明它在当前路由下也支持 Agent 所需的工具调用。
四、模型适配器要处理哪些事情?
一个适配器不仅负责发送 HTTP 请求,还要处理输入和输出之间的对应关系。
| 环节 | 需要处理的问题 |
|---|---|
| 请求转换 | 消息、工具 Schema 和生成参数如何映射到提供方协议? |
| 能力解析 | 当前模型是否声明了上下文容量、输入类型或推理等级? |
| 流式输出 | 文本片段、工具调用片段和结束原因如何转换? |
| 取消与错误 | 请求取消、接口错误和协议错误如何传递? |
| 凭据管理 | 凭据从哪里获取,如何避免写入日志或源码? |
一个适配器请求通常代表一次提供方调用尝试。需要重试时,还应结合当前组合中的重试能力和策略,而不是假设所有失败都会自动重试。
五、流式响应不只有文本
模型服务可能以流的形式逐步返回内容。在 Harness 的流式协议中,常见信息包括:
- 内容块开始与结束,例如
block-start和block-end。 - 文本增量,例如
text-delta。 - 工具调用增量,例如
tool-call-delta。 - 可用时返回的用量信息,以及表示结束原因的
finish。
如果输出中有工具调用,工具名称、调用标识和参数片段需要被正确组装;只把所有增量拼成一段普通文本,可能丢失工具调用的结构。
开发适配器时,还需要遵守协议边界。例如,内容块应正确配对;如果发送用量信息,它应出现在 finish 之前,finish 之后不再发送新的片段。
六、实践:在 Web 界面配置并验证模型
下面以已有的 Web 运行环境为例,检查一条模型路由是否可用。
1. 打开模型设置
启动 Web 界面,进入 Settings → Models。
如果使用 DeepSeek 路由,在对应设置中输入并保存 API Key。如果需要接入其他受支持的提供方,可以选择添加模型提供方;接入自定义网关时,需要按界面要求填写路由标识、接口地址、协议、凭据和模型 ID。
自定义路由的协议必须与实际网关支持的协议一致。不要把 API Key 写进博客、源码示例或共享日志。
2. 创建新会话并选择模型
在模型选择器中选择已配置的模型,然后创建一个新的测试会话。
选择模型会影响新会话的默认选择;已经发出过请求的会话会保留其日志中记录的模型选择,不应假设修改默认值会自动迁移所有旧会话。
3. 先做一个简单文本测试
发送一个范围明确的问题:
先不要调用工具:用一句话解释连接超时与读取超时的区别。
如果得到正常回答,说明这一次文本请求已经走通。它并不证明工具调用、图像输入或更长上下文也已经验证通过。
4. 再单独测试工具调用
如果当前 Profile 已加载第 4 篇的 count_codepoints 工具,可以继续测试:
请调用 count_codepoints 工具,统计下面文本的 Unicode 码点数:
Agent 工具
观察执行轨迹,确认模型确实发起了工具调用,参数是否正确,以及工具结果是否返回。模型只在回答中写出数字,并不能证明工具调用链已经跑通。
若工具没有暴露给当前 Agent,先检查插件加载与工具限制;如果工具可见但调用仍失败,再检查模型、网关和协议对工具调用的支持。
七、模型配置常见问题
1. 提示缺少凭据
检查对应 Provider 是否保存了有效凭据,或是否正确配置了该路由使用的环境变量。不要通过复制完整请求日志来排查密钥。
2. 提示模型不存在
核对选择的 Provider 和模型 ID 是否匹配;使用自定义网关时,还要确认网关实际提供该模型。模型列表可以帮助选择,但具体可调用能力仍由适配器和服务端决定。
3. 文本正常,工具调用失败
分别检查工具是否对当前 Agent 可见、网关协议是否支持工具调用,以及模型返回的工具参数是否符合要求。
4. 修改默认模型后,旧会话没有变化
先检查该会话当前记录的模型选择。新会话的默认模型和已有会话的选择是两个需要分别确认的状态。
5. 图像或推理参数被拒绝
确认模型和网关实际支持相关能力,再检查路由中的输入类型或推理等级配置。配置中声称支持某种能力,并不会让不支持该能力的服务自动具备它。
八、这一篇需要记住什么?
Provider 决定请求使用哪条服务路由,Model 指定路由中的模型,Adapter 负责连接 Harness 与提供方协议。
排查模型问题时,先分清是凭据、模型 ID、协议、能力声明,还是流式结果与工具调用的问题;不要把“接口能返回文本”直接当成整条 Agent 链路已经验证通过。
**下一篇预告:**我们将深入 Session 的持久化与恢复,看看事件日志如何支持会话历史和继续执行。
参考资料
- DeepSeek Harness Configure Models 文档
- DeepSeek Harness LLM Adapters 开发文档
- DeepSeek Harness LLM Streaming 子系统文档
- DeepSeek Harness Adding an LLM Adapter 文档
- DeepSeek Harness LLM 包说明
- 点赞
- 收藏
- 关注作者
评论(0)