jmche/dsh-llm-verifier-pro

dsh-llm-verifier-pro

License
Platform
[Type]()
[Method]()

DeepSeek Harness 的质量门禁：采样 N 个候选答案，用细粒度 logprob 奖励为它们打分，只重放最优的那个——而不是把模型的初稿直接交给你。

- Best-of-N 对话模式——每个文本轮次采样 N 种方式，按期望得分排序，胜出者以静默的 ⚡ Best-of-N 页脚重放；
- 三个 verify_ 工具——verify_compare / verify_select / verify_track，用于自检、Best-of-N 选择和进度跟踪；
- 论文方法——细粒度奖励为验证器在  位置 top-20 logprob 分布上的期望（arXiv:2607.05391），配合 Bradley–Terry + 概率枢轴锦标赛（O(N·k)，而非 O(N²)）；
- 始终故障开放——采样超时、打分失败、端点不支持 logprobs：一切都会优雅降级，绝不出现死轮次。

基于 LLM-as-a-Verifier 论文（arXiv:2607.05391）；
工程核心来自 dsh-llm-as-a-verifier（TaurenMountain），产品层
来自 @aispin/plugin-verifier（Aispin），二者均为 MIT。

安装

需要 DeepSeek Harness 配置文件
（web 或无头模式）。将插件添加到目标配置文件——编译后的
lib/ 已纳入本仓库跟踪，因此 GitHub 安装开箱即用：

从 GitHub 安装（推荐——立即可用）
dsh plugin --profile web add github:jmche/dsh-llm-verifier-pro

或从本地检出 / 路径安装
dsh plugin --profile web add /path/to/dsh-llm-verifier-pro

该插件注册为 bundle 行 llm-verifier-pro。然后在配置文件的 patch 层中配置它
（见下方配置），重启 dsh web，插件将暴露：

- 向每个 agent 提供三个 verify_ 工具；
- Web UI 中的 verifier-pro 设置区（Best-of-N 面板）；
- 可选的 Best-of-N 对话模式（默认关闭）。

完整指南：docs/USER-GUIDE.md。

三个面向

1. 工具（agent 按需调用）

- verify_compare——在你的标准下，对一次有向成对比较给出细粒度奖励 (R_A, R_B) ∈ [0, 1]。
- verify_select——概率枢轴锦标赛 Best-of-N 选择：
O(N·k) 次验证器比较，而非 O(N²)，带种子且可复现。
- verify_track——在你的轨迹上给出逐步进度曲线（A = 0% … T = 100%），
从 logprob 期望解码得出。

2. 服务（ctx.verifier）

供代码消费者使用的 ctx.verifier.verify / compare / select / track。

3. 模式（Best-of-N 对话模式）
启用后，每一个产生最终文本答案的助手回合都会以 N 种方式采样，只有胜出的响应会被回放给你。工具调用回合永远不会被采样——当模型的回合是一个动作（读取文件、运行命令、调用工具）时，该回合会按原样精确回放：Best-of-N 只对文本答案进行排名，而对一个可用的回合进行采样会浪费 token 并产生不可用的候选。该决策会逐回合重新评估，并且刻意采用全有或全无——该模式覆盖所有对话，没有按会话分级：

| 层级 | 开关 |
|---|---|
| 设置（Web UI 面板） | boN: true / boN: false——显式的 Off 是主终止开关，会覆盖配置默认值 |
| 配置默认值 | 插件配置中的 boN: true（仅当该部分未设置时） |

行为变更： dsh 会话 UI 中的 bo-n 会话预设不再有任何效果——该模式是全有或全无。如果你之前通过预设让特定会话选择启用，请改为全局启用该模式（或按配置文件限定范围）。

模型组合（候选多样性）。 候选 0 始终使用对话自身的模型（贪婪锚点）。后续每个槽位按顺序从 boNModelMix 中取一个 { provider, model } 条目；超出列表的槽位会回退到锚点模型的变体，并采用采样温度。可在补丁层配置它，也可从 Web 设置面板实时配置（verifier-pro 部分有专门的编辑器——每行一个 provider/model；不含 / 的行是对话所用提供商上的完整模型 id）。

provider 是真实的 dsh 提供商路由（omni-chat、omni-message、deepseek-official……）；model 是该提供商所公布的完整模型 id（可能包含它自己的 /，例如 agnes/agnes-2.5-flash）。面板会在每行的第一个 / 处拆分——因此，本身包含 / 的模型 id（例如 ollama-local/qwen3.8:27b）在面板中必须连同其真实提供商一起书写（omni-chat/ollama-local/qwen3.8:27b）；只有不含 / 的模型 id 才能作为裸行使用对话的提供商。

boNModelMix:
- provider: omni-chat
model: agnes/agnes-2.5-flash
- provider: omni-message
model: opencode-go/minimax-m3
- provider: omni-chat
model: ollama-local/qwen3.8:27b

每一条失败路径都开放失败：采样超限会从 Bo5 降级为 Bo-K，再降级为普通答案，并附带一条说明所发生情况的弱化页脚。绝不会出现死回合。

