195、NPU的编译器开发：文档编写与API设计

昨晚调试一个客户反馈的模型部署问题，折腾到凌晨两点。现象很诡异：同样的模型，在内部测试板上跑得好好的，到了客户那边就报“算子参数校验失败”。我盯着日志看了半小时，最后发现是客户调用API时传了一个uint8的tensor，但文档里写的是“支持int8输入”——这两个类型在C语言层面差了整整一个符号位。客户照着文档写代码，文档没写清楚符号性，编译器后端也没做类型自动转换，结果就是炸了。

这个坑让我意识到，NPU编译器开发中，文档和API设计不是“写完代码再补”的收尾工作，而是决定整个工具链可用性的核心环节。今天聊聊这块的经验。

文档不是写给编译器看的，是写给调试器看的

很多做编译器开发的兄弟有个误区：觉得文档就是API参考手册，把函数签名、参数类型列出来就完事了。实际上，NPU编译器的文档最该解决的是“当模型跑不起来时，用户怎么定位问题”。

我见过最糟糕的文档写法：只写“input_tensor: 输入张量，类型为int8”。用户传了个float32进来，编译器报错“类型不匹配”，用户翻遍文档找不到float32的支持说明，最后怀疑是编译器bug。其实文档里写了“仅支持int8”，但藏在第47页的表格里。

好的做法：在API文档的每个参数说明后面，直接给出“常见错误示例”和“调试建议”。比如：

input_tensor: 输入张量 - 支持类型: int8, uint8, int16 (注意：float32需先量化，参考quantize()接口) - 常见错误: 传入float32会导致E1001错误，此时应检