> ## 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.
# Dragonwing 上的第 0 天：先验证环境，再运行你的第一个模型（第 2 部分，共 7 部分）
> 在迁移自定义 Jetson 工作负载之前，验证 Dragonwing EVK、QNN 和 HTP、GenieX 以及一个已知良好的视觉模型。
在硬件迁移过程中，损失一天时间最快的方式就是从最难的模型开始。
如果你正在从 Jetson 迁移到 Dragonwing，我们的最佳实践是在把你的生产 TensorRT 应用、自定义 CUDA 预处理和手工调优的检测器搬过来之前，先从一块已知良好的开发板和一个已知良好的模型开始：
```text theme={null}
我能 SSH 进开发板吗？
我能确认预期的 OS 镜像吗？
必需的 Qualcomm AI 包安装了吗？
我能看到 QNN 运行时和 HTP 库吗？
我能运行一个已知良好的 LLM 吗？
我能运行一个已知良好的视觉模型吗？
```
本文并不替代官方的开发板设置文档。它假设你的 EVK 已经烧录、接入网络并安装了所需的软件包。这里的目标是迁移的健全性检查：在调试你自己的模型之前先证明平台工作正常。
再来一个框架性观点：**Ubuntu 是通往"它能跑起来"的快速路径。Qualcomm Linux（QLI）是一个基于 Yocto 的嵌入式 Linux 发行版，它的参考发行版、layer、recipe 和示例代码可以帮助客户构建和维护自己的设备软件。** 下面的示例使用 Ubuntu 风格的命令，因为它们在 EVK 上易于复现。同样的检查点在基于 QLI 的镜像上仍然适用：QNN 运行时已安装、HTP 可见、AI Hub 工件可用、已知良好的模型能运行、应用行为已验证。我们将在本系列后面覆盖从 Ubuntu 到客户自维护 Yocto 的可选过渡。
在贯穿本系列的案例研究中，这是移植 Jetson 智能摄像头应用前的实验室日：先在 Dragonwing 上证明 SSH、QNN/HTP、GenieX 和一条已知良好的视觉路径。
在开始之前：
```text theme={null}
[ ] Dragonwing EVK 已烧录且可通过 SSH 访问
[ ] 必需的 AI/运行时包已安装
[ ] QNN/HTP 工具可用或已知安装路径
[ ] AI Hub 凭据已配置，或已规划离线工件复制路径
[ ] 已选定一个已知良好的 LLM 和一个已知良好的视觉模型
```
***
## 目标设备
同样的第 0 天模式一般适用于 Dragonwing EVK。具体的型号可用性、包名和性能会因开发板和 SoC 而异，所以请在 AI Hub 中选择正确的目标，并使用匹配的 Dragonwing 设置页面。
对于本文中的示例，先想到"Dragonwing EVK"。本系列使用 IQ-9075/IQ-8275 作为 EVK 名称，使用 IQ-9/IQ-8 作为家族简称。IQ-8 和 IQ-9 是具体示例：
| 示例 EVK | SoC | 设置文档 |
| -------- | ----------------- | -------------------------------------------------------------- |
| IQ-8 EVK | IQ-8275 / QCS8275 | [Ubuntu 设置指南](/zh/Ubuntu/devices/iq8275-evk/set-up-the-device) |
| IQ-9 EVK | QCS9075 | [Ubuntu 设置指南](/zh/Ubuntu/devices/iq9075-evk/set-up-the-device) |
必需软件包文档：
* IQ-8：[必需的软件包](/zh/Ubuntu/devices/iq8275-evk/Install_required_software_packages)
* IQ-9：[必需的软件包](/zh/Ubuntu/devices/iq9075-evk/Install_required_software_packages)
那些页面涵盖了 Ubuntu 的烧录、串口控制台、网络、SSH、显示和包安装。如果你的团队使用 QLI / Qualcomm Linux，请改用匹配的 QLI 设置流程，并保持相同的验证检查点。本文从 EVK 已经可访问且必需的 AI 运行时包已安装之后开始。
***
## 步骤 1：从一台就绪的 EVK 开始
对于本文，假设你已经具备：
```text theme={null}
[ ] Dragonwing EVK 已烧录
[ ] Ubuntu 已启动
[ ] 网络已配置
[ ] SSH 访问正常
[ ] 必需的软件包已安装
```
Dragonwing 必需包页面会安装我们在本文中关心的部分，包括：
```text theme={null}
libqnn-dev
qnn-tools
tensorflow-lite-qcom-apps
GStreamer Qualcomm 插件和示例应用
FastCV / 多媒体支持包
python3-pip 和常用开发工具
```
一旦 EVK 可通过 SSH 访问，就收集基本的系统信息：
```bash theme={null}
ssh ubuntu@DEVICE_IP
cat /etc/os-release
uname -a
free -h
```
这项检查值得早做。惊人比例的"模型调试"其实是意外的镜像、包集合、库路径或开发板变体问题。
***
## 步骤 2：验证 AI 运行时层
在运行你自己的模型之前，先验证必需包设置中的 Qualcomm AI 运行时组件是否存在。
```bash theme={null}
qnn-net-run --version
ls /usr/lib/libQnnHtp*.so
ls /usr/lib/libQnnTFLiteDelegate.so
```
为了更深入地检查 HTP 的健全性，可以在已安装的工具中使用 QNN 平台验证器（如果可用）：
```bash theme={null}
qnn-platform-validator --backend dsp --testBackend
```
预期结果：DSP/HTP 后端测试通过。
如果这一步失败，我们建议暂停模型级调试，直到运行时层健康。在引入自定义模型之前修复开发板/运行时设置要便宜得多。
***
## 步骤 3：配置 AI Hub 访问
AI Hub 是获取已知良好模型和设备特定工件最简单的来源。根据你使用的工作流，从主机或从设备配置客户端。在 Ubuntu 24.04 上，使用虚拟环境而不是安装到系统 Python 中：
```bash theme={null}
python3 -m venv ~/qaihub-venv
source ~/qaihub-venv/bin/activate
pip install qai-hub "qai-hub[torch]"
qai-hub configure --api_token YOUR_TOKEN
```
然后验证 AI Hub 能否看到你关心的设备类别：
```bash theme={null}
qai-hub list-devices | grep -E "IQ|QCS"
```
最佳实践：在下载模型之前先使用 AI Hub 的芯片组过滤器。选择与你的 EVK 匹配的目标，例如 IQ-8 用 IQ-8275/QCS8275，或 IQ-9 用 IQ-9075/QCS9075。
如果你的网络阻塞了 AI Hub 下载，通过获取你打算使用的确切模型工件来提早检查；如果该命令失败，则规划离线复制路径。避免依赖硬编码的公共资源 URL；目录路径和版本会变化。
***
## 步骤 4：使用 GenieX 运行一条已知良好的 LLM 路径
对于第 0 天的 LLM 验证，我们建议从 [GenieX 快速入门](https://geniex.aihub.qualcomm.com/en/get-started/quickstart) 开始。
GenieX 为你提供本地 LLM/VLM 推理的 Qualcomm 面向开发者路径：CLI、Python SDK、Linux ARM64 上的 Docker 以及一个与 OpenAI 兼容的本地服务器。在底层，它可以使用两种运行时：
| GenieX 运行时 | 模型来源 | 最适合 |
| ----------- | ------------------------- | --------------------------- |
| `llama_cpp` | 来自 Hugging Face 的 GGUF 模型 | 广泛的模型覆盖、快速实验、CPU/GPU/NPU 选项 |
| `qairt` | Qualcomm AI Hub 预编译包 | 受支持模型上的最高性能 NPU 路径 |
在 Linux ARM64 / Dragonwing 上，请遵循 [GenieX Linux 安装指南](https://geniex.aihub.qualcomm.com/en/run/linux/install)。
基本验证检查点是：
```bash theme={null}
geniex --help
```
然后通过 QAIRT 路径运行一个 Qualcomm AI Hub 模型。请把该模型 ID 视为当前 GenieX 文档中的一个已知良好示例，并对照你 GenieX 版本的受支持模型页面进行验证：
```bash theme={null}
geniex infer ai-hub-models/Qwen3-4B
```
或者通过 `llama_cpp` 路径运行一个 GGUF 模型，同样对照你版本的 Hugging Face ID 和精度进行验证：
```bash theme={null}
geniex infer unsloth/Qwen3.5-0.8B-GGUF:Q4_0
```
对于 GGUF 模型，`Q4_0` 是通常用于 Hexagon NPU 支持的第 0 天选择。
对于应用集成，有用的冒烟测试是本地服务器：
```bash theme={null}
geniex pull ai-hub-models/Qwen3-4B-Instruct-2507
geniex serve
```
服务器默认监听：
```text theme={null}
http://127.0.0.1:18181
```
并暴露一个与 OpenAI 兼容的 `/v1/chat/completions` API。这在迁移期间很重要，因为许多 Jetson 演示已经与本地 LLM 服务通信。如果应用能讲与 OpenAI 兼容的 HTTP，那么把模型主机迁到 Dragonwing EVK 可能只是一次服务 URL 变更，而不是应用重写。
原始 `llama.cpp` 仍然对高级调试和模型实验有用，但对于这条第 0 天的 LLM 路径，GenieX 应该是首要推荐。
***
## 步骤 5：运行一条已知良好的视觉路径
对于第一次视觉运行，使用 Dragonwing AI Hub 或 LiteRT 示例，而不是你自己的自定义检测器。
推荐的起始页：
* [AI Hub 工作流](/zh/Ubuntu/ai-workflows/ai-hub)
* [LiteRT/TFLite 工作流](/zh/Ubuntu/ai-workflows/lite-rt)
AI Hub 页面用轻量级人脸检测作为端到端示例。LiteRT 页面展示了使用 QNN 委托的核心模式。
一个简单的 LiteRT 冒烟测试是通过 `benchmark_model` 用 QNN 委托运行一个已安装的量化模型。在本系列使用的 IQ-9075 实验室镜像上，已安装的人脸检测模型位于 `/etc/models` 下：
```bash theme={null}
benchmark_model \
--graph=/etc/models/face_det_lite_quantized.tflite \
--external_delegate_path=/usr/lib/libQnnTFLiteDelegate.so \
--external_delegate_options='backend_type:htp;library_path:/usr/lib/libQnnHtp.so;skel_library_dir:/usr/lib/rfsa/adsp;htp_precision:0;htp_performance_mode:2'
```
预期结果：委托创建成功，输出包含平均推理时间和内存统计。在实验室的 IQ-9075 镜像上，这完全在 HTP 上委托运行。如果委托加载失败，请在动你的自定义检测器之前修复运行时/包设置。
重要的应用运行时模式是这样的：
```python theme={null}
from ai_edge_litert.interpreter import Interpreter, load_delegate
qnn_delegate = load_delegate(
"libQnnTFLiteDelegate.so",
options={"backend_type": "htp"},
)
interpreter = Interpreter(
model_path="model-w8a8.tflite",
experimental_delegates=[qnn_delegate],
)
interpreter.allocate_tensors()
```
从 Dragonwing AI Hub 文档中值得带入你自己应用的一些实用经验：
* 在 AI Hub 中为正确的芯片组选择模型。
* 优先选择量化模型进行 NPU 执行。
* 检查 AI Hub 示例仓库以了解确切的预处理和后处理。
* 图像布局和缩放是模型特定的：LiteRT 示例常用 NHWC，ONNX 示例常用 NCHW。
* 一些模型有令人意外的预处理细节；请使用该模型对应的确切 AI Hub 示例代码，而不是假设通用的灰度、RGB 或 BGR 处理。
这就是为什么一个已知良好的视觉示例有价值。它证明了委托路径，并提醒你模型只是应用的一部分。
***
## 步骤 6：选择你将继续使用的路径
在一个 LLM 冒烟测试和一个视觉冒烟测试都通过之后，为下一个迁移步骤选择运行时通道：
| 工作负载 | 首要推荐 | 原因 |
| ------------ | ---------------------- | ----------------------- |
| LLM/VLM 演示 | GenieX + `llama_cpp` | 广泛的 GGUF 模型覆盖和快速迭代 |
| LLM/VLM 生产候选 | GenieX + `qairt` | 受支持模型的 AI Hub 预编译 NPU 包 |
| 视觉演示 | AI Hub + LiteRT/QNN 委托 | 通往 NPU 推理的最小 Python 路径 |
| 自定义视觉模型 | ONNX -> QAIRT/QNN 流水线 | 当你的确切模型尚未作为现成工件提供时所需 |
第 0 天的目标不是选择所有生产细节，而是在把 Jetson 模型带过来之前证明开发板、运行时和已知良好模型路径。
### 这证明了什么，又不能证明什么
这是 Qualcomm 的快速上手通道，并不是"每个 Jetson 模型都能在第 0 天运行"的主张。一个受支持的 AI Hub/GenieX/LiteRT 工件可以让你快速到达首次推理。一个自定义的 `.pt` 模型仍然要走更长的第 3 部分路径：导出、算子兼容性、量化、上下文生成、部署和验证。在比较上手速度时请把这两种体验分开。
***
## 第 0 天检查表
在迁移自定义模型之前，让这个清单变得无聊：
```text theme={null}
[ ] Dragonwing EVK 已按匹配的 Dragonwing 文档完成设置
[ ] 必需的软件包已安装
[ ] SSH 工作正常
[ ] OS 和内核版本已确认
[ ] QNN 工具可见
[ ] libQnnHtp.so 存在
[ ] libQnnTFLiteDelegate.so 存在
[ ] 在验证器可用时 HTP 平台验证通过
[ ] AI Hub token 已配置
[ ] AI Hub 目标设备可见
[ ] AI Hub 工件下载已验证或已规划离线复制路径
[ ] GenieX 已安装或 Docker 路径已验证
[ ] GenieX 已知良好的 LLM 通过 `qairt` 或 `llama_cpp` 运行
[ ] 如果应用使用与 OpenAI 兼容的 API，已考虑 GenieX 本地服务器
[ ] LiteRT/QNN 委托的已知良好视觉模型在 HTP 上运行
```
如果任何一项失败，下一步最好通常是先修复那一层，再移植你自己的模型。
***
## 为什么这避免了与设置文档的重叠
Dragonwing 文档已经完成了开发板启动工作：
```text theme={null}
烧录镜像
连接串口控制台
配置网络
启用 SSH
安装必需的包
安装或运行 GenieX
运行 AI Hub / LiteRT 示例
```
本文有意比那些设置指南更轻。它的角色是解释迁移工作流：
```text theme={null}
使用官方设置文档让 EVK 就绪。
当你想要通往工作演示的最快路径时使用 Ubuntu。
使用 GenieX 和已知良好的视觉模型来验证运行时。
只有到那时才引入 Jetson 模型。
如果你选择基于 Yocto 的系统，QLI 可以为客户自己的集成、构建、安全、更新和维护流程提供发行版和参考输入。
```
这个顺序让第一次自定义模型迁移保持聚焦。之后当你的 YOLO 检测器失败时，你会知道开发板、QNN 运行时、AI Hub 路径、LiteRT 委托和 LLM 冒烟测试都已经工作。