cogito/calculet-npu-research-archive
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
calculet-npu-research-archive/reports/Calculet-NPU-新模型适配工程Runbook-20260802.md
T

16 KiB
Raw Permalink Blame History

Calculet NPU 新模型适配工程 Runbook

日期：2026-08-02
目标：从一个可公开/合法使用的模型权重，生成可复现、可验证、可服务化的 Calculet NPU 版本

1. 两阶段策略

第一阶段选择 1-7B decoder-only dense 模型，batch 1、单芯粒优先、context 4K/8K。目的不是追求业务最大模型，而是闭环 ONNX、量化、compiler、calbin、Runtime、llama.cpp、golden 和恢复。

第二阶段再进入 MoE、双芯粒、40K context、batch 4/8/16。否则一次引入 router、expert kernel、TP 通信、巨型 KV 和 dynamic D2D，任何失败都难以归因。

单芯粒产物本身是 C3，必须由厂商 compiler 生成；不能在当前双芯粒 calbin 上只传 chipId=0。

2. 项目角色和职责

角色 负责 不可转交的签字
Model owner 模型许可、任务质量、参考实现 参考输出和质量门槛
Export owner HF->ONNX、dynamic/static shape ONNX checker、数值一致性
Quant owner 校准集、quant config、误差 量化质量报告
Compiler/vendor op lowering、kernel、partition、calbin 可复现编译和兼容矩阵
Runtime owner runner、buffer/KV、错误恢复 golden、soak、故障注入
Serving owner tokenizer、scheduler、API、metrics 端到端/并发/SLA
Release owner hash、SBOM、签名、回滚 release manifest

每个 Gate 有唯一 owner；“厂商支持”不是 owner 名称，必须写到个人/团队和版本交付日期。

3. 工作目录合同

model-port/<MODEL_ID>/
  00-source/
    source-manifest.json
    hf-config/
    weights/                  # 可用引用/对象存储，不要求 Git
  01-reference/
    environment.lock
    prompts.jsonl
    tokens.jsonl
    outputs.jsonl
    tensor-golden/
  02-onnx/
    export-config.yaml
    model.onnx
    model.onnx.data
    onnx-report.json
  03-quant/
    calibration-manifest.jsonl
    quant-config.yaml
    quant-report.json
  04-compiler/
    compiler-manifest.json
    compile-config.yaml
    compile.sh
    logs/
  05-calbin/
    package/
    validation.json
    file-sha256.txt
  06-runtime/
    runner-config.yaml
    correctness/
    performance/
    faults/
  07-serving/
    service-manifest.json
    conformance/
    soak/
  08-release/
    release-manifest.json
    decision.md

所有 JSON/YAML 中的路径使用相对路径或内容寻址 URI。绝对编译机路径只保留在受控原始日志，不写进发布 API。

4. Gate 0：模型立项

4.1 输入

  • 模型仓库 URL、revision commit、权重文件 hash。
  • license、商用/再分发约束、依赖许可证。
  • 目标任务、并发、TTFT/TPOT、context、吞吐、功耗和精度要求。
  • 架构 config：层数、hidden、heads/KV heads、head dim、FFN、vocab、RoPE、norm、activation。

4.2 复杂度打分

特征 0 分 1 分 3 分
架构 标准 dense decoder 小变体 MoE/multimodal/custom code
attention MHA/GQA 已有 sliding window 新 mask/latent attention
activation/norm 已支持 参数变化 自定义算子
context <=8K <=40K >40K/dynamic
deployment B1 单芯粒 双芯粒 batch>1/多模型

首个模型建议总分 <=3。Gate 0 输出 source-manifest.json 和 go/no-go；没有许可与产品 SLA 不进入导出。

4.3 source manifest

{
  "schema":"calculet-model-source/v1",
  "model_id":"vendor/name@revision",
  "license":"SPDX-ID",
  "files":[{"path":"config.json","bytes":0,"sha256":"..."}],
  "architecture":{"layers":32,"hidden":4096,"q_heads":32,"kv_heads":8,"head_dim":128},
  "tokenizer":{"vocab_size":0,"sha256":"..."},
  "targets":{"context":[4096,8192],"batch":[1],"chips":[1]}
}

5. Gate 1：CPU/GPU 参考基线

5.1 环境固定

记录 OS、Python、PyTorch/Transformers、CUDA（如有）、模型 revision、tokenizer hash、dtype、seed、determinism flags。保存 lock file 和容器 digest。

