calculet-npu-research-archive/reports/Calculet-NPU-研究导航-20260802.md

Calculet NPU 研究导航

日期：2026-08-02

1. 当前基线，一页读懂

当前系统是“llama.cpp 服务层 + CalRT 0.7.6 预编译整图”：llama.cpp 处理 tokenizer、slot、请求调度和 CPU sampling；NPU 执行预编译 prefill/decode。当前 Qwen3-30B-A3B calbin 固定 batch 1、context 40960、双芯粒逐层 tensor parallel。Runtime 的非阻塞、ping/pong、parallel mode、队列状态、trace 和高级 KV 能力尚未完整接入。

最关键的现实边界：

• 当前只有一个物理 VirtualDevice；两个芯粒不等于两张板。
• infer() 虽非阻塞，生产紧接 Wait()，所以应用层同步。
• 当前模型目录 67 个文件，models 树 68 个文件，但只有一套模型。
• 参数 16.938 GiB，BF16 KV 3.750 GiB，当前 calbin batch 1。
• 新模型的 ONNX->calbin 工具链不在归档中，必须由厂商补齐。
• origin/runtime_replace/cal-llm 是历史演进方向，不是当前生产。

2. 建议阅读顺序

顺序	文档	用途
1	总体研究报告	先建立架构、风险、性能和优先级全貌
2	源码、Git 历史与驱动证据分析	查完整仓库、分支、stash、不可达实验、历史性能文件和驱动版本缺口
3	模型产物与内存映射	理解 calbin 文件、I/O、参数、KV、地址与静态命令流
4	推理引擎接口与 NPU 特性矩阵	查 C/C++ API、状态、测试覆盖和对外暴露建议
5	多芯粒多模型动态加载与并发演进设计	实施异步、batch、多模型、单芯粒、TP/EP/PP 演进
6	新模型适配与算子优化教程	启动 dense-first 新模型和 kernel/fusion 项目
7	证据索引与厂商确认清单	追溯每个结论，并形成厂商交付问题单
8	环境源码与算子优化分析	查首轮环境、源码问题和早期优化建议
9	接口测试报告	查样机首轮 API 实测结果和限制

下载、解包、OCI、模型和远端清理记录是资料来源与交接文档，不应和技术结论混读。原始归档已在本地验收，后续研究不需要连接或改动测试样机。

2.1 实施级下钻文档

上面的八份文档用于理解全貌；真正拆任务、写代码、跑实验时使用下面的实施规格：

实施文档	可直接得到的细节
异步执行器与生产稳定性实施规格	类/方法、锁顺序、buffer/KV 所有权、8 个 PR、15 个故障注入点
Runtime API 精确契约与错误恢复手册	0.7.6 真实签名、借用指针、0-29 错误码、三层 API 安全边界
calbin 产物字段字典与静态验收规范	67 文件角色、逐字段语义、跨文件规则、Gate A-F、拒绝条件
calbin 离线校验器	可执行 fast/full-hash 校验，输出机器可读 JSON
当前模型静态校验结果	对本地 67 文件实跑结果：pass_with_warnings、图数量和两项 metadata 告警
逐算子优化实验手册	GEMM/FA/KV/MoE/D2D/fusion/top-k 实验卡、数值和性能门槛
新模型适配工程 Runbook	G0-G10、目录合同、manifest、命令模板、角色与失败回退
性能压测故障注入与验收规范	正确 TTFT/TPOT、JSONL schema、open-loop 负载、soak/fault/pass-fail
Batch、KV 与多模型调度实现规格	lane/profile、continuous batching、KV 状态、load/unload、公平性和配置
双芯粒双模型独立服务可行性与实施规格	CalCore/芯粒边界、组合 calbin、chip session、双 worker、容量/并发/故障验收

这些规格故意把“设计完成”和“硬件已支持”分开。凡涉及新 calbin、kernel、partition、单芯粒、多模型常驻或 batch>1 的部分仍标 C3，直到厂商产物通过 runner。

3. 按问题查文档

