2. 硬件与软件栈基础

在开始整理模型、镜像、脚本和部署说明之前，必须先建立一张“硬件—软件—工具链”的整体地图。地平线旭日X3与X5虽然同属旭日系列，但在算力、BPU架构、内存带宽和典型应用场景上存在明显差异。理解这些差异，才能判断同一份模型或镜像能否跨平台复用，以及部署脚本中哪些参数必须随芯片型号调整。

一、X3/X5芯片架构：从SoC到BPU

X3与X5均为面向边缘智能的SoC，内部通常集成CPU集群、BPU（Brain Processing Unit，神经网络加速单元）、GPU、ISP、DSP、内存控制器以及丰富的外设接口。CPU负责通用逻辑、前后处理与系统调度；BPU承担卷积、矩阵运算等神经网络核心计算；ISP处理摄像头原始数据；GPU可用于部分图形或并行计算任务。对部署而言，最关键的是BPU的算力与支持算子集，因为它直接决定模型能否高效运行。

X3定位入门级边缘AI，BPU算力相对有限，适合轻量分类、检测和简单分割模型；X5算力更高，支持更复杂的网络结构和更高分辨率输入。两者在工具链上共享同一套“模型转换—量化—编译—部署”流程，但编译目标（如 march 参数）和运行时库不同。因此，整理交付物时必须明确标注目标芯片，避免把X5编译产物直接烧录到X3。

二、BPU与工具链：模型如何变成可执行产物

BPU不能直接执行PyTorch或TensorFlow训练出的浮点模型。典型流程是：先把模型导出为ONNX等中间格式，再通过地平线工具链进行算子检查、量化校准和编译，最终生成板端可加载的 .hbm 文件。量化是关键环节，它把FP32权重和激活值映射到INT8，以换取更高吞吐和更低内存占用，但也会带来精度损失。若模型包含BPU不支持的算子，工具链会提示回退到CPU，此时需要评估性能是否可接受。

工具链通常包含模型转换、量化、编译和仿真工具。编译时必须指定目标芯片的 march 参数，例如 X3 与 X5 对应不同的架构标识。若忽略这一点，生成的产物在板端可能无法加载，或出现算子不匹配的运行时错误。因此，交付说明中应记录工具链版本、march参数、量化校准集和编译日志。

三、开发环境与依赖关系

开发环境分为“主机侧”和“板端侧”。主机侧通常使用Ubuntu，安装地平线工具链Docker镜像，依赖Python、ONNX、NumPy以及厂商提供的转换工具。板端侧则需要与芯片匹配的系统镜像、BPU驱动、运行时库和必要的Python或C++接口。两者版本必须对应，否则会出现“主机编译成功、板端加载失败”的典型问题。

四、案例场景：一次跨芯片部署的复盘

某团队在X5上完成了一个检测模型的量化编译，推理正常。随后直接把同一份 .hbm 和启动脚本复制到X3板端，结果运行时提示算子不支持。排查发现：该模型使用了X5 BPU支持但X3不支持的网络层，且编译时 march 参数为X5。修正方法是重新在X3工具链中编译，替换不支持的算子或调整网络结构，并更新部署脚本中的模型路径与输入尺寸。

五、整理交付说明时的检查清单

• 芯片型号：明确标注 X3 或 X5，禁止混用编译产物。
• 工具链版本：记录转换、量化、编译工具的版本号。
• march参数：与目标芯片一致，写入编译脚本。
• 模型信息：输入尺寸、量化方式、校准集来源、算子回退情况。
• 镜像与驱动：系统镜像版本、BPU驱动版本、运行时库版本。
• 部署脚本：环境变量、模型路径、启动命令、日志输出位置。
• 验证结果：板端推理耗时、精度对比、异常记录。

# 示例：编译阶段关键参数记录
model: yolov5s.onnx
target: X5
march: x5
quant: int8_ptq
calib: ./calib_data/
output: yolov5s_x5.hbm

# 板端运行前检查
ls /usr/lib/libdnn.so
cat /etc/version
./run_model --model yolov5s_x5.hbm --input test.jpg

把上述信息整理成结构化说明，后续无论是替换模型、升级镜像还是迁移到另一块板子，都能快速定位依赖关系，减少重复试错。