cogito/calculet-npu-research-archive

Fork 0

Files

T

cogito 98e6cadcb6 data: publish complete Calculet NPU research archive

2026-08-02 14:57:11 +08:00

22 KiB

Raw Blame History

Calculet NPU 推理引擎接口与 NPU 特性矩阵

日期：2026-08-02
核对对象：Runtime PDF、CalRT 0.7.6 头文件、libcalrt-linux-x86_64.so.0.7.6 动态符号、生产 llama.cpp fd9bd632

实施下钻：真实 C++ 签名、对象生命周期、0-29 错误码、调用前后置条件、reset/取消边界和三层服务 API 见《Calculet NPU Runtime API 精确契约与错误恢复手册》。本文矩阵负责“有没有/用没用”，手册负责“如何正确调用”。

1. 阅读方法

列定义：

“PDF”表示开发文档中是否出现及其签名口径。
“SDK”表示 0.7.6 已归档头文件中的真实声明。
“符号”表示 0.7.6 动态库是否导出可链接符号；inline 方法记为“不适用”。
“生产”表示当前 llama.cpp 整图路径是否调用。
“测试”区分已在样机首轮验证、仅静态核对、尚未隔离测试。
“状态”采用 C0 当前确认、C1 SDK 有但未接入、C2 可工程实现、C3 依赖厂商、C4 不支持/不应开放。

暴露面分为三层：

平面	面向对象	原则
推理面	普通服务请求	只暴露模型、请求、流式结果、取消和有限状态
观测面	运维/性能工程	只读、鉴权、限频、可审计；不泄露任意地址
特权控制面	设备管理员/厂商调试	reset、寄存器、任意内存、配置卸载；与业务 API 隔离

2. PDF 与 0.7.6 的版本差异

能力	PDF 口径	SDK 0.7.6 / 动态符号	结论
创建 calbin	第 7 页示例 `CreateParser`，第 15 页参考 `CreateCalbin`	`Calbin::CreateCalbin(path)`，有符号	PDF 内部版本漂移，以 0.7.6 头文件为准
枚举模型	`GetAllModels()` 返回 vector	返回 `std::vector<CalbinModel>*`，有符号	调用方必须处理指针和生命周期
按名称模型	`GetModelInfo(name)`	`GetModelByName(string_view)`，有符号	PDF 名称已变化
提交推理	PDF 写作返回 `void`	C++ `infer()` 返回 `CalrtError_e`，有符号	必须检查返回码
tensor 地址重定位	`RelocateTensorAddress`	头文件无声明，动态库无符号	C4，不得调用或承诺
设备内存分配	PDF `AllocDevMem`	同名接口无头文件、无动态符号	C4；底层另有 `CreateBuf`，但不是等价公共契约
parallel/fixed task	PDF 未充分说明	`EnableParallelMode`、`infer_with_fixed_task_type` 均存在符号	C1，需要隔离验证
golden/trace/KV 高级功能	PDF 不完整	SDK 与符号提供多项能力	C1，先构建测试再产品化

不能根据 PDF 编译示例猜测兼容性。构建时必须锁定 0.7.6 头文件和 SONAME，并在启动时核对 Runtime/driver/firmware/calbin 版本。

3. C API 完整矩阵

3.1 Calbin、设备和配置

C API	PDF	SDK 0.7.6	符号	生产	测试	状态	暴露建议
`create_calbin(cal_calbin*, path)`	有	有	有	C++ 等价路径	C++ 路径已测；C 包装未测	C1	内部模型管理，不直接给请求方
`get_models_number(calbin)`	有	有	有	无	静态核对	C1	观测面可返回净化后的模型数
`get_all_models(n,names,calbin)`	有	有	有	无	静态核对	C1	观测面；隐藏路径和内部子图名需权衡
`print_calbin(calbin)`	有	有	有	无	未测	C1	仅调试日志，不做公网 API
`create_device(device*)`	有	有	有	C++ 等价路径	C++ 已测	C1	进程启动内部调用
`create_device_by_type(device*,type)`	有	有，PCIe/USB/EMU	有	C++ 使用 PCIe	PCIe 已测	C1	类型由配置白名单控制
`configure_device(device,calbin)`	有	有	有	C++ 等价路径	已测	C1	模型控制面，串行化且鉴权
`reset_device_configuration(device)`	有	有	有	无	未测	C4	特权控制面，维护窗口使用
`reset_device(device)`	有	有	有	无	未测	C4	特权控制面；会影响所有请求

