文档中心：每个模块怎么用，报告怎么验

1. 平台概览与证据链

平台不接触任何厂商 SDK 或工具链，只通过一个 zip 包契约交换数据： 平台下发输入向量与清单，客户在被测芯片、仿真器或软件栈上本地计算， 再原样回传产物；平台用 float64 双精度金标准独立复算并判定。

1.1 四个验证套件

1.2 四层证据链

1. 一次性挑战码：所有盲测包（单算子、模型级组合块、量化方案、PIM 链路、ONNX 子图） 在下载时绑定账号与有效期（默认 30 分钟）， 向量按挑战码现场派生；同一包只能成功提交一次，杜绝录答、转发与离线预计算。
2. 服务端金标准：盲测包只含 inputs/，期望输出只保存在服务端 sidecar 中； 客户无法通过「把答案抄进 outputs」通过判定。
3. Ed25519 签名 + 哈希链：报告使用 v2 信封签名，签名覆盖 data_hash / uid / report_id / prev_hash / signed_at / nonce / key_id； 每份报告链接到同一账号的前一份，形成不可静默删改的哈希链。
4. RFC 3161 时间戳：配置可信 TSA 后，报告时间戳由第三方签名； 未配置时诚实标注为本地时间（timestamp_trusted=false）。

1.3 账号、登录与配额

• 在官网登录后，验证页面会自动获得短期 Bearer Token；所有下载、提交、报告接口都需要 Authorization: Bearer <token>。
• 令牌内含账号标识、档位与每日配额，由官网 HMAC 签名，浏览器无法伪造。
• 默认配额：免费版 5 次/日，完整版 50 次/日；按本地自然日重置。
• POST /check 与 POST /graph/package 共用同一份配额； ONNX 解析（/graph/inspect）不计配额，但有频率限制。

2. 快速开始（单算子，5 步）

以下示例使用 curl 与 Python；任何能读写二进制文件的语言都可以完成同样流程。

步骤 1：确认身份与目录

export DBHOO_API="https://www.dbhoo.com/api/verify-suite"
export DBHOO_TOKEN="<登录官网后获取的令牌>"

curl -s "$DBHOO_API/catalog?task=operator" \
  | python -c "import json,sys; d=json.load(sys.stdin); print(d['total_cases'], 'cases'); print([o['op'] for o in d['operators']])"

步骤 2：下载盲测向量包

curl -s -D headers.txt -o pack.zip \
  -H "Authorization: Bearer $DBHOO_TOKEN" \
  "$DBHOO_API/package?suite=operator&ops=gemm,softmax"

响应头包含本次挑战信息：

步骤 3：解压并在本地计算

mkdir work && cd work
unzip -q ../pack.zip -d pack
cd pack
ls            # manifest.json  inputs/  （盲测包没有 expected/）

读取 manifest.json 中每个 case 的输入规格，按名称与形状读取 inputs/<case_id>__<tensor>.bin（小端、行优先）， 在你的硬件/仿真器上计算，再把结果写入 outputs/。

import json
import numpy as np
from pathlib import Path

m = json.loads(Path("manifest.json").read_text(encoding="utf-8"))
for case in m["cases"]:
    x = np.fromfile(case["input_files"]["x"]["file"], dtype="<f8")
    x = x.reshape(case["input_files"]["x"]["shape"])

    y = your_operator(x)          # ← 被测算法（硬件 / 仿真器）

    out = case["outputs"][0]      # 输出名以 manifest 为准
    y.astype("<f8").tofile(
        "outputs/" + case["case_id"] + "__" + out["name"] + ".bin")

步骤 4：原样回传判定

cd .. && (cd pack && zip -qr ../return.zip .) && cd ..
curl -s -X POST "$DBHOO_API/check" \
  -H "Authorization: Bearer $DBHOO_TOKEN" \
  -H "Content-Type: application/zip" \
  -H "X-Report-Title: GEMM+Softmax%20FPGA%20%E5%9B%9E%E5%BD%92" \
  --data-binary @return.zip

