semantic-router sr-bench 结果解读指南：读懂报告指标、Dashboard 与未完成任务恢复

• 后端
• API网关
• 模型推理服务
• AI Agent

导读

本篇指南围绕 semantic-router 仓库中 sr-bench 基准评测的结果读取环节展开，讲解如何阅读评测报告中的各项指标（完整计划分母、四类 token、成本、TTFT、延迟分位数）、如何用reconcile-usage做离线用量对账、如何理解基线选择与配对置信区间、如何在 Dashboard 的 Runs / Create evaluation / Datasets / Compare iterations 等页面中完成评测管理，以及如何用recover-plan与recover显式恢复未完成任务。读完本文，你可以准确解释一次 sr-bench 运行的每一行报告输出，并能独立完成从创建评测到恢复失败运行的完整闭环。

sr-bench 的 CLI 与Dashboard → Evaluation共享同一套持久化服务、运行 ID、结果与报告（参见 sr-bench 1.0 总览），因此本文的命令与页面操作针对同一份数据，可互为印证。

报告指标：先看分母，再谈分数

报告给出的指标构成一次完整评测的"结算单"，包括：

• 完整计划分母（full planned denominators）：每个目标（target）按计划应完成的全部题数，而不是实际完成的题数；
• 正确 / 已评分 / 失败数：correct为判定正确的题数，scored为已完成且能给出正确性布尔值的题数，failed为失败题数；
• 每个基准的分数和区间：各 benchmark 的准确率及其 95% 置信区间；
• 四类互斥 token：input_tokens、cached_input_tokens、cache_write_tokens、output_tokens四个桶，四者互斥加总；
• 主体与裁判/模拟器成本：subject 调用（被测模型/路由）与 judge/simulator（裁判/用户模拟器）分别计费的成本；
• TTFT、延迟分位数、请求时长之和及实际 wall time：首 token 延迟、P50/P90 等分位延迟、各请求耗时总和以及真实墙钟时间。

关键语义约定：未知值一律为null，不会被打成 0。失败和部分运行仍然可见，但不能称为完整评测——只有全部计划单元格都有明确终止结果时，complete才为真。这一约定在 report.py 的 metric 实现 中体现为：accuracy = correct / total，其分母是全部计划题数（"failures and unanswered count as incorrect"），即失败与未答都按错误计入，而不是按"已作答数"计算。

从源码看，95% 置信区间采用 Wilson 区间（见 report.py 的 wilson 函数），对二项比例给出不因样本量为 0 而退化的区间。延迟分位数通过percentile()对排序后的延迟列表做线性插值得到（report.py），缺失时返回None。

用量对账：reconcile-usage修正已知费用

对已终止的真实（live）运行，可执行：

vllm-sr benchmark reconcile-usage RUN_ID

该命令从保留的 SSE 计量（retained SSE usage）离线追加一条幂等、带版本的费用更正：

• 零模型调用：只重算已保存的用量回执，不发起任何推理请求；
• 报告、比较和后续导出都采用更正后的派生计量（derived accounting）；
• 原始调用/结果详情回执及冻结 manifest 保持不变，更正不修改原始证据；
• 报告会暴露更正哈希、时间、核验/变更条数和新旧已知费用；
• 证据缺失或冲突仍保持unknown，不会变成 0 或成为节省率证据。

对账支持的场景是单模型调用以及有明确单次调用凭据的直接 MoM（Mixture of Models）调用。源码在 accounting.py 的 reconcile_usage 中逐条核验保存的流与终止调用回执是否一致（done、finish_reason、raw_usage、model），并生成包含evidence_sha256、verified_call_count、corrected_call_count、新旧已知花费的 artifact，通过store.append_accounting_correction持久化。对 MoM 目标，只有当inference_call_count == 1、没有model_usage、且selected_model与回执模型一致时才允许用最终响应流推算费用；不能用最终响应流推算多次内部调用的费用。更正后的视图由effective_calls统一提供（accounting.py），原始调用详情接口则保留原始回执。

CLI 侧命令定义见 benchmark.py 的 reconcile-usage 命令，其注释明确："Append an offline accounting correction from saved streams; no inference."

cache_neutral_cost_usd：反事实 token 等价费用

cache_neutral_cost_usd是一个反事实指标：将全部输入 token 按冻结的普通输入单价（frozen fresh-input rate）计价，再加上输出费用，得到不依赖缓存折扣的 token 等价费用。