3.2 Buffer、tensor 和 CSR

C API	PDF	SDK	符号	生产	测试	状态	暴露建议
`create_input_buffer(...,model_name)`	有	有	有	C++ 等价路径	C++ 已测	C1	adapter 内部
`create_output_buffer(...,model_name)`	有	有	有	C++ 等价路径	C++ 已测	C1	adapter 内部
`get_input_tensor_num`	有	有	有	无	静态核对	C1	启动校验/观测面
`get_output_tensor_num`	有	有	有	无	静态核对	C1	启动校验/观测面
`get_input_tensor_by_name`	有	有	有	C++ 等价路径	C++ 已测	C1	adapter 内部，严格名称
`get_output_tensor_by_name`	有	有	有	C++ 等价路径	C++ 已测	C1	adapter 内部
`set_csr_by_name`	有	有，返回 void	有	C++ 等价路径	C++ 已测	C1	adapter 内部；建议 C++ 路径检查错误
`get_csr_value_by_name`	有	有	有	无	静态核对	C1	诊断和测试
`get_tensor_info`	有	有	有	无	静态核对	C1	启动 manifest 校验
`cal_copy_mem(host,tensor,size,direction)`	有	有	有	无	未测	C1	内部低级 API；校验方向与长度
`copy_mem_to_device_by_tensor_name`	有	有	有	C++ MapBuf/slice	等价能力已测	C1	推荐内部安全封装
`copy_mem_to_host_by_tensor_name`	有	有	有	C++ MapBuf/slice	等价能力已测	C1	推荐内部安全封装

3.3 推理与资源释放

C API	PDF	SDK	符号	生产	测试	状态	暴露建议
`block_infer_model`	有	有，返回 void	有	无	未测	C1	仅兼容层；产品内部优先 C++ 错误码
`non_block_infer_model`	有	有，返回 void	有	无	未测	C1	需要 buffer 所有权和 completion 管理
`wait_infer_done`	有	有，返回错误码	有	无	未测	C1	completion worker 内部
`release_device`	有	有	有	RAII 等价	进程退出路径部分覆盖	C1	生命周期管理内部
`release_calbin`	有	有	有	RAII 等价	已覆盖	C1	生命周期管理内部
`release_input_buffer`	有	有	有	RAII 等价	已覆盖	C1	生命周期管理内部
`release_output_buffer`	有	有	有	RAII 等价	已覆盖	C1	生命周期管理内部
`release_tensor_info`	有	有，C++ 引用参数	有	无	未测	C1	只在 C 包装兼容层使用

C API 的 blocking/nonblocking 提交均为 void，提交阶段无法直接返回详细错误；这也是生产适配层优先使用 C++ infer() 的理由。

4. C++ Calbin 和部署矩阵

