此页面由 AI 自动翻译。查看英文原版
最后更新

本页目录

  • 概述
  • 替代独立 RVC4 推理选项
  • 安装
  • 推理管道
  • 相机
  • 模型和解析器
  • 队列
  • 结果
  • 示例
  • 故障排除
  • 设置模型 SHAVE
  • 更改解析器参数
  • 不同的可视化和模型输入大小
  • 从 HubAI 下载模型时的模型位置
  • 延伸阅读
  • RVC4 上的并发模型执行
Claude CodeCodexCursor
Luxonis 智能体工具包为你常用的编程智能体加载 Luxonis 上下文与技能,更快地基于 OAK 开发应用。
安装工具包
最后更新

概述

为 RVC 平台转换的模型可以部署在 OAK 设备上以执行推理。 以下部分将指导您设置所需 AI 模型的简单推理管道。 我们利用 DepthAI 将推理管道构建为以下序列:当它们的输入和输出消息类型兼容时,两种节点都可以连接。 内置节点稳定、优化,并确保在 Luxonis 设备上高效运行, 而主机节点提供更大的灵活性,可以根据特定用例进行定制。 请查看 DepthAI 节点 库,了解我们内部的 Python 主机节点集合。推理管道可以手动定义,逐个节点。 但是,我们还提供基于相关 NN 存档的管道创建自动化程度 (例如,自动将神经网络与负责解码其输出的解析器连接)。 请参阅下文了解更多信息。

替代独立 RVC4 推理选项

这些运行时直接在应用程序中加载模型,在 DepthAI NeuralNetwork 节点之外,并支持设备 Hexagon Tensor Processor (HTP) 上的硬件加速。

ONNX Runtime with QNN

通过标准 ONNX Runtime API 加载 ONNX 模型,并使用 QNN Execution Provider 加速支持的操作。
运行 ONNX 模型

llama.cpp

使用 CPU 或 Hexagon 加速在本地运行 GGUF 语言和视觉语言模型,包括有关相机图像的问题。
运行语言和视觉语言模型

安装

创建推理管道需要 DepthAI (v3) 库。 使用我们的自定义主机节点(例如,用于模型输出解码)需要 DepthAI 节点库。 当前的 DepthAI 节点包需要 Python 3.10 或更高版本以及 DepthAI 3.9 或更高版本。安装它还会安装其 DepthAI 依赖项:
Command Line
1pip install depthai-nodes

推理管道

我们在此处提供一个简单的推理管道模板。 它由四个主要部分组成,我们将在下面详细描述:
  • 相机,
  • 模型和解析器;
  • 队列;
  • 结果。
Python
1import depthai as dai
2from depthai_nodes.node import ParsingNeuralNetwork
3
4model = "..." # HubAI 模型标识符,或使用 dai.NNArchive("model.tar.xz")
5
6# 创建管道
7with dai.Pipeline() as pipeline:
8
9    # 相机
10    camera = pipeline.create(dai.node.Camera).build()
11
12    # 模型和解析器
13    nn_with_parser = pipeline.create(ParsingNeuralNetwork).build(
14        camera, model
15    )
16
17    # 队列
18    parser_output_queue = nn_with_parser.out.createOutputQueue()
19
20    # 启动管道
21    pipeline.start()
22
23    while pipeline.isRunning():
24
25        # 结果
26        parser_output = parser_output_queue.get()
27        ...

相机

推理管道从 相机 节点开始。 它是进行推理的图像帧的来源。 该节点可以按如下方式添加到管道中:
Python
1camera_node = pipeline.create(dai.node.Camera).build()

模型和解析器

推理包括两个步骤。 首先,模型对输入数据进行预测。 其次,使用后处理节点(也称为解析器)来处理模型输出。 此步骤是可选的,如果跳过,则返回原始模型输出。 您可以在 DepthAI 节点 API 参考 库中找到有关可用解析器的更多信息。使用 NeuralNetwork 节点设置模型。 可以建立模型-解析器对:
  • 自动,使用 ParsingNeuralNetwork 节点,或
  • 手动,将它们初始化为独立节点并将其链接在一起。
前者自动将模型输出与相关 NN 存档 中定义的相应解析器链接。 这抽象了所有配置细节,因此是与解析器交互的首选方式。 创建的节点(独立或不独立)可以像标准 DepthAI 节点一样使用,通过将它们链接到其他节点或将它们定义为管道队列。

自动设置