使用场景：连续运行时缓存会被预热，实测的四类 token 费用会因 cached_input 折扣而偏低。比较时同时查看它相对同一基线的节省率和实测四类 token 费用，就能识别缓存预热的影响。务必记住：

• 它不是账单费用（not billed spend）；
• 也不是实测的"无缓存执行"（not a measured cache-free execution）；
• 比较中该指标仅覆盖 subject 调用（subject-only）。

源码实现见 accounting.py 的 cache_neutral_cost：按model_usage分段累加，每段输入按冻结的普通输入单价计价再加输出；用量缺失时返回None。报告侧在 report.py 的 metric 中只有当所有 subject 调用都具备该值时才会汇总。

完整分数：九个基准的固定权重

完整 sr-bench 总分使用固定基准权重，且九项全部完整时才输出总分：

源码中这些权重定义在 contracts.py 的 BENCHMARK_WEIGHTS，键名为mmlu-pro、simpleqa-verified、gpqa-diamond、hle、arc-agi-2、livecodebench、scicode、terminal-bench-2.1、tau3。任一基准缺失时，子集宏平均仍然是子集结果，带有自己的 subset 标签，不能被当作完整分数。运行不包含全部九个基准就没有完整 sr-bench 分数（参见 index.md 中的规模表：smoke 共 36 题、quick/dev 共 740 题、standard/holdout 共 3,183 题，均为每个目标的整题任务数）。

基线选择与节省率：不逐题选优，不臆造节省

基线（baseline）是在相同完整题集上按相同汇总规则选出的最强已测单模型，不是逐题选优的 oracle。选择规则：

1. 精确加权质量（weighted quality）相同出现并列时，优先选择主体费用完整且最低的单模型；
2. 仍并列则按固定目标 ID排序；
3. 报告会列出全部并列最强模型。

若任一并列最强模型的费用不完整（total cost incomplete），则节省率保持未知。节省率公式为：

节省率 = 100 × (1 − 候选主体成本 / 基线主体成本)

要求完整兼容的计量。比较同时报告total_cost_saving_percent（含 subject 与 judge/simulator 全部调用）与subject_cost_saving_percent（仅主体调用），两者都用同一公式与同一完整计量范围（见 report.py 的比较构建）；cache-neutral 比较则保持 subject-only。

两条重要告诫：

• 小样本只能判断方向；要声称"质量持平（non-inferiority）"，需要预先确定的非劣界值（prespecified margin）和保留集（holdout）置信区间；
• 自托管 token 等价价格不是 GPU 账单节省——换算出的价格不能直接等同于 GPU 发票上的省钱。

配对质量差值：保守的 Hoeffding 区间

配对比较的默认质量区间是基于独立题目差值的保守加权 Hoeffding 区间。其特点：

• 即使所有配对结果完全相同（全部打平），或全部答错，区间也不会退化为零；
• 分层 bootstrap 区间保留为诊断值：小样本产生[0, 0]不能证明能力持平；
• 两种区间都不包含最强基线选择、调优选择或数据污染带来的不确定性。

源码实现见 report.py 的 paired_conservative_interval：对每条独立配对差值（值域[-1, 1]）施加 Hoeffding 不等式，半径sqrt(2·log(2/α)·Σ(w_b²/n_b))，区间以quality_delta_ci95_method: weighted-paired-hoeffding标注；bootstrap 用固定种子20260918重采样 2,000 次，取[samples[49], samples[1949]]作为 95% 诊断区间（report.py）。

另外，报告还给出wins / losses / ties计数与逐题微平均差值micro_quality_delta，方便判断提升的广度。

连续性（continuity）与缓存读取指标

英文原版 results.md 进一步补充了连续性模块（中文版标注 outdated，以下内容以仓库英文原版与源码为准）：

• multi_request_tasks：含两次及以上 subject 请求的任务数（如 agent、coding 任务）；每任务请求按存储顺序读取，不触发 judge/simulator；
• model_switches：连续两次请求所选模型不同视为一次切换，同时给出每任务均值与最大值；decision_changed_tasks统计路由决策发生变化的任务数；
• switched_accuracy/unswitched_accuracy：按"发生切换/未切换"分组统计准确率，失败计入错误；
• 没有所选模型的请求记为unknown而不是切换，连续已知选择之间才累计切换，unknown_model_requests记录它；Fusion、Confidence、Workflows 或 fallback 下一次请求多次推理调用会隐藏自身模型序列，其任务只计入multi_inference_tasks；
• 切换被当作事实报告，而非惩罚（"A switch is reported as a fact, not a penalty"）。

