dsh-llm-verifier
English | 中文
npm 包名：dsh-llm-as-a-verifier（裸名 dsh-llm-verifier 在 npm 上已被他人占用，仓库与 npm 包统一为 dsh-llm-as-a-verifier）。
把 LLM-as-a-Verifier（arXiv 上的统一验证框架）魔改进 DeepSeek Harness（dsh）：让智能体在干活时能对自己的候选答案做细粒度概率化验证——不再是「好/坏」一锤子判断，而是读取验证模型在 20 级评分字母上的完整 logprob 分布并取期望。
你会得到
三个模型可直接调用的工具（安装后自动注册，无需重启即可用）：
| 工具 | 能力 | 复杂度 |
|---|
verify_compare | 对两个候选（代码/方案/轨迹）按评价标准打分，返回 [0,1] 的细粒度奖励 (scoreA, scoreB) | 1 次验证调用 / 标准 / 次 |
verify_select | N 选一：Probabilistic Pivot Tournament（概率枢纽锦标赛），O(Nk) 次比较替代 O(N²) 全循环 | 线性于 N |
verify_track | 逐步进度追踪：验证器以 A(0%)..T(100%) 为每个 checkpoint 打分，画出进度曲线 | O(K) 次调用 |
为什么比「LLM-as-a-Judge」更细？ 上游框架的核心思想是：① 用细粒度评分（20 级字母尺度）；② 对评分 token 的完整 logprob 分布取期望（而不是只取 argmax）；③ 用重复评估 + 标准分解缩放可靠性。本插件原样移植了这套逻辑（打分提取、成对提示词、锦标赛、进度追踪、token 计量），并适配为 DSH 的 Cordis 工具插件。
安装
dsh plugin --profile web add dsh-llm-as-a-verifier
要求：dsh ≥ 0.1.0-rc.6、Node ≥ 18。安装完成后重启 dsh web（或等待 HMR 自动生效）。
配置验证后端
验证模型必须是能返回 token 级 logprobs 的 OpenAI 兼容服务：DeepSeek 官方 API、vLLM/SGLang 本地服务、OpenAI 等均可。
在你的 profile 配置（~/.dsh/profiles/<name>/cordis.patch.yml 或 ~/.dsh/cordis.patch.yml）里写：
- id: llm-verifier
config:
baseUrl: https://api.deepseek.com # 或 vLLM: http://localhost:8000/v1
apiKey: '${DEEPSEEK_API_KEY}' # 推荐用环境变量，见下
model: deepseek-v4-flash # 不填时：DeepSeek 默认 deepseek-v4-flash，其余自动探测 /models
maxConcurrency: 8
凭证解析顺序（与上游一致）：插件 config → OPENAI_BASE_URL + OPENAI_API_KEY → DEEPSEEK_API_KEY（自动启用 DeepSeek 端点与 thinking 参数）。什么都不配时，工具注册不受影响，调用时才报 MissingAPIKeyError。
export DEEPSEEK_API_KEY=sk-... # 最省事的配置方式
使用示例
装好后直接在对话里让智能体用（无需额外命令）：
我写了三个候选实现，帮我用 verify_select 按「正确性、性能」标准选出最好的，
然后对选中的实现用 verify_track 检查我之前的修复步骤是否有进展。
或者手动指定：
verify_compare: problem="写一个反转字符串的函数", candidateA="def rev(s): return s[::-1]",
candidateB="def rev(s): return s", criteria={"Correctness": "代码是否真的反转了字符串？"}
配置项
| 配置 | 默认 | 说明 |
|---|
model | DeepSeek: deepseek-v4-flash；其余自动探测 | 验证模型名 |
baseUrl | 按凭证推断 | OpenAI 兼容端点 |
apiKey | 按环境推断 | 建议走环境变量 |
timeoutMs | 60000 | 单次请求超时（毫秒） |
maxConcurrency | 8 | 最大并发验证调用 |
deepseek | 按 baseUrl 推断 | 强制 DeepSeek 调用路径（thinking 开启） |
prefill | true | 非 DeepSeek 服务器上对评分标签做 prefill（vLLM/SGLang 读取字母分布更稳） |
compare / select / track | true | 是否注册对应工具 |
工具参数（nEvaluations 重复评估次数、pivots 枢纽数、seed 环赛种子、groundTruthNote 基准提示等）与上游 llm_verifier Python 包一一对应，详见 使用手册。
作为库使用
import { Verifier } from 'dsh-llm-as-a-verifier'
const verifier = new Verifier({ baseUrl: 'http://localhost:8000/v1' })
const { scoreA, scoreB } = await verifier.compare(problem, a, b, { Correctness: '...' })
const result = await verifier.select(problem, candidates, { Correctness: '...' }, { pivots: 2 })
const curve = await verifier.track(problem, steps, { checkpoints: [1, 3] })
开发与测试
npm ci
npm run check # typecheck + vitest（76 个用例，含本地 mock logprobs 服务器端到端测试）
npm run build
TDD 过程与全流程 SOP 见 docs/SOP.md。
许可与致谢
MIT。打分期望、成对提示词、Probabilistic Pivot Tournament、进度追踪与 logprob 提取逻辑移植自 llm-as-a-verifier/llm-as-a-verifier（MIT），完整归属见 LICENSE。