ParsingNeuralNetwork 节点封装了一个标准的 NeuralNetwork 节点,并从存档元数据中选择本机 DepthAI 解析器。 使用具有相同构建参数的 HostParsingNeuralNetwork 来选择 Python 主机解析器。这会更改解析器实现,而不是底层推理节点;不可用的本机解析器不会自动回退到 Python。 它可以从 depthai_nodes 包中导入为:
Python
1from depthai_nodes.node import ParsingNeuralNetwork
并直接从以下任一实例化:(1) NN 存档对象,或
Python
1# 设置 NN 存档
2nn_archive = dai.NNArchive("path/to/NNArchiveName.tar.xz")
3
4# 设置模型(带解析器)并将其链接到相机输出
5nn_with_parser = pipeline.create(ParsingNeuralNetwork).build(
6    camera_node, nn_archive
7)
(2) HubAI,通过指定模型标识符(HubAI 平台上模型的唯一标识符。 在 模型上传/下载 部分查找更多信息)。
Python
1# 设置 HubAI 模型标识符
2model = "..."
3
4# 设置带解析器的模型
5nn_with_parser = pipeline.create(ParsingNeuralNetwork).build(
6    camera_node, model
7)
您还可以传递 dai.NNModelDescription。纯字符串被视为模型标识符,因此将本地路径包装在 dai.NNArchive(...) 中。 对于下载的模型,如果没有指定平台,包装器会填充连接设备的平台。本地存档必须已经针对正确的平台。 它配置来自所提供相机的输出,并将其链接到模型输入。

手动设置

模型和解析器也可以实例化为独立节点。首先,导入感兴趣的 DepthAI 节点解析器或实现您自己的解析器。
Python
1# 例如:from depthai_nodes.node import ClassificationParser
2# 或实现您自己的解析器(骨架):
3class ParserNode(dai.node.ThreadedHostNode):
4    def __init__(self) -> None:
5        super().__init__()
6        self.input = self.createInput()
7        self.out = self.createOutput()
8    def build(self) -> "ParserNode":
9        return self
10    def run(self) -> None:
11        while self.isRunning():
12            nn_out_raw = self.input.get()
13            nn_out_processed = ... # 替换为您的后处理和消息创建
14            self.out.send(nn_out_processed)
其次,通过调用管道上的 create() 方法将模型和解析器初始化为独立节点:
Python
1model = pipeline.create(dai.node.NeuralNetwork)
2parser = pipeline.create(ParserNode)
对于内置 Python 解析器,支持的初始化参数和配置字典因解析器而异。在启动管道之前配置它们,或者:
  • 在初始化时,可以通过将参数值作为参数传递给 create() 方法来设置配置: parser = pipeline.create(<ParserNode>, <ParameterName>=<ParameterValue>, ...) 如果配置多个参数,您可以将它们排列成一个 dict 并将其作为参数传递给解析器 build() 方法: parser = pipeline.create(ParserNode).build(config_dict);
  • 初始化后,可以通过使用 setter 方法更改配置: parser.<SetterMethodName>(<ParameterValue>)。 您可以在 DepthAI 节点 API 参考 页面上找到特定解析器的所有可用 setter 方法。
第三,设置模型可执行文件(即 RVC2 的 .blob 或 RVC4 的 .dlc 文件):
Python
1model.setModelPath("path/to/model_executable")
最后,准备相机流并链接独立节点以构成管道。将其大小、图像类型和布局与模型匹配:
Python
1width, height = 640, 640 # 替换为您的模型输入大小
2camera_stream = camera_node.requestOutput(size=(width, height))
3camera_stream.link(model.input)
4model.out.link(parser.input)

队列

队列用于从管道的特定节点获取数据。 要获取输入到模型的图像帧,您可以使用直通队列:
Python
1frame_queue = nn_with_parser.passthrough.createOutputQueue()
要获取(解析的)模型输出,您可以使用输出队列。 定义取决于模型头的数量:

单头

Python
1parser_output_queue = nn_with_parser.out.createOutputQueue()

多头

Python
1head0_parser_output_queue = nn_with_parser.getOutput(0).createOutputQueue()
2head1_parser_output_queue = nn_with_parser.getOutput(1).createOutputQueue()
3...
对于同步多头结果,请使用 nn_with_parser.outputs.createOutputQueue()。它发出以字符串头索引(例如 "0" 和 "1")为键的 dai.MessageGroup 消息。out 属性需要一个头;outputs 需要多个头。

结果

管道通过 pipeline.start() 启动后,可以从定义的队列中获取输出。 您可以获取输入帧和解析的模型输出,如下所示:
Python
1while pipeline.isRunning():
2
3    # 获取相机输出
4    frame_queue_output = frame_queue.get()
5    frame = frame_queue_output.getCvFrame()
6    ...
7
8    # 获取解析输出
9    parser_output = parser_output_queue.get()
10    ...
按顺序读取帧和结果队列本身并不能同步它们。在将结果与帧配对时,请匹配时间戳或序列号。提供的解析器返回本机 DepthAI 消息,包括 dai.ImgDetections、dai.SegmentationMask 和 dai.beta 类型,例如 Classifications 和 Keypoints。 有关格式以及用于分组和上传的单独自定义容器,请参阅 消息参考。

示例

请参阅 OAK 示例 页面。

故障排除

以下是一些常见问题及其解决方案。

设置模型 SHAVE