C++ API	PDF	SDK	符号	生产	测试	状态	暴露建议
`Calbin::CreateCalbin(path)`	名称不同	有	有	有	已测	C0	模型管理内部；路径不可由普通用户任意传入
`GetCalbinBrief()`	有	有	有	无	静态核对	C1	观测面输出白名单字段
`GetModelByName(name)`	名称不同	有	有	有	已测	C0	改为 manifest 精确匹配
`GetAllModels()`	返回类型不同	有	有	有	已测	C0	仅启动校验，避免运行时 substring
`GetModelByType(type)`	文档不完整	有	有	无	静态核对	C1	启动发现；仍需唯一性检查
`GetPairedElf(model,chipMask)`	不完整	有	有	configure 内部	静态核对	C1	不对业务面暴露
`GetGlobalMemInfo()`	不完整	有	有	configure 内部	静态核对	C1	观测/静态检查
`GetLLMInfo()`	不完整	有	有	KV 初始化使用	已覆盖	C0	只读能力摘要可暴露
`Report()`	有	有	有	无	未测	C1	诊断日志
`GetStackLoc()`	不完整	有	有	无	静态核对	C1	内部调试
`Version()`	不完整	inline	不适用	无	静态核对	C1	健康/版本端点
`GetModelWorloadByName()`	不完整	有	有	无	未测	C1	拼写/单位需厂商确认后再观测
`GetGoldenInputByModelName()`	不完整	有	有	无	未测	C1	测试工具，不进业务面
`GetGoldenOutputByModelName()`	不完整	有	有	无	未测	C1	测试工具，不进业务面
`GetRootPath()`	不完整	inline	不适用	无	静态核对	C4	路径信息不对外
`configure(vdev,calbin,dumpIni)`	有	有两种重载	有	有，默认不 dump	已测	C0	模型控制面；配置期间拒绝新请求
`findModel(list,name)`	有	有	有	辅助路径/自有查找并存	已覆盖	C0	统一为 exact match
`RelocateTensorAddress(...)`	PDF 有	无	无	无	已确认缺失	C4	0.7.6 不支持
`AllocDevMem(...)`	PDF 有	无同名 API	无	无	已确认缺失	C4	不承诺；底层分配器不是替代公共 API

5. C++ buffer、tensor 与推理矩阵

C++ API/能力	PDF	SDK	符号	生产	测试	状态	暴露建议
`createInputBuf(model)`	有	有	有	每次 infer 创建	已测	C0	建立池化，禁止跨 in-flight job 复用
`createOutputBuf(model)`	有	有	有	每次 infer 创建	已测	C0	建立池化和 completion 生命周期
`CalrtTensor::MapBuf/UnMapBuf`	有	有	有	MapBuf 已用	已测	C0	adapter 内部；RAII 封装
`CalrtTensor::SliceTensor/UndoSlice`	有	有	有	prefill 输入/输出使用	已测	C0	校验 offset/size 并每次恢复
`CalrtTensor::Fill/CheckTensor`	有	有	部分模板/符号	少量辅助路径	部分覆盖	C1	单测/安全填充
`InputBuf::GetTensorByName`	有	有	有	有	已测	C0	manifest 驱动
`InputBuf::SliceTensorByName`	有	有	有	主要用 tensor slice	静态核对	C1	两套 slice 接口统一封装
`InputBuf::ResetTensorByName/ResetAllTensors`	不完整	有	有	无	未测	C1	buffer pool 归还时调用
`ModelHyperParameters::SetCsrByName`	有	有，返回错误码	有	有但忽略返回码	正常路径已测	C0，有缺陷	每次提交检查返回码
`GetCsrValueByName`	有	有	有	无	未测	C1	测试断言
`InputBuf::GetInputTransferTime`	不完整	有	有	adapter/服务有自有计时	部分覆盖	C0	观测面聚合，不按请求泄露内部地址
`OutputBuf::SliceTensorByName`	有	有	有	tensor slice 等价路径	已测	C0	输出长度严格校验
`OutputBuf::Reset/ResetAllTensors`	不完整	有	有	无	未测	C1	pool 复用前必测
`OutputBuf::GetStatus`	不完整	有五态	有	无	未测	C1	completion/metrics；CCU exception 单独计数
`OutputBuf::Wait()`	有	有，返回错误码	有	`infer()` 后立即调用，忽略返回码	正常路径已测	C0，有缺陷	completion worker 必须检查错误
`GetWaitTime/GetOutputTransferTime`	不完整	有	有	服务有相关指标	部分覆盖	C0	观测面直方图
`infer(vdev,model,in,out)`	PDF 返回 void	有，返回错误码	有	有但忽略返回码	正常路径已测	C0，有缺陷	检查 submit 错误；本身非阻塞
`infer_with_fixed_task_type(...,PING/PONG)`	未充分说明	有两种重载	有	无	未测	C1	仅实验开关；验证后由调度器控制

