虚拟模型路由 andrepontesmelo/dsh-model-router

dsh-model-router

CI
Version
local gate

dsh-model-router banner

一个 DeepSeek Harness (DSH) 插件，将模型选择转变为智能路由：在配置中声明一个虚拟模型 id，将其绑定到针对一组真实 provider/model 候选者的路由算法上，然后就可以在任何地方使用这个虚拟 id —— agent 选项、模型选择器。每次调用都会被透明地分派到由算法选出的真实模型，并带有自动故障转移。

它的功能

- 虚拟模型 id。 诸如 routed-chat 这样的路由在选择器中表现得像任何真实模型一样，但它只是你定义的候选池之上的一个门面。
- 透明故障转移。 当某个候选者失败时，会尝试下一个 —— 相同的请求，用户看不到错误 —— 并且插件会记录每次调用实际由哪个真实模型提供服务，因此故障转移总是能在来源信息中体现，而不是悄无声息。
- 两种路由算法（可插拔的扩展点）：
- priority —— 总是先尝试第一个候选者；仅在失败时才跳过它。失败的候选者会获得指数退避，让陷入困境的模型在被再次尝试之前有时间恢复。
- round-robin —— 在候选池中分配调用。
- 每个候选者的推理级别。 候选者可以声明一个 reasoning 努力级别，当该候选者服务请求时会被应用；没有匹配级别的模型则保持其 provider 默认值。
- 你自己的算法。 RoutingAlgorithm 是一个工厂契约（select、onFailure，可选的 onDispatch/onSuccess）—— 实现一个并注册它。

单个回合的故障转移 —— 一个候选者失败，下一个接手，来源信息记录谁做出了响应：

flowchart LR
V["request: routed-chat"] --> P["algorithm selectsthe first live candidate"]
P --> C1["candidate 1alpha/alpha-model"]
C1 -- "stream error" --> F["mark failed +backoff cooldown"]
F --> R["retry: select thenext live candidate"]
R --> C2["candidate 2beta/beta-model"]
C2 -- "stop" --> OK["success — provenancerecords beta as the model that served"]

为什么存在

模型池是现实：一个便宜快速的模型、一个强大的模型、一个备用模型。硬编码一个 id 意味着 provider 的故障就是你的故障。在插件层进行路由意味着 harness 的其余部分永远不会知道故障 —— 也永远不需要知道。

安装

需要 Node ≥ 22 以及一个用于安装的 DSH profile。

npm pack
dsh plugin --profile add file:/path/to/dsh-model-router-.tgz

或者直接从 GitHub 安装：

markdown
dsh plugin --profile add github:andrepontesmelo/dsh-model-router

[!WARNING]
路由由配置驱动，不会绕过任何你未声明的内容——但你列出的每个候选者都是真实提供方，你的提示词和补全结果都会被发送到那里。在安装并非由你编写的路由配置之前，请审计 candidates 列表，并固定安装版本（tag 或本地 tarball），而不是跟随分支浮动。

安装前验证构建： bash
npm pack --dry-run # 检查实际发布的内容
sha256sum dsh-model-router-.tgz

将校验和与你要安装的版本随附发布的校验和进行比较。github: 安装会在安装时解析默认分支——为了可复现性，请固定一个 tag。

安装后有有用的命令： bash
npm test # 76 项测试的单元测试套件（node --test）
npm run smoke # 5 个故障转移演练，内存中运行，零网络
dsh plugin --profile list

快速开始

向你的 profile 的 cordis.patch.yml 添加一条路由： jsonc {
"routes": [
{
"id": "routed-chat",
"algorithm": "priority", // "priority" | "round-robin"
"candidates": [
{ "provider": "deepseek-official", "model": "deepseek-v4-flash", "reasoning": "high" },
{ "provider": "pi-ai", "model": "..." }
]
}
]
}

在模型选择器中选择 routed-chat（或将其设为某个 agent 的模型）即可路由。发生故障转移时，响应来源会显示实际应答的模型，以及任何正处于退避窗口中的候选者。

候选者可选的 reasoning 是该提供方模型的一个 effort id。当该候选者处理请求时， shim 会以该 reasoning effort 进行分发；如果模型没有 reasoning 概念（或没有这样的 effort），该级别会被忽略，并应用提供方自身的默认值——请求绝不会因此失败。

从配置到选择器的整个栈——一条声明的路由会变成一个由候选池支撑的真实模型选择器条目： mermaid
flowchart TD
C["cordis.patch.ymlroute routed-chat, algorithm priority,candidates: deepseek-official/deepseek-v4-flash, pi-ai/…"] --> A["apply(): validate config,group routes by provider"]
A --> S["RouterShim registers thevirtual provider routed-chat"]
S --> L["llm runtime"]
L --> M["model picker advertisesrouted-chat"]
M --> D["picking routed-chat dispatches throughthe algorithm with transparent failover"]

编写你自己的算法

算法是一个工厂函数 (ctx, routes) => algorithm：
js
{
select(route, callCtx) // -> candidate | undefined (纯函数——不推进状态)
onFailure(route, candidate) // 记录失败，以便 select 跳过它
onDispatch?(route, candidate) // 请求的首次分发
onSuccess?(route, candidate) // 可选
}

shim 会对 select 进行布尔检查探测，因此它必须保持纯函数；状态推进发生在 on* 回调中。test/ 中的测试套件固定了这些接缝机制。
文档

从文档索引开始：

- 架构 — 插件接线、垫片、路由、退避。
- 开发 — 目录结构、测试门禁、如何运行冒烟测试套件。

贡献

欢迎提交 PR — 工作流程和本地门禁请参见 CONTRIBUTING.md。
安全问题：SECURITY.md（请勿公开提交 issue）。

路线图

- 会话粘性 — 将会话固定到首次为其提供服务的候选者 — 上游阻塞：插件在适配器的 prepareCall(provider, model, signal) 接缝处选择其候选者，而该接缝不携带会话 ID（循环在请求选项上的可选 sessionId 只会在稍后、流式传输时、选择之后才出现），因此插件无法按对话进行固定。如果 DSH 在候选者选择过程中传递会话 ID，则可解除阻塞。

要求

- Node ≥ 22。
- 一个用于安装的 DSH 配置文件；候选者指向已在该配置中配置好的提供者。

测试

npm test # 单元测试套件
npm run smoke # 内存故障转移演练（LOCAL 模式）

许可证

MIT — 参见 LICENSE。