实现见 report.py 的 continuity 函数：对每个 case 的请求序列用_observed_model取观察模型，统计_changes（相邻模型不同的次数），并按请求阶段（phase）归因model_switches_by_phase。

会话相关：目标默认stateless；session_mode: session_aware的目标在 live 运行的每次 subject 调用上发送不透明的x-session-id（同一 case 内保持一致，跨运行/case/目标不同），judge/simulator 调用不带该头，subject 回执以session_id保留；Router 侧会话策略需在配置中启用（参见 tasks-and-targets.md 的session_mode说明）。回执还包含phase与phase_source：MoM 目标下 sr-bench 请求 Router debug 响应头读取会话策略阶段，router表示响应含x-vsr-session-phase，request表示 sr-bench 从最近消息推导tool_loop/user_turn。

缓存读取指标（cache_read_ratio、cache_read_call_count）只统计 provider 实际上报了缓存字段（cache_read_reported=true，显式 0 也算上报）的 subject 调用，因此缺失的缓存用量保持未知，而不是变成零命中观察；流式调用中cache_read_usage保留上报过缓存读取的规范化用量事件，后续省略缓存字段的事件不会抹掉该观察（实现见 report.py 的 cache_read_metrics）。旧运行缺少这些字段时，缺失 phase 归入unknown，缓存读取比率为 null 且样本数为 0。

使用 Dashboard：从 Runs 到 Compare iterations

Dashboard 默认进入Runs页，可按名称、模型、状态和模式筛选任务，每行展示完成分母、失败数、持久化更新时间（persisted update time）和目标类型。只读轮询（read-only polling）在断网后会自动恢复，并会发现 CLI 新建的任务；关闭或刷新页面不会重启任务——运行由共享 worker 持续推进。

在Create evaluation中：

1. 先选择smoke、quick或standard三种 profile（standard 使用 holdout split，与 quick 不相交）；
2. 再勾选一个或多个已准备 benchmark，或使用Select all benchmarks；
3. 可用来源必须具有相同的 profile、seed 和 split；
4. Review plan只从这些冻结来源组合完整 benchmark 题组：不下载数据、不重新抽样、不调用模型。完整使用一个来源时保留原数据集身份；选择子集或组合多个来源时生成可复用的冻结数据集；存在冲突时明确拒绝，不静默合并（"Conflicting selections are rejected rather than silently merged"）。

采样、预算以及请求和任务限制通过表单控件设置，无需编辑 JSON；已注册目标的固定参数会覆盖运行默认值并保持只读。Route preview还可填写可选的会话（session）和对话上下文（conversation context），以检查依赖会话状态的路由。启动前先审阅冻结计划；审阅计划不生成模型答案。

Datasets支持搜索、按 profile/benchmark 筛选和分页。点击数据集可查看题目、benchmark 覆盖和学科分组；题目每页 25 条，可按 benchmark、学科和文本搜索；打开题目可阅读任务说明与选项，固定来源（pinned source）可用时还能展示代码和 agent 任务的完整输入。参考答案、隐藏测试和工具凭据不会返回；来源信息和哈希默认折叠；点击Evaluate dataset可复用所选数据。注意两条纪律：

• 能浏览公开题目不代表题目从未被见过——不要用 standard 题目调优；
• 各 profile 的总题量是其已准备题集的题数之和，题集可能重叠，因此该数值不是去重题数，也不是所选运行的实际分母。

运行详情分为Results、Questions、Calls、Evidence和Recipe五个视图：先看汇总结果，再按需查看逐题响应、计量（accounting）和冻结配置。题目结果和调用列表每次最多读取 100 条、每页展示 25 条，搜索仅作用于已加载记录，完整调用内容按需读取；汇总指标始终来自完整报告，不受详情条数影响。恢复候选、排除原因和子任务也有分页。

运行期间，即使没有新题完成，已用时间也会继续更新。正在执行的调用展示当前阶段、已用时间、最近记录的响应活动和接收字节数，帮助区分"长响应"与"已停止接收数据"。但流活动不能证明答案质量，也不是计费 token 数——token 和费用仍需完整的用量回执。CLI 可用同一条命令读取相同活动：