命令模板（版本仅占位，由项目锁定）：

python -m pip freeze > 01-reference/environment.lock
sha256sum 00-source/hf-config/* > 01-reference/source-sha256.txt
python tools/generate_reference.py \
  --model-dir 00-source \
  --prompts 01-reference/prompts.jsonl \
  --dtype float32 \
  --greedy \
  --dump-logits \
  --output 01-reference/outputs.jsonl

5.2 prompt corpus

每条记录含 sample_id、原始 text（或受控引用）、token ids、attention mask、position ids、expected generated token ids。覆盖：空/最短、特殊 token、多语种、代码、数字、重复、最大 context 附近、非法超长。

5.3 输出

  • FP32 和 BF16 参考 logits/token 序列。
  • 每层或关键边界 tensor golden（输入/输出 hash + stats）。
  • 模型任务质量基线、perplexity/accuracy。
  • tokenizer conformance：encode/decode round-trip、BOS/EOS/chat template。

Gate 1 失败条件：同一环境/seed 不能稳定复现；tokenizer 资产不唯一；模型自定义代码来源未审计。

6. Gate 2：ONNX 导出

6.1 图边界

至少生成两个逻辑 profile：

prefill(input_ids[B,S], position_ids[B,S], empty/past KV)
  -> logits[B,1,V] + KV side effect/outputs

decode(input_ids[B,1], position_ids[B,1], past KV up to S-1)
  -> logits[B,1,V] + updated KV

当前 Calculet 图将 KV 交给 Runtime manager，最终 ONNX/calcc 如何把 96 个 past K/V 输入转为 KV scatter 是厂商编译契约。不可自行删除 KV 输入而不验证图语义。

6.2 export config

schema: calculet-onnx-export/v1
opset: VENDOR_CONFIRMED
external_data: true
constant_folding: false
profiles:
  prefill:
    input_ids: [1, 8192]
    position_ids: [1, 8192]
    valid_sequence_lengths: [1, 16, 128, 1024, 8191]
  decode:
    input_ids: [1, 1]
    position_ids: [1, 1]
    past_sequence_max: 8191
output:
  logits: [1, 1, VOCAB]

opset 不能凭通用 ONNX 最新版选择，必须用厂商支持矩阵。

6.3 验收命令模板

python -m onnx.checker 02-onnx/model.onnx
python tools/list_onnx_ops.py 02-onnx/model.onnx > 02-onnx/op-inventory.json
python tools/compare_reference_onnx.py \
  --reference 01-reference \
  --onnx 02-onnx/model.onnx \
  --matrix configs/shape-matrix.yaml \
  --output 02-onnx/onnx-report.json

若模型 >2 GiB，external data 文件必须进入 hash manifest。shape inference 后逐 input/output 比对 name/rank/dtype；禁止 exporter 自动改 tokenizer 或 position 逻辑。

6.4 Gate 2 门槛

  • ONNX checker success，external data 全部可解析。
  • op inventory 中每个 domain/opset 明确。
  • 100 个固定 prompt 的 greedy tokens 与 Gate 1 一致。
  • 关键 tensor 容差满足 FP32/BF16 基线。
  • prefill/decode 在所有边界 shape 上结果一致。

7. Gate 3：算子支持差距

生成 op-support.csv：

node_name,op_type,domain,opset,input_shapes,dtypes,quant,
support(C0-C4),lowering,kernel,fallback,owner,blocking_issue

分类：

  • Direct：厂商已有 op/kernel。
  • Fuse：必须通过 pass 与相邻 op 融合。
  • Decompose：可降成多个支持 op，但需性能/数值评估。
  • Custom C oplib/kernel：C3。
  • CPU fallback：若存在，必须显式标记并测性能；不允许静默 fallback。
  • Unsupported：阻断编译。

每个 unsupported op 给最小复现 ONNX、固定输入、reference output、shape/dtype 列表。厂商不能只回复“支持这个 op”，要返回最低 compiler/runtime 版本和 runnable case。

8. Gate 4：量化与校准

8.1 calibration manifest

每个样本记录 hash、domain、token count、tokenizer hash、许可/隐私审核。校准集与最终质量测试集必须分离。

8.2 quant config

schema: calculet-quant/v1
method: VENDOR_TOOL_METHOD
activation:
  default: int8
  granularity: per_tensor
  calibration: percentile
weights:
  default: int8
  group_size: null
overrides:
  lm_head: bfloat16
  router: bfloat16
  sensitive_layers: []
excluded_ops: []
seed: 1234

当前模型名中的 W8A8/W4AF16 不足以重建量化；必须拿到每 tensor/layer 的规则、scale/zero point 格式、packing、校准算法和工具版本。

8.3 敏感度流程

  1. 全 BF16 作为 compiler reference（若硬件/工具支持）。
  2. 全 W8A8 候选。
  3. 分组将 embedding、QKV/O、router、experts、lm_head 回退 BF16，测质量恢复。
  4. 在不敏感 expert/FFN 尝试 W4。
  5. 选择质量、参数大小、带宽、性能 Pareto 点。

Gate 4 同时报告 layer error 和任务质量；“校准成功”不等于业务质量达标。

9. Gate 5：compiler 可复现

9.1 compiler manifest

{
  "schema":"calculet-compiler/v1",
  "oci_digest":"sha256:...",
  "calcc_commit":"...",
  "tvm_commit":"...",
  "oplib":{"version":"...","sha256":"..."},
  "kernels":{"version":"...","sha256":"..."},
  "license_id":"...",
  "host":{"arch":"x86_64","driver_requirement":"..."}
}

9.2 compile config

model: ../02-onnx/model.onnx
onnx_sha256: REQUIRED
profiles:
  - name: prefill_b1_s8192
    batch: 1
    max_seq: 8192
    is_prefill: true
  - name: decode_b1_s8192
    batch: 1
    max_seq: 8192
    is_prefill: false
device:
  type: ks1
  chips: 1
  calcores_per_chip: 2
features:
  flash_attention: true
  one_token: true
  dynamic_d2d: false
quant_config: ../03-quant/quant-config.yaml
output: ../05-calbin/package

真实 CLI 参数由厂商交付后替换。任何 secret/license server 地址通过环境注入，不写进脚本/日志。

9.3 可复现门槛

  • 干净环境加载固定 OCI，单条 compile.sh 成功。
  • 同输入至少重编两次。若二进制非 deterministic，要解释时间戳/地址差异，并证明结构/golden 等价。
  • log 含所有 pass、fallback、warning、kernel selection、memory planner 和 partition 决策。
  • 不允许人工复制隐藏参数块或运行未记录命令完成打包。

10. Gate 6：calbin 静态验收

运行：

ruby calculet_package_validate.rb \
  --full-hash \
  --output 05-calbin/validation.json \
  05-calbin/package

检查细节见《calbin 产物字段字典与静态验收规范》。新 dense 单芯粒包预期：chip_nums=1、只含 chip0 mask、无跨芯粒 gather/reduce/D2D；但具体文件数量由 compiler schema 决定，不能硬套当前双芯粒 67 文件。

Gate 6 必须 ERROR=0；BLOCKED_REPRODUCIBILITY 也必须在新模型项目中清零。

11. Gate 7：独立 Runtime runner

11.1 runner 接口

calrt_runner inspect --calbin DIR
calrt_runner golden --calbin DIR --case CASE.json --output RESULT.json
calrt_runner stress --calbin DIR --matrix MATRIX.yaml --duration 1h
calrt_runner fault --calbin DIR --scenario wait-timeout

runner 不依赖 llama.cpp server，直接覆盖 CreateVDevice/CreateCalbin/configure/buffer/CSR/infer/Wait/KV/release。这样能区分 Runtime/calbin 问题和服务调度问题。

11.2 最小 golden sequence

  1. prefill 长度 1/16/17/128/1024/max-1。
  2. 每个 prefill 后 decode 1、32、256 token。
  3. 比较 final logits、greedy token 和 KV length。
  4. free sequence 后资源回收，再用同 seq id。
  5. 两 seq 交替，确认无串扰。

11.3 故障

缺 tensor、错 CSR、越界 slice、KV 满、submit busy、Wait timeout、CCU exception、reset 后 warmup。所有失败必须结构化返回，runner 不 abort()。

12. Gate 8：llama.cpp adapter

12.1 manifest 驱动

adapter 输入一个发布 manifest，不再 substring 找子图：

{
  "generation":1,
  "calbin_sha256":"...",
  "submodels":{
    "prefill_ids":{"exact_name":"...","input0":"inputs[0]","position":"inputs[1]","logits":"outputs[0]"},
    "decode":{"exact_name":"...","input0":"inputs[0]","position":"inputs[1]","logits":"outputs[0]"}
  },
  "csr":{"cur":"cur_seq_len[0]","total":"past_kv_cur_seq_len[0]"},
  "limits":{"batch":1,"context":8192,"vocab":VOCAB}
}

12.2 接入检查

  • tokenizer hash/vocab 与 logits 一致。
  • n_ctx/n_batch/n_ubatch/n_seq_max 都来自经过校验的 generation。
  • Runtime tensor layout 不在 adapter 中硬编码 D0。
  • buffer pool 独占 backing storage。
  • 所有 CalRT return code 上抛。
  • 当前不支持的 llama KV copy/shift/state 功能显式禁用。

12.3 一致性

比较独立 runner 与 server 对相同 token ids 的 logits；再比较 HTTP prompt 经 tokenizer 后的 token ids。第一步失败看 adapter/Runtime，第二步失败看 tokenizer/API template。

13. Gate 9：服务、负载和恢复

13.1 功能矩阵

stream/non-stream、greedy/sampling、stop token/string、logprobs、取消、deadline、超长拒绝、并发 slot、服务 shutdown。未实现的 KV state/prompt sharing 不出现在能力声明中。

13.2 性能矩阵

prompt 1/16/128/512/2K/4K/max-1，output 1/32/256，concurrency 1/2/4/8。batch=1 时并发只是排队/多 slot，不能称硬件 batch。

13.3 稳定性

1h 开发、8h 候选、24h 发布 soak。记录请求成功率、TTFT/TPOT P50/P99、RSS/device memory、KV/pool、温度/功耗、错误/reset。资源在稳定负载后不得单调增长。

14. Gate 10：发布和回滚

release-manifest.json 绑定：

source revision + tokenizer hashes
ONNX hash + export tool versions
calibration/quant hashes
compiler OCI/commits/oplib/kernel
calbin all-file hash manifest
Runtime/driver/firmware/chip compatibility
llama.cpp commit/image digest
correctness/perf/soak/fault report hashes
known limitations and disabled features
previous known-good generation

发布采用 immutable generation：先静态验证，再 configure/warmup/golden，原子切 alias。回滚不重新编译，直接指向上一已签名 generation；旧 generation 至少保留到新版本完成观察窗口。

15. Gate 状态表

Gate 输出 硬门槛 失败回到
G0 立项 source manifest 许可、目标、复杂度 停止/换模型
G1 参考 reference corpus 可复现 修环境/tokenizer
G2 ONNX model+report checker+数值 exporter/model wrapper
G3 op gap support matrix 无未知 op vendor/lowering
G4 quant quant report 质量达标 config/calibration
G5 compile calbin build logs 可重放 compiler/vendor
G6 static validation.json ERROR=0 packer/compiler
G7 runner golden/fault 正确+可恢复 Runtime/calbin
G8 adapter conformance runner=server adapter
G9 service perf/soak SLA+24h scheduler/adapter/calbin
G10 release signed manifest 可回滚 对应失败 Gate

16. 第一个项目建议拆票

Ticket 估算依赖 完成定义
M01 source/tokenizer freeze model owner manifest+hash+license
M02 reference harness model owner 100 prompt+tensor golden
M03 ONNX exporter export owner G2 pass
M04 op support matrix compiler/vendor 每 node 有处置
M05 quant calibration quant owner G4 pass
M06 compiler container vendor 离线 OCI+SBOM+license
M07 reproducible compile compiler/vendor clean build x2
M08 package validator Runtime owner G6 machine pass
M09 CalRT runner Runtime owner golden+fault
M10 async/stable adapter Runtime owner in-flight=1 24h
M11 service conformance serving owner API matrix
M12 performance report perf owner raw+summary+CI
M13 release/rollback release owner signed generations

17. 厂商 kickoff 必须带回的东西

  • 可加载 compiler OCI，不是远程截图。
  • 真实 compile command/config 和当前 Qwen3 重放样例。
  • ONNX/opset/dynamic shape 支持矩阵。
  • quant/calibration 工具、格式和样例。
  • 单芯粒 dense 示例 calbin、golden、Runtime runner。
  • kernel/fusion/partition/trace 文档和解析器。
  • calbin/Runtime/driver/firmware compatibility matrix。
  • batch、KV、timeout/reset 的精确接口契约。

缺前四项时可以继续做 reference/export/harness，但项目状态必须标记 BLOCKED_COMPILER，不能承诺新模型上线日期。

Reference in New Issue View Git Blame Copy Permalink