infer() 后立即 Wait() 是当前并发瓶颈之一。只删除 Wait() 会造成 backing vectors 和 KV 状态被并发覆盖；必须先完成 buffer/job/KV 所有权改造。

6. VirtualDevice 与设备能力矩阵

API	PDF	SDK	符号	生产	测试	状态	暴露建议
`CreateVDevice()` / `(type)`	有	有	有	`PCIE`	已测	C0	进程级单例
`GetDevice()`	不完整	inline	不适用	读寄存器/配置使用	已覆盖	C0	不跨业务边界返回裸指针
`GetDeviceInfo(idx)`	不完整	有但 idx 未用于多设备	inline	无	未测	C1	只读健康信息；不要推断多卡
`SubmitJob(...,forceEngineMode)`	不完整	有	有	`infer` 间接提交	默认模式已覆盖	C0/C1	默认 C0；强制 ping/pong 为 C1
`EnableParallelMode(bool)`	不完整	有	有	无	未测	C1	灰度实验，需证明调度和 buffer 安全
`EnableTraceDevice(bool)`	不完整	inline	不适用	无	未测	C1	观测面受控开关，限制磁盘/性能影响
`Status()`	有	有	有	启动使用	已测	C0	健康端点映射成稳定状态
`ReportDeviceInfo()`	有	有	有	无	未测	C1	诊断日志
`Shutdown()/Release()`	有	有	有	RAII/信号路径	部分覆盖	C1	有界 drain 后执行
`ReadMem/WriteMem(...,chipId)`	不完整	有	有	启动读固定寄存器	只读固定地址已覆盖	C4	任意访问仅特权控制面；白名单诊断可 C1
`ResetCCU()`	不完整	有	有	无	未测	C4	特权恢复，影响在途任务
`ResetConfiguration()`	有	有	有	无	未测	C4	模型控制面维护操作
`Reset()`	有	有	有	无	未测	C4	设备管理员；完整审计
`Type()`	不完整	有	有	无	未测	C1	健康/版本信息

0.7.6 头文件明确写着“temporary only support one physical device”，内部也是单个 shared_ptr<CalrtDevice>。因此它只证明一个物理设备内可指定 chip ID，不证明多个物理板可被一个 VirtualDevice 调度。多板为 C4/C3 厂商演进项。

7. 底层 CalrtDevice 矩阵

这些接口比 VirtualDevice 更接近驱动，只应出现在 Runtime、厂商调试器或严格封装的设备管理进程中。

能力组	SDK 示例	符号	当前使用/测试	状态	建议
创建/发现	`CreateDevice/CreatePCIeDevice/CreateEmuDevice/RefreshDevice`	有	VirtualDevice 间接使用	C1	Runtime 内部
内存保留	`RegisterDram/RegisterSramBuf/RegisterSyncUnit`	有/虚函数	configure 内部	C0 内部	不开放
配置模型	`Configure`、`SetConfigModel`、`GetCurrentCalbinOnDevice`	有	configure 使用	C0/C1	模型控制面封装
配置 dump	`DumpDeviceConfigureMetaData`、section dump	有/模板	未测	C1	观测面，净化路径/地址
DMA	`WriteToDevice/ReadFromDevice`	虚函数	Runtime buffer 间接使用	C0 内部	不开放任意地址
寄存器	`WriteReg/ReadReg`	虚函数	固定只读寄存器路径	C4	特权控制面，写操作默认禁用
动态分配	`CreateBuf/CreateSramBuf/ApplySyncUnit`	虚函数	configure/Runtime 内部	C1 内部	不是 PDF `AllocDevMem` 的兼容承诺
释放/清空	`Free*`、`ClearAllDevMem/ClearDynamicMem`	虚函数	无直接产品调用	C4	特权、维护窗口、全审计
复位	`Reset/ResetCCU`	有/虚函数	未测	C4	故障恢复状态机调用
固件/信息	`GetFirmwareInfo/GetDevInfo/GetReservedMem`	有/虚函数	部分启动检查	C1	只读观测面
电源	`SetPowerMode`	虚函数	未测	C1/C4	管理策略控制，不开放给请求方
内存用量	`GetMemoryUsage`	虚函数	未接入	C1	Prometheus 指标，先核对单位
队列计数	`GetNumPendingJob/GetNumFinishedJob/GetNumLeftJob`	有	未接入	C1	高价值观测指标
trace	`EnableTraceDevice`、trace data	有	未接入	C1	性能实验开关，不能永久全量开启