返回 JSON，其中 summary 为汇总，cases 为逐用例明细， report_id 为本次签名报告编号。

步骤 5：下载并验真报告

# HTML / PDF / JSON
curl -o report.html "$DBHOO_API/report/$RID?format=html"
curl -o report.json "$DBHOO_API/report/$RID?format=json"

# 在线复验（需登录）
curl -s -H "Authorization: Bearer $DBHOO_TOKEN" \
  "$DBHOO_API/report/$RID/verify"

离线验真方法见 第 9 节。

3. 单算子验证

适合 IP 核、指令集模拟器、算子库或 NPU 单算子单元的精度验收。一次提交可以覆盖一个或多个算子。

3.1 支持的算子

3.2 选择与下载

• 页面 Step 1 勾选算子（可按「大模型推理 / 大模型训练 / 端侧视觉」筛选）， 或直接调用 GET /package?suite=operator&ops=gemm,softmax。
• 下载必须登录；每个包都绑定一次性挑战码与当前账号。
• 下载动作本身不消耗配额；成功提交才计入配额。

3.3 回传与判定

• 保持目录结构原样打包；zip 根目录下应直接是 manifest.json、inputs/、outputs/。
• 同一个挑战包只能成功消费一次；判定失败（如格式错误）可以修正后用原包重试， 但报告一旦成功落库，挑战码即作废。
• 可选把同一输入重跑一次的结果写入 outputs_repeat/，平台据此检查确定性。
• 可选在包根目录提供 performance.json（耗时/周期/功耗）， 满足条件时会进入排行榜，详见 第 11 节。 平台不测量时间、不复算 GFLOPS，报告与榜单只原样记录客户自报值。

3.4 反作弊检查

4. 模型级验证（ONNX 子图）

上传一个 ONNX 模型，平台在 float64 环境中执行指定子图，生成输入与金标准， 客户只需在硬件上跑同一段子图并回传输出。

4.1 流程

1. 解析模型：POST /graph/inspect?nodes=a,b，请求体为 .onnx 原始字节。 返回节点、算子类型、输入/输出形状、initializer 列表，以及是否全部受支持。
2. 生成子图包：POST /graph/package?nodes=a,b&name=my_model，同样上传 ONNX。 服务端执行子图生成金标准 sidecar，返回 zip（含一次性挑战码与 graph_id）。 该接口消耗一次配额。
3. 本地计算：按 manifest 在硬件上执行同一段子图。
4. 回传：与单算子相同，POST /check；manifest 中 suite=graph， 挑战码自动绑定。

4.2 模型限制

4.3 支持的算子

Gemm、MatMul、Add、Sub、Mul、Div、Neg、Abs、Relu、Sigmoid、Tanh、Erf、Exp、Log、Sqrt、Pow、 Softmax、LogSoftmax、Cast、Identity、Constant、Concat、Reshape、Transpose、Flatten、Squeeze、Unsqueeze、 ReduceMean、ReduceSum、LayerNormalization、BatchNormalization、Conv、Gather、Shape、Slice、Where、Clip

4.4 组合块套件（不下发 ONNX）

也可以直接用 GET /package?suite=graph 下载内置的 Conv-BN-ReLU 与 Transformer Block 组合块，用法与单算子一致： 包同样按一次性挑战码派生，提交时需回传原包。

5. 量化验证

量化套件验证的是 量化方案本身：缩放因子、零点、per-channel 处理与累加位宽， 而不是只看反量化后的浮点结果。

5.1 四个方案

5.2 使用方法

curl -s -o quant.zip -H "Authorization: Bearer $DBHOO_TOKEN" \
  "$DBHOO_API/package?suite=quant&ops=quant_gemm_ptq,quant_gemm_pc"

包内输入通常包含 a_q、b_q（INT8 量化张量）以及 scale_a、scale_b、必要时 zero_point_b。 输出名与形状以 manifest 为准。提交同样走 POST /check。

5.3 判定重点

