# 评测证据交付约定

这份约定解决一个最基本的问题：报告里的每个数字，别人怎样从结论一路查回实际音频和模型原始输出。

## 一条结论必须能这样回溯

```text
场景结论
  → 样本与实际送测音频（含时长、SHA）
  → 独立人工参考或明确标注的代理参考
  → 模型原始响应（不可覆盖）
  → 规范化后的可读 TXT / SRT / RTTM
  → 逐句、逐段或字符对齐明细
  → 样本指标
  → 场景汇总与排名
```

如果中间任何一层缺失，报告必须直接说明缺什么；不能用汇总分数掩盖断链。

## 普通读者在样本目录里看什么

| 想知道 | 首选入口 | 至少包含 |
|---|---|---|
| 测的音频是什么 | `README.md`、`audio/` | 来源、场景、实际送测文件、时长、许可和限制 |
| 正确答案是什么 | `reference/` | 人工逐字稿；有时间或说话人任务时附 SRT、RTTM、TextGrid 等 |
| 模型到底转了什么 | `outputs/<system>/` | 原始输出的可读副本、规范化 TXT、可用时附 SRT/VTT/RTTM |
| 分数为什么是这个值 | `outputs/<system>/SCORE_DETAILS.md` 或 `COMPARISON.md` | 指标公式、reference/prediction、替换/删除/插入、逐句或逐段对齐 |
| 跑了多久、用了什么资源 | `outputs/<system>/RUN.md` | 实际采集到的 wall time、inference time、RTF、硬件和峰值资源 |

`RUN.md` 不为未知字段填 `0`、`N/A` 或估算值。没有采集到的资源信息直接省略，并在汇总处写“本轮未采集，不参与比较”。

## 开发者可复算证据

机器产物统一放在样本的 `_machine/` 或冻结 run 目录中，并从人读入口回链：

- `request.*`：完整请求参数、adapter 和分段策略；
- `raw.*`：服务或模型未经修饰的返回；
- `normalized.*`：评分器实际读取的预测；
- `metrics.*`：样本级指标与 S/D/I 等计数；
- `alignment.*`：能定位到具体句、段或字符的错误对齐；
- `run.*`：开始/结束时间、耗时、硬件和软件环境；
- `resource.*`：只有实际采集时才创建，记录峰值显存/内存/CPU 等；
- `SHA256SUMS` 或 provenance：音频、reference、raw、评分配置和派生产物的身份。

JSON 是复算证据，不是普通读者唯一入口。正式报告和样本目录必须同时保留可读文本。

## HTML 报告的最低要求

每个发布结论至少提供一行“证据账本”，包含：

1. 样本名称、场景、时长和实际音频入口；
2. reference 类型及入口，明确 `人工 gold`、`代理参考` 或 `无 gold`；
3. 每个参评系统的原始输出和可读输出；
4. 样本级评分明细，能回答“哪一句、哪一段或哪些字符造成这个分数”；
5. 有记录时展示总耗时、推理耗时、RTF 和资源；未知项不展示数值；
6. 样本指标如何汇总成章节结论，以及证据等级为何是正式、暂定或工程事实。

报告可以先展示代表性入口，再链接完整 run；不能只链接一个汇总 JSON，也不能让读者猜文件之间的关系。

## 规则变化时

- 音频、模型 revision、请求提示、外部分段策略变化：新建 run，旧 raw 永久保留；
- CER/MER 归一化、时间戳容差或说话人评分规则变化：从冻结 raw 派生新版本，不重跑模型；
- 新报告必须指向自己实际使用的 metric/alignment 版本，不能让链接漂移到“最新版”；