254 lines
22 KiB
Markdown
254 lines
22 KiB
Markdown
# 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 本身明确不支持。
|