• 余弦相似度对幅度不敏感，因此量化套件同时校验 相对 L2 误差； 漏乘 scale 这类 1000 倍幅度错误会被识别。
• INT8 用例的 dtype 门限更宽（见 第 7 节），但累加通路必须是 INT32， 用 float 累加会在边界用例上暴露。

6. 向量包与回传契约

6.1 目录结构

<package>.zip
├── manifest.json
├── inputs/<case_id>__<tensor>.bin      小端、行优先，形状见 manifest
├── expected/<case_id>__<tensor>.bin    金标准（盲测包中没有此目录）
├── outputs/<case_id>__<tensor>.bin     客户产物，支持 .bin/.npy/.npz/.csv/.json
├── outputs_repeat/...                   可选：确定性复测
├── performance.json                     可选：耗时/周期/功耗
└── device_attestation.json              可选：设备证明（HIL 自动生成）

6.2 manifest 关键字段

6.3 输出文件命名

统一为 outputs/<case_id>__<输出名>.<扩展名>。例如 outputs/gemm_fp32_small_0001__output.bin。也允许直接放在 zip 根目录 （不带 outputs/），但推荐保持目录结构。

6.4 资源与体积限制

7. 判定口径与门限

每个用例输出四项指标：余弦相似度、相对 L2 误差、PSNR 与 最大绝对偏差。判定以余弦相似度（方向一致性）与相对 L2 误差（幅度相对偏差）为准， 启用 PSNR 门限时 PSNR 亦需达标；全部达标才算 PASS。最大绝对偏差用于定位离群点，不单独作为判定条件。

7.1 四种状态

• PASS 两项指标均达到 PASS 门限。
• WARN 至少一项落在 WARN 区间，且没有 FAIL。
• FAIL 任一项低于 FAIL 门限，或触发反作弊规则。
• UNTESTED 未找到该用例的合法产物；不计入通过率分母，也绝不判通过。

7.2 汇总字段

8. 报告中心

每次成功判定都会生成一份带签名的报告，保存在账号历史中，可下载 HTML 与 JSON（引擎生成 PDF 时另提供 PDF）。

8.1 历史与下载

报告 ID 形如 20261021_203015_001， 与账号绑定：使用其他账号的令牌读取会得到 404。

8.2 报告里的证据字段

9. 报告如何验证

验真分两种场景：报告持有方可用账号令牌调用在线复验； 不持有账号的第三方用公开公钥与离线 CLI 验签，无需登录、也不接触平台内部数据。 注意：在线复验按账号隔离，未登录调用会返回 401。

9.1 在线复验（推荐给报告接收方）

curl -s -H "Authorization: Bearer $DBHOO_TOKEN" \
  "$DBHOO_API/report/20261021_203015_001/verify"

返回字段：

9.2 离线 CLI 验真

平台提供独立工具 dbhoo-verify，只需 Python 与报告文件：

# 安装（在发布包内）
pip install ./tools/dbhoo-verify

# 验证 JSON / HTML / PDF
dbhoo-verify report.json --public-key official_public.key
dbhoo-verify report.html --public-key official_public.key
dbhoo-verify report.pdf  --public-key official_public.key --json

# 只提取完整性信息，不验签
dbhoo-verify report.json --extracting

退出码：0 = 通过，1 = 失败。 公钥可从 GET $DBHOO_API/trust/public-key 获取， 或直接使用平台发布的 official_public.key。

9.3 手工复核（不依赖本平台工具）

1. 从报告中取出除 integrity、badge_url、 badge_markdown、has_pdf 之外的全部字段；
2. 按 键名排序、UTF-8、紧凑分隔符 序列化为 JSON，计算 SHA-256， 应与 integrity.data_hash 相同；
3. 按同一规则序列化 integrity.signed_envelope， 用平台公钥验证 integrity.signature（Ed25519）；
4. 核对 signed_envelope 中的 uid、report_id、prev_hash、nonce 与报告其余字段一致；
5. 计算 SHA256(prev_hash + ":" + data_hash)， 应与 chain_hash 相同；
6. 如需核对时间，使用 integrity.timestamp 对应的 RFC 3161 token 与平台公布的 TSA 根证书验证。