vllm-sr benchmark show RUN_ID --calls --active # --after 与 --limit 控制每页游标与条数

Compare iterations分两步：

1. 先选择存在兼容结果的 live 单模型基线；
2. 再勾选任意数量的可比较候选（没有兼容候选的基线不会出现在选项中）。

搜索可缩小候选范围，Select all会跨页选择当前搜索匹配的可用运行。更换基线会清空候选；更改任何选择后旧比较结果会隐藏，直到再次点击Compare runs——服务端仍会逐一核验成对结果（"The service still validates every paired outcome"）。

候选按创建时间排序，选择保存在 URL 中，不限制为两轮优化（可多轮迭代）。质量/成本图和迭代图配合成对置信区间、节省率、token、延迟和 wall time 展示；结果卡片分页，图表和 CSV、JSON 导出保留全部选中比较。判定准则：点估计为正但区间跨零时，不能认定已经提升（"A positive estimate with an interval spanning zero is not proof of a gain"）。

MoM 目标的 Frozen recipes

MoM 目标可由运维人员在注册信息中设置capture_recipe: true，并固定config_hash和规范的preview_url。worker 仅在以下条件同时满足时捕获脱敏 recipe（redacted recipe projection）：

• 捕获前后，生成的配置与生效运行时哈希都匹配冻结目标；
• 源配置 ETag 保持不变。

Frozen recipes支持查看、下载及核对采集时间、投影哈希；真实调用会独立确认实际配置哈希。下载内容省略部署连接信息和凭据，是 recipe 产物，不是完整可部署配置；旧运行没有快照时明确显示"不可用"，而不会借用后续配置。

Run events：事件快照与分页读取

Run events按时间从早到晚显示可读事件，支持类型筛选，每页展示 25 条。打开详情最多读取 1,000 条，后续记录需点击Load more events显式加载。接口不提供总数，因此满页时只标注"已加载数量"；筛选也仅覆盖已加载事件。事件是快照：Refresh evidence重新读取快照，运行进度仍独立轮询更新；读取失败会保留游标和已有记录。重评分（regrade）和训练矩阵导出复用已保存证据，不产生模型调用（live 之外的离线操作均如此，参见 iterate.md）。

显式恢复未完成任务

worker 停止或响应丢失，不等于可以自动重试生成。必须先核对持久化派发（dispatches）与调用记录。在已终止任务中使用Review recovery plan，它区分两种范围：

• Continue undispatched cases：只允许继续从未派发过模型调用的单元格；
• Retry known failed cases as new attempts：需要明确选择单元格，并确认新尝试及额外费用；调用状态或费用不明确、已有完整答案、已被其他恢复任务领取的单元格均排除。

恢复会创建独立子任务（child run）并保留原任务。子任务的分母、进度和成本只覆盖本次选择的范围；原任务已知费用单独显示在 lineage 中。子任务完成不等于原 benchmark 已全量完成。Dashboard 在当前标签页保存待确认的完整恢复请求，响应丢失时复用同一幂等键；不会自动重试模型生成或重启 worker。

CLI 命令流（对应 benchmark.py 的 recover-plan / recover 命令）：

vllm-sr benchmark recover-plan RUN_ID --mode undispatched --output recovery.json # 核对可继续/排除的单元格；可用 selected_cells 指定已审核的子集。 vllm-sr benchmark recover RUN_ID --plan recovery.json --idempotency-key recovery-1

若使用--mode failed，最后一步还需--acknowledge-new-attempt（源码中acknowledge_new_attempt为is_flag=True，用于"Authorize new paid attempts for the exact reviewed failed cells"）。对账不确定的提交时，必须复用相同计划、单元格和幂等键——recover会校验计划中的parent_run_id与目标运行一致，防止跨运行误用计划。

配套阅读

• sr-bench 1.0 总览：规模表与三种 profile 的题量分布
• Connect the shared worker：CLI 与 Dashboard 共享的 worker 服务
• Prepare reusable tasks and targets：数据集冻结、历史保留与目标注册
• Plan and run：manifest 冻结、run 命令与限额
• Iterate with preview, replay and live evaluation：预览、重放与 live 评测循环
• 报告与对账实现：report.py、accounting.py、contracts.py

• 后端
• API网关
• 模型推理服务
• AI Agent