> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 从 Jetson 到 Dragonwing：真正可迁移的部分（第 1 部分，共 7 部分）
> 了解 Jetson AI 应用中哪些部分可以移植到 Dragonwing，为什么 ONNX 是桥梁，以及 Qualcomm 特定的部署工作从哪里开始。
许多边缘 AI 项目最初选择 NVIDIA Jetson 是有充分理由的：开发循环基于熟悉的 Linux、Python、PyTorch、CUDA、TensorRT、OpenCV 以及经常用到的 DeepStream。一个团队可以训练模型、导出它、用 TensorRT 优化它、将它接入摄像头流水线，并快速交付一个可工作的原型。
当同一个团队开始考虑 Qualcomm Dragonwing 硬件时，第一个问题通常是：
```text theme={null}
我能把我的模型带过来吗？
```
如果这里的"模型"指的是像 `best.pt` 这样的 PyTorch 检查点，答案基本上是肯定的。
好消息是：如果你已经有训练好的 PyTorch 模型，将它导出到一个干净的静态 ONNX 图，能让许多受支持的视觉模型在通往 Qualcomm 的道路上走完很大一部分。不是 100%，也不是每个算子都可以，但足以让迁移通常变成一个优化和产品化问题，而不是一个重新训练的问题。
最重要的区分是：
```text theme={null}
可移植的起点：
best.pt / model.onnx / SavedModel / .tflite
不可移植：
TensorRT .engine / .plan
```
一个 TensorRT `.engine` 文件无法迁移到 Qualcomm。它已经是一个编译后的、NVIDIA 特定的部署工件，与 TensorRT、CUDA、JetPack 以及它所构建的 GPU 架构绑定。但该引擎背后的源模型仍然有价值。如果你有 `.pt` 或一个干净的 ONNX 导出，你并不是从零开始。
剩下的工作是让该模型在 Dragonwing 上变得快速、准确、可测量且可交付。
在本系列中，我们将围绕一个 Jetson 智能摄像头应用来展开，它带有一个自定义 YOLO 检测器、一个 TensorRT 引擎、CUDA/DeepStream 风格的预处理，以及一个可选的本地 LLM sidecar。目标平台首先是 Dragonwing IQ-9075，在设置或运行时不同的地方会点出 IQ-8275。
在开始迁移之前，先把无聊但重要的事实收集起来：
```text theme={null}
[ ] 源模型或中性导出可用
[ ] 仅 Jetson 的工件已识别
[ ] 目标 Dragonwing 开发板和操作系统已选定
[ ] 已定义准确率、延迟、FPS、功耗和热控门槛
[ ] 验证数据和样本输入可用
[ ] 已选择运行时通道：CPU、GPU、HTP/NPU、LiteRT、QNN 或 GenieX
```
***
## Jetson 的心智模型
一条常见的 Jetson 部署路径如下：
```text theme={null}
PyTorch / ONNX 源模型
-> TensorRT 构建
-> .engine
-> CUDA GPU 推理
```
对于摄像头应用，周边的技术栈通常是这样的：
```text theme={null}
camera / V4L2 / Argus
-> GStreamer 或 DeepStream
-> CUDA 预处理
-> TensorRT 推理
-> 跟踪 / 叠加
-> 显示 / 编码 / 流传输
```
开发者体验以 TensorRT 和 CUDA 为中心。你可能会用 `trtexec` 来构建和基准测试：
```bash theme={null}
trtexec \
--onnx=model.onnx \
--saveEngine=model.engine \
--fp16
```
如果 TensorRT 拒绝某个算子，你就重写图或写一个 TensorRT 插件。如果需要 INT8，就使用 TensorRT 校准。如果做剖析，就使用 `trtexec`、Nsight Systems、Nsight Compute、`tegrastats` 或 DeepStream 剖析。
这是一个连贯的世界。但它不是 Qualcomm 的世界。
***
## Dragonwing 的心智模型
在 Dragonwing 上，高层路径不同，但第一步很熟悉：
```text theme={null}
best.pt
-> 导出到静态 ONNX
-> 在 CPU 上验证 ONNX
-> 针对目标 Qualcomm 运行时进行优化
```
那个 ONNX 导出就是桥梁。对于许多具有受支持算子的常规视觉模型，得到一个干净的静态 ONNX 模型意味着核心模型迁移基本已经解决。剩下的工作是部署工程：
```text theme={null}
ONNX 源模型
-> 先检查 AI Hub
-> 如需要则转换为 Qualcomm 工件
-> 如目标为 HTP/NPU 则进行量化
-> 构建目标特定的上下文二进制文件
-> 部署运行时包
-> 验证准确率
-> 剖析延迟、功耗和内存
-> 集成到应用流水线中
```
Qualcomm 迁移通常不是"从零重新训练模型"。它是"把你已经训练好的模型转变成用于另一套加速器栈的生产工件"。
## 入门速度差距是真实存在的
不要把下面这些路径描述成等价的：
| 起点 | 最快的可信 Qualcomm 路径 | "首次推理"意味着什么 |
| -------------------------- | --------------------------------------- | ------------------------ |
| 模型已在 AI Hub 或 GenieX 中获得支持 | 下载与设备匹配的工件并运行参考命令 | 一个在开发板上工作的模型，通常是第 0 天的练习 |
| 具有干净源导出的常见模型 | ONNX -> CPU 验证 -> QNN/QAIRT 工件 -> 目标运行时 | 一个短小的移植项目，而不是一条命令的复制 |
| 具有不受支持算子或自定义 CUDA 行为的自定义模型 | 图修复、量化试验、回退/自定义算子工作以及应用集成 | 可能需要多次迭代和专家协助 |
Jetson 通常通过一条隐藏了更多硬件特定工作的框架/运行时路径，从"我找到了一个模型"到"推理运行起来"。**当模型已经被 AI Hub、GenieX、LiteRT 或另一条已验证的运行时路径覆盖时**，Qualcomm 可以提供同样快速的首次结果。差距出现在模型是自定义的时候：导出、量化、上下文生成、目标特定打包和不受支持算子的调试都是真正的门槛。
比起暗示"每个模型在 ONNX 导出后就基本解决了"，下面的实际区分更有用：
```text theme={null}
已知良好且受支持的模型 -> 快速的第 0 天推理
自定义模型 -> 分阶段迁移，前期集成工作更多
```
优化后的端点通常是 QAIRT/QNN 上下文二进制文件，而不是 TensorRT 引擎。
一个实际的 Qualcomm 模型生命周期如下：
```text theme={null}
0. 盘点现有的 Jetson 工件
1. 恢复源模型
2. 导出 / 验证静态 ONNX
3. 检查 AI Hub 是否有现成工件
4. 将源模型转换为 QNN 模型库，或使用 AI Hub / DLC 风格的工件
5. 如目标为 HTP/NPU 则进行量化
6. 构建目标特定的上下文二进制文件
7. 部署模型和运行时库
8. 运行推理并剖析
9. 与源模型基线对比验证
```
Qualcomm 部署比常见的 TensorRT 工作流更偏向提前编译（ahead-of-time）。你为目标 SoC、SDK、BSP、后端和精度准备工件。
***
## Jetson 与 Dragonwing 一览
| 领域 | Jetson | Dragonwing |
| ----- | ------------------------------- | ----------------------------------------------------------------------------- |
| 编译模型 | TensorRT JIT/运行时引擎构建 | QAIRT/QNN AOT 上下文二进制文件离线生成 |
| 转换 | TensorRT 工具 | 本地 QNN SDK 通道：ONNX -> QNN `.cpp/.bin` -> 模型 `.so`；AI Hub / DLC 风格通道：现成工件或 DLC |
| 量化 | TensorRT INT8 校准 | AIMET PTQ/QAT + QNN 转换器量化流程 |
| 图优化 | TensorRT 自动融合 | QAIRT/QNN 图准备和编译器优化 |
| 自定义算子 | TensorRT 插件 / UDO | QNN Custom Op Package / UDO |
| 主要运行时 | TensorRT | QAIRT/QNN 主要 |
| 开源运行时 | 不是 Jetson 的主路径 | LiteRT、ExecuTorch、ONNX Runtime QNN EP |
| 加速器 | CUDA GPU | HTP/NPU、Adreno GPU、CPU |
| 视觉流水线 | DeepStream / GStreamer | IM SDK / GStreamer |
| 剖析 | Nsight Systems / Nsight Compute | QNN profiler / 平台跟踪 |
简短版本：
```text theme={null}
Jetson 优化工件：
TensorRT .engine
Qualcomm 优化工件：
AI Hub 工件、QAIRT/QNN 上下文二进制文件、LiteRT 模型或 GenieX 包
```
命名说明：本系列使用 **HTP/NPU** 指代 Hexagon Tensor Processor 加速路径。某些工具通过 DSP 或 HTP 后端名称暴露该路径，例如 `--backend dsp`；GenieX 和产品资料可能称之为 NPU。
***
## 硬件目标很重要
最佳实践：不要把每个 Qualcomm 目标都视为可互换的。
命名说明：家族名称常写作 IQ-9/IQ-8，而设置页面和 AI Hub 设备名称通常使用 IQ-9075/IQ-8275 EVK。选择设备或文档时请使用 EVK 名称。
来自当前 Dragonwing 设备文档，注意这些是供应商公布的峰值能力而非实测结果（[IQ-9075 EVK 设备概览](/zh/Linux/devices/iq9075-evk/device-overview) 和 [IQ-8275 EVK 设备概览](/zh/Linux/devices/iq8275-evk/device-overview)）：
| 设备 | SoC | HTP 架构 | 加速器说明 | 峰值 |
| ------- | ------- | -----: | -----: | ---------: |
| IQ-9075 | QCS9075 | v73 | 2x NPU | 100 TOPS |
| IQ-8275 | QCS8275 | v75 | 双 HTP | 高达 40 TOPS |
这会影响上下文二进制生成、运行时库、VTCM 设置、性能预期和验证。
例如，最佳实践是在迁移到另一个 SoC 时重建并重新验证上下文二进制文件。QAIRT SDK 更新、BSP 更新、新目标 SoC 或模型更新可能都需要同样的处理。
对于习惯把模型文件当成产品工件的团队来说，这是一个重大转变。
***
## 承诺之前：迁移适配性检查
在构建转换流水线之前先做这项检查：
| 问题 | 为什么重要 |
| ----------------------------------------------------------- | ------------------------------------ |
| 有多少个摄像头，分辨率和 FPS 是多少？ | 决定摄像头、ISP、内存带宽和编码负载。 |
| 模型是否适合目标内存和受支持的算子？ | 避免太晚才发现模型需要图手术或不同的运行时。 |
| 什么样的延迟、FPS、功耗和热控目标定义了成功？ | 即使某个狭义 GPU 基准不同，Qualcomm 可能在产品功耗上胜出。 |
| 哪些 CUDA、TensorRT 插件或 DeepStream 行为是自定义的？ | 自定义平台代码通常比神经网络本身更费工。 |
| 需要哪条 OS 路径：Ubuntu 评估、客户自维护的 Ubuntu，还是基于 QLI 资源构建的 Yocto 系统？ | 运行时包、服务、更新、安全和维护所有权都会随 OS 策略而变化。 |
如果这张表存在未知项，请把首个 Dragonwing 里程碑视为一次评估，而不是移植承诺。
***
## 迁移的起点只有一个问题：你有源模型吗？
在写新代码之前，先盘点你实际拥有的东西。
如果你有下面这些，你的情况就不错：
```text theme={null}
.pt / .pth / .onnx / SavedModel / .tflite
```
对于 PyTorch 模型，第一个有用的里程碑很无聊：
```bash theme={null}
yolo export model=best.pt format=onnx imgsz=640 dynamic=False nms=False
```
然后在做任何加速器特定的事情之前，先在 CPU 上验证该 ONNX。
模型周围的文件也很重要：
```text theme={null}
预处理代码
后处理代码
标签和模型配置
验证数据
准确率 SLA
延迟/FPS/功耗要求
```
不能直接迁移的 Jetson 特定工件：
```text theme={null}
TensorRT .engine / .plan
TensorRT INT8 校准缓存
CUDA 内核
DeepStream 配置（原样）
JetPack 锁定的 Docker 容器
```
如果你只有 `model.engine`，迁移就会阻塞，直到你恢复源模型。TensorRT 引擎不是一种中立的模型交换格式。
***
## 在构建转换流水线之前先检查 AI Hub
最快的 Qualcomm 路径通常不是转换，而是复用。在投入自定义转换流水线之前，先检查是否有兼容的工件。
如果你的模型架构已经存在于 Qualcomm AI Hub 中，你或许可以下载一个预构建的工件，或者至少获得针对目标设备的预先测量的性能。
例如：
```bash theme={null}
python3 -m venv ~/qaihub-venv
source ~/qaihub-venv/bin/activate
pip install qai-hub-models
qai-hub-models perf yolov8-det \
--device "Dragonwing IQ-9075 EVK"
qai-hub-models perf mobilenet-v3-large \
--device "Dragonwing IQ-9075 EVK"
```
当前文档以 AI Hub IoT 模型目录为准，涵盖 LLM、VLM、视觉、音频、深度、恢复和机器人等领域的数百种模型变体。
如果存在兼容的工件，你可以跳过困难的部分：
```text theme={null}
转换 -> 量化 -> 构建上下文二进制文件
```
那是通往一个可工作演示的最短路径。
***
## 运行时选择是一个产品决策
Dragonwing 提供不止一个执行目标：
```text theme={null}
CPU
Adreno GPU
HTP/NPU
```
当你需要正确性和调试时先使用 CPU。CPU 执行较慢，但它在你验证预处理、张量布局、输出解码和后处理时能去除加速器特定的变量。
当模型或应用受益于浮点加速、HTP 路径尚未就绪、或某个算子对 NPU 部署很别扭时，把 GPU 作为中间路径。请注意 GPU 使用可能会与显示或图形工作产生资源竞争。
当目标是高效的边缘推理时使用 HTP/NPU。这就是量化和目标特定工件最重要的地方。
避免像"Qualcomm 需要量化"这种笼统说法。更精确的措辞：
> Qualcomm CPU 执行可以运行浮点模型。GPU 执行可能是有用的中间路径，具体取决于运行时和算子支持。为了获得最佳性能和支持，HTP/NPU 加速通常期望低精度工件，例如 INT8/a8w8 或相关受支持模式。
***
## 基准测试之前先验证
对损坏模型的基准测试就是噪声。
在收集延迟或吞吐量数字之前，先验证加速器：
```bash theme={null}
qnn-platform-validator --backend dsp --testBackend
```
然后对着正确的基线验证模型输出。对于迁移后的模型，基线通常应该是 ONNX Runtime FP32，而不是 TensorRT FP16。
为什么不用 TensorRT？因为 TensorRT 已经应用了 NVIDIA 特定的图变换、精度选择和插件行为。中立的比较点是源模型的导出。
一个好的验证链看起来像这样：
```text theme={null}
PyTorch 输出
-> ONNX Runtime FP32 输出
-> FP32 Qualcomm 工件输出
-> 量化后的 HTP 输出
```
只有这样，你才应发布延迟、FPS、功耗或 tokens/sec。
***
## 四条迁移路线
本系列将迁移分解为四种常见情形。
### 1. 还没有模型
从 Qualcomm AI Hub 或参考模型开始。避免在还没有产品问题之前就制造出可移植性问题。
### 2. 现有的 CNN、检测器或分类器
恢复源模型、导出静态 ONNX、检查 AI Hub，然后仅在必要时进行转换/量化/构建。
### 3. LLM、VLM、音频或 VLA 工作负载
把它当作一个运行时编排问题，而不仅仅是模型转换问题。你现在需要关心提示格式化、prefill、decode、KV 缓存、内存、tokens/sec、TTFT、多模态拆分和量化敏感度。
Qualcomm 路径包括 llama.cpp HTP 和带 QAIRT 工件的 GenieX。
### 4. 完整的多媒体应用
一个智能摄像头不只是一个神经网络。它是一个从摄像头到推理到输出的流水线。DeepStream 和 CUDA 组件需要通过 IM SDK、GStreamer、QNN、显示、编码、叠加和跟踪等组件获得 Qualcomm 等价物。
***
## 下一步
在下一篇文章中，我们将完全避免自定义模型迁移，做最快的有用之事：让一个 IQ-9075 EVK 启动、验证 HTP，并运行一个已知良好的 LLM 和视觉模型。
在那之后，本系列将沿着运行中的智能摄像头迁移，走过 YOLO 模型重建、量化、GenAI/sidecar 选择、IM SDK/GStreamer 流水线迁移，以及从标准 Ubuntu 到使用 QLI 资源的客户自维护 Yocto 系统的可选过渡。