DeepSeek Harness 照 Cookbook 加 LLM 适配器:流式、错误分类与重试
LLM 适配器最容易写成「一个能发 HTTP 请求的函数」,但 Cookbook 要的是一段能接进 DeepSeek Harness 流式与错误体系的实现。 适配器的职责不是「调通一次」,而是把提供商的响应翻译成统一的流式帧,把失败分成可重试与不可重试,并让配置与凭据从外部注入(来源)。
DeepSeek Harness 适配器 seam:先定边界
适配器是一个 seam,不是业务插件:它只负责协议翻译,不负责决定用哪个模型、用哪把凭据。 在 DeepSeek Harness 里,模型选择、路由、凭据都由上层配置决定;适配器拿到的是已经准备好的调用,产出的是统一流。(来源)
这条边界划清后,三件事就不该写进适配器:
- 不写死模型名 — 模型由配置传入,适配器只按传入值发请求;
- 不写死端点 — 基础 URL、协议由 provider 配置决定;
- 不写死重试策略 — 适配器分类错误,重试由请求层或调用方决定。
把这三件事写死,短期能跑,长期会在换模型、换网关、调重试时全部返工。Cookbook 的示例之所以把这些放在配置里,就是为了让适配器保持可替换。
适配器的注册走 ctx.llm,它向共享上下文贡献一个能力,而不是启动一个独立服务。注册后,上层按模型选择找到适配器,再发起请求。
DeepSeek Harness 流式词汇:start、chunk、end
流式不是「一次性返回完整字符串」,而是按帧推进。 官方把流式响应拆成 start、chunk、end 三类帧(来源)。
适配器要做的是:
- start — 确认请求已建立,准备接收增量;
- chunk — 把提供商返回的增量翻译成统一 chunk,按到达顺序发出;
- end — 结束本次流,交出一个完整消息或失败尝试。
三个常见错误:
- 把 chunk 攒到最后一次发 — 看起来结果对,但流式体验没了,取消也不及时;
- 在 end 之前发完整消息 — 上层会收到重复内容;
- 断流时不发 end — 上层无法区分「还在等」和「已经失败」。
流式帧的顺序比内容更容易出错。写适配器时,先把帧的顺序跑通,再调内容翻译;顺序对了,断流与取消才有明确的落点。
DeepSeek Harness 错误分类:可重试与不可重试
错误分类是适配器最重要的输出之一,分类错了,重试就会帮倒忙。 一个实用分法是三类(工程分析,非官方分类)(来源):
| 类别 | 例子 | 处理 |
|---|---|---|
| 临时失败 | 网络中断、超时、429、5xx | 可重试,带退避 |
| 确定性失败 | 401、模型不存在、参数非法 | 不重试,原样抛 |
| 流中断 | 连接在 chunk 中途断开 | 视情况重试,但不要拼接两次流 |
第一类重试有意义,因为下一次可能成功;第二类重试没有意义,只会浪费配额;第三类最容易出错,重试后如果把两次流拼在一起,会得到重复或错乱的内容。
适配器不需要自己决定重试几次,但必须把类别标清楚。上层拿到「可重试」才重试,拿到「不可重试」就直接失败。分类模糊时,默认不要重试,避免把确定性错误放大。
还有一个细节:错误信息里不要带明文凭据。适配器的日志与错误应该脱敏,尤其是 401 这类响应可能回显请求头。
DeepSeek Harness 重试边界:什么该重试
重试不是越多越好,边界不清会导致重复计费、重复副作用和难以复现的错乱。 三条边界建议(来源):
- 只重试没有产生副作用的请求 — 模型调用通常无副作用,但如果适配器在请求前写了本地状态,重试要小心;
- 只重试幂等的请求 — 同一请求重复发送应得到同一结果;带随机种子或会话状态的请求不一定幂等;
- 重试要换请求序列 — 一次失败尝试不应伪装成同一条消息的一部分,重试应开始新的请求序列。
第三条最容易被忽略。把失败尝试和重试结果拼成一条消息,模型历史里就会出现重复内容;正确做法是保留失败尝试,重试作为新尝试,由上层决定如何呈现。
如果适配器同时做「分类」和「重试」,要避免两层重复:上层已经重试,适配器再重试,实际请求次数会翻倍。职责分清,比多加一层保险更重要。
DeepSeek Harness 配置与凭据:不要写死
配置与凭据从外部注入,是适配器可替换的前提。 官方 Cookbook 把 provider、基础 URL、协议、凭据都放在配置层(来源)。
适配器只做三件事:
- 读配置 — 端点、模型、超时、重试上限;
- 取凭据 — 通过凭据引用或环境变量,不读明文;
- 发请求 — 按协议翻译请求与响应。
不要把 API Key 写在适配器常量里,也不要把端点拼成固定字符串。否则换一个网关就要改代码,适配器就失去了 seam 的意义。
凭据缺失时,适配器应该抛出明确的错误,而不是回退到匿名请求。匿名请求通常会被端点拒绝,错误信息还不如「缺少凭据」清楚。
DeepSeek Harness 三类验证:正常流、断流、可重试错误
验证适配器,不要只测「正常返回」。 三类场景各测一次,才能确认流式与错误处理都成立(来源):
- 正常流 — 用假端点按顺序发 start、多个 chunk、end,确认上层收到完整消息且顺序正确;
- 断流 — 在 chunk 中途断开连接,确认适配器发出失败信号,不把半截内容当完整消息;
- 可重试错误 — 让端点返回 429 或超时,确认错误被标为可重试,且不会重复拼接内容。
三类都过,再测不可重试错误(401、模型不存在),确认它们不会被重试。最后测取消:在 chunk 之间取消,确认适配器停止发送并清理连接。
验证顺序建议从正常流开始,再破坏它。正常流跑通说明帧顺序对;断流与取消跑通说明生命周期对;错误分类跑通说明重试边界对。
旧文 develop-llm-adapter 讲接口与注册,develop-llm-stream-chunks 讲 chunk 细节;本篇补的是官方 Cookbook 的走查与三类验证。适配器写对,模型接入才不是一次性工程。
常见问题
DeepSeek Harness 的 LLM 适配器最小要实现一次请求的流式词汇:发起调用、产出 start/chunk/end 帧,并把最终消息或失败尝试交给上层;配置与凭据由外部注入,不写死在适配器里。
DeepSeek Harness 的适配器应按错误来源分类:网络中断、超时、429 等临时失败可重试;鉴权失败、模型不存在、参数非法等确定性错误不应重试,原样抛出。
DeepSeek Harness 会把已到达的流作为一次尝试保留或按失败处理,具体取决于错误分类;未完成的尝试不会伪装成完整消息,重试会开始新的请求序列。
DeepSeek Harness 里,通常不需要把所有重试内建在适配器里。DeepSeek Harness 的请求层与适配器各有职责;适配器应把错误分类清楚,让上层决定是否重试,避免两层重复重试。
相关术语
- LLM 适配器
- LLM 适配器是 DeepSeek Harness 中连接模型提供商的实现,负责把统一请求翻译成提供商协议,并把响应流翻译回统一流式词汇。— DeepSeek Harness 官方文档 - 新增 LLM Adapter
- 流式帧
- 流式帧是 DeepSeek Harness 流式响应中的 start、chunk、end 等单位,start 标记开始,chunk 携带增量,end 结束一次流。— DeepSeek Harness 官方文档 - LLM 流式响应
- 可重试错误
- 可重试错误是临时性失败,例如网络中断、超时或限流;适配器应明确标记它,让上层决定是否重新发起请求。— DeepSeek Harness 官方文档 - 新增 LLM Adapter
- 失败尝试
- 失败尝试是 DeepSeek Harness 保留的未完成请求记录,用于重试、取消与诊断;它不会被当作完整消息写入模型历史。— DeepSeek Harness 官方文档 - LLM 流式响应
来源
- DeepSeek Harness 官方文档 - 新增 LLM Adapter· deepseek-harness
- DeepSeek Harness 官方文档 - LLM 流式响应· deepseek-harness