8. KV Manager 特性矩阵

API/能力	PDF	SDK 0.7.6	符号	生产	测试	状态	暴露建议
`KvManager(vdev,calbin)`	不完整	有	有	有	已测	C0	adapter 内部
`canAllocate(seq_num)`	不完整	有	有	无	未测	C1	admission control，优先接入
`Allocate(seq_info)`	不完整	有	有	Apply 间接/当前路径不清晰	部分覆盖	C1	显式资源状态机
`Apply(seq_info)`	不完整	有	有	有，外层无限重试	正常路径已测	C0，有缺陷	改成有界等待和 backpressure
`Free(seq_id)`	不完整	有	有	有	已覆盖	C0	请求结束可靠执行
`RemoveTokensAtEnd`	不完整	有	有	有	部分覆盖	C0	context rollback；补边界测试
`isExist/GetSeqLen`	不完整	有	有	部分使用	部分覆盖	C1	KV 诊断和断言
`canShift/DoShift`	不完整	有	有	adapter 的 shift 能力不完整	未充分测试	C1/C2	补齐 llama KV 语义后再开放
`Clear()`	不完整	有	有	有	部分覆盖	C0	模型/设备故障恢复的一部分
`seqPosMin/seqPosMax`	不完整	有	有	adapter 多个状态函数为空	未测	C2	补齐后供 scheduler 使用
batch KV layout	不完整	`KvBatchMode ONLY_VALID/ALL/AUTO`	相关符号有	当前 batch 1	未测	C1 + C3 calbin	需要 batch calbin 和一致调度
S8 V-cache	不完整	`KvDataType BF16/S8`	相关符号有	当前 BF16	未测	C1 + C3	需新产物、精度和容量 A/B

当前 llama KV adapter 的 copy/keep/add/div/state 等多项函数为空或不完整。SDK 存在 KV shift 不等于 llama.cpp 的 context shift、sequence copy 和共享 prompt 已经产品可用。

9. 类型、版本、调试与错误契约

API/类型	SDK 0.7.6	符号/生产	状态	建议
`calrt_version()`	返回 `const char *`	有符号；生产启动时读取	C0	健康端点返回规范化版本，保留原始字符串到日志
`PrimitiveTypeBitSize(type)`	dtype 位宽查询	有符号；生产切片计算使用	C0	shape/dtype/byte-size manifest 校验
`PrimitiveType`	U1/PRED/U8/S8/FP8/U16/S16/BF16/U32/S32/F32/U4/S4/F35/F16/F64/C64/C128 等枚举	类型定义；出现枚举不等于 kernel 支持	C1/C3	以具体 calbin/op 支持矩阵为准；头文件明确 U64/TF32 不支持
`CalbinTensorInfo_s`	name、shape、dtype、ping/pong 地址、size	parser/buffer 内部使用	C0/C1	启动时只读校验；地址不对外
`CalbinSection_s`	section type/place/path/offset/address/size/chip mask/tensors	configure 内部使用	C1	静态分析和受控 config dump；净化路径/地址
`CalbinLLM_s`	max batch、max sequence、KV spec	生产读取 max sequence/KV	C0	作为服务能力真实来源并与 manifest 交叉验证
`CalbinModel`	configured、acc type、chip mode、type/arch/name、sections、target chips	parser/configure 使用	C0/C1	精确模型选择和能力摘要；不允许调用方篡改
`TaskType_e`	PING/PONG/UNDEFINED	fixed-task API 使用	C1	仅 executor 内部；普通请求不选择 engine bank
`ChipArch_e`	SINGLE/MULTIPLE/UNDEFINED	task metadata	C1/C3	只是任务枚举，不证明任意单/多芯粒图可运行
`SetFullDebug/isFullDebug`	全局 debug 开关	均有符号；生产未启用	C1/C4	只在隔离诊断开启；评估性能、日志和敏感数据影响
`CalrtError_e`	0-29，含 memory/config/device/version/file/timeout/busy/crash/dtype/shape/direction	多数 C++ API 返回	C1/C2	映射为请求/模型/设备三级错误；保留原始 code，不以字符串猜测