开关、候选数量、验证预算和模型组合都可以从 Web 设置面板实时编辑——参见
Web 设置面板。

Web 设置面板（Best-of-N）

dsh Web UI 公开一个设置部分（verifier-pro → Best-of-N）。
每个控件都会写入设置文档，并在下一个回合立即生效——无需重启。逐回合决策由 resolveBoNMode 决定（设置 → 配置默认值 → 关闭），并且它是全有或全无：该模式适用于每一个
对话；没有按会话划分的层级。

当前效果（实时横幅）

面板顶部的状态横幅用通俗的英语说明当前设置的实际结果——不再有“哪些会话”的问题需要猜测：

- Best-of-N 对所有对话开启 · 5 路
- Best-of-N 对所有对话关闭

Best-of-N 模式（整个决策）

- 关闭 — 写入 boN: false。主开关：不进行任何采样，并且它也会覆盖配置默认值。
- 快速 · 3 路 — boN: true，boNCandidates: 3。约 2–3 倍 token，约 2 倍延迟。
- 精确 · 5 路 — boN: true，boNCandidates: 5。约 3–5 倍 token，2–4 倍延迟（约 16 次模型调用——论文中的 Bo5）。
- 自定义 — boN: true，boNCandidates: N，其中 N 被限制在 2–8。

高级设置（默认折叠）

- 验证超时（秒） — 仅用于排序阶段的独立墙钟时间预算（默认 90 秒，范围 30–600）。采样单独预算（timeoutMsBoN）。超时后，该轮次降级为普通回答，并附带页脚说明。
- Rollout 调度 — 并行（默认）：所有候选同时触发，在快速模型上最快。串行：一次一个候选，当多个候选共享一个缓慢的本地模型时更安全。
- 验证器（评分模型） — 为每一对候选评分的单一模型。一行，与 Model mix 相同的规则：provider/model 会从 dsh 的 provider 配置中查找端点和 API key（无需输入 base URL）；不带 / 的裸模型 id 沿用会话的 provider。留空 → 跟随会话模型（零配置默认，论文中的自验证）。解析后的端点必须返回 token 级 logprobs。
- Model mix（候选多样性） — 文本区域，每行一个条目：provider/model 指定显式 provider 路由（在第一个 / 处分割）；不带 / 的裸模型 id 沿用对话的 provider。候选 0 始终是对话的模型（贪婪锚点）；槽位 1..N−1 按顺序从列表中填充；超出列表的槽位回退到采样温度下的锚点模型变体。
- 保存 model mix 会解析并写入 boNModelMix（短暂的“已保存 ✓”反馈）；恢复配置默认值 会清空该部分的值（插件配置基础会重新应用）；可用模型 徽章可点击追加，并带有显式 provider 路由。
- 当端点缺少 logprobs 时自动降级 — 开启（默认）：当端点不返回 token 级 logprobs 时，评分回退为对评分字母进行采样，并且轮次页脚会标记“sampling scoring”（精度略低）。关闭：严格模式——不支持的端点会直接显示错误，Bo-N 轮次会作为普通回答返回；绝不静默降级。

我如何知道它正在运行？

每个 Best-of-N 轮次都会在回答后附加一个柔和的页脚——“⚡ Best-of-N · 5-choose-1 → …”——包含层级、耗时和 token 使用量；服务器
控制台还会在每轮记录 [bo-n] mode: …。

对论文的忠实度

这些工具、服务以及 Bo-N 模式完全按照官方仓库（MIT）所发布的方式实现了 LLM-as-a-Verifier 方法（arXiv:2607.05391）：细粒度奖励 = 在 20 个字母（A–T）量表的  /  位置上，对验证器 top-20 logprob 分布求期望，并归一化到 [0, 1]（论文式 3.1）；Bradley–Terry 偏好 p = σ(R_A − R_B)（式 3.2）；概率枢轴锦标赛（Probabilistic Pivot Tournament），包含随机哈密顿环环遍历、按平均偏好选取 top-k 枢轴以及枢轴轮次——N + k(N−k) + C(k,2) = O(Nk) 次比较，带种子且可复现（算法 1）；准则分解（C）与重复评估（K）；逐检查点进度跟踪（A = 0% … T = 100%）；以及针对 logit 受限后端的 vLLM/SGLang score-tag 预填充流程（论文附录 B.6）。成对比较与进度提示词与官方模板一致。

与官方仓库 / 论文相比有记录的偏差——均不改变方法本身：

