For the complete documentation index, see llms.txt. This page is also available as Markdown.

人工智能软件

本页提供在树莓派 5 上运行由 Hailo NPU 驱动的 AI 模型的说明。Hailo NPU 是专为运行神经网络设计的 AI 加速芯片;AI 工作不由树莓派设备的 CPU 完成,而由 NPU 更高效地处理。

你可以通过以下任一方式将 Hailo NPU 连接到树莓派 5:

注意

以上三种方式都可以在树莓派 5 上运行视觉 AI 模型。不过,AI Kit 已停止生产,因此对于新设计,我们推荐使用 AI HAT+ 或 AI HAT+ 2。

AI HAT+ 2 还允许你运行生成式 AI(GenAI)模型。使用 AI HAT+ 2,你可以:

硬件前提

运行 AI 模型需要一台树莓派 5,安装64 位树莓派系统(Trixie),以及以下 Hailo AI 加速器(NPU)选项之一:

  • 树莓派 AI HAT+ 或 AI HAT+ 2(推荐),两者均带有板载 Hailo 模块。有关这些配件的更多信息,请参阅 AI HAT。

  • 树莓派人工智能套件(AI Kit),包含预装 Hailo-8L AI 加速器的 M.2 HAT+。有关 AI Kit 的更多信息,请参阅人工智能套件(AI Kit)。

注意

AI Kit 已停止生产;对于新设计,我们推荐使用 AI HAT+ 或 AI HAT+ 2。

如果你想运行视觉 AI 模型,还需要一个受支持的摄像头,例如树莓派摄像头模块 3。我们建议在连接 AI 硬件之前先接好摄像头。有关说明,请参阅安装树莓派摄像头。请跳过重新接通树莓派电源的步骤,因为下一步需要先断开树莓派的电源。

然后,根据你的 AI 硬件,按照说明将 AI HAT(HAT+ 或 HAT+ 2)或 AI Kit 连接到树莓派 5。

接下来,按照软件前提中的说明启用 PCIe Gen 3.0(仅 AI Kit)、安装所需依赖项,并确认所有设置都正确无误。

软件前提

在树莓派 5 上运行视觉 AI 模型或 GenAI 模型之前,你必须配置所需的软件。总体而言,这包括以下任务,按顺序执行:

  1. 启用 PCIe Gen 3.0。手动配置 PCIe 接口,使 Hailo NPU 能以全速通信。仅 AI Kit 需要此步骤。

  2. 更新树莓派系统。确保你的树莓派系统软件包完全更新。

  3. 安装所需依赖项。安装必要的软件依赖项,使操作系统(OS)和应用程序能够检测 Hailo NPU、与其通信并在其上运行 AI 模型。

  4. 验证。验证你的 AI 硬件已被正确检测并准备就绪。

启用 PCIe Gen 3.0(仅 AI Kit)

如果你使用 AI Kit,我们强烈建议启用 PCIe Gen 3.0。对于 AI HAT+ 和 AI HAT+ 2,此设置会自动应用,可以跳过。

默认情况下,树莓派 5 的 PCIe 接口使用 Gen 2.0(5 GT/s)速度。为获得 NPU 的最佳性能,请使用以下任一方法启用 Gen 3.0(8 GT/s)速度:

  • 通过配置命令行(CLI)工具(raspi-config)在树莓派 5 上启用 Gen 3.0。

  • 更新配置文件(config.txt),使树莓派 5 上的 PCIe 接口以 PCIe Gen 3.0 速度运行。

有关此设置的更多信息,请参阅 PCIe Gen 3.0。

使用 raspi-config

首先打开树莓派配置 CLI;在树莓派终端中运行以下命令:

然后,在配置 CLI 中完成以下步骤:

  1. 选择 Advanced Options > PCIe Speed。

  2. 选择 Yes 以启用 PCIe Gen 3.0 模式。

  3. 选择 Finish 退出配置 CLI。

  4. 重启树莓派以使更改生效。你可以在终端中使用 sudo reboot 完成。

使用 config.txt

首先,以 root 用户打开配置文件(/boot/firmware/config.txt)。然后:

  1. 在 config.txt 文件中添加以下行:

  1. 重启树莓派以使这些设置生效:

更新树莓派系统

确保树莓派 5 运行的是安装有最新软件的树莓派系统 Trixie,并具有最新的树莓派固件:

更多信息,请参阅更新软件和更新引导加载程序配置。

安装所需依赖项

在将树莓派更新到最新的树莓派软件和固件后,使用 NPU 需要以下依赖项:

  • Hailo 内核设备驱动和固件。

  • Hailo RT 中间件软件。

  • Hailo Tappas 核心后处理库。

这些依赖项的安装方式取决于你使用的 AI 硬件。请为你的 AI 硬件选择合适的安装选项:

注意

AI Kit 和 AI HAT+ 需要不同的软件包(hailo-all),而 AI HAT+ 2 需要 hailo-h10-all。这两个软件包不能共存。

AI Kit 和 AI HAT+

要为 AI Kit 或 AI HAT+ 安装所需依赖项,请打开树莓派终端并运行以下命令:

AI HAT+ 2