错误码中 IncompatibleDriver、RequireNewerRT、InvalidCalbin 应在 load/configure 阶段阻断；DeviceBusy 可有界重试；Timeout、DeviceUnavailable、DeviceCrash 进入 drain/recovery。当前 adapter 将捕获的异常折叠为 -2，同时没有检查 CSR、submit 和 Wait 的直接返回码；需要保留原始 CalRT code 才能做可靠恢复。

10. 已确认但尚未产品化的高价值特性

按建议优先级：

优先级	特性	状态	前置条件	产品收益
P0	job pending/finished/left 计数	C1	核对线程安全和单位	发现排队与 Runtime 饱和
P0	output 五态和 CCU exception	C1	completion worker	正确异步与故障分类
P0	`canAllocate` + backpressure	C1/C2	KV 状态机重构	消除无限忙等
P1	ping/pong 双缓冲	C1/C2	独立 backing buffers	覆盖 H2D/NPU/D2H，提升吞吐
P1	parallel mode	C1	厂商确认语义 + 压测	增加 in-flight job
P1	trace/config dump	C1	数据格式和开销说明	找到长上下文和 D2D 瓶颈
P1	golden input/output	C1	产物包含有效 golden	自动化 calbin 冒烟
P2	batch KV layout	C1/C3	batch 4/8/16 calbin	continuous batching
P2	S8 V-cache	C1/C3	compiler/runtime/精度验证	减少长上下文容量和带宽
P2	单芯粒小模型	C3	单芯粒编译产物	多模型常驻和资源隔离
P3	NPU top-k/sampling	C3	新图/kernel/API	避免全 vocab logits D2H
P3	多物理板调度	C3/C4(0.7.6)	新 Runtime/设备抽象	横向扩展

11. 对外 API 设计建议

推理面

可以开放：model alias、input、sampling 参数、stream、request ID、cancel、使用量和标准错误。context/batch 上限由服务公布并验证。不要开放 calbin 路径、子模型名、chip ID、设备地址、ping/pong 或 CSR 名称。

观测面

建议开放只读指标：Runtime/driver/firmware/calbin hash、健康状态、队列深度、in-flight、KV slots、TTFT/TPOT、H2D/infer/D2H/sampling 分层直方图、CCU exception、reset 次数、温度/功耗/内存。地址、token、prompt、内部路径默认脱敏。

特权控制面

模型 load/unload、trace 开关、configuration reset、CCU/device reset、电源模式只允许管理员身份、互斥锁、drain、超时、审计和回滚。任意寄存器/内存读写不应做成常规 HTTP/RPC 能力；若厂商调试必须使用，采用地址白名单、只读优先和物理维护窗口。

12. 最终判断

0.7.6 已经提供非阻塞提交、ping/pong、parallel mode、队列状态、KV 管理、trace 和 per-chip 诊断的基础，但当前生产只使用了其中的同步整图子集。最现实的演进顺序是先修 buffer/KV/错误生命周期并接入观测，再验证 in-flight=2，随后通过厂商 batch calbin 实现 continuous batching。多板、expert parallel、NPU sampling 和新模型编译都不能仅凭现有 Runtime 头文件落地，属于 C3；多物理设备在 0.7.6 本身明确不支持。

22 KiB Raw Blame History Unescape Escape