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 倉庫
• 社區目錄