系列目录 · 工程与交付 · Read in English
用户发来一张模型图：“这个节点你们不是支持吗？我在源码里搜到了。”
开发者也搜了一遍，果然有定义、有推理函数，甚至有测试文件。但模型还是停在后端。两边都没有说谎，只是“支持”这个词装进了不同含义。
一条算子路径上有多少道门
把模型编译想成一次接力，会更容易理解：
1 | 模型导入 → 语义表示 → 目标 lowering → 优化与合法化 |
在前端认识某个节点，只证明接住了第一棒。中间表示存在同名操作，只证明有地方存放它。后端如果没有合法配置、资源规划或最终编码，整条路径仍然断着。
因此支持声明应该以使用场景和参数范围为单位。即便某个算子有完整路径，也未必支持所有 rank、量化方式、广播、动态形状和属性组合。一个名字后面必须有条件。
所审阅的文档整理明确区分完整转换路径、编译器自动分解、特定融合，以及只存在定义却没有完整路径的情况。这比一张勾选表更难写，也更接近用户真正需要的答案。
分解支持为什么不是“理论上都行”
某个复杂算子在数学上可以由基本算子组成，只说明存在一种表达方式。要成为编译器支持，还需要实现实际的重写、保持类型与量化语义，并保证生成的基本算子组合本身合法。
例如一个标准化表达可以拆成归约、减法、乘法和倒数平方根。若倒数平方根只有部分输入域可用，或者中间张量超过资源限制，数学分解并不能让任意模型通过。
同样，某个激活可以在特定图模式中融合到生产者之后，不意味着它作为独立节点也有实现。支持矩阵应把“独立支持”和“满足模式条件时可消除或融合”写成不同状态。
这不是对能力的保守包装，而是让用户能够预测失败。
名称相似是最便宜，也最危险的推断
Gather 与其他索引操作可能共享“收集元素”的直觉，却有不同输出 shape 与索引解释。逐元素 Max、ReduceMax 与 MaxPool 都在找最大值，遍历集合却不同。自定义复合函数的名字，也不等于交换格式中存在同名标准节点。
因此支持文档要从节点语义出发，而不是字符串相似度。最有帮助的信息往往是“这个名字不要与哪个名字混淆”，以及“如果想表达这个计算，应使用哪种明确的基本图结构”。
当然，给出替代表达也必须有实现证据。不能在文档里用一个从未验证的手工分解替用户保证可编译。
编译成功为什么仍然可能精度错误
为调通管线而构造的临时量化参数，可以帮助验证导入、lowering 和代码生成是否连通。它们不必然对应真实模型的激活范围与权重尺度。
如果用户拿这种占位参数做精度验收，程序可能顺利生成模型，却给出没有意义的结果。文档必须把“流程验证”与“数值验收”明确区分。
运行精度还依赖输入布局、预处理、量化解释与状态衔接。模型加载成功只是另一个阶段完成，不等于端到端任务正确，更不等于性能达标。
所阅读的使用指南强调这些区别，并要求失败反馈包含模型、配套量化信息、完整命令和最早的具体错误。它让技术支持从猜测环境，转向比较可复现输入。
为什么一份短指南反而可能更完整
按实现模块排列文档，对维护者很自然：环境、工具、输出、各阶段分别一页。初次使用者却可能不知道应该先读哪页，或误把源码构建环境当成发布包环境。
按用户任务重新组织，则可以形成一条顺序：确认环境，准备模型与关联文件，运行一个完整入口，理解产物，保留失败证据，再根据具体错误深入对应限制。
这不意味着所有信息都应挤进 README。通用起步路径适合集中，复杂能力边界可以独立维护；关键是导航应对应读者的任务，而不是只反映代码目录。
同一整理中，还要同步安装与打包的必要文档检查。否则源码里入口已经换了，交付包却还在等待一个被删除的页面。
改 shape 为什么不会自动获得流式推理
一个容易出现的误解是：把时间维改短，模型就可以逐帧运行。形状工具或许能重推静态维度，甚至调整 reshape 常量，但它不会自动决定跨调用状态如何保存。
若计算依赖历史窗口或递归状态，还需要定义输入状态、输出状态、重置时机和时间顺序。只改变维度而不处理这些约束，得到的可能是另一个计算任务。
这里是对使用接口边界的说明，不意味着所有模型都具有相同状态需求。文章的好处在于把“工具能改什么”与“应用想实现什么”拆开，使一个看似简单的参数不背负不存在的能力。
让故障报告带着足够的上下文
可以设计一个最小反馈包，而不是让用户截最后一行异常：
| 信息 | 帮助回答的问题 |
|---|---|
| 工具版本与完整命令 | 是否在运行预期入口 |
| 模型及关联文件 | 输入是否完整且相互配套 |
| 最早的具体诊断 | 真正失败在哪个阶段 |
| 输入输出约定 | 布局、位宽、预处理是否一致 |
| 参考输出与实际输出 | 差异属于结构、数值还是运行逻辑 |
| 运行环境 | 编译与加载接口是否匹配 |
这些内容应按问题需要收集，并在对外分享前处理敏感数据。博客里的教学例子可以重新设计，不需要公开真实业务模型。
日志保留还应注意管道的退出码，输出目录则应避免混入上次成功产物。一个准确的支持结论，需要准确的实验输入和成功判据来支撑。
支持表本质上是一组可检验命题
“支持 X”最好能够拆成：在这些输入类型、属性、布局和资源条件下，存在这条完整路径，并由这些测试约束。条件变化，命题也可能变化。
维护支持文档的成本由此变得合理：它连接实现、验证与用户预期。与其让源码里一个孤零零的名字替整个系统作承诺，不如明确写出接力赛到底跑到了哪一棒。
If you like this blog or find it useful for you, you are welcome to comment on it. You are also welcome to share this blog, so that more people can participate in it. All the images used in the blog are my original works or AI works, if you want to take it,don't hesitate. Thank you !