1. 课程导入与交付全景

欢迎进入《地平线旭日X3/X5交付：模型、镜像、脚本和部署说明整理》课程。本课程面向已经具备一定深度学习基础、准备把算法真正落到地平线旭日X3或X5芯片上的工程师。与单纯讲“如何训练一个模型”不同，本课程关注的是交付：一个模型从训练完成到在板端稳定运行，中间需要经过哪些转换、打包、验证和文档整理环节。很多项目失败并非因为模型精度不够，而是因为交付链路不清晰——模型格式不对、镜像版本不匹配、脚本参数写错、部署说明缺失，导致现场调试反复返工。

一、核心概念：什么是“交付”

在地平线旭日X3/X5的语境下，交付不是单一动作，而是一条完整的链路。它至少包含四个核心对象：

• 模型：通常来自PyTorch、ONNX等训练框架，需要经过地平线工具链转换为可在BPU上运行的量化模型，最终产出.bin等可部署文件。
• 镜像：包含系统、驱动、运行时库和工具链的板端运行环境。X3与X5的镜像并不通用，版本号、BPU架构和算子支持范围都有差异。
• 脚本：负责模型转换、量化校准、板端推理、性能测试和结果校验的自动化命令集合，是保证交付可复现的关键。
• 部署说明：把上述内容串起来的文档，包括环境依赖、目录结构、执行顺序、参数含义和常见问题处理。

这四者不是并列关系，而是有明确的依赖顺序：模型决定脚本内容，脚本依赖镜像环境，部署说明则记录前三者的版本与操作。任何一环版本漂移，都会导致“在我机器上能跑，在板子上跑不通”。

二、整体框架与学习路径

本课程共30章，整体遵循“先全景、再分件、后集成”的路径。前几章建立交付全景和工具链认知；中间章节分别深入模型转换、量化校准、镜像烧录、脚本编写和部署文档；最后通过综合案例把各环节串成一条可复现的交付流水线。下图展示了本节要建立的整体交付框架，它也是后续所有章节的骨架。

从图中可以看到，交付框架分为三层：上层是模型从训练到板端的流转，中层是脚本对全流程的支撑，下层是部署说明对版本和操作的固化。底部红色区域强调的“版本一致性红线”，是本课程反复强调的核心原则。

三、典型场景：一次完整的交付长什么样

假设你有一个在PyTorch上训练好的目标检测模型，需要部署到旭日X5开发板。一个规范的交付流程大致如下：

1. 确认X5镜像版本和工具链版本，记录在部署说明中。
2. 将PyTorch模型导出为ONNX，检查算子是否被工具链支持。
3. 准备校准数据集，运行量化校准脚本，生成量化模型。
4. 使用工具链编译，产出可在BPU上运行的.bin模型。
5. 将模型和推理脚本拷贝到板端，运行推理并记录延迟、内存和精度。
6. 把上述所有命令、参数、版本号和结果整理成部署说明。

下面是一段典型的板端推理脚本片段，用于验证模型是否正常加载：

# 板端推理示例（示意）
export LD_LIBRARY_PATH=/usr/lib/hbplayer:$LD_LIBRARY_PATH
./infer_demo \
  --model ./model/yolov5_x5_quantized.bin \
  --input ./data/test.jpg \
  --output ./result/ \
  --thread 2
# 观察输出日志中的 BPU 耗时与检测框数量

这段脚本看似简单，但它依赖镜像中的运行时库、模型转换时的输入尺寸、以及校准阶段确定的量化参数。任何一个环节不一致，都会表现为“模型加载失败”或“检测结果异常”。

四、常见误区与复盘

复盘这些误区，可以发现它们都指向同一个问题：交付缺少统一的全景视图。本课程后续章节会逐一展开模型转换、量化校准、镜像烧录、脚本编写和文档整理，但在此之前，你需要先建立本节给出的整体框架，知道每个环节在链路中的位置和依赖关系。

五、本节要点清单