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。