模型提供方、适配器与模型选择

举报
yd_229544978 发表于 2026/11/13 01:11:20 2026/11/13
【摘要】 DeepSeek Harness 20 天实战(08):模型提供方、适配器与模型选择本文是「DeepSeek Harness 20 天实战」的第 8 篇。上一篇介绍了启动配置的组合方式;这一次,我们看看 Agent 如何通过模型适配层连接不同的模型服务。本文基于截至 2026 年 11 月的公开资料。DeepSeek Harness 仍处于开发者预览阶段,界面、配置和接口可能随版本变化。同...

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,可以把一次常见请求简化为:

  1. 根据会话当前选择,确定 Provider 和 Model。
  2. 准备消息历史、工具说明和本次请求参数。
  3. 通过模型运行时选择负责该 Provider 路由的适配器。
  4. 适配器调用对应的模型服务,并转换流式响应。
  5. 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 的持久化与恢复,看看事件日志如何支持会话历史和继续执行。

参考资料

  1. DeepSeek Harness Configure Models 文档
  2. DeepSeek Harness LLM Adapters 开发文档
  3. DeepSeek Harness LLM Streaming 子系统文档
  4. DeepSeek Harness Adding an LLM Adapter 文档
  5. DeepSeek Harness LLM 包说明
【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。