383 lines
18 KiB
Markdown
383 lines
18 KiB
Markdown
# Calculet NPU Runtime API 精确契约与错误恢复手册
|
||
|
||
日期：2026-08-02
|
||
真实 ABI 基线：归档的 CalRT 0.7.6 headers + `libcalrt-linux-x86_64.so.0.7.6`
|
||
|
||
## 1. 使用规则
|
||
|
||
1. 编译和实现以 0.7.6 头文件为准；PDF 用来解释概念，不能覆盖真实签名。
|
||
2. 所有 C++ `CalrtError_e` 都必须检查；`void` API 不能假设成功，需通过后续 status/health 验证。
|
||
3. `unique_ptr` 拥有 Calbin/VirtualDevice/InputBuf/OutputBuf；`CalbinModel*` 和 `CalrtTensor*` 是借用指针，不得跨所属对象生命周期。
|
||
4. 当前 `VirtualDevice` 只支持一个物理设备；per-chip 参数不代表多卡。
|
||
5. reset、任意寄存器/内存读写不属于普通业务 API。
|
||
|
||
## 2. PDF 与 SDK 关键不兼容
|
||
|
||
| 主题 | PDF 写法 | 0.7.6 真实写法 | 实现结论 |
|
||
| --- | --- | --- | --- |
|
||
| 创建解析器 | 第 7 页示例为 `CreateParser`，第 15 页 API 参考为 `CreateCalbin` | `Calbin::CreateCalbin(const std::string &)` | PDF 内部版本漂移；0.7.6 只能使用后者 |
|
||
| 全部模型 | 返回 vector | `std::vector<CalbinModel> *GetAllModels()` | 返回借用指针，判空并限制生命周期 |
|
||
| 按名找模型 | `GetModelInfo(name)` | `GetModelByName(std::string_view)` | exact name |
|
||
| infer 返回值 | 文档示例为 void | C++ 返回 `CalrtError_e` | 必须检查 |
|
||
| CSR setter | 第 28 页写作 `void SetCsrByName(...)` | 返回 `CalrtError_e` | 0.7.6 必须检查返回码 |
|
||
| VirtualDevice 物理设备数 | 第 29 页泛称 one or multiple | header 注释明确临时只支持一个，成员为单个 device | 多物理板保持 C4/C3 |
|
||
| tensor 重定位 | `RelocateTensorAddress` | header 和 SO 无接口 | C4，不得调用 |
|
||
| 设备内存分配 | `AllocDevMem` | 无同名公共接口 | C4，不用底层 `CreateBuf` 冒充 |
|
||
|
||
## 3. C++ 生命周期接口
|
||
|
||
### 3.1 创建、配置和销毁
|
||
|
||
真实签名：
|
||
|
||
```cpp
|
||
static std::unique_ptr<calrt::VirtualDevice>
|
||
calrt::VirtualDevice::CreateVDevice(calrt::CalrtDeviceType_e type);
|
||
|
||
static std::unique_ptr<calrt::Calbin>
|
||
calrt::Calbin::CreateCalbin(const std::string &path);
|
||
|
||
calrt::CalrtError_e
|
||
calrt::configure(calrt::VirtualDevice *vdev, calrt::Calbin *calbin,
|
||
bool dumpIni = false);
|
||
```
|
||
|
||
调用契约：
|
||
|
||
| 输入 | 前置条件 | 输出/后置条件 | 失败处理 |
|
||
| --- | --- | --- | --- |
|
||
| `type=PCIE` | driver/设备存在 | 返回非空 vdev，随后 `Status()==Success` | 判空；非 success 停止启动 |
|
||
| calbin path | 受信目录、目录完整、hash 已验证 | 返回 parser，内部模型借用指针有效 | 捕获异常/判空；不得 configure |
|
||
| configure | vdev/calbin 非空，设备未被其他 generation 使用 | 参数/命令/内存 reservation 部署完成 | 按错误分类回滚；不接流 |
|
||
| `dumpIni` | 仅诊断环境 | 可能写出地址/路径 | 生产默认 false，输出目录受控 |
|
||
|
||
销毁顺序必须是：停止 admission -> 等待所有 in-flight -> 销毁 buffer/KV manager -> reset configuration（仅按厂商契约）-> 销毁 Calbin -> Shutdown/Release vdev。不能先销毁 vdev 再让 OutputBuf 析构。
|
||
|
||
### 3.2 最小启动代码
|
||
|
||
```cpp
|
||
StatusOr<RuntimeObjects> open_runtime(const std::string &calbin_dir) {
|
||
auto vdev = calrt::VirtualDevice::CreateVDevice(calrt::PCIE);
|
||
if (!vdev) return Status::Unavailable("CreateVDevice returned null");
|
||
|
||
CAL_RETURN_IF_ERROR(check_rc(vdev->Status(), "vdev.Status"));
|
||
|
||
auto calbin = calrt::Calbin::CreateCalbin(calbin_dir);
|
||
if (!calbin) return Status::InvalidArtifact("CreateCalbin returned null");
|
||
|
||
CAL_RETURN_IF_ERROR(validate_calbin(*calbin));
|
||
CAL_RETURN_IF_ERROR(check_rc(calrt::configure(vdev.get(), calbin.get(), false),
|
||
"configure"));
|
||
CAL_RETURN_IF_ERROR(check_rc(vdev->Status(), "vdev.Status.after_configure"));
|
||
|
||
return RuntimeObjects{std::move(vdev), std::move(calbin)};
|
||
}
|
||
```
|
||
|
||
`CAL_RETURN_IF_ERROR` 是我方包装，不是 SDK API。
|
||
|
||
## 4. Calbin 查询精确契约
|
||
|
||
真实接口：
|
||
|
||
```cpp
|
||
CalrtCalbin &GetCalbinBrief();
|
||
CalbinModel *GetModelByName(std::string_view modelName);
|
||
std::vector<CalbinModel> *GetAllModels();
|
||
std::vector<CalbinModel *> GetModelByType(std::string_view type);
|
||
std::vector<Parsed_Elf_s> &GetPairedElf(const std::string &, const std::vector<uint32_t> &);
|
||
CalbinModel &GetGlobalMemInfo();
|
||
const CalbinLLM_s &GetLLMInfo() const;
|
||
void Report();
|
||
CalbinSectionPlace_e GetStackLoc(const std::string &modelName);
|
||
const std::string &Version() const;
|
||
uint64_t GetModelWorloadByName(const std::string &modelName);
|
||
std::vector<uint8_t> GetGoldenInputByModelName(const std::string &modelName);
|
||
std::vector<uint8_t> GetGoldenOutputByModelName(const std::string &modelName);
|
||
```
|
||
|
||
字段/生命周期规则：
|
||
|
||
- `GetAllModels()` 返回的 vector 由 Calbin 所有，禁止 delete，禁止在 Calbin 销毁后使用。
|
||
- `GetModelByName()` 返回借用指针；必须 exact match，null 是正常失败结果。
|
||
- `GetModelByType("prefill"/"decode"/"kv_update")` 只能用于发现，metadata 已知存在错误时不能取代 manifest。
|
||
- `GetLLMInfo()` 引用只在 Calbin 生命周期内有效；启动时复制必要的标量到 immutable generation。
|
||
- `GetGolden*()` 返回值由调用方拥有；空 vector 既可能是“无 golden”也可能是空数据，需结合产物 manifest 判定。
|
||
- `GetModelWorloadByName` 的拼写和单位需厂商确认，不能直接作为计费/容量口径。
|
||
|
||
启动校验至少断言：
|
||
|
||
```text
|
||
models != nullptr
|
||
expected exact model count and names
|
||
llm.max_batch_size == service expected batch
|
||
llm.max_seq_len == manifest max_seq
|
||
each required input/output/CSR exists
|
||
calbin Version is compatible with runtime/driver/firmware
|
||
golden hash agrees with signed manifest, when golden is required
|
||
```
|
||
|
||
## 5. Buffer 和 tensor 精确契约
|
||
|
||
### 5.1 创建
|
||
|
||
```cpp
|
||
std::unique_ptr<calrt::CalrtInputBuf> calrt::createInputBuf(const CalbinModel &model);
|
||
std::unique_ptr<calrt::CalrtOutputBuf> calrt::createOutputBuf(const CalbinModel &model);
|
||
```
|
||
|
||
创建后检查非空、`Name()`、`GetTensorNum()` 和 required tensor 集。对象不可复制；OutputBuf 也不可 move，所以 pool 应保存 `unique_ptr<BufferSlot>`，不把 OutputBuf 作为值移动。
|
||
|
||
### 5.2 tensor 获取与映射
|
||
|
||
```cpp
|
||
CalrtTensor *CalrtInputBuf::GetTensorByName(const std::string &);
|
||
CalrtTensor *CalrtOutputBuf::GetTensorByName(const std::string &);
|
||
CalrtError_e CalrtInputBuf::SliceTensorByName(void *src, const std::string &, uint64_t offset, uint64_t size);
|
||
CalrtError_e CalrtOutputBuf::SliceTensorByName(void *src, const std::string &, uint64_t offset, uint64_t size);
|
||
CalrtError_e ResetTensorByName(const std::string &);
|
||
void ResetAllTensors();
|
||
```
|
||
|
||
生产代码当前也直接使用 `CalrtTensor::MapBuf()` 和 `SliceTensor()`。安全包装必须保存：原始 ByteSize、当前 slice offset/size、host pointer、映射 generation。任何 slice 需满足：
|
||
|
||
```text
|
||
offset <= byte_size
|
||
size <= byte_size - offset
|
||
size > 0
|
||
host backing capacity >= size
|
||
offset and size satisfy Runtime alignment requirement (厂商确认)
|
||
```
|
||
|
||
归还 buffer pool 前调用 `ResetAllTensors()`；若使用 tensor 级 `SliceTensor()`，同时调用匹配的 `UndoSlice()`。两套 slice API 不混用，除非 runner 证明 reset 能完全恢复。
|
||
|
||
### 5.3 CSR
|
||
|
||
```cpp
|
||
uint32_t ModelHyperParameters_s::GetCsrValueByName(const std::string &csrName);
|
||
CalrtError_e ModelHyperParameters_s::SetCsrByName(const std::string &csrName,
|
||
uint32_t value);
|
||
```
|
||
|
||
当前图两个 CSR：
|
||
|
||
| 名称 | 当前代码值 | 业务含义 | 检查 |
|
||
| --- | --- | --- | --- |
|
||
| `cur_seq_len[0]` | 当前 ubatch token 数 | 本次有效 token 数 | `1..max_seq` |
|
||
| `past_kv_cur_seq_len[0]` | `past_len + cur_seq_len` | 推理后逻辑总长度 | `<=max_seq` |
|
||
|
||
`GetCsrValueByName()` 用 0 表示错误，因此无法区分合法 0 和失败；只用于测试回读，不能作为错误判定主路径。setter 返回值才是主契约。
|
||
|
||
## 6. 推理和完成精确契约
|
||
|
||
真实接口：
|
||
|
||
```cpp
|
||
CalrtError_e calrt::infer(VirtualDevice *, CalbinModel *,
|
||
CalrtInputBuf *, CalrtOutputBuf *);
|
||
|
||
CalrtError_e calrt::infer_with_fixed_task_type(
|
||
VirtualDevice *, CalbinModel *, CalrtInputBuf *, CalrtOutputBuf *, TaskType_e);
|
||
|
||
CalrtError_e CalrtOutputBuf::Wait();
|
||
CalrtOutputBufStatus_e CalrtOutputBuf::GetStatus();
|
||
float CalrtInputBuf::GetInputTransferTime();
|
||
float CalrtOutputBuf::GetWaitTime();
|
||
float CalrtOutputBuf::GetOutputTransferTime();
|
||
```
|
||
|
||
状态枚举：`DEFAULT -> PENDING -> RUNNING -> DONE`，异常终态为 `DONE_CCU_EXCEPTION`。头文件只说明语义，未保证每次轮询都观察到中间状态；产品不能依赖一定出现 PENDING/RUNNING。
|
||
|
||
单次调用规则：
|
||
|
||
1. infer 前 OutputBuf 必须属于当前 job 且不是未完成的旧 job。
|
||
2. infer 返回非 success：不得 Wait 这个“新 job”，不得交付输出；是否可复用 buffer 由错误类别决定。
|
||
3. infer 返回 success：buffer、model、vdev、host memory 在 Wait 终止前全部保持有效。
|
||
4. Wait success 后仍检查 `GetStatus()!=DONE_CCU_EXCEPTION`。
|
||
5. 只有完成 D2H、shape/size/数值检查后才交付结果和提交 KV。
|
||
6. `GetWaitTime()` 是 SDK 计时，不等同端到端 infer；单位虽注释/当前使用为 ms，仍应由 runner 校准。
|
||
|
||
## 7. PING/PONG 和 parallel mode
|
||
|
||
真实入口：
|
||
|
||
```cpp
|
||
void VirtualDevice::EnableParallelMode(bool switch_on);
|
||
void VirtualDevice::SubmitJob(CalbinModel *, CalrtInputBuf *, CalrtOutputBuf *,
|
||
TaskType_e forceEngineMode = UNDEFINED_TASK);
|
||
```
|
||
|
||
头文件注释只给出 `0=ping, 1=pong, -1=auto`。它没有给出：
|
||
|
||
- 最大 in-flight；
|
||
- 是否线程安全；
|
||
- 同一 OutputBuf 能否连续提交；
|
||
- H2D/compute/D2H 的重叠范围；
|
||
- 两个 engine 的顺序、公平性和异常隔离；
|
||
- parallel mode 开关时对在途任务的影响。
|
||
|
||
因此现状为 C1。隔离 runner 必须用两套完全独立 buffer/backing storage，强制 Ping/Pong，覆盖四种序列：P-P、Q-Q、P-Q、Q-P（P/Q 代表不同输入/seq），验证输出 hash、KV、状态和队列计数。未通过前产品使用普通 `infer()` 且 in-flight=1。
|
||
|
||
## 8. VirtualDevice/Device 的可用面
|
||
|
||
| 接口 | 等级 | 产品用途 | 禁止事项 |
|
||
| --- | --- | --- | --- |
|
||
| `Status()` | C0 | 启动/健康检查 | 不能替代实际 golden |
|
||
| `GetDeviceInfo(idx)` | C1 | 净化后版本信息 | idx 不证明多物理设备 |
|
||
| `EnableTraceDevice(bool)` | C1 | 受控性能实验 | 不永久开启；限制磁盘 |
|
||
| `ReadMem/WriteMem(...,chipId)` | C4 特权 | 厂商/故障诊断 | 不给普通 API 任意地址 |
|
||
| `ResetCCU()` | C4 特权 | 明确 CCU 故障恢复 | 不在普通请求失败时调用 |
|
||
| `ResetConfiguration()` | C4 特权 | drain 后卸载 generation | 未知影响范围前不自动化 |
|
||
| `Reset()` | C4 特权 | 最后级设备恢复 | 全审计、限频、防 reset storm |
|
||
| `Release()/Shutdown()` | C1 | 有界退出 | 不在 in-flight 时直接释放 |
|
||
|
||
0.7.6 header 明确写着临时仅支持一个物理设备，成员也是单个 `shared_ptr<CalrtDevice>`。`GetDeviceInfo(size_t idx)` 不得作为多卡枚举 API 使用。
|
||
|
||
## 9. KV Manager 精确契约
|
||
|
||
```cpp
|
||
bool canAllocate(size_t seq_num);
|
||
void Allocate(KvSeqInfo &seq_info);
|
||
void Free(KvSeqId seq_id);
|
||
void RemoveTokensAtEnd(KvSeqId seq_id, size_t n_tokens);
|
||
bool isExist(KvSeqId seq_id);
|
||
bool Apply(KvSeqInfo &seq_info);
|
||
void DoShift(KvBatchMode_e mode, std::vector<CalrtSeqShift> &seqs);
|
||
KvPos GetSeqLen(KvSeqId seq_id) const;
|
||
void Clear();
|
||
KvPos seqPosMin(KvSeqId seq_id) const;
|
||
KvPos seqPosMax(KvSeqId seq_id) const;
|
||
```
|
||
|
||
已知限制：
|
||
|
||
- `Allocate/Free/Remove/DoShift/Clear` 返回 void，失败传播语义不清晰。
|
||
- `Apply` 只有 bool，不提供错误码。
|
||
- `KvPos/KvSeqId` 为 int32，服务入口需限制范围。
|
||
- batch>1 的 K/V 布局不同；header 的 layout 说明不能替代 batch calbin。
|
||
- `KvBatchMode::ALL` 注释指向 16 lanes 和阈值建议，但不等于任意 B4/B8/B16 已可用。
|
||
- S8 明确只在字段说明中提到 V-cache 支持，具体 K/V 压缩范围和误差仍需厂商确认。
|
||
|
||
适配层最小支持表：
|
||
|
||
| llama KV 语义 | 当前实现 | 对外策略 |
|
||
| --- | --- | --- |
|
||
| clear | 委托 `Clear()` | C0，补恢复测试 |
|
||
| remove tail (`p1=-1`) | `RemoveTokensAtEnd` | C0 部分能力，补边界测试 |
|
||
| arbitrary remove | 返回 false | 明确不支持 |
|
||
| copy sequence | 空实现 | 禁用 prompt/KV copy |
|
||
| keep only sequence | 空实现 | 禁用 |
|
||
| add/div positions | 空实现 | 禁用 context shift 相关路径 |
|
||
| state save/load | 空实现 | 禁止宣称 session state 支持 |
|
||
| min/max | 委托 Runtime | C1，覆盖不存在/空/满场景 |
|
||
|
||
## 10. C API 精确签名和使用场景
|
||
|
||
C API 提供 `create_calbin/create_device/configure_device/create_*_buffer`、tensor 查询/复制、`block_infer_model/non_block_infer_model/wait_infer_done` 和 release。关键差异是两个 infer 提交函数返回 `void`。
|
||
|
||
因此：
|
||
|
||
- 新 C++ 产品路径继续优先使用 C++ API，以获得 submit 错误码。
|
||
- C API 只适合兼容/ABI runner，必须在每步检查可检查的返回值并在 infer 后检查 wait/status/health。
|
||
- `set_csr_by_name` 也是 void，无法替代 C++ CSR setter 的错误处理。
|
||
- `cal_copy_mem` 需要调用方保证 tensor 方向；优先使用按 tensor name 的安全复制接口。
|
||
- 所有 `release_*` 只接收 handle，没有幂等保证；包装层释放后立即清空自己的 handle。
|
||
|
||
## 11. 全部错误码与动作
|
||
|
||
| 值 | 名称 | 可重试 | 污染范围默认值 | 推荐动作 |
|
||
| --- | --- | --- | --- | --- |
|
||
| 0 | Success | - | 无 | 继续 |
|
||
| 1 | MemoryAllocation | 条件性 | job/generation | 降低 admission；持续则摘模型 |
|
||
| 2 | MemoryAlreadyRegistered | 否 | generation | 生命周期缺陷，drain |
|
||
| 3 | Assert | 否 | 未知 | 停止提交，保留证据 |
|
||
| 4 | InvalidValue | 否 | job | 拒绝输入/修代码 |
|
||
| 5 | InvalidConfiguration | 否 | generation | 回滚产物 |
|
||
| 6 | NoDevice | 条件性 | device | 503，等待设备/重启实例 |
|
||
| 7 | AlreadyConfigured | 否 | generation | 串行化 load/unload |
|
||
| 8 | IncompatibleDriver | 否 | instance | 升级 driver |
|
||
| 9 | RequireNewerRT | 否 | instance | 升级 Runtime |
|
||
| 10 | FileNotFound | 否 | artifact | 修复包/路径 |
|
||
| 11 | BrokenFile | 否 | artifact | hash/完整性失败 |
|
||
| 12 | InvalidELF | 否 | artifact | 编译器/兼容矩阵 |
|
||
| 13 | Timeout | 条件性 | submitted job/可能 generation | 停止 admission，按恢复流程 |
|
||
| 14 | OutOfRange | 否 | job | 本地边界应先拦截 |
|
||
| 15 | NotExpected | 否 | 未知 | 保守 drain |
|
||
| 16 | MissConfiguration | 否 | generation | 重新 configure/warmup |
|
||
| 17 | DeviceBusy | 是，有界 | job/queue | backoff，不立刻 reset |
|
||
| 18 | DeviceUnavailable | 条件性 | device | 摘流、恢复 |
|
||
| 19 | InvalidCalbin | 否 | artifact | 回滚旧 generation |
|
||
| 20 | Unknown | 否 | 未知 | 保守 drain，厂商分析 |
|
||
| 21 | InvalidDataType | 否 | artifact/job | manifest mismatch |
|
||
| 22 | InvalidDataShape | 否 | artifact/job | manifest mismatch |
|
||
| 23 | InvalidLibDep | 否 | instance/artifact | 修复依赖 |
|
||
| 24 | DeviceMapBroken | 否 | device | reset/restart |
|
||
| 25 | FailedSoftReset | 否 | device | 进程/设备级恢复 |
|
||
| 26 | FailedConnectServer | 条件性 | instance | 外部服务/EMU 路径诊断 |
|
||
| 27 | DeviceUnsupport | 否 | feature | 关闭特性 |
|
||
| 28 | DeviceCrash | 否 | device/generation | CCU fault 恢复 |
|
||
| 29 | WrongDirection | 否 | job/programming | 修正 copy 方向 |
|
||
|
||
“污染范围默认值”是我方保守策略，不是厂商保证。拿到官方 rollback/reset 语义后才可缩小。
|
||
|
||
## 12. 对外服务 API
|
||
|
||
### 12.1 普通推理面
|
||
|
||
```text
|
||
POST /v1/inference
|
||
request_id, model_alias, prompt/tokens, max_new_tokens,
|
||
sampling parameters, deadline_ms, stream
|
||
|
||
DELETE /v1/inference/{request_id}
|
||
只请求取消，不承诺立即停止硬件
|
||
|
||
GET /v1/models
|
||
alias, generation, context_limit, ready state
|
||
```
|
||
|
||
不得返回 calbin 路径、tensor 地址、寄存器、chip raw memory、内部子图名或未净化的 Runtime exception。
|
||
|
||
### 12.2 观测面
|
||
|
||
```text
|
||
GET /internal/health
|
||
GET /internal/runtime/version
|
||
GET /internal/models/{alias}/manifest
|
||
GET /metrics
|
||
POST /internal/trace/start (鉴权、时长和大小限制)
|
||
POST /internal/trace/stop
|
||
```
|
||
|
||
manifest 输出 hash、batch/context、dtype/shape、generation 和兼容版本，不输出绝对源路径/地址。
|
||
|
||
### 12.3 特权控制面
|
||
|
||
reset、configure、unload、原始内存/寄存器访问放在独立管理进程或 Unix socket；mTLS/RBAC、双人审批（生产环境）、完整审计、速率限制。默认不提供任意 `ReadMem/WriteMem` HTTP 代理。
|
||
|
||
## 13. API runner 测试矩阵
|
||
|
||
| 组 | 用例 | 通过条件 |
|
||
| --- | --- | --- |
|
||
| 生命周期 | 正常 load/configure/release 100 次 | 无泄漏、无 AlreadyConfigured |
|
||
| calbin | 缺文件、坏 ELF、错版本、错 hash | 在接流前失败，错误分类正确 |
|
||
| tensor | 缺名、错 dtype/rank/shape、零 size、越界 slice | 无设备提交、无越界 |
|
||
| CSR | 正常边界、未知名、总长溢出 | setter/本地校验可见失败 |
|
||
| infer | normal、submit busy/unavailable、Wait timeout/crash | job 状态和恢复符合表格 |
|
||
| status | 快速 DONE、PENDING->RUNNING->DONE、CCU exception | 不依赖必现中间态，异常不交付 |
|
||
| parallel | Auto/Ping/Pong 两任务排列 | 无串扰；未证明时不启用产品 |
|
||
| KV | allocate/apply/free/remove/clear、容量耗尽 | 无忙等，长度/资源可回收 |
|
||
| reset | CCU/config/device 分级恢复 | 厂商契约一致、warmup 后才 Ready |
|
||
| 安全 | 未授权 reset/read/write/trace | 403/拒绝且有审计 |
|
||
|
||
## 14. 厂商必须补齐的接口契约
|
||
|
||
1. 0.7.6 对应的正式 API 文档和完整 error-to-recovery 表。
|
||
2. `Wait()` timeout 行为、是否可取消、底层 DMA 完成判定。
|
||
3. OutputBuf status 原子性、状态转换和复用前置条件。
|
||
4. parallel/PING/PONG 时序、最大 in-flight、线程安全与关闭语义。
|
||
5. KV Apply 的 bool 失败原因和 submit/Wait 失败后的 KV 一致性。
|
||
6. 三种 reset 对在途任务、KV、参数、另一芯粒和 host mapping 的精确影响。
|
||
7. trace/counter 的 schema、单位、时钟域、开销和清零规则。
|
||
8. PDF-only API 的正式删除或版本归属，避免后续工程误用。
|