要为 AI HAT+ 2 安装所需依赖项,请打开树莓派终端并运行以下命令:

重启并验证

安装所需依赖项后,你必须重启树莓派 5。你可以在树莓派终端中使用以下命令完成:

树莓派 5 重新启动完成后,运行以下命令检查一切是否正常运行:

如果你看到类似以下的输出,说明你已成功安装 NPU 及其软件依赖项:

AI HAT+ 和 AI HAT+ 2 的 Serial Number、Part Number 和 Product Name 可能显示为 <N/A>。这是预期行为,不影响功能。

此外,你可以运行 dmesg | grep -i hailo 检查内核日志,预期输出类似以下内容:

在树莓派 5 上运行视觉 AI 模型

本节提供在树莓派 5 上设置 Hailo NPU 的指导,使摄像头应用程序能够在摄像头输入上运行实时 AI 任务,如目标检测。以下说明适用于 AI Kit、AI HAT+ 和 AI HAT+ 2。

第 1 步:安装摄像头依赖项

首先,你必须安装树莓派摄像头软件栈。rpicam-apps 软件包提供树莓派系统使用的摄像头实用工具,并包含视觉 AI 流水线所需的 Hailo 后处理软件演示阶段。

使用以下命令安装最新的 rpicam-apps 软件包:

然后,运行以下命令确保摄像头正常工作:

这会启动摄像头并显示预览窗口五秒钟。如果预览窗口出现,说明摄像头设置正确。

第 2 步:运行实时视觉 AI 演示

验证一切安装正确后,你可以使用 rpicam-apps 摄像头软件运行摄像头 AI 演示。该软件使用后处理框架实现 AI 演示;它使用预训练的神经网络,通过 NPU 对摄像头帧运行 AI 推理。

为展示 NPU 的部分能力,本节概述了一些演示,展示不同的模型和后处理阶段,例如在物体周围绘制边界框或在人体上绘制姿态线。结果显示在实时预览窗口上(默认),或在树莓派终端中显示为文本。

以下演示使用 rpicam-hello,但你也可以使用其他 rpicam-apps 应用,如用于视频录制的 rpicam-vid 和用于静态图像的 rpicam-still。这些应用程序可能需要你添加或修改一些命令行选项才能兼容。

目标检测

以下 rpicam-apps 演示使用 rpicam-hello 和不同的 YOLO 模型执行目标检测。每个演示都会在检测到的物体周围绘制边界框,并支持可选标志以修改输出,如 -n 关闭取景器、-v 2 仅显示文本输出。

不同演示在速度和准确性上有不同的取舍。运行以下命令在树莓派 5 上尝试每个演示:

模型
命令
后处理阶段

YOLOv6

rpicam-hello -t 0 --post-process-file /usr/share/rpi-camera-assets/hailo_yolov6_inference.json

目标检测。

YOLOv8

rpicam-hello -t 0 --post-process-file /usr/share/rpi-camera-assets/hailo_yolov8_inference.json

目标检测。

YOLOX

rpicam-hello -t 0 --post-process-file /usr/share/rpi-camera-assets/hailo_yolox_inference.json

轻量快速的目标检测。

YOLOv5

rpicam-hello -t 0 --post-process-file /usr/share/rpi-camera-assets/hailo_yolov5_inference.json

人体与人脸检测。

图像分割

以下 rpicam-apps 演示使用 rpicam-hello 执行目标检测,然后通过在取景器图像上绘制颜色掩码来分割物体。运行以下命令在树莓派 5 上尝试该演示:

姿态估计

以下 rpicam-apps 演示使用 rpicam-hello 执行 17 点人体姿态估计,绘制连接检测点的线条。运行以下命令在树莓派 5 上尝试该演示:

AI Kit 与 AI HAT+ 的软件包版本

如果你想使用由特定版本 Hailo 工具链生成的 AI Kit 或 AI HAT+ 运行模型,必须确保使用兼容版本的 Hailo 软件包和设备驱动。如果版本不匹配,这些组件将无法正常工作。

首先,如果你之前曾用 apt-mark 固定过任何相关软件包,可能需要使用以下命令取消固定:

然后你可以安装所需版本的软件包:

4.19

要安装 4.19 版本的 Hailo 神经网络工具,请运行以下命令:

4.18

要安装 4.18 版本的 Hailo 神经网络工具,请运行以下命令:

4.17

要安装 4.17 版本的 Hailo 神经网络工具,请运行以下命令:

更多资源

在树莓派 5 上运行 LLM(仅 AI HAT+ 2)

本节提供在 AI HAT+ 2 上设置 Hailo 10 NPU 的说明,以便在树莓派 5 上本地运行大语言模型(LLM)。完成以下设置后,你可以通过以下方式访问 LLM:

  • POST 请求(API 调用):直接向 hailo-ollama 服务器发送查询。

  • Web UI 前端:使用基于浏览器的聊天式界面。

运行本地 LLM 的组件

在树莓派 5 上运行本地 LLM 涉及多个协同工作的系统层,以实现硬件加速推理。

硬件层