9.4 常见失败原因

10. 设备证明与 HIL 自动化

tools/dbhoo_hil.py 把「下载 → 板卡执行 → 回传」固化为一命令， 适合硬件在环回归与 CI。设备证明协议用于把输出哈希与本次挑战码绑定到设备私钥。

10.1 基本用法

python tools/dbhoo_hil.py run \
  --api https://www.dbhoo.com/api/verify-suite \
  --suite operator --ops gemm --runner fpga-lab-01 \
  --cmd "python hw_runner.py {package} {outputs}"

--cmd 可用占位符：{package}（解压后的包目录）、 {outputs}（package/outputs）、{workdir}。 命令需返回 0，结果写入 {outputs}/<case_id>__<name>.bin。

10.2 模型级 HIL

python tools/dbhoo_hil.py run \
  --api https://www.dbhoo.com/api/verify-suite \
  --suite graph --onnx model.onnx --nodes gemm0,relu0 \
  --runner fpga-lab-01 --cmd "python hw_runner.py {package} {outputs}"

10.3 设备证明

板卡需对平台约定的 canonical message 签名：

dbhoo-device-attestation-v1\n
<nonce>\n
<output_hashes 的紧凑、键名排序 JSON>

HIL 会把原始 message 写入 {workdir}/device_attestation.message， 签名命令应读取该文件并输出：

{"device_id": "board-01", "algorithm": "Ed25519", "signature_b64": "..."}

python tools/dbhoo_hil.py run ... \
  --attest-cmd "python board_sign.py --in {message_file}" \
  --attest-pubkey "<设备根公钥 base64>"

• --attest-pubkey 会在回传前本地自检；签错对象会立即失败，而不是到服务端才被拒。
• 服务端配置设备根公钥后，会校验 nonce 绑定、重算输出哈希、验证签名； 任一不符则 verified=false，报告中保留失败原因。
• --attest-unsigned 只生成占位文件，用于联调，不构成设备证明。

10.4 退出码

0 全部通过；2 存在 FAIL 用例；1 运行、网络或解析错误。

11. CI、徽章与排行榜

11.1 把结果写入公开 CI 历史

仅持有共享密钥的自动化 Runner 可以写入公开历史。提交时需同时带：

dbhoo_hil.py 会自动携带上述头。普通手动提交即使伪造 X-CI-Run 也不会进入公开历史。

11.2 查询历史

curl -s "$DBHOO_API/ci/history?suite=operator&limit=20"
python tools/dbhoo_hil.py history --api "$DBHOO_API" --suite quant --limit 20

11.3 徽章

成功判定返回 badge_url 与 badge_markdown， 可嵌入 README 或官网。徽章查询参数带服务端签名， 手工改写 status/rate 会得到 403。

