> ## 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.

# QRB ROS NN Inference

[`qrb_ros_nn_inference`](https://github.com/qualcomm-qrb-ros/qrb_ros_nn_inference) 是一个通用的 ROS 2 节点，它加载神经网络模型并通过 [Qualcomm AI Engine Direct（QNN）](https://docs.qualcomm.com/bundle/publicresource/topics/80-63442-50/overview.html) SDK 在 Hexagon HTP NPU 上运行推理。您只需将其指向一个模型文件，它就会订阅输入话题，并在输出话题上发布原始推理结果——无需针对特定模型进行任何接线。

<Note>
  这就是"我能从 ROS 在 NPU 上运行**我自己的**模型吗？"这一问题的单节点答案。放入从 [Qualcomm AI Hub](https://aihub.qualcomm.com) 导出的 `.tflite` / `.so` / `.bin`（或您自己的 QNN 导出文件），将节点指向它，然后发布/订阅即可。
</Note>

## 它是什么

在底层，该节点封装了 `qrb_inference_manager`——一个调用 QNN API 和 [TensorFlow Lite 的 QNN delegate](https://docs.qualcomm.com/bundle/publicresource/topics/80-63442-2/overview.html) 的小型 C++ 库。ROS 层只是添加了订阅、发布以及由参数驱动的后端选择。

```mermaid theme={null}
flowchart LR
    M[".tflite / .so / .bin<br/>(AI Hub or custom)"] --> N
    IN["input topic<br/>(image, tensor, etc.)"] --> N["qrb_ros_nn_inference<br/>node"]
    N --> Q["qrb_inference_manager<br/>(QNN SDK + TFLite delegate)"]
    Q --> H["Hexagon HTP NPU"]
    H --> Q
    Q --> N
    N --> OUT["output topic<br/>(raw model output)"]
    style H fill:#31017D,stroke:#31017D,color:#fff
```

## 支持的模型格式

| 格式        | 使用场景                            |
| --------- | ------------------------------- |
| `.tflite` | 从 AI Hub 导出或本地训练的 TFLite 模型。    |
| `.so`     | 预编译的 QNN 二进制文件（HTP 性能最佳，与目标绑定）。 |
| `.bin`    | QNN 上下文二进制文件。                   |

<Warning>
  根据上游 README：`qrb_ros_nn_inference` 1.1.0-jazzy **不支持** `.tflite` 推理。如果您使用该版本且需要 TFLite，请从 `main` 分支源码构建，或使用 [`npu-workflows.mdx`](./npu-workflows) 中的手工构建方法。
</Warning>

## 快速开始

<Steps>
  <Step title="在 Qualcomm® IoT 平台的 Ubuntu 上安装">
    ```bash theme={null}
    sudo add-apt-repository ppa:ubuntu-qcom-iot/qcom-ppa
    sudo add-apt-repository ppa:ubuntu-qcom-iot/qirp
    sudo apt update
    sudo apt install ros-jazzy-qrb-ros-nn-inference
    ```
  </Step>

  <Step title="使用您的模型运行">
    ```bash theme={null}
    ros2 run qrb_ros_nn_inference qrb_ros_nn_inference \
      --ros-args \
        -p model_path:=/path/to/your_model.so \
        -p backend_option:=htp
    ```

    然后在配置的输入话题上发布您的输入，并订阅输出话题。完整参数列表请参见[上游 API 参考](https://github.com/qualcomm-qrb-ros/qrb_ros_nn_inference#-apis)。
  </Step>
</Steps>

## 为什么它有帮助

| 替代方案                                                       | 简评                                      |
| ---------------------------------------------------------- | --------------------------------------- |
| 手工编写的 TFLite 节点——参见 [`npu-workflows.mdx`](./npu-workflows) | 最大程度的控制；预处理、delegate 加载、话题接线都由您掌控。适合学习。 |
| 仅 CPU 的 TFLite / ONNX 节点                                   | 到处都能运行，但没有 NPU——失去了使用 Qualcomm 硬件的意义。   |
| `qrb_ros_samples` 打包管线                                     | 针对特定模型的封装（目标检测、分割等）；不如通用加载器灵活。          |

一个通用 ROS 2 节点，通过 QNN 在 Hexagon HTP NPU 上加载 `.tflite` / `.so` / `.bin` 模型。对于评估者：放入您自己的模型，配置节点，即可在 ROS 话题上发布推理结果。前后处理由您自行负责（或对 YOLO 形状的张量使用 [`qrb_ros_tensor_process`](https://github.com/qualcomm-qrb-ros/qrb_ros_tensor_process)）。

## 相关内容

* [`npu-workflows.mdx`](./npu-workflows) — 直接使用 QNN TFLite delegate 的手工深度估计管线。如果您想了解 `qrb_ros_nn_inference` 自动化了什么，这很有用。
* [`qrb-ros-samples.mdx`](./qrb-ros-samples) — 围绕此节点构建的针对特定模型的参考管线。
* 上游：[`qualcomm-qrb-ros/qrb_ros_nn_inference`](https://github.com/qualcomm-qrb-ros/qrb_ros_nn_inference)。