问题	首选文档	具体章节
Git 历史是否完整、如何恢复	源码/Git/驱动证据分析	资产表、mirror clone、校验和不可达恢复
哪些改动未进入主线	源码/Git/驱动证据分析	未合入分支、当前 stash、过期 stash
驱动源码能否直接修改上线	源码/Git/驱动证据分析	0.9.0/1.0.0 版本断层和上游 Gitea 缺口
历史性能日志和失败实验在哪里	源码/Git/驱动证据分析	24 个恢复文件及 blob 索引
当前到底怎么跑	总体报告	构建、端到端链路、双芯粒分配
67/68 个文件是什么	模型产物与内存映射	产物分类、目录语义
参数/KV/内存够不够	模型产物与内存映射	参数映射、KV、reservation、地址并集
哪些 Runtime API 真存在	接口矩阵	PDF 差异、C API、C++ API、KV/设备
哪些接口可对外开放	接口矩阵	推理/观测/特权控制三平面
为什么现在没有并发	并发演进设计	当前执行模型、buffer 所有权
如何做 ping/pong	并发演进设计	异步 Phase A/B、状态机
如何做 batch/continuous batching	并发演进设计	B4/B8/B16、KV lane、调度
能否两芯粒各跑一个模型	并发演进设计	单芯粒小模型、多模型常驻
如何让两个模型各自完成 prefill/decode 并同时服务	双芯粒双模型实施规格	路径 A/B、内存预算、服务架构、Phase 0-5、Go/No-Go
如何动态加载卸载	并发演进设计	model generation、drain/load/unload
新模型从哪里开始	适配教程	dense-first 和阶段 0-11
如何做算子/fusion 优化	适配教程	算子盘点、kernel 优先级、A/B 方法
哪些事情必须找厂商	证据索引	V01-V60 确认清单
某个数字/结论从哪来	证据索引	B/R/K/M/C/A/I/P 编号
稳定性改造具体改哪些类	异步执行器实施规格	数据类型、锁、调用流、分阶段 PR
Runtime 返回码怎么处理	Runtime 精确契约	生命周期、infer、KV、错误码与恢复
新 calbin 包如何自动验收	calbin 字段字典+校验器	Gate A-F、严格拒绝、validation.json
某一类算子怎么设计实验	逐算子实验手册	第 8-15 节实验卡
新模型每一步交付什么	新模型 Runbook	G0-G10 和拆票表
正式 TTFT/TPOT 怎么采	性能规范	时钟、schema、矩阵和统计
B4/B8/B16 调度如何实现	Batch/KV 调度规格	profile、lane、KV、tick 和验收

4. 状态口径

所有后续 issue、设计和报告统一使用：

状态	使用规则
C0	当前源码、产物或实测直接证明
C1	0.7.6 头文件和动态符号存在，但生产未用或未测
C2	我方可用现有源码/接口实现，仍需开发和验收
C3	需要厂商 compiler/kernel/Runtime/新 calbin
C4	当前明确不支持，或只适合受控特权面

禁止把 C1 写成“已支持”，把 C2 写成“已有”，把 C3 写成“改几行服务代码即可”，或把两个芯粒写成多板。

5. 第一批三个工程包

WP1：稳定性、指标和 buffer 所有权

目标：让当前 batch 1 成为可靠基线，并为异步做准备。

工作：

• 修复 KV Apply 无限忙等，增加 canAllocate、有界排队、超时和 backpressure。
• 移除请求路径 abort()，建立 submit/KV/CCU/设备错误分类和 recovery。
• 补齐或显式禁用 CalRT KV adapter 的 seq copy/keep/add/div/state/context shift。
• 用版本化 manifest 精确匹配子模型，校验 context/batch/vocab/tensor/dtype。
• 去掉 D0=16 业务硬编码，改由 layout metadata 驱动。
• 修复非 CALRT 构建中的 cal_ctx metrics guard。
• 增加 queue/H2D/infer/D2H/BF16 conversion/sampling/KV/buffer 指标。
• 建立 JobContext 和独占 backing-memory buffer pool；先保持 in-flight=1。

完成条件：功能/错误注入回归通过，1h/8h/24h soak 无挂死、串扰或持续内存增长，基线指标可重复。

WP2：性能 harness 和 A/B 矩阵

目标：替换历史 CSV 的错误口径，得到可用于优化决策的数据。

工作：

