1. 课程导入

欢迎进入《旭日X5视觉推理项目》。本课程面向已经具备一定 Python 与深度学习基础、希望在国产边缘 AI 芯片上完成真实视觉推理部署的开发者。整门课程围绕一块旭日X5（Sunrise X5）开发板展开，从环境搭建、模型转换、量化校准，一直走到多路视频推理、性能调优与工程化落地。本章不写代码，而是先把"我们要做什么、为什么这样做、整体怎么串起来"讲清楚，为后续 29 章建立一张可对照的认知地图。

一、学习目标：学完之后你能做到什么

本课程的目标不是"跑通一个 demo"，而是让你具备独立交付一个边缘视觉推理项目的能力。具体可拆解为四个层次：

• 环境层：能在 Ubuntu 主机上完成 Docker 工具链部署，正确安装 OpenExplorer（OE）包，并让开发板与主机通过网线或串口稳定通信。
• 模型层：能把 PyTorch / ONNX 模型通过 hb_mapper 转换为 X5 可执行的 .bin 模型，理解量化校准集的作用与精度损失来源。
• 推理层：能使用 hbdk 运行时与 Python/C++ API 完成单图推理，并进一步搭建多路视频解码 + 推理 + 后处理的完整流水线。
• 工程层：能读懂性能剖析数据，定位瓶颈在解码、推理还是后处理，并给出可验证的优化方案。

二、核心概念：先建立正确的术语坐标系

旭日X5的部署链路涉及几个高频术语，初学时最容易混淆。这里先给出精确定义，后续章节会反复使用。

理解这些概念之间的关系，比记住定义更重要。BPU 只吃定点张量，所以模型必须先量化；量化需要校准数据，所以数据流从摄像头或视频文件开始；而视频进入 BPU 之前，往往要经过 VPS 做尺寸与格式转换。这条链路就是本课程的主干。

三、整体框架：一张图看清全流程

下图把课程涉及的主要环节按数据流方向串起来。左侧是数据来源，中间是模型转换与部署，右侧是运行与优化。你可以把它当作整门课的"总目录"：后续每一章，基本都对应图中某一个方框或某一条箭头。

图中有一条橙色虚线回路，表示"精度不达标时回到量化校准重新调整"。这是实际项目中最常见的迭代路径，也是很多初学者容易忽略的一步——他们往往以为模型转换一次就能成功，实际上校准集选择、量化敏感层处理通常需要两到三轮调整。

四、典型场景：这门课解决的真实问题

为了让你对"学完能干什么"有具体感知，这里给出三个典型场景，它们会在后续章节中以案例形式出现。

• 场景 A：单路实时目标检测。接入一路 1080p USB 摄像头，运行 YOLO 系列模型，要求端到端延迟低于 80ms，并在 HDMI 上叠加检测框。核心难点是预处理与后处理的耗时控制。
• 场景 B：四路视频结构化。同时接入四路 RTSP 流，做行人检测与属性分类，要求每路不低于 15 FPS。核心难点是 VPS 多路复用与 BPU 任务调度。
• 场景 C：模型精度抢救。一个在 PC 上 mAP 0.78 的模型，转换到 X5 后掉到 0.61。核心难点是定位是哪些层量化损失过大，并通过混合量化或替换校准集修复。

五、常见误区与学习建议

根据以往教学经验，初学者最容易在以下几个地方走弯路，提前说明可以节省大量时间。

1. 把 X5 当成"小号 GPU"。BPU 的算子支持范围、内存布局、量化要求都与 GPU 差异很大。不要假设"PC 上能跑，板子上就能跑"，必须以 OE 工具链的算子支持列表为准。
2. 忽略输入格式一致性。模型编译时指定的输入尺寸、颜色空间、归一化参数，必须与运行时送入的数据完全一致，否则会出现"能跑但结果全错"的隐蔽问题。
3. 校准集随便凑。用几十张与真实场景分布不符的图片做校准，是精度崩塌的头号原因。校准集应覆盖实际部署中的光照、角度、目标尺度。
4. 过早优化。在单图推理还没跑通、精度还没验证之前，就去折腾多线程和流水线，往往事倍功半。先正确，再快速。

最后给出本课程的整体节奏建议：前 8 章打基础（环境、工具链、模型转换），中间 12 章做核心能力（量化、推理 API、多路流水线、后处理），后 10 章进入工程化（性能剖析、稳定性、部署交付）。你可以按顺序学，也可以在有基础的情况下直接跳到需要的章节，但建议至少完整走通一次"转换—推理—调优"的闭环。