![DBHOO verified](https://www.dbhoo.com/api/verify-suite/badge.svg?status=pass&rate=100.00&cases=201&sig=...)

11.4 排行榜

• 完全自愿：提交包中需包含 submitter 与 performance.json， 且至少有 5 个已测用例。
• 只接受引擎验证结果；自报 / 自检结果没有资格。
• 排名顺序：通过率 → 自报 GFLOPS → 已测用例数；公开数据不含账号 ID。 性能值来自客户 performance.json，平台不测量、不复算。

12. API 参考

除公开接口外，均需 Authorization: Bearer <token>。 请求/响应均为 JSON，上传接口使用原始字节体。

12.1 端点

12.2 请求头

12.3 状态码

13. 错误码与常见问题

13.1 常见错误

13.2 为什么盲测包没有 expected/？

期望输出是判定依据。下发答案等于允许「把答案抄进 outputs」， 硬件完全不在环。金标准只保存在服务端，判定时现场计算。

13.3 一份报告能证明什么、不能证明什么？

• 能：在报告生成时刻，提交的产物由该账号上传；平台用对应版本的金标准独立计算， 给出的指标与结论未被篡改；报告属于该账号的证据链。
• 不能：不能证明产物一定来自声称的硬件（除非同时有已验签的设备证明）， 也不能证明未提交的用例也正确（看覆盖率）。

13.4 如何复现一次历史判定？

下载该报告的 JSON 与对应版本的向量包（baseline_version 必须一致）， 按 manifest 重新计算并比对用例指标；报告的 data_hash 同时锁定了当时的内容。

13.5 报告时间戳为什么显示本地时间？

平台只在配置了可信 TSA 时才请求第三方时间戳；未配置或 TSA 不可达时会诚实降级为本地时间， 并在 timestamp_trusted 标记为 false。这不会影响签名与哈希链的有效性。

14. PIM 算法验证（L1 契约）

PIM 套件验证的是客户的 PIM 实现（算法模型、驱动或仿真器）在冻结器件参数下的 数值一致性，不是芯片实测。期望值由服务端在 float64 中按同一契约复算，器件参数 锁死在服务端金标准内，客户端修改 manifest 不生效。首期只做 L1 算法级契约； PRO 闭源特性（INT4 GPTQ / LLM 专用算子）不在 L1 范围内。

14.1 冻结器件基准

14.2 三条链路

默认全选 36 条：3 条链路 × 4 种形状（64³ / 128³ / 128×256×64 非方阵 / 256³） × 3 种激励分布（int8uniform 覆盖满量程与 ADC 截断边界、 normal σ = 0.5、int8sparse 约 3 成零，覆盖稀疏累加与零跳过）。 在页面上按链路筛选下载时，包内用例按选中的链路线性递减（每条链路 12 条）。 形状从「ADC 基本不饱和」到「K 撑满阵列、深度饱和」，非方阵用例同时覆盖 M/N/K 不对称与分块边界。 输入张量为 a、b，噪声用例额外带 noise_z， 全部 float32；输出名固定为 output。

同一形状、同一分布的三条链路共用同一组 a / b，但 noise_z 按形状 + 分布各自派生：36 条用例对应 12 组独立 GEMM 激励和 12 组独立噪声样本， 差异全部来自链路本身，便于把问题定位到 ADC 还是噪声环节。回传时仍须 按用例逐条计算——跨用例复用同一份产物会被输出重复检测判 FAIL。

14.3 契约公式

C0 = A · B                    # fp32，行主序，alpha=1 / beta=0
q  = clamp(round_half_away(C0 / LSB), ±(2^(b-1)-1))   # 严格 mid-tread
C  = q · LSB                  # 仅 pim_gemm_adc6
C  = C0 + σ · z               # 仅 pim_gemm_noise，z 来自 inputs/<case>__noise_z.bin

14.4 判定：精度门限 + 器件契约检查

除通用 cos / rel-L2 门限（见 第 7 节）外，平台对 PIM 用例追加 结构性二值检查；它们不会被宽松的 rel-L2 门限掩盖（σ = 0.008 时漏加噪声的 rel-L2 仅约 1e-3，仍可能落在门限内）：

• adc_lsb_grid：输出必须落在 LSB = 0.5 的量化网格上（码值偏差 ≤ 1e-3）； 使用 range/(2^bits−1) 这类错误 LSB 会被直接判 FAIL。
• adc_code_range：输出峰值不得超过 15.5（对称码值上限 31 × LSB）， 缺少饱和钳位会被识别。
• noise_residual：‖(C − A·B) − σ·z‖ / ‖σ·z‖ ≤ 0.05； 漏加、时机错误或幅度错误都会被识别。

14.5 下载与提交

curl -s -o pim.zip -H "Authorization: Bearer $DBHOO_TOKEN" \
  "$DBHOO_API/package?suite=pim&ops=pim_gemm_adc6,pim_gemm_noise"

与其他套件一致：按次派生（a / b / noise_z 随 一次性挑战码重新生成）、盲测包不含 expected/、提交同样走 POST /check。报告会额外渲染只读的器件参数卡片与逐用例器件契约检查结果。