X3派AI算法推理快速入门指南

本教程将带您快速掌握地平线X3派上AI推理引擎hobot_dnn的核心用法。从环境搭建到模型加载、推理，再到一个完整的分类示例，每一步都配有清晰的代码和详细说明。跟着操作，您也能轻松完成自己的AI算法部署。

0 环境安装

在进行AI算法开发之前，请参考地平线X3派用户手册完成系统安装及配置。此时X3派上已默认安装好地平线Python版本AI推理引擎（hobot_dnn）及其配套依赖环境。hobot_dnn提供了Model、pyDNNTensor、TensorProperties三个类和load接口。您可通过如下方式获取hobot_dnn的基本信息：

python3
>>> from hobot_dnn import pyeasy_dnn as dnn
>>> dir(dnn)
['Model', 'TensorProperties', '__doc__', '__file__', '__loader__', '__name__', '__package__', '__spec__', 'load', 'pyDNNTensor']

AI推理引擎的更新可参考如下方式（出于系统安全、稳定性的考虑，建议统一通过APT命令更新地平线X3派板级开发包）：

#更新package列表
sudo apt update
#升级所有已安装的软件包到最新版本
sudo apt full-upgrade
#清除缓存文件（非必须）
sudo apt clean
#重启设备
sudo reboot

小提示：如果您在开发过程中遇到版本兼容问题，先尝试通过sudo apt full-upgrade更新所有软件包，通常能解决大部分依赖冲突。

常见问题：为什么我执行from hobot_dnn import pyeasy_dnn as dnn报错？
答：请确认您已经正确安装了地平线X3派系统镜像，并且系统版本支持该库。可以执行dpkg -l | grep hobot查看是否已安装。如果未安装，请参考X3派用户手册通过APT安装：sudo apt install hobot-dnn。

1 推理接口介绍

1.1 Model

Model是AI算法模型类，描述模型的名称、输入输出数据属性信息，其forward方法用来完成模型的推理。

class hobot_dnn.pyeasy_dnn.Model
'''
Parameters：
1、name (string)：模型名称
2、inputs (tuple(hobot_dnn.pyeasy_dnn.pyDNNTensor))：模型的输入tensor
3、outputs (tuple(hobot_dnn.pyeasy_dnn.pyDNNTensor))：模型的输出tensor
4、forward (args &args, kwargs &kwargs)：模型推理函数接口，输入模型推理所必要的参数，返回模型推理结果
parameters：
    input_tensor：输入数据
    core_id (int)：模型推理的core id，可为0,1,2，默认为0表示任意核推理
    priority (int)：当前模型推理任务的优先级，范围[0~255]，越大优先级越高
'''

其中，forward方法的input_tensor支持三种格式输入：

forward方法的返回值为模型推理结果，有如下两种情况：

resizer模型指在模型转换时input_source设置为“resizer”编译生成的模型，相关配置方式可参考地平线社区X3用户手册。resizer模型推理时，hobot_dnn会先使用ROI从输入数据中抠图后resize到模型输入大小再送入模型进行推理。

注意：目前resizer模式暂只支持单输入的nv12/nv12_bt601模型。

小提示：当您使用多模型推理或需要控制CPU核负载时，可以指定core_id参数（0、1、2）。如果不确定，保持默认0即可，系统会自动分配。

常见问题：forward方法返回的输出tensor如何访问？
答：返回的是一个tuple，每个元素是pyDNNTensor对象，通过outputs[0].buffer可以得到numpy数组，后续可以继续进行后处理（如argmax等）。

1.2 pyDNNTensor

pyDNNTensor是AI算法输入/输出tensor类。

class hobot_dnn.pyeasy_dnn.pyDNNTensor
'''
Parameters：
1、properties (TensorProperties)：tensor的属性，详细参见本文1.3节
2、buffer (numpy)：tensor中的数据，数据访问方式同numpy
3、name (string)：tensor的名称
'''

小提示：您可以直接对buffer进行numpy操作，例如切片、索引、统计等。这在后处理中非常实用。

常见问题：如何获取输入tensor的shape？
答：通过tensor.properties.shape获取，它会返回一个tuple，例如(1,3,224,224)。

1.3 TensorProperties

TensorProperties是AI算法输入/输出tensor的属性类。

class hobot_dnn.pyeasy_dnn.TensorProperties
'''
Parameters：
1、tensor_type (string)：tensor的数据类型，如：NV12、BGR、float32等
2、dtype (string)：数据的存储类型，同numpy数据类型，如：int8、uint8、float32等
3、layout (string)：数据排布格式，NHWC或者NCHW
4、shape (tuple)：数据的shape信息，例如：(1,3,224,224)
'''

小提示：查看模型的tensor_type可以知道模型期望的输入格式（例如NV12、BGR），您需要根据此准备数据。如果不匹配，推理可能会失败或得到错误结果。

常见问题：layout的NHWC和NCHW有什么区别？
答：NHWC表示[批次, 高度, 宽度, 通道]，NCHW表示[批次, 通道, 高度, 宽度]。地平线模型通常使用NHWC布局，但具体以模型转换时的设置为准。您可以通过properties.layout查看。

