DeepSeek Harness 中的 429 限流重试次数增大与 RetryPolicy 配置陷阱1. 关于 DeepSeek HarnessDeepSeek Harness简称 dsh是 DeepSeek AI 开发的开源 Agent 运行时框架。采用 Cordis 插件架构一切皆插件支持 Web UI 和 CLI 两种交互方式。当前处于开发者预览阶段迭代迅速。npx deepseek-ai/dsh web # 启动 Web UI默认 http://127.0.0.1:30802. 问题生产环境遇到模型 API 限流导致的请求失败RetryAfter: 1064ms Failure: 429 {message:rpm exhausted,type:quota_exceeded_error,code:8}DSH 默认DEFAULT_MAX_RETRIES 2定义于pi-ai/dist/utils/retry.js。对于高频调用场景2 次重试在指数退避的初始阶段即耗尽请求在 1-2 秒内失败。3. 配置架构3.1 适配器路由settings.yaml中的agent-default-model决定了请求的适配器路由agent-default-model:provider:provider-amodel:model-xprovider字段作为路由 key决定请求发往哪个适配器provider 值适配器配置文件存在于llm-pi-ai.providers下llm-pi-aisettings.yamldeepseek-officialllm-deepseekcordis.patch.yml关键必须先确认模型走哪个适配器再改对应的配置文件。改错文件不会生效。3.2 Provider 配置插槽llm-pi-ai适配器的 Provider 配置结构llm-pi-ai.providers.provider: - apiKeyEnv # 凭证环境变量名 - api # API 协议openai-completions / openai-chat - baseURL # 端点 - retryPolicy # 重试策略可选 - models[] # 模型声明列表每个 provider 的配置是独立命名空间retryPolicy只影响当前 provider 的请求。4. 配置 RetryPolicy4.1 配置项retryPolicy:mode:normal# 重试模式maxRetries:12# 最大重试次数默认 2retryableCodes:# 可重试的错误码列表-RATE_LIMIT-SERVER-TIMEOUT-TRANSPORT-EMPTY_RESPONSEbackoff:initialDelayMs:5000# 初始退避延迟maxDelayMs:30000# 最大退避延迟指数退避上限4.2 参数语义mode: normal— 标准退避模式Retry-After响应头优先级高于backoff计算值maxRetries— 重试次数的硬上限与retryableCodes共同构成重试判定backoff.initialDelayMs— 首次重试前的延迟基数backoff.maxDelayMs— 指数退避的上限超过此值的退避延迟会被截断4.3 指数退避算法DSH 的退避实现采用 capped exponential backoffdelay min(initialDelayMs × 2^(attempt-1), maxDelayMs)对initialDelayMs5000, maxDelayMs30000AttemptDelayCumulative15,000ms5s210,000ms15s320,000ms35s430,000ms (capped)65s530,000ms95s630,000ms125s…30,000ms…1230,000ms~6min4.4 配置热加载settings.yaml采用热加载机制——DSH 在运行时通过文件系统 watch 检测变更无需进程重启修改后立即生效。5. 陷阱错误分类导致重试失效配置了maxRetries: 12之后遇到 429 限流仍然不重试直接报错429: {message:Allocated quota exceeded, please increase your quota limit.,type:invalid_request_error,code:insufficient_quota}5.1 重试判定流程Request → Failure → classifyPiAiError(message) ← 错误分类 → isQuotaExceededError(message) ① 优先匹配 quota → /429|rate.?limit/i ② 其次匹配 429 → retryableCodes.includes(code) ← 重试判定 → true → recover() ← 指数退避后重试 → false → next() ← 直接终止抛出终态错误5.2 根因错误分类的优先级反转classifyPiAiErrordsh-llm-pi-ai/lib/index.js的实现functionclassifyPiAiError(message){if(isQuotaExceededError(message))returnQUOTA_EXCEEDED_CODE;// priority 1if(/\b429\b|rate.?limit/i.test(message))returnRATE_LIMIT;// priority 2// ...}isQuotaExceededErrordsh-llm/lib/index.js的判定正则/\b(?:quota|usage[\s_-]limit)[\s_-](?:exceeded|exhausted|reached)\b/i当错误消息中出现quota_exceeded_error或quota exceeded等词面时函数返回QUOTA_EXCEEDED_CODE QUOTA与 HTTP 状态码无关。match 发生在判定 429 之前。5.3 重试判定短路dsh-llm-retry/lib/index.js的recover方法if(!policy.retryableCodes.includes(failure.code))returnnext();retryableCodes默认值不包含QUOTA。因此即使maxRetries配置为 12一旦错误被归类为 QUOTA重试判定在第一步就短路直接调用next()抛出终态错误。6. 解决方案在retryPolicy.retryableCodes中显式声明QUOTAretryPolicy:mode:normalmaxRetries:12retryableCodes:-RATE_LIMIT-SERVER-TIMEOUT-TRANSPORT-EMPTY_RESPONSE-QUOTA# 让配额类429 也参与重试backoff:initialDelayMs:5000maxDelayMs:30000注意显式声明retryableCodes会覆盖默认值因此需要将其他可重试错误码一并列出。7. 设计缺陷与改进建议7.1 错误分类的优先级反转QUOTA判定优先于RATE_LIMIT导致 429 限流被错误归类为终态错误。合理的做法是将具体的 HTTP 状态码匹配429置于语义匹配quota之前或提供可配置的分类优先级。7.2retryableCodes默认值不完整QUOTA 码在语义上属于可重试的临时错误应纳入默认可重试列表。7.3providerRetryAfterMs的静默丢弃当Retry-After响应头值大于maxDelayMs时normal 模式直接调用next()放弃重试无日志、无告警。8. 调用链与代码路径层级组件职责配置宿主settings.yaml→llm-pi-ai.providers.provider.retryPolicy用户配置入口Schema 验证pi-ai/dist/types.d.ts→maxRetries?: number类型约束适配器dsh-llm-pi-ai/lib/index.js→classifyPiAiError错误分类错误分类dsh-llm/lib/index.js→isQuotaExceededErrorQUOTA 判定正则重试控制dsh-llm-retry/lib/index.js→recover重试判定 退避执行退避算法pi-ai/dist/utils/retry.js→DEFAULT_MAX_RETRIES 2默认值 指数退避计算9. 参考代码位置node_modules/deepseek-ai/dsh-llm-pi-ai/lib/index.js—classifyPiAiErrornode_modules/deepseek-ai/dsh-llm/lib/index.js—isQuotaExceededError(±L298),QUOTA_EXCEEDED_CODE QUOTAnode_modules/deepseek-ai/dsh-llm-retry/lib/index.js—recover中的retryableCodes.includesnode_modules/earendil-works/pi-ai/dist/utils/retry.js—DEFAULT_MAX_RETRIES 2C:\Users\user\.dsh\settings.yaml— 用户配置