dsh-llm-failover：DeepSeek Harness 模型提供方故障转移插件

前言¶

在使用 DeepSeek Harness 进行模型推理开发时，遇到模型提供方返回限流（429）或配额耗尽错误是常见问题。手动切换或重试不仅效率低，还容易导致用户体验中断。dsh-llm-failover 插件旨在解决这一问题，通过自动检测错误并切换至下一个提供方，保障推理服务的连续性。

是什么¶

dsh-llm-failover 是一个 DeepSeek Harness (DSH) 插件，由 HB00 维护。它实现了模型提供方的故障转移机制。当当前提供方因限流或配额问题失败时，插件会根据配置自动切换至下一个提供方，直到找到可用的服务或到达永久兜底提供方。

核心功能¶

• 自动切换：检测到 RATE_LIMIT 或 QUOTA 错误时，自动切换提供方。
• 按提供方配置模型：切换后，新的提供方可使用不同的模型。
• 冷却机制：提供方在冷却期间会被跳过，避免频繁切换，直到冷却结束。
• 永久兜底：配置列表中的最后一条提供方是永久兜底项，永远不会被切走。
• UI 提示：每次切换时，界面输入框上方会显示自动消失的提示条。
• 多配置方式：支持通过设置卡片或 YAML 文件进行配置。

安装¶

使用官方安装命令添加插件：

dsh plugin --profile web add dsh-llm-failover

配置与用法¶

插件配置文件位于 ~/.dsh/settings.yaml。有两种配置方式：在设置界面中通过“插件配置”卡片填写，或直接编辑 YAML 文件。

YAML 配置示例¶

llm-failover:
  enabled: true
  providers:
    - provider: huoshan
      model: deepseek-v4-flash
    - provider: huoshan2
      model: deepseek-v4-flash
    - provider: deepseek-official
      model: deepseek-v4-flash
  fallbackAfterRetries: 2
  cooldownMs: 60000

配置项说明：
* enabled：总开关，控制插件是否生效。
* providers：提供方列表，按顺序尝试。列表末尾的提供方为永久兜底。
* fallbackAfterRetries：连续失败几次后触发切换和冷却。
* cooldownMs：提供方的冷却时长（毫秒）。

工作原理¶

插件通过挂载到 DSH 的两个官方 Agent 钩子实现逻辑：
1. agent/request：在请求时，从配置列表中选取第一个未冷却的提供方。
2. agent/request-error：在错误发生时，根据 fallbackAfterRetries 判断是否触发切换。如果触发，将当前提供方置入冷却状态，并返回重试指令。列表末尾的提供方永远不会被切走。

注意事项¶

• 依赖项：插件依赖 zod、@deepseek-ai/cordis、@deepseek-ai/dsh-settings 和 @deepseek-ai/schemastery。
• 权限与源码：插件以当前 DSH 进程的权限运行，安装前建议检查源码与许可证（MIT）。
• 目录性质：本插件收录于社区目录，与 DeepSeek 或幻方无官方从属关系。

总结¶

dsh-llm-failover 提供了一种简单且高效的方案，通过配置即可实现多模型提供方的自动容错，适合需要高可用性的 DeepSeek Harness 智能体开发场景。

• GitHub 仓库
• 社区目录