SHAVE 是 RVC2 VPU 中运行神经网络的计算核心。 有时,模型构建时使用的 SHAVE 数量与目标设备支持的 SHAVE 数量不同。如果模型编译时使用的 SHAVE 数量多于设备实际拥有的 SHAVE 数量,管道将失败并出现类似于以下内容的 RuntimeError:
Command Line
1NeuralNetwork: Blob compiled for ... shaves, but only ... are available in current configuration
可用分配取决于管道配置,包括推理线程计数。相反,如果模型编译时使用的 SHAVE 数量少于设备上可用的 SHAVE 数量,它仍然会运行,但您可能会看到类似以下内容的警告:
Command Line
1[14442C103180EECF00] [2.1] [4.736] [NeuralNetwork(2)] [warning] Network compiled for 8 shaves, maximum available 13, compiling for 6 shaves likely will yield in better performance
SHAVE 数量越多不一定能提高吞吐量。请同时对分配和推理线程配置进行基准测试。要修复使用的 SHAVE 数量,您可以:
  • 如果模型是使用旧版 Blobconverter 导出的,您可以重新编译模型以匹配 SHAVE 数量,或者
  • 如果 NN 存档包含具有合适编译变体的超级 blob,则无需重新编译。在配置解析器和队列之前,在原生网络上选择 SHAVE 数量。这需要一个超级 blob,而不仅仅是任何从 Hub AI 导出的存档:
Python
1nn_archive = dai.NNArchive("model.tar.xz")
2model = pipeline.create(dai.node.NeuralNetwork).build(camera_node, nn_archive)
3# 需要一个具有兼容的六 SHAVE 变体的超级 blob。
4model.setNNArchive(nn_archive, numShaves=6)

更改解析器参数

要修改解析器参数,您首先需要访问解析器对象。
  • 带有单独解析器节点的管道: 直接访问解析器节点。
  • 带有 ParsingNeuralNetwork 节点的管道: 在这种情况下,解析器与 AI 模型集成。 通过调用 ParsingNeuralNetwork 节点上的 .getParser() 方法来检索它。
本机解析器和 Python 解析器可以公开不同的 setter;检查所选解析器的 API。例如,本机 dai.node.DetectionParser 使用:
Python
1parser.setConfidenceThreshold(0.5)

不同的可视化和模型输入大小

您可以为模型输入和可视化使用单独的图像大小。 使用 ImageManip 节点在将图像发送到模型之前调整图像大小,同时保持原始分辨率以供显示。示例:
Python
1cam = pipeline.create(dai.node.Camera).build()
2
3# 请求特定的图像大小进行捕获
4cam_out = cam.requestOutput(size=(1280, 720))
5
6# 为模型输入创建和配置调整大小节点
7resize_node = pipeline.create(dai.node.ImageManip)
8resize_node.initialConfig.setOutputSize(640, 640) # 使用您的模型输入大小
9cam_out.link(resize_node.inputImage)
10
11# 定义具有调整大小输入的模型
12nn_with_parser: ParsingNeuralNetwork = pipeline.create(ParsingNeuralNetwork).build(
13    resize_node.out, ...
14)
15
16# 使用原始分辨率进行可视化
17video_queue = cam_out.createOutputQueue() # 高分辨率流
18detection_queue = nn_with_parser.out.createOutputQueue() # 低分辨率流上的检测
19...
在将检测映射回显示帧时,请考虑裁剪或信箱。有关支持的消息转换,请参阅 CoordinatesMapper。

从 HubAI 下载模型时的模型位置

下载的模型会被缓存。您可以使用 dai.getModelFromZoo() 中的 cacheDirectory 或 DEPTHAI_ZOO_CACHE_PATH 环境变量选择位置;它不一定是项目根目录。 如果模型已缓存,则会从本地加载,而不是重新下载。 要强制重新下载,可以使用 useCached=False 参数下载模型。 示例:
Python
1nn_archive = dai.NNArchive(dai.getModelFromZoo(model_description, useCached=False))
2nn_with_parser = pipeline.create(ParsingNeuralNetwork).build(
3    ..., nn_archive
4)
有关模型下载和缓存选项,请参阅 DepthAI Python API。

延伸阅读

以下部分提供了有关 RVC4 平台上的推理过程以及 NN 模型如何在 Qualcomm 的 Hexagon Tensor Processor (HTP) 上执行的更多信息和见解。

RVC4 上的并发模型执行

在 Qualcomm SoC 的 Hexagon Tensor Processor (HTP) 上并发运行多个模型时,需要考虑一些重要的资源分配和调度问题。HTP 动态共享计算和片上内存资源。根据 Qualcomm 的说法,没有直接的方法可以优先处理 HTP 上的一个模型而不是另一个模型,并且这是用户不可调的。您应该将 HTP 视为一个黑盒调度程序,并选择经验上效果最佳的线程策略。

HTP 上的资源分配

  • HTP 计算核心和 V-TCM 内存弹性地共享给所有并发 SNPE 会话。
  • 内部调度程序使用循环策略;资源分配在多个模型之间不固定,并且可能因帧而异。

控制旋钮

  • 不支持资源转向。没有每个模型的优先级、核心亲和性或配额 API。唯一的全局杠杆是 --perf_profile 标志,它会影响 SoC 级别的功耗/性能权衡。

实用指导

  1. 假设当新的/并发会话启动或停止时,延迟和吞吐量会波动。
  2. 使用 SNPE 计时日志(例如分层分析)来测量端到端延迟,而不是猜测资源份额。