ChatGPTClaudeGrok / X / CursorGemini

DeepSeek Harness 照 Cookbook 加 LLM 适配器:流式、错误分类与重试

插件开发发布于 2026-11-18作者: DeepSeek Plugin 插件市场
DeepSeek HarnessDSH pluginLLM Adapter流式响应Cookbook
官方 Cookbook 的 LLM 适配器不只是发请求:它要实现流式词汇、区分可重试与不可重试错误,并让配置与凭据可替换。本文按适配器 seam 走一遍,并给正常流、断流、可重试错误三类验证。

LLM 适配器最容易写成「一个能发 HTTP 请求的函数」,但 Cookbook 要的是一段能接进 DeepSeek Harness 流式与错误体系的实现。 适配器的职责不是「调通一次」,而是把提供商的响应翻译成统一的流式帧,把失败分成可重试与不可重试,并让配置与凭据从外部注入(来源)。

DeepSeek Harness 适配器 seam:先定边界

适配器是一个 seam,不是业务插件:它只负责协议翻译,不负责决定用哪个模型、用哪把凭据。 在 DeepSeek Harness 里,模型选择、路由、凭据都由上层配置决定;适配器拿到的是已经准备好的调用,产出的是统一流。(来源)

这条边界划清后,三件事就不该写进适配器:

  1. 不写死模型名 — 模型由配置传入,适配器只按传入值发请求;
  2. 不写死端点 — 基础 URL、协议由 provider 配置决定;
  3. 不写死重试策略 — 适配器分类错误,重试由请求层或调用方决定。

把这三件事写死,短期能跑,长期会在换模型、换网关、调重试时全部返工。Cookbook 的示例之所以把这些放在配置里,就是为了让适配器保持可替换。

适配器的注册走 ctx.llm,它向共享上下文贡献一个能力,而不是启动一个独立服务。注册后,上层按模型选择找到适配器,再发起请求。

DeepSeek Harness 流式词汇:start、chunk、end

流式不是「一次性返回完整字符串」,而是按帧推进。 官方把流式响应拆成 start、chunk、end 三类帧(来源)。

适配器要做的是:

  1. start — 确认请求已建立,准备接收增量;
  2. chunk — 把提供商返回的增量翻译成统一 chunk,按到达顺序发出;
  3. end — 结束本次流,交出一个完整消息或失败尝试。

三个常见错误:

  • 把 chunk 攒到最后一次发 — 看起来结果对,但流式体验没了,取消也不及时;
  • 在 end 之前发完整消息 — 上层会收到重复内容;
  • 断流时不发 end — 上层无法区分「还在等」和「已经失败」。

流式帧的顺序比内容更容易出错。写适配器时,先把帧的顺序跑通,再调内容翻译;顺序对了,断流与取消才有明确的落点。

DeepSeek Harness 错误分类:可重试与不可重试

错误分类是适配器最重要的输出之一,分类错了,重试就会帮倒忙。 一个实用分法是三类(工程分析,非官方分类)(来源):

类别例子处理
临时失败网络中断、超时、429、5xx可重试,带退避
确定性失败401、模型不存在、参数非法不重试,原样抛
流中断连接在 chunk 中途断开视情况重试,但不要拼接两次流

第一类重试有意义,因为下一次可能成功;第二类重试没有意义,只会浪费配额;第三类最容易出错,重试后如果把两次流拼在一起,会得到重复或错乱的内容。

适配器不需要自己决定重试几次,但必须把类别标清楚。上层拿到「可重试」才重试,拿到「不可重试」就直接失败。分类模糊时,默认不要重试,避免把确定性错误放大。

还有一个细节:错误信息里不要带明文凭据。适配器的日志与错误应该脱敏,尤其是 401 这类响应可能回显请求头。

DeepSeek Harness 重试边界:什么该重试

重试不是越多越好,边界不清会导致重复计费、重复副作用和难以复现的错乱。 三条边界建议(来源):

  1. 只重试没有产生副作用的请求 — 模型调用通常无副作用,但如果适配器在请求前写了本地状态,重试要小心;
  2. 只重试幂等的请求 — 同一请求重复发送应得到同一结果;带随机种子或会话状态的请求不一定幂等;
  3. 重试要换请求序列 — 一次失败尝试不应伪装成同一条消息的一部分,重试应开始新的请求序列。

第三条最容易被忽略。把失败尝试和重试结果拼成一条消息,模型历史里就会出现重复内容;正确做法是保留失败尝试,重试作为新尝试,由上层决定如何呈现。

如果适配器同时做「分类」和「重试」,要避免两层重复:上层已经重试,适配器再重试,实际请求次数会翻倍。职责分清,比多加一层保险更重要。

DeepSeek Harness 配置与凭据:不要写死

配置与凭据从外部注入,是适配器可替换的前提。 官方 Cookbook 把 provider、基础 URL、协议、凭据都放在配置层(来源)。

适配器只做三件事:

  • 读配置 — 端点、模型、超时、重试上限;
  • 取凭据 — 通过凭据引用或环境变量,不读明文;
  • 发请求 — 按协议翻译请求与响应。

不要把 API Key 写在适配器常量里,也不要把端点拼成固定字符串。否则换一个网关就要改代码,适配器就失去了 seam 的意义。

凭据缺失时,适配器应该抛出明确的错误,而不是回退到匿名请求。匿名请求通常会被端点拒绝,错误信息还不如「缺少凭据」清楚。

DeepSeek Harness 三类验证:正常流、断流、可重试错误

验证适配器,不要只测「正常返回」。 三类场景各测一次,才能确认流式与错误处理都成立(来源):

  1. 正常流 — 用假端点按顺序发 start、多个 chunk、end,确认上层收到完整消息且顺序正确;
  2. 断流 — 在 chunk 中途断开连接,确认适配器发出失败信号,不把半截内容当完整消息;
  3. 可重试错误 — 让端点返回 429 或超时,确认错误被标为可重试,且不会重复拼接内容。

三类都过,再测不可重试错误(401、模型不存在),确认它们不会被重试。最后测取消:在 chunk 之间取消,确认适配器停止发送并清理连接。

验证顺序建议从正常流开始,再破坏它。正常流跑通说明帧顺序对;断流与取消跑通说明生命周期对;错误分类跑通说明重试边界对。

旧文 develop-llm-adapter 讲接口与注册,develop-llm-stream-chunks 讲 chunk 细节;本篇补的是官方 Cookbook 的走查与三类验证。适配器写对,模型接入才不是一次性工程。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DeepSeek Harness 的 LLM 适配器最小要实现什么?

DeepSeek Harness 的 LLM 适配器最小要实现一次请求的流式词汇:发起调用、产出 start/chunk/end 帧,并把最终消息或失败尝试交给上层;配置与凭据由外部注入,不写死在适配器里。

DeepSeek Harness 的适配器怎么区分可重试错误和不可重试错误?

DeepSeek Harness 的适配器应按错误来源分类:网络中断、超时、429 等临时失败可重试;鉴权失败、模型不存在、参数非法等确定性错误不应重试,原样抛出。

DeepSeek Harness 适配器断流后,已经产出的内容会怎样?

DeepSeek Harness 会把已到达的流作为一次尝试保留或按失败处理,具体取决于错误分类;未完成的尝试不会伪装成完整消息,重试会开始新的请求序列。

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 流式响应

来源