• 重写客户端，真实记录请求发出、首 token、完成时间。
• 服务记录排队、tokenizer、batch prep、prefill/decode、postprocess/sampling。
• prompt 分桶 1/16/256/1K/2K/4K/8K/16K/32K/40K。
• output 固定 1/32/128/512，concurrency 1/2/4/8/16。
• 记录 P50/P90/P99、吞吐、功耗、温度、频率、内存和错误。
• 隔离验证 OutputBuf 状态、queue counters、golden、trace、parallel mode、fixed ping/pong。
• 对比 immediate Wait 与异步 in-flight=1，再决定是否灰度 in-flight=2。

完成条件：所有原始 JSONL/trace 可复算，三套时钟对齐，基线方差和热稳定范围明确，任何性能结论同时带正确性结果。

WP3：厂商工具链、batch calbin 和新 dense 模型

目标：取得自主模型适配所需供应链，并完成第一个新模型闭环。

工作：

• 以证据索引 V01-V60 发厂商问题单，优先 V01-V27、V33、V43-V48。
• 要求 Qwen3 编译容器、原 ONNX、完整命令、量化配置、golden 和兼容矩阵。
• 要求 decode batch 4/8/16 calbin，以及 single-chip 小模型示例。
• 选 1B-7B dense decoder-only，先 4K/8K context、W8A8/BF16 KV。
• 完成 HF->ONNX->量化->calbin->runner->llama.cpp->服务闭环。
• 在 batch1 正确后接 continuous batching；MoE/EP 放到 dense 闭环之后。

完成条件：固定容器可重放、所有产物有 hash/golden、单芯粒 batch1 和至少一档 batch>1 通过正确性/并发/24h soak/性能验收。

6. 三个工程包的依赖

flowchart LR
    WP1["WP1 稳定性、指标、buffer pool"] --> ASYNC["安全 async / ping-pong"]
    WP2["WP2 正确性能 harness"] --> ASYNC
    WP1 --> BATCH["continuous batching"]
    WP2 --> BATCH
    WP3["WP3 工具链、batch calbin、新 dense 模型"] --> BATCH
    WP3 --> NEW["新模型和算子优化"]
    WP2 --> NEW
    BATCH --> ADV["多模型、EP/PP、NPU sampling"]
    NEW --> ADV

WP1 和 WP2 可以并行；WP3 的厂商沟通也可立即启动。安全 async 依赖 WP1/2，continuous batching 同时依赖三者。多模型、EP/PP 和 NPU sampling 放在这些基线之后。

7. 建议两周启动节奏

时间	WP1	WP2	WP3
D1-D2	建 issue、冻结源码/模型版本	定义指标 schema 和 workload	发 V01-V60，标 P0/P1
D3-D5	KV/error/metrics guard 修复	新 harness + 单并发基线	选 dense 模型、准备 HF reference
D6-D8	JobContext/buffer pool，in-flight=1	长度/并发矩阵，trace 试验	ONNX/op inventory/厂商导入会
D9-D10	故障注入、1h soak	分析瓶颈和 A/B 计划	确认 batch/single-chip 交付时间
D11-D14	8h/24h soak、评审	固化 baseline dashboard	锁定 compiler container 验收脚本

8. 暂时不要做

• 不要直接删除 Wait() 开启并发。
• 不要在当前双芯粒 calbin 上用 chip ID 假装单芯粒模型。
• 不要把软件 slot 聚合称为硬件 batch。
• 不要手工拼接 calbin 或修改静态地址计划。
• 不要基于历史 CSV 的 TTFT 做优化收益承诺。
• 不要把 origin/runtime_replace 当成当前生产代码。
• 不要用 0.7.6 的 per-chip memory API 推断多物理板支持。
• 不要把任意寄存器/设备内存/reset 暴露给普通推理请求。

9. 研究完成后的直接决策

现在可以直接立项 WP1 和 WP2，并同时向厂商启动 WP3。第一个技术评审应只决定三件事：当前 batch1 稳定性修复范围、性能基线 schema、厂商必须交付的 P0 工具/产物。待这三项有结果后，再用数据决定 ping/pong、batch 4/8/16、单芯粒模型和 MoE partition 的优先级。