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 仓库