📚 课程目录第3章工程交付全景

3. 工程交付全景

ONNX 模型从训练完成到真正被业务系统稳定调用，中间隔着一条完整的工程化交付链路。很多算法工程师交付时只给一个 .onnx 文件，结果下游推理团队拿到后既不知道输入张量的具体排布，也不清楚动态轴的范围，更无法判断算子兼容性是否满足目标硬件要求，最终导致集成反复返工。工程交付的本质不是“把模型文件传过去”，而是把模型的可运行性、可验证性和可维护性以结构化方式传递给下游。本章从交付物组成、典型流程、角色分工与质量门槛四个维度，拆解一次规范的 ONNX 工程交付应该长什么样。

上图展示了 ONNX 工程交付的完整链路。从模型准备到静态校验、动态验证、打包交付，每个阶段都有明确的输入输出和质量检查点。交付物组成与角色分工在图中并列呈现，便于团队快速对齐责任边界。接下来逐一展开每个模块的具体操作方法和实践要点。

3.1 交付物组成：不只是模型文件

一次完整的 ONNX 工程交付，至少包含六类交付物。缺少任何一类，下游集成时都可能陷入“模型能加载但跑不通”的困境。

交付物	内容说明	缺失风险
模型文件	`.onnx` 文件，命名含版本号（如 `detect_v2.3.onnx`）	无法追溯版本，回滚困难
推理脚本	预处理、推理、后处理封装，含输入输出张量说明	下游不知道如何调用
兼容性报告	算子版本、目标硬件支持情况、精度对比结果	部署时才发现算子不支持
测试用例	代表性输入数据 + 基准输出（.npz 或 .bin）	无法验证推理结果正确性
部署配置	动态轴范围、精度设置（FP32/FP16）、设备映射	性能调优无从下手
README	运行环境、依赖库版本、示例命令、常见问题	团队协作效率低

模型文件本身只是交付的起点。推理脚本需要明确输入张量的 shape、dtype、通道顺序（NCHW 还是 NHWC）、归一化参数（均值/方差），以及后处理中阈值、NMS 参数等。兼容性报告则要覆盖算子级兼容性（哪些算子需要降级或替换）、硬件级兼容性（CPU/GPU/NPU 是否支持）和精度级兼容性（FP32 与 FP16 的误差范围）。

  实践建议：交付物目录建议采用固定结构，例如 model/、scripts/、tests/、docs/、configs/ 五个子目录。每个子目录内放置对应文件，并在 README 中说明目录用途。这样下游团队拿到压缩包后，无需额外沟通即可快速定位所需内容。

3.2 典型流程：从导出到验收的五个阶段

ONNX 工程交付的典型流程可以拆解为五个阶段，每个阶段都有明确的入口条件和出口标准。流程设计的目标是尽早发现问题，避免问题在下游放大。

模型导出阶段：从训练框架导出 ONNX，设置 opset_version（建议 13-17），固定输入输出名称，处理动态轴。导出后立即用 onnx.checker.check_model() 做基础校验。
静态分析阶段：使用 onnx.shape_inference 推断张量 shape，用 onnxruntime 的 get_providers() 检查目标硬件支持情况，扫描算子版本是否超出目标环境。
动态验证阶段：准备多组测试输入（不同 batch、不同分辨率），对比原始框架输出与 ONNX Runtime 输出，记录最大误差和相对误差。误差阈值通常设定为 1e-4（FP32）或 1e-2（FP16）。
性能摸底阶段：在目标硬件上跑 benchmark，记录首延迟、稳态延迟、吞吐量。如果性能不达标，需要分析瓶颈算子，考虑图优化或算子替换。
打包验收阶段：整理所有交付物，生成兼容性报告，提交测试团队验收。验收通过后归档发布。

这五个阶段中，静态分析和动态验证是最容易出问题的环节。静态分析能发现结构性问题，但无法发现数值问题；动态验证能发现数值问题，但需要精心设计测试用例。两者缺一不可。

3.3 角色分工：谁对什么负责

工程交付不是一个人的事，需要算法、推理、测试三方紧密协作。每个角色都有明确的责任边界，避免“都管但都没管好”的局面。

算法工程师：负责模型导出的正确性，确保 ONNX 输出与训练框架输出一致。需要提供基准输出供下游验证。如果模型包含自定义算子，算法工程师需要提供算子实现或替代方案。
推理工程师：负责模型在目标硬件上的可运行性和性能。需要验证算子兼容性，处理不支持的算子（如替换、拆解、自定义实现），并完成性能调优。
测试工程师：负责制定验收标准，执行回归测试，验证交付物完整性。测试用例应覆盖正常输入、边界输入（如最大 batch、最小分辨率）和异常输入（如空张量）。
项目经理：协调资源，确认交付时间节点，处理跨团队阻塞问题。
运维工程师：负责模型上线后的监控，包括推理延迟、内存占用、错误率等指标。

