external-cannbot-ops-ascendc-api-best-practices

name	external-cannbot-ops-ascendc-api-best-practices
description	Ascend C API 使用最佳实践。提供算术、归约、数据搬运、Buffer管理、精度转换等 API 的正确用法和限制说明。触发：用户询问具体 API 用法（如"DataCopy 怎么用"）、遇到 API 参数错误或限制报错（如 repeatTimes、对齐问题）、需要查看 API 最佳实践或避坑指南时。
original-name	ascendc-api-best-practices
synced-from	https://gitcode.com/cann/cannbot-skills
synced-date	2026-05-26
synced-commit	ac5bbd2b4cf427d011874e11f8d1e8b1bef66eda
license	UNKNOWN

Ascend C API 最佳实践

---

API 类别索引

API 类别	涵盖 API	核心文档	典型场景
算术运算	Add, Sub, Mul, Div, Adds, Muls	api-arithmetic.md	Softmax, LayerNorm, 广播优化
归约操作	ReduceMax, ReduceSum	api-reduce.md, api-reduce-pattern.md	Softmax, LayerNorm, ReduceMean
数据搬运	DataCopy, DataCopyPad	api-datacopy.md	非对齐处理、多维搬运
Transpose / 重排	TransDataTo5HD, Gather	api-transpose.md	小通道 transpose、permute
Buffer 管理	TBuf, TQue	api-buffer.md	Double Buffer、内存规划
精度转换	Cast	api-precision.md	FP16/FP32 混合精度
流水线同步	EnQue, DeQue, SetFlag	api-pipeline.md	多级流水线、事件同步
Compare 256B对齐	Compare	api-restrictions.md	Padding 策略
repeatTime 限制	repeatTimes ≤ 255	api-repeat-limits.md	分批处理
API 限制	-	api-restrictions.md	禁用 API、编译期限制
Host Runtime	aclrtSetDevice, aclrtGetDeviceInfo	api-host-runtime.md	设备初始化、核数获取

---

场景索引

使用场景	相关文档	关键技巧
Softmax/LayerNorm	api-reduce.md, api-reduce-pattern.md, api-arithmetic.md	标量操作、广播优化、Buffer 复用
逐行处理（AR 模板）	api-arithmetic.md	Adds/Muls、节省 UB
Transpose / 重排	api-transpose.md	2维度 转置性能
多行广播（ARA 模板）	api-arithmetic.md	BinaryRepeatParams.src1RepStride=0、分批处理
半精度加减法（FP16/BF16 Add/Sub）	api-arithmetic.md, api-precision.md	默认升精度（除非 spec 明确同量级）、in-place 复用
非对齐数据	api-datacopy.md	DataCopyPad、32 字节对齐
混合精度	api-precision.md	FP16 输入 FP32 计算
流水线优化	api-pipeline.md, api-buffer.md

---

快速参考

完整的 API 参数速查表：api-quickref.md

---

⛔️ API 黑名单

禁止在生产代码中使用：

API	禁止原因	替代方案	文档
GlobalTensor::SetValue()	效率极低	DataCopyPad	api-datacopy.md
GlobalTensor::GetValue()	效率极低	DataCopyPad	api-datacopy.md

限制使用的 API：

API	限制条件	说明	文档
DataCopy(GM↔UB)	仅当搬运数据严格 32 字节对齐时允许使用	非对齐场景必须使用 DataCopyPad	api-datacopy.md

仅允许调试时使用：

// ✅ 调试：单点验证
AscendC::printf("debug: xGm[0]=%f\n", xGm.GetValue(0));