# Accelerator Qualification Lab：把“能跑”变成可验收决策

这个实验对应国产与异构 AI 加速器高级专题。你会用 G0–G5 六道门，把三个虚构候选的材料收敛为 `NO_GO`、`CONDITIONAL` 或 `QUALIFIED`，并解释每个结论由哪条证据支撑。

> **证据边界：fictional / synthetic / CPU-only。** 程序只用 Python 标准库检查“材料是否齐全、门是否通过、决策是否符合规则”。它不连接任何真实加速器，不导入厂商 SDK，也不会验证算子、Profiler、集合通信、Kubernetes、性能、功耗或可靠性。输出中的 Qualified 只表示“虚构候选在虚构合同下通过了教具规则”，绝不代表任何真实产品通过验收。

## 你要完成什么

- 预计用时：60–90 分钟；
- 前置知识：会运行 Python、能读 JSON，理解模型质量、P95 延迟和故障恢复的基本含义；
- 最终交付：一份机器可读 JSON、一份 Markdown 决策摘要，以及你对一个候选的 gate-by-gate 复核；
- 完成标准：不靠平均分掩盖硬门失败，能区分 No-Go、Conditional 与 Qualified，并能说明 CPU-only 证据不能证明什么。

## 六道门不是六个平均分

| Gate | 必答问题 | 最低证据 | 本教具的决策作用 |
|---|---|---|---|
| G0 版本身份 | 测的到底是哪一套东西？ | 镜像、框架/扩展、驱动、固件、SDK、算子/编译器、集合通信、Profiler、工作负载摘要 | 失败即 No-Go |
| G1 正确性与质量 | 结果还是同一个任务吗？ | 黄金用例、数值容差、任务质量、关键算子与安全门 | 失败即 No-Go |
| G2 原生执行路径 | 关键路径真的在加速器上吗？ | Profiler、算子覆盖、CPU fallback、graph break | 失败即 No-Go |
| G3 可比性能与成本 | 比较合同公平且结果满足 SLO 吗？ | 同模型/负载/质量/失败口径、预热、重复、原始样本与成本边界 | 失败即 No-Go |
| G4 分布式与拓扑 | 目标规模下通信正确、可扩展、可恢复吗？ | rank 映射、集合通信正确性、scale efficiency、故障恢复 | 需要分布式时失败即 No-Go；单设备可 Not Required |
| G5 平台与运维 | 能调度、能看见、能隔离、能回滚吗？ | 资源分配、健康闭环、遥测对齐、故障注入与回滚 | 仅 G5 存在可控缺口时可 Conditional |

这里故意不用总分。一个候选即使吞吐很好，只要黄金用例失败或关键路径暗中回退 CPU，仍然是 No-Go。Conditional 也不是“差不多能上”，而是 G0–G4 已经通过、剩余运维缺口可隔离，并且进入真实项目后还必须补负责人、截止时间和回滚方案。

## 一次运行

在本目录执行：

```bash
python3 qualification_lab.py
python3 -m unittest -v
```

只查看某个候选或输出 Markdown：

```bash
python3 qualification_lab.py --candidate fictional-candidate-b
python3 qualification_lab.py --format markdown
```

把可审计附件写到临时目录：

```bash
python3 qualification_lab.py --output-dir /tmp/accelerator-qualification-evidence
```

生成的 `qualification-results.json` 保存结构化 gate、reason code 和决策；`qualification-results.md` 适合人工评审。默认不在教材目录制造产物。

## 练习 1：先预测，再运行

先读 `qualification_cases.json`，不要急着执行程序。为 A、B、C 各写一句预测，格式如下：

```text
Candidate __ should be ______ because gate __ has ______ evidence.
```

然后运行程序，对照实际输出。交付物是一张三行表：`candidate / predicted / actual / decisive evidence`。

验收标准：

- A 的结论必须引用 G1 和 G2，而不是“性能可能不好”；
- B 的结论必须说明 G0–G4 已通过，不能因为 G5 缺口直接写 Qualified；
- C 的 Qualified 必须带上 “synthetic / CPU-only contract” 边界。

常见错误：看到 `slo_passed=true` 就忽略质量与 fallback。答案片段：`Performance evidence cannot compensate for failed correctness or native-path gates.`

## 练习 2：制造一次决策跃迁

复制 JSON 到临时路径，任选一个变化：

1. 删除 C 的 `firmware` 版本；
2. 把 C 的 `same_comparison_contract` 改成 `false`；
3. 把 B 缺失的 health、telemetry 和 rollback 三项补为 `true`，同时补相应虚构 evidence path。

用 `--cases /tmp/your-cases.json` 重跑，记录 before / change / after / gate reason。

验收标准：删除身份字段必须 fail-closed；不公平比较必须在 G3 被拒绝；只有把 B 的全部 G5 缺口关掉后，它才从 Conditional 变成 Qualified。

如果卡住：先只运行 `python3 qualification_lab.py --format json`，在 `results[].gates[].reasons` 中找稳定的 reason code，再回到 `evaluate_g0`–`evaluate_g5` 对照输入字段。

## 练习 3：映射到真实 PoC，但不要伪造证据

选择你有权测试的真实环境，用作品集模板建立三份文件：

1. `accelerator-portability-inventory.template.yaml`：列出框架、算子、编译器、集合通信、调度和遥测依赖；
2. `accelerator-telemetry-crosswalk.template.yaml`：校准健康、利用率、显存、功耗、互联、错误和 fallback 的语义；
3. `accelerator-qualification-and-acceptance.template.md`：引用真实 manifest、原始样本、Profiler 和故障证据，形成评审结论。

验收标准：每个 PASS 都有路径与 checksum；每个 N/A 都有适用性解释；每个 Conditional 条件都有 owner、deadline 和 containment；任何没有真实执行的部分都标为 Unproven，而不是 Pass。

## 文件地图

- `qualification_cases.json`：三个虚构候选及其预期决策；
- `qualification_lab.py`：G0–G5 的 fail-closed 评估与报告生成；
- `test_qualification_lab.py`：决策、负例、Not Required 和证据边界回归测试；
- `../../portfolio-kit/`：把教具升级成真实 PoC 证据的模板。

## 本实验不能证明什么

- 不能证明任何国产或海外芯片、加速卡、服务器、云实例的兼容性或性能；
- 不能证明驱动、固件、SDK、框架扩展、算子/编译器和集合通信版本彼此兼容；
- 不能证明关键算子真的在设备执行，也不能发现真实 CPU fallback、同步或 graph break；
- 不能证明吞吐、TTFT、ITL、E2E、功耗、TCO 和 scale efficiency；
- 不能证明 device plugin、资源 API、健康隔离、遥测、发布、回滚或 on-call 已经工作；
- 不能代替厂商支持边界、安全/合规评审和业务方验收。

真正的升级路径不是把 JSON 里的 `false` 手动改成 `true`，而是在授权环境中执行同一证据合同：冻结版本与工作负载，保留原始数据和 checksum，用 Profiler 证明原生路径，注入设备/通信/调度故障，再由应用、平台、安全和运维共同签字。