1. Bo-N 在 N ≤ 3 时使用完整循环赛（src/bon.ts）：PPT 仅从 N ≥ 4 起适用，此时它更便宜且方差更低；对极小池进行穷举评分是精确的。verify_select 始终使用 PPT。
2. 默认值弱于论文的旗舰协议（G=20、K=8、三准则分解）：verify_compare K=1，verify_select K=4（官方仓库的默认值），Bo-N 轮次 K=1 且使用单一 correctness 准则。所有这些均可配置（nEvaluations、criteria、……）。
3. verify_track 是离线单次调用变体（与官方 track() 相同）：一次调用为每个检查点评分并看到整条轨迹；严格的逐前缀协议（官方 ProgressTracker）未被移植。
4. 不支持多模态（图像/视频）输入——官方仓库接受 images；TS 后端不接受。
5. 没有持久化 JSON 分数缓存——select 仅在每次运行时保留内存缓存。
6. 跨实现并非逐位可复现——PRNG 是 mulberry32（不是 Python 的 random），因此一个种子可在 JS 内复现一场锦标赛，但不会复现与 Python 相同的环；准则 ID 的 slug 化使用 - 而不是 _。

配置

零配置默认： 在没有显式 baseUrl / apiKey / model（且面板的 Verifier 字段为空）时，验证器跟随会话——与对话使用相同的提供商路由、端点和模型。仅开启 Best-of-N 即可获得论文的自验证体验：候选答案作为对话自身模型的变体被采样，并由同一模型为其评分。会话提供商的端点从其设置命名空间读取（llm-pi-ai.providers. 风格）。仅当会话提供商未知时，解析才会回退到：

插件配置 → verifier 设置部分 →
会话提供商端点 → OPENAI_BASE_URL / OPENAI_API_KEY /
DEEPSEEK_API_KEY → api.deepseek.com。

验证器必须位于一个返回token 级 logprobs 的端点上
（vLLM、SGLang、OpenAI、DeepSeek 以及现代 Ollama 都支持；一个会剥离 logprobs 的普通网关则不行）。非 DeepSeek 服务器会获得可选的
vLLM/SGLang 预填充处理，使评分标签恰好落在标签位置上。

~/.dsh/profiles//cordis.patch.yml
- id: llm-verifier-pro
config:
将 baseUrl/apiKey/model 留空以跟随会话模型。
显式设置它们以使用专用的评分端点：
baseUrl: https://your-gateway/v1
apiKey: credential:YOUR_API_KEY_ENV
model: opencode-go/deepseek-v4-flash
boN: false          # 总开关 — Web 面板或此行可将其打开；显式的 Off 优先于一切
boNCandidates: 5
samplingMode: parallel   # 每轮 rollout 数：'parallel'（默认）一次性触发 N 个；'serial' 一次等待一个（当多个候选共享一个缓慢的本地模型时更安全）
showFooter: true

参数（一套词汇，两个层级）

每个用户可调参数在插件配置
（cordis.patch.yml）和设置部分（~/.dsh/settings.yaml →
verifier-pro:）中使用相同的名称。设置部分优先于插件配置，而
插件配置优先于内置默认值：

| 参数 | 默认值 | 层级 | 含义 |
|---|---|---|---|
| boN | false | 两者 | Best-of-N 总开关。面板中显式的 false 覆盖一切。 |
| boNCandidates | 5 | 两者 | 每个文本回答轮次采样的候选数。 |
| samplingTemperature | 0.7 | 两者 | 采样候选的多样性温度。 |
| samplingMode | parallel | 两者 | Rollout 调度：parallel（一次性全部）或 serial（一次一个）。 |
| boNModelMix | [] | 两者 | 非锚点候选的模型混合；空 = 同模型（跟随会话）。 |
| timeoutMs | 300000 | 两者 | 每次验证器 HTTP 请求超时，单位毫秒。 |
| timeoutMsBoN | 300000 | 两者 | 采样阶段的挂钟时间预算。 |
| verifyTimeoutMsBoN | 300000 | 两者 | 排名阶段的挂钟时间预算。 |
| showFooter | true | 两者 | 在获胜者下方追加弱化的 ⚡ Best-of-N … 页脚。 |
| criteria | [] | 两者 | 追加到比较提示中的额外评分标准。 |
| boNPivots | 2 | 两者 | PPT 枢轴数 k。 |
| boNSeed | 0 | 两者 | 锦标赛环形轮次的种子。 |
| verifier | '' | 两者 | 验证器作为 provider/model 路由；空 = 跟随会话模型。 |
| autoDegrade | true | 两者 | 当端点缺少 logprobs 时回退到采样评分。 |
| baseUrl / apiKey / model | '' | 两者 | 显式验证器端点三部分；空 = 跟随会话。 |
| maxConcurrency | 8 | 配置 | 最大进行中的验证器调用数。 |
| deepseek | 自动 | 配置 | 强制使用 DeepSeek 调用路径。 |
| prefill | true | 配置 | vLLM/SGLang 评分标签预填充处理。 |
| compare / select / track | true | config | 注册三个 verify_* 工具。 |
| settingsNs | verifier-pro | config | 设置命名空间 ID。 |

仅用于部署的参数（maxConcurrency、deepseek、prefill、
compare/select/track、settingsNs）仅存在于插件配置中——它们
不是面向用户的设置。

开发

npm install
npm run check      # 类型检查 + 测试（114 个测试）
npm run build      # tsc + 复制 client.js

许可证

MIT。实现移植自上述两个上游项目，二者均为 MIT。