运行本地 LLM 所需的物理计算能力来自:

  • 树莓派 5:提供主 CPU、内存和通用 I/O,用于运行操作系统、管理软件并协调与 AI 加速器的通信。

  • Hailo AI 加速芯片(通过 AI HAT+ 2 提供的 Hailo-10H NPU):提供 AI 推理的神经处理能力,让你可以运行本地 LLM。

有关这些前提的更多信息,请参阅硬件前提。

软件层

要在树莓派 5 上使用 Hailo NPU 运行本地 LLM,你必须安装一组软件依赖项、驱动和运行时组件。

运行 LLM(以及视觉 AI)需要软件依赖项。有关所需依赖项及安装说明,请参阅软件前提中的安装所需依赖项。

AI 模型层

Hailo Gen-AI Model Zoo 包含适合在 Hailo-10H 上运行的预训练 LLM。这些模型作为第 1 步的一部分安装。随后运行时加载这些模型,并由 AI 加速器执行。

后端层

LLM 由 Hailo Ollama 服务器 加载和运行。该后端层:

  • 从 Hailo Gen-AI Model Zoo 加载 LLM。

  • 管理 Hailo-10H NPU 上的推理。

  • 提供 REST API,用于向 NPU 发送请求(提交提示)并返回 AI 推理结果(接收响应)。

Hailo Ollama 服务器作为第 2 步的一部分安装。

前端层(可选)

由 Open WebUI 提供的前端层是一个可选的、基于浏览器的聊天界面,用于与 LLM 交互。或者,你也可以继续使用第 2 步中介绍的基于终端的 POST 请求与 LLM 交互。

虽然运行 LLM 并不需要 Open WebUI,但它提供了一种更友好的方式来提交提示和查看响应,而不是使用基于终端的 POST 请求。Open WebUI 通过其 REST API 与 Hailo Ollama 服务器通信,并在对话式 UI 中显示模型输出。

Open WebUI 需要运行在 Docker 容器中。这是因为 Open WebUI 与 Python 3.13(树莓派系统 Trixie 所用版本)不兼容。Docker 提供容器化环境以保证稳定运行。

Open WebUI 的设置由第 3 步和第 4 步组成。

第 1 步:安装 Hailo Ollama 服务器

Hailo Ollama 服务器提供:

  • 为 Hailo-10H NPU 优化的预训练 LLM。

  • 暴露 REST API 以供模型推理的 Hailo Ollama 服务器。

要安装 Hailo Ollama 服务器,请下载适用于树莓派 5 的 Hailo Model Zoo GenAI 5.1.1 版 Debian 软件包,然后在树莓派终端中使用以下命令安装:

第 2 步:启动 Hailo Ollama 服务器并运行 LLM

安装完成后,启动本地 hailo-ollama 服务器以暴露供 LLM 请求使用的 REST API,然后下载并运行一些 LLM。

  1. 在树莓派终端中运行以下命令启动本地 hailo-ollama 服务器:

  1. 在新的终端窗口中运行以下命令获取 LLM 列表:

  1. 运行以下命令从提供的列表中下载模型,将 "examplemodel:tag" 替换为所列的任一模型(例如 "qwen2:1.5b"):

  1. 运行以下命令通过 POST 请求向 LLM 发送查询,将 "examplemodel:tag" 替换为你已下载并想要运行的模型:

第 3 步:安装 Docker(用于 Open WebUI)

如果你不打算使用 Open WebUI 界面,可以跳过此步骤。

以下说明在树莓派 5 上安装 Docker,这是部署和运行 Open WebUI 的前提,详见第 4 步。更全面的安装说明,请参阅 Docker 的页面:在 Debian 上安装 Docker Engine。

要安装 Docker:

  1. 移除任何现有的 Docker 软件包:

  1. 安装 Docker apt 仓库:

  1. 检查 docker.sources 文件是否已正确创建:

预期输出会列出以下内容,其中 Suites 是操作系统的 VERSION_CODENAME(trixie):

  1. 安装并运行 Docker 服务:

  1. 创建 docker 组:

  1. 将你的用户添加到 docker 组:

  1. 注销并重新登录以使组成员资格重新评估,或运行以下命令激活组成员资格更改:

  1. 测试 Docker:

第 4 步:安装并使用 Open WebUI(可选)

在上一节安装 Docker 后,你可以使用 Docker 部署并运行 Open WebUI 容器。

注意

以下方法是部署和使用容器的一种方式,并非唯一方法。例如,你也可以改用 docker-compose 进行容器管理。

  1. 要使用 Open WebUI,首先需要安装它。下载运行前端层所需的 Open WebUI 镜像:

  1. 确保 hailo-ollama 已在运行。然后启动 Open WebUI 容器并将其连接到 hailo-ollama 后端服务器:

  1. 监视容器启动。容器最多可能需要一分钟初始化。要查看进度和日志,请运行以下命令,然后等待日志表明服务器已运行并准备好接受连接。

  1. 在网页浏览器中访问 Open WebUI,输入以下 URL:http://127.0.0.1:8080。这会打开一个聊天界面,你可以选择模型并开始与 LLM 交互。

更详细的说明,请参阅 Open WebUI 文档中的快速入门指南。

最后更新于