> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs-staging.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) 导出（或您自己的 QNN 导出）的 `.tflite` / `.so` / `.bin` 文件，将节点指向它，然后进行发布/订阅即可。
</Note>

## 它是什么

在底层，该节点包装了 `qrb_inference_manager`——一个调用 QNN API 和 [QNN delegate for TensorFlow Lite](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)。