dsh-llm-auto-route：DeepSeek Harness 的自動路由與故障轉移插件

前言¶

DeepSeek Harness（DSH）強調“一切皆插件”的架構理念。在構建使用多個模型推理提供商的智能體時，開發者通常需要顯式指定 provider，並在服務故障時手動切換。這增加了配置的複雜度。dsh-llm-auto-route 插件旨在解決這一問題，它通過自動發現已配置的 provider、匹配請求規則、執行健康檢查以及在輸出前的故障轉移，簡化了多 provider 的管理流程。

插件簡介¶

dsh-llm-auto-route 是一個社區維護的 Cordis 插件，由用戶 qinyu765 開發。它定位爲一個路由策略層，負責在請求發送前決定使用哪個 dsh-llm-pi-ai 路由，並在必要時執行故障轉移。

它不實現 HTTP 協議，也不提供 provider SDK 或註冊適配器路由（如 openai 或 deepseek），這些功能仍由官方的 @deepseek-ai/dsh-llm-pi-ai 插件負責。

核心功能¶

插件主要提供以下能力：

1. Provider 發現與匹配

   • 通過在請求選項中設置 provider: auto 或配置文件中 provider 爲 auto 來觸發自動選擇。
   • 採用固定的優先級順序進行匹配：explicit（顯式指定）→ provider_env（環境變量檢測）→ base_url（基礎 URL）→ model_prefix（模型前綴）。
   • 利用環境變量（如 DEEPSEEK_API_KEY）和特定端口（11434 對應 Ollama，8000 對應 vLLM）作爲匹配信號。

2. 健康檢查

   • 支持三種模式：adaptive（複用官方模型發現接口，帶緩存）、off（跳過預檢）、probe（每次請求均進行探測）。
   • 使用內存緩存和有界超時來控制性能。

3. 輸出前故障轉移

   • 僅在文本、推理、工具調用或塊輸出開始前允許切換 provider。
   • 遵循保守策略：不重試已中止的請求、顯式 provider 的請求或已開始輸出的請求。

4. 不可變性

   • 插件返回新的不可變請求配置，不修改傳入的凍結請求對象。

安裝與啓用¶

插件通過 npm 安裝，版本要求 Node.js >= 22.19.0，DeepSeek Harness >= 0.1.0-rc.5。

pnpm add dsh-llm-auto-route

安裝後，需加載插件自帶的 cordis.patch.yml 文件。如果開發者手動組合插件，需確保在加載 dsh-llm-auto-route 之前，已正確加載官方的 @deepseek-ai/dsh-llm-pi-ai 適配器。

典型用法¶

配置路由策略¶

插件默認提供規則，開發者可以通過 YAML 配置覆蓋默認行爲。

provider: auto
precedence:
  - explicit
  - provider_env
  - base_url
  - model_prefix
healthCheck:
  mode: adaptive
  timeoutMs: 3000
  cacheTtlMs: 30000
failover:
  enabled: true
  maxAttempts: 3
diagnostics: info
routes:
  deepseek:
    apiKeyEnv: DEEPSEEK_API_KEY
    defaultModel: deepseek-chat
    priority: 10
  openai-compatible:
    apiKeyEnv: GATEWAY_API_KEY
    baseURLEnv: LLM_BASE_URL
    modelPrefixes: [gateway-]

路由字段說明¶

配置中的路由字段僅爲提示，不直接配置 adapter：

代碼中使用 API¶

插件導出了純函數 resolveRoute 和 normalizeConfig，可用於手動解析路由決策。

import { normalizeConfig, resolveRoute } from 'dsh-llm-auto-route'

const decision = resolveRoute(normalizeConfig(), {
  model: 'deepseek-chat',
  env: { DEEPSEEK_API_KEY: 'present' },
  registeredProviders: new Set(['deepseek']),
})

if (decision.kind === 'matched') {
  console.log(decision.candidate.provider, decision.candidate.model, decision.stage)
}

適用場景與注意¶

• 適用場景：需要在一個服務中管理多個 OpenAI 兼容或 DeepSeek 專用 provider 的開發者；需要根據環境變量或模型名稱自動路由的場景。
• 注意事項：
  • 本項目爲社區項目，非 DeepSeek 官方維護。
  • 確保依賴的 @deepseek-ai/dsh-llm-pi-ai 已正確配置 route names，否則會報 NO_REGISTERED_ROUTE。
  • 故障轉移僅作用於輸出前的階段，不會修改已凍結的請求對象。
  • 需檢查源碼以確認許可證（MIT）符合項目需求。

結語¶

dsh-llm-auto-route 爲 DeepSeek Harness 生態提供了一個輕量級的路由策略層。通過自動化的 provider 選擇和輸出前的故障轉移機制，它降低了多 provider 部署的維護成本，適合追求高可用性的智能體開發場景。

• 插件目錄頁
• GitHub 倉庫