> ## 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 执行 AI 模型推理

[qrb\_ros\_nn\_inference](https://github.com/qualcomm-qrb-ros/qrb_ros_nn_inference) 是一个 ROS2 软件包，用于在设备上运行神经网络模型，使你的机器人应用程序无需离开 ROS 图即可获得基于 AI 的感知能力。

**它提供以下功能:**

* 模型推理 API,支持三种模型格式:
  * `.tflite`
  * `.so`
  * `.bin`
* 基于 Qualcomm 平台的模型推理加速。

## `qrb_ros_nn_inference` 的管道流程

下图展示了预处理节点如何将输入张量传送给 `qrb_ros_nn_inference`，后者将输出张量发布到后处理节点。

<img src="https://mintlify.s3.us-west-1.amazonaws.com/qualcomm-staging/zh/SDKs/QIR-SDK-2.0/media/80-65220-2-qirp-sdk-qsg/nn-inference-pipeline.svg" alt="预处理节点将输入张量发布到 nn 推理节点，该节点将输出张量发布到后处理节点。" style={{ width: '100%', display: 'block', margin: '0 auto' }} />

<p style={{ textAlign: 'center', fontWeight: 'bold' }}>
  图: qrb\_ros\_nn\_inference 管道
</p>

## `qrb_ros_nn_inference` 管道中使用的 ROS 主题

下表列出了管道中的 ROS 主题、它们的消息类型以及发布或订阅每个主题的节点。

<table>
  <thead>
    <tr>
      <th style={{ width: '30%' }}>ROS 主题</th>
      <th style={{ width: '20%' }}>消息类型</th>
      <th style={{ width: '20%' }}>发布者/订阅者</th>
      <th style={{ width: '20%' }}>描述</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`/qrb_inference_input_tensor`</td>
      <td>`qrb_ros_tensor_list_msgs::msg::TensorList`</td>
      <td>由 `qrb_ros_nn_inference` 订阅</td>
      <td>订阅用于模型推理的输入张量。</td>
    </tr>

    <tr>
      <td>`/qrb_inference_output_tensor`</td>
      <td>`qrb_ros_tensor_list_msgs::msg::TensorList`</td>
      <td>由 `qrb_ros_nn_inference` 发布</td>
      <td>发布模型的输出张量。</td>
    </tr>
  </tbody>
</table>

## `qrb_ros_nn_inference` 管道中使用的 ROS 节点参数

下表列出了节点参数、它们的类型及其默认值。

<table>
  <thead>
    <tr>
      <th style={{ width: '20%' }}>节点参数</th>
      <th style={{ width: '25%' }}>类型</th>
      <th style={{ width: '25%' }}>默认值</th>
      <th style={{ width: '30%' }}>描述</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`backend_option`</td>
      <td style={{textAlign: 'center'}}>`string`</td>
      <td style={{textAlign: 'center'}}>`""`</td>
      <td>模型推理的硬件加速选项。有效值请参见 [qrb\_ros\_nn\_inference 文档](https://github.com/qualcomm-qrb-ros/qrb_ros_nn_inference/blob/main/qrb_inference_manager/Documentation.md#2.1)。</td>
    </tr>

    <tr>
      <td>`model_path`</td>
      <td style={{textAlign: 'center'}}>`string`</td>
      <td style={{textAlign: 'center'}}>`""`</td>
      <td>指示模型文件的路径。</td>
    </tr>
  </tbody>
</table>

## 前提条件

* 您已根据 [设置运行示例应用程序的环境](./set-up-env-for-sample-app) **设置好设备**。
* 在 `qcom-robotics-image` 设备（Overlay Config #1）上，请确保您已安装 Qualcomm AI Engine Direct SDK (`qairt-sdk`) 和 `qrb-ros-nn-inference` 包。相关操作说明请参见 [在 QIR SDK 上启用和评估 Qualcomm Linux overlays](./enable-and-evaluate-qualcomm-linux-overlays-on-QIR-SDK)。
  在 `qcom-robotics-proprietary-image` 设备（Overlay Config #2）上，该包已经预装。
* 您已从 [Qualcomm AI hub](https://aihub.qualcomm.com/) 下载模型。
* 您已根据 [qrb\_ros\_nn\_inference 示例](https://github.com/qualcomm-qrb-ros/qrb_ros_nn_inference/tree/main/test) 准备好预处理节点和后处理节点。

## 运行开箱即用的 `qrb_ros_nn_inference`

<Accordion title="试一试">
  <Steps>
    <Step title="在设备上设置 QIR SDK 和 ROS2 环境">
      启动一个终端,并运行以下命令。

      `ROS_DOMAIN_ID` 的取值范围:\[0, 232]

      ```bash theme={null}
      ssh root@[ip-addr]
      ```

      ```bash title="SSH Session" theme={null}
      source /usr/share/qirp-setup.sh
      export ROS_DOMAIN_ID=xx
      ```
    </Step>

    <Step title="启动节点">
      启动三个节点:预处理节点、`qrb_ros_nn_inference` 节点和后处理节点。

      ```bash title="SSH Session" theme={null}
      ros2 launch model_inference.launch.py
      ```
    </Step>
  </Steps>
</Accordion>

## 构建并运行 `qrb_ros_nn_inference`

<Accordion title="试一试">
  <Steps>
    <Step title="在主机上构建 qrb_ros_nn_inference">
      ```bash theme={null}
      cd <qirp_decompressed_workspace>
      source setup.sh
      cd qirp-samples/platform/qrb_ros_nn_inference
      colcon build --merge-install --cmake-args ${CMAKE_ARGS}
      ```
    </Step>

    <Step title="将 qrb_ros_nn_inference 推送到设备">
      <Note>
        **注意**

        确保设备上已安装 QIR SDK。
      </Note>

      ```bash theme={null}
      cd qirp-samples/platform/qrb_ros_nn_inference/install
      tar czvf qrb_ros_nn_inference.tar.gz include lib share
      scp qrb_ros_nn_inference.tar.gz root@[ip-addr]:/opt/
      ssh root@[ip-addr]
      ```

      ```bash title="SSH Session" theme={null}
      tar --no-overwrite-dir --no-same-owner -zxf /opt/qrb_ros_nn_inference.tar.gz -C /usr/ros/jazzy/
      ```
    </Step>

    <Step title="在设备上设置 QIR SDK 和 ROS2 环境">
      启动一个终端,并运行以下命令。

      `ROS_DOMAIN_ID` 的取值范围:\[0, 232]

      ```bash theme={null}
      ssh root@[ip-addr]
      ```

      ```bash title="SSH Session" theme={null}
      source /usr/share/qirp-setup.sh
      export ROS_DOMAIN_ID=xx
      ```
    </Step>

    <Step title="启动节点">
      启动三个节点:预处理节点、`qrb_ros_nn_inference` 节点和后处理节点。

      ```bash title="SSH Session" theme={null}
      ros2 launch model_inference.launch.py
      ```
    </Step>
  </Steps>
</Accordion>

## 限制

有关最新限制,请参见 GitHub 上的 [qrb\_ros\_nn\_inference](https://github.com/qualcomm-qrb-ros/qrb_ros_nn_inference)。