1.4 load

load接口用于加载模型。

hobot_dnn.pyeasy_dnn.load(model_file)
'''
接口支持两种模型加载方式：
1、输入模型的文件路径，加载单个模型，或者单个pack模型
    model_file = "/userdata/single_model.bin"
    models = hobot_dnn.pyeasy_dnn.load(model_file)
2、输入模型的文件列表，加载多个模型
    model_file = ["model1.bin", "model2.bin"]
    models = hobot_dnn.pyeasy_dnn.load(model_file)
接口返回hobot_dnn.pyeasy_dnn.Model类型的tuple列表
'''

小提示：如果模型文件路径中包含中文或特殊字符，请确保文件系统支持，或者使用英文路径避免出错。

常见问题：加载多个模型时，返回的models列表顺序与传入的文件列表一致吗？
答：是的，返回的tuple顺序与传入的model_file列表顺序一一对应。

2 快速上手示例

地平线X3派配套AI推理示例默认安装在/app/ai_inference目录下，包含如下示例：

|-- 01_basic_sample             # 从本地读取图片并完成mobilenetv1分类模型推理
|-- 02_usb_camera_sample        # 从USB camera获取视频数据并完成FCOS检测模型推理
|-- 03_mipi_camera_sample       # 从MIPI camera获取视频数据并完成FCOS检测模型推理
|-- 05_web_display_camera_sample # 基于MIPI Camera的FCOS目标检测及web端展示
|-- 06_yolov3_sample            # 从本地读取图片并完成Yolov3检测模型推理
|-- 07_yolov5_sample            # 从本地读取图片并完成Yolov5检测模型推理
`-- models

本节将以01_basic_sample为例，为大家展示如何使用hobot_dnn完成模型推理。运行以下示例您需要准备编译好的混合异构模型mobilenetv1_224x224_nv12.bin（存放于/app/ai_inference/models路径下），以及一张图片zebra_cls.jpg（存放于01_basic_sample文件夹下）。

from hobot_dnn import pyeasy_dnn as dnn
import numpy as np
import cv2

# 查看模型输入输出节点的信息
def print_properties(pro):
    print("tensor type:", pro.tensor_type)
    print("data type:", pro.dtype)
    print("layout:", pro.layout)
    print("shape:", pro.shape)

# 依据模型input_type_rt决定是否需要进行数据格式转换（本实例所用模型为nv12输入）
def bgr2nv12_opencv(image):
    height, width = image.shape[0], image.shape[1]
    area = height * width
    yuv420p = cv2.cvtColor(image, cv2.COLOR_BGR2YUV_I420).reshape((area * 3 // 2,))
    y = yuv420p[:area]
    uv_planar = yuv420p[area:].reshape((2, area // 4))
    uv_packed = uv_planar.transpose((1, 0)).reshape((area // 2,))
    nv12 = np.zeros_like(yuv420p)
    nv12[:height * width] = y
    nv12[height * width:] = uv_packed
    return nv12

# 1.加载模型
models = dnn.load('../models/mobilenetv1_224x224_nv12.bin')

# 2.查看模型输入输出节点的信息
for input in models[0].inputs:
    print_properties(input.properties)
for output in models[0].outputs:
    print_properties(output.properties)

# 3.准备输入数据
# 打开图片
img_file = cv2.imread('./zebra_cls.jpg')
# 把图片缩放到模型的输入尺寸
h, w = models[0].inputs[0].properties.shape[2], models[0].inputs[0].properties.shape[3]
resized_data = cv2.resize(img_file, (w, h), interpolation=cv2.INTER_AREA)
nv12_data = bgr2nv12_opencv(resized_data)

# 4.模型推理
outputs = models[0].forward(nv12_data)

# 5.后处理
np.argmax(outputs[0].buffer)
print("cls id: %d Confidence: %f" % (np.argmax(outputs[0].buffer), outputs[0].buffer[0][np.argmax(outputs[0].buffer)]))

运行上述示例，即可在终端查看到如下信息：

小提示：如果您的模型输入格式不是NV12（例如是BGR），则不需要执行bgr2nv12_opencv转换，直接使用OpenCV读取并resize后的BGR数据作为输入即可。请务必根据models[0].inputs[0].properties.tensor_type的返回值来调整数据准备逻辑。

常见问题：推理结果outputs[0].buffer的shape是什么？
答：对于分类模型，通常是(1, num_classes)。您可以通过outputs[0].buffer.shape查看。如果模型输出有多个，可以分别访问outputs[1].buffer等。

本文转自地平线开发者社区

原作者：颜值即正义

原链接：https://developer.horizon.ai/forumDetail/98129467158916308

你是一名 AI 行业编辑，请围绕下面这条热点输出一份资讯解读：
热点：X3派AI算法推理快速入门指南要求：
1. 先用一句话解释这条热点在讲什么
2. 再总结它为什么重要
3. 说明会影响哪些 AI 产品或内容方向
4. 最后给出 3 个适合资讯站使用的标题