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

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

### 2.1 实施级下钻文档

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

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

这些规格故意把“设计完成”和“硬件已支持”分开。凡涉及新 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. 三个工程包的依赖

```mermaid
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 的优先级。