协作建议：建议在项目启动时定义一份《交付责任矩阵》（RACI 表），明确每个交付物的 Responsible、Accountable、Consulted、Informed 角色。例如，模型文件的 Responsible 是算法工程师，Accountable 是项目经理，Consulted 是推理工程师，Informed 是测试工程师。这样可以避免交付时互相推诿。

3.4 质量门槛：可量化的验收标准

质量门槛是交付的“红线”，没有达到门槛的交付物不应被接受。以下是建议的最低质量门槛，团队可根据项目实际情况调整。

检查项	门槛标准	检查方法
静态检查	`onnx.checker` 通过，无 warning	运行 checker 脚本
数值精度	FP32 最大误差 < 1e-4	对比基准输出
动态 shape	覆盖 batch 1~32，分辨率 ±20%	多组测试输入
算子兼容	目标硬件支持率 100%	算子扫描报告
性能达标	P95 延迟 < 50ms（视业务而定）	benchmark 脚本
文档完整	README 包含运行环境和示例	人工检查

数值精度门槛需要特别注意：1e-4 是 FP32 的常见标准，但如果模型包含 Softmax、LayerNorm 等对数值敏感的操作，误差可能放大。建议在交付前用真实业务数据做一次全量比对，而不是只跑几个随机张量。

风险提示：不要为了通过精度测试而降低门槛。如果模型在 FP16 下误差超过 1e-2，说明模型对精度敏感，需要保留 FP32 推理或使用混合精度策略。强行压缩精度可能导致线上推理结果异常，且问题难以排查。

3.5 案例拆解：一次失败的交付与复盘

某团队交付一个目标检测模型，算法工程师导出了 detect.onnx 文件后直接发给推理团队。推理团队加载模型后，发现以下问题：

输入张量名称是 input.1，没有语义化命名，下游不知道应该传什么数据。
模型包含 NonMaxSuppression 算子，目标硬件（某 NPU）不支持，推理直接报错。
动态 batch 没有声明，推理团队只能固定 batch=1，无法满足线上多路并发需求。
没有提供基准输出，推理团队无法验证自己的预处理和后处理是否正确。

最终，推理团队花了 3 天时间反查模型结构、联系算法工程师确认输入输出含义、手动实现 NMS 替代方案，才勉强跑通。整个交付周期从预期的 2 天延长到 5 天，且留下了技术债。

复盘分析：这个案例的根因是算法工程师没有按照工程交付规范执行。如果算法工程师在导出时做到以下几点，问题完全可以避免：

将输入命名为 images，输出命名为 boxes、scores、classes，并在 README 中说明含义。
提前用 onnxruntime 的 get_available_providers() 检查算子兼容性，发现 NMS 不支持后，将 NMS 拆解为多个基础算子或提供替代实现。
在导出时设置 dynamic_axes={'images': {0: 'batch'}}，声明动态 batch 维度。
导出后立即运行 10 组测试输入，保存基准输出，随交付物一起提供。

这个案例说明，工程交付的规范不是“额外负担”，而是保障团队协作效率的基础设施。一次规范的交付，能为下游节省数天时间，也能避免线上事故。

3.6 常见误区与总结

在 ONNX 工程交付中，以下误区最为常见：

误区一：只交付模型文件。模型文件只是“半成品”，没有配套脚本和文档，下游无法使用。
误区二：忽略动态 shape。很多模型导出时默认固定 shape，导致线上无法处理变长输入。应在导出时声明动态轴，并测试边界值。
误区三：不验证数值一致性。ONNX 导出后算子实现可能与训练框架有细微差异，必须用真实数据比对。
误区四：兼容性报告流于形式。只写“支持 CPU/GPU”，不写具体算子版本和硬件型号，等于没写。
误区五：没有版本管理。模型文件命名不带版本号，或者覆盖旧文件，导致无法回滚。

总结来说，ONNX 工程交付的核心是让下游团队能够独立、快速、正确地使用模型。交付物要完整，流程要规范，角色要清晰，质量门槛要可量化。建议团队将本章内容固化为《ONNX 交付检查清单》，在每次交付前逐项打勾确认。这样既能保证交付质量，也能积累团队的最佳实践。