树莓派部署YOLOv8手势检测实战：USB IMX378摄像头 + Python + PyTorch + ONNX Runtime + Systemd开机自动运行

一、项目介绍

近年来，树莓派已经不仅仅是一块学习 Linux 和 Python 的开发板。

结合：

• USB 摄像头
• Python
• YOLO
• PyTorch
• ONNX Runtime
• OpenCV
• Linux Systemd

就可以搭建一个小型的边缘 AI 视觉检测终端。

本文以树莓派部署手势检测为例，实现下面的系统结构：

USB IMX378摄像头
    │
    ▼
Linux /dev/video
    │
    ▼
Python视觉程序
    │
    ▼
YOLOv8
    │
    ▼
手势目标检测
    │
    ▼
fatigueDetect.py
    │
    ▼
Systemd服务
    │
    ▼
开机自动运行

最终目标不是每次开机之后手动执行：

python fatigueDetect.py

而是：

树莓派开机
    ↓
Linux启动
    ↓
Systemd启动服务
    ↓
Python虚拟环境
    ↓
fatigueDetect.py
    ↓
AI视觉检测自动运行

这也是树莓派从"开发测试程序"走向"实际部署设备"的重要一步。

二、本文使用的树莓派系统环境

本次环境为 Raspberry Pi ARM64 系统。

系统信息：

Linux rpi5-251213-0003 6.12.47+rpt-rpi-2712 #1
SMP PREEMPT Debian 1:6.12.47-1+rpt1 (2025-09-16)
aarch64 GNU/Linux

其中最重要的是：

aarch64

说明当前系统是 ARM64 架构。

因此后面安装 Python、Miniconda 以及 AI 相关依赖时，需要考虑：

树莓派 ARM64

而不是直接按照普通 Windows x86 或 Intel Linux 环境处理。

三、第一步：安装 USB IMX378 摄像头

手势检测首先需要图像输入。

本文使用：

USB IMX378摄像头

树莓派通过 USB 接口连接摄像头。

连接之后，需要先确认 Linux 系统是否能够识别摄像头。

整个过程：

USB摄像头
    ↓
树莓派USB接口
    ↓
Linux USB设备
    ↓
/dev/video*
    ↓
Python / OpenCV / AI视觉程序

四、安装 FSWebcam

首先安装：

sudo apt install fswebcam

fswebcam 可以用于快速验证 USB 摄像头是否能够正常工作。

对于 AI 视觉项目来说，这一步非常重要。

因为：如果摄像头基础采集都没有成功，后面的 YOLO 程序自然无法正常工作。

所以建议将整个项目拆成几个阶段：

第一阶段：摄像头能不能工作？

第二阶段：Python环境能不能工作？

第三阶段：YOLO模型能不能运行？

第四阶段：程序能不能自动启动？

不要一开始就直接运行完整 AI 程序。

五、添加用户到 video 用户组

执行：

sudo usermod -a -G video rpi5

然后查看当前用户组：

groups

这里的作用是让用户具备访问视频设备相关资源的权限。

Linux 下 USB 摄像头通常会对应：

/dev/video0
/dev/video1
...

因此用户需要具备相应的视频设备访问权限。

如果修改用户组之后权限没有立即生效，可以重新登录系统。

六、查看 USB 摄像头

首先查看 USB 设备：

lsusb

然后查看视频设备：

ls /dev/video*

如果系统正常识别摄像头，通常可以看到类似：

/dev/video0

这说明 Linux 已经创建视频设备节点。

整个判断过程非常简单：

lsusb
    ↓
有没有USB摄像头？

ls /dev/video*
    ↓
有没有/dev/video0？

fswebcam image.jpg
    ↓
能不能正常拍照？

七、使用 fswebcam 拍照测试

执行：

fswebcam image.jpg

如果正常，就会生成：

image.jpg

此时可以将图片打开查看。

如果能够看到摄像头拍摄的画面，说明：

USB连接正常
+
Linux识别正常
+
视频设备正常
+
摄像头采集正常

这样就可以进入下一阶段。

八、为什么一定要先测试摄像头？

AI 视觉开发中非常容易出现一个误区：程序运行不了，就认为是 YOLO 模型有问题。

实际上可能只是：

摄像头没有识别

或者：

/dev/video0不存在

甚至可能只是：

用户没有视频设备权限

因此建议养成一个习惯：

硬件测试
    ↓
操作系统设备测试
    ↓
Python采集测试
    ↓
AI模型测试
    ↓
完整程序测试

这套排查方法同样适用于工业相机、USB 相机和边缘视觉设备。

九、第二步：安装 Miniconda

摄像头测试完成之后，开始配置 Python AI 开发环境。

本文使用 Miniconda。

Miniconda 最大的作用是方便管理多个 Python 环境。

例如：

系统Python
    │
    ├── yolov8-env
    │
    ├── mqtt-env
    │
    └── other-env

不同项目可以使用不同 Python 版本和依赖，这样可以减少不同 AI 项目之间的依赖冲突。

十、下载 ARM64 版本 Miniconda

本文树莓派是：

aarch64

因此使用 Linux ARM64 版本 Miniconda。

下载：

wget https://repo.anaconda.com/anaconda/Miniconda3-py312_25.11.1-1-Linux-aarch64.sh

然后执行安装：

bash Miniconda3-py312_25.11.1-1-Linux-aarch64.sh

安装完成以后，可以检查 Conda 是否正常。

十一、为什么树莓派要特别注意 ARM64？

普通电脑可能是：

x86_64

而树莓派 5 运行的是：

aarch64

两者 CPU 架构不同。

因此：

Windows x64
Linux x86_64
ARM64

不能完全按照相同方式处理。

在树莓派部署 AI 模型的时候，经常需要关注：

Python版本
CPU架构
PyTorch版本
ONNX Runtime版本
NumPy版本
Ultralytics版本

因此：边缘 AI 部署的第一步不是安装 YOLO，而是确认硬件架构和操作系统环境。

十二、Conda 配置软件源

安装完成后，可以配置 Conda 源：

conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free

继续：

conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main

然后：

conda config --set show_channel_urls yes

这样可以让 Conda 显示实际使用的软件源。

对于国内网络环境，配置镜像源通常能够改善 Python 环境安装体验。

十三、第三步：创建 YOLOv8 虚拟环境

接下来创建专门用于 YOLO 的 Python 环境：

conda create -n yolov8-env python=3.10

创建完成后激活：

conda activate yolov8-env

此时命令行环境就进入：

yolov8-env

建议以后运行 YOLO 程序之前都确认一下：

(yolov8-env)

是否存在。

十四、为什么要单独创建虚拟环境？

假设系统里面有：

Python 3.11

而 YOLO 项目使用：

Python 3.10

如果所有项目都安装到系统 Python 中，就容易出现：

numpy版本冲突
torch版本冲突
opencv版本冲突
onnxruntime版本冲突

使用 Conda 之后：

系统环境
    │
    ├── yolov8-env
    │
    └── 其他Python环境

项目之间相对独立，这对于 AI 视觉项目尤其重要。

十五、查看当前 Python 环境

进入环境后：

conda list

可以查看当前环境已经安装的 Python 软件包。

建议在项目开始时记录：

Python版本
NumPy版本
PyTorch版本
Ultralytics版本
ONNX Runtime版本
OpenCV版本

后续如果程序出现问题，排查会方便很多。

十六、配置 pip 国内镜像源

接下来配置 pip：

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple/

然后使用 pip 安装 Python 依赖。

这样以后执行：

pip install xxx

就会使用配置的软件源。

十七、安装 NumPy

执行：

pip install numpy

NumPy 是 Python AI 视觉开发中非常重要的基础库。

它主要用于：

数组
矩阵
图像数据
模型输入
模型输出
数值计算

例如摄像头采集到的图像最终就可以转换成 NumPy 数组进行处理。

十八、安装 ONNX Runtime

继续：

pip install onnxruntime

ONNX Runtime 主要用于运行 ONNX 模型。

整个模型部署关系可以理解成：

YOLO训练模型
    ↓
ONNX
    ↓
ONNX Runtime
    ↓
树莓派CPU

因此 ONNX Runtime 非常适合用于模型部署阶段。

十九、安装 PyTorch

如果还需要直接运行 PyTorch 模型，可以安装：

pip install torch torchvision torchaudio

这里需要注意：ARM64 平台的 PyTorch 安装对版本和系统环境比较敏感。

本文提供的是实际部署流程中的安装命令，具体能够安装到哪个版本，应以当前树莓派系统、Python 版本以及对应 ARM64 软件包实际可用情况为准。

二十、安装 Ultralytics

继续：

pip install ultralytics

Ultralytics 提供 YOLO 模型训练和推理接口。

安装完成后，Python 程序就可以使用：

from ultralytics import YOLO

加载 YOLO 模型。

因此整个 Python AI 环境基本形成：

Python 3.10
    │
    ├── NumPy
    ├── ONNX Runtime
    ├── PyTorch
    ├── TorchVision
    ├── TorchAudio
    └── Ultralytics

二十一、树莓派上的 YOLO 部署架构

到这里可以把整个软件结构画成：

┌───────────────────────────────┐
│        Raspberry Pi 5         │
│                               │
│   Debian ARM64 / aarch64      │
│           │                   │
│       Miniconda               │
│           │                   │
│      yolov8-env               │
│           │                   │
│  ┌─────────┼──────────┐       │
│  │         │          │       │
│ NumPy   PyTorch   ONNX RT     │
│  │         │          │       │
│  └─────────┼──────────┘       │
│            │                  │
│         YOLOv8                │
│            │                  │
│     手势检测程序               │
└────────────┬──────────────────┘
             │
             ▼
        USB IMX378 Camera

这就是一个典型的：树莓派边缘 AI 视觉系统。

二十二、第四步：运行手势检测程序

本文最终运行程序：

fatigueDetect.py

虽然当前文件名为：

fatigueDetect.py

但实际项目可以根据模型任务修改成：

gestureDetect.py

或者：

yoloDetect.py

关键并不在文件名称，而在于：Python 程序负责调用摄像头和 AI 模型完成实时检测。

完整运行逻辑可以理解为：

摄像头
    ↓
读取图像
    ↓
图像预处理
    ↓
YOLO模型
    ↓
AI推理
    ↓
手势检测结果
    ↓
后续业务处理

二十三、为什么还需要 Systemd？

开发阶段，我们可以手动执行：

python fatigueDetect.py

但是如果真正部署到设备上，就会遇到一个问题：树莓派重启之后，谁来运行 Python 程序？

如果每次都需要：

SSH登录
    ↓
进入目录
    ↓
conda activate
    ↓
python fatigueDetect.py

那么这个设备还不能算真正的自动化部署。

因此我们使用 Linux Systemd，让程序变成一个系统服务。

二十四、创建 FatigueDelect.service

创建：

sudo nano /lib/systemd/system/FatigueDelect.service

写入：

[Unit]
Description=FatigueDetect Comm Server
After=network.target
Requires=network-online.target

[Service]
WorkingDirectory=/home/rpi5/FatigueDetection/
ExecStart=/bin/bash -c "source /home/rpi5/miniconda3/etc/profile.d/conda.sh && conda activate yolov8-env && python /home/rpi5/FatigueDetection/fatigueDetect.py"
Restart=always
User=root
Group=root
StandardOutput=journal+console
StandardError=journal+console

[Install]
WantedBy=multi-user.target

这里是整个自动运行功能的核心。

二十五、WorkingDirectory

配置：

WorkingDirectory=/home/rpi5/FatigueDetection/

表示程序工作目录：

/home/rpi5/FatigueDetection/

因此程序运行时涉及的相对路径会以这个目录作为工作路径。

例如模型：

model.onnx

或者：

weights/best.pt

如果程序使用相对路径，就需要特别注意当前工作目录。

二十六、ExecStart 是最关键的一行

配置：

ExecStart=/bin/bash -c "source /home/rpi5/miniconda3/etc/profile.d/conda.sh && conda activate yolov8-env && python /home/rpi5/FatigueDetection/fatigueDetect.py"

这一行实际上完成了三个动作。

第一步，加载 Conda：

source /home/rpi5/miniconda3/etc/profile.d/conda.sh

第二步，激活 YOLO 环境：

conda activate yolov8-env

第三步，运行 Python 程序：

python /home/rpi5/FatigueDetection/fatigueDetect.py

也就是说：

Systemd
    ↓
Bash
    ↓
Conda
    ↓
yolov8-env
    ↓
Python
    ↓
fatigueDetect.py

这样 Systemd 就可以运行指定的 Conda Python 环境。

二十七、为什么不能简单写 python？

例如直接：

ExecStart=python fatigueDetect.py

可能调用的是系统 Python。

但是我们真正需要的是：

/home/rpi5/miniconda3/
    ↓
yolov8-env
    ↓
Python 3.10
    ↓
YOLO依赖

因此本文采用：

source conda.sh
conda activate yolov8-env
python fatigueDetect.py

确保程序使用正确的虚拟环境。

二十八、Restart=always

配置：

Restart=always

它的作用是：如果程序异常退出，Systemd 会自动尝试重新启动。

对于长期运行的边缘 AI 视觉设备非常有意义。

例如：

AI程序
    ↓
运行
    ↓
异常退出
    ↓
Systemd检测
    ↓
重新启动
    ↓
AI程序恢复

这样可以减少设备无人值守时需要人工干预的情况。

二十九、日志输出

配置：

StandardOutput=journal+console
StandardError=journal+console

表示程序输出可以进入 Systemd 日志。

因此后续可以使用：

journalctl

查看运行日志。

对于 AI 视觉项目非常重要，因为真正部署之后最怕的就是：

程序停止了
但是不知道为什么停止

Systemd 日志可以帮助定位问题。

三十、重新加载 Systemd

修改服务文件以后：

sudo systemctl daemon-reload

这是让 Systemd 重新读取服务配置。

然后：

sudo systemctl enable FatigueDelect

设置开机自动启动。

三十一、启动 AI 视觉服务

执行：

sudo systemctl start FatigueDelect

这时候：

FatigueDelect.service
    ↓
conda
    ↓
yolov8-env
    ↓
fatigueDetect.py
    ↓
AI视觉检测

开始运行。

三十二、检查服务状态

部署完成以后，建议检查：

sudo systemctl status FatigueDelect

如果服务正常，可以看到：

active (running)

这时候说明 Python AI 程序已经由 Linux Systemd 接管。

三十三、查看 AI 程序运行日志

可以使用：

journalctl -u FatigueDelect

实时查看：

journalctl -u FatigueDelect -f

这样可以观察：

Python启动
模型加载
摄像头初始化
AI推理
异常信息

对于树莓派 AI 项目调试非常实用。

三十四、完整部署流程

现在整个项目已经可以总结成一条完整流程：

USB IMX378
    ↓
安装fswebcam
    ↓
测试摄像头
    ↓
lsusb /dev/video*
    ↓
Miniconda
    ↓
创建yolov8-env
    ↓
Python 3.10
    ↓
NumPy / ONNX Runtime
    ↓
PyTorch / Ultralytics
    ↓
YOLO手势检测程序
    ↓
fatigueDetect.py
    ↓
Systemd Service
    ↓
开机自动运行

三十五、从"程序"升级到"产品"

这一步非常关键。

很多 AI 项目做到：

python xxx.py

就结束了。

但是工业现场、边缘设备和实际项目往往需要：

设备上电
    ↓
系统启动
    ↓
服务启动
    ↓
摄像头初始化
    ↓
模型加载
    ↓
AI检测

用户不需要：

SSH
终端
Python命令
Conda命令

这才更加接近真正的 AI 设备。

因此：Systemd 并不是简单的"自动启动命令"，而是把 Python AI 程序转换成 Linux 系统服务的一种部署方式。

三十六、后续可以继续升级什么？

本文完成的是基础的：

树莓派 + USB摄像头 + YOLOv8 + Systemd自动运行

在此基础上还可以继续扩展。

1. 手势识别

例如：

OK
点赞
握拳
手掌
数字1
数字2
数字3

2. 人体检测

摄像头
    ↓
YOLO
    ↓
人体检测
    ↓
人数统计

3. 疲劳驾驶检测

进一步结合：

闭眼
打哈欠
低头
疲劳

实现驾驶员状态分析。

4. 工业视觉

将 USB 摄像头换成工业相机，可以继续开发：

产品缺陷检测
零件检测
尺寸检测
装配检测
目标定位

5. MQTT 联网

树莓派可以将 AI 结果通过 MQTT 发送到服务器：

树莓派
    ↓
YOLO
    ↓
检测结果
    ↓
MQTT
    ↓
EMQX
    ↓
MES / AI平台

这就可以进一步形成：

边缘AI + MQTT + MES + 云平台

架构。

三十七、常见问题排查思路

摄像头不存在

首先：

lsusb

然后：

ls /dev/video*

如果没有视频设备，就不要急着检查 YOLO。

先解决：

USB
摄像头
驱动
权限

Conda 环境没有激活

检查：

conda env list

然后：

conda activate yolov8-env

再：

python --version

确认 Python 版本。

YOLO 程序手动运行正常，Systemd 运行失败

这是部署过程中非常常见的问题。

重点检查：

WorkingDirectory
ExecStart
Conda路径
模型路径
摄像头权限
Python路径

尤其注意：

手动运行环境

和：

Systemd运行环境

并不完全相同。

三十八、总结

本文从一个最基础的问题开始：如何让树莓派上的 USB 摄像头配合 YOLO 模型实现手势检测，并在设备启动后自动运行？

最终建立了完整的边缘 AI 部署流程：

USB IMX378摄像头
    ↓
fswebcam测试
    ↓
Linux视频设备
    ↓
Miniconda
    ↓
Python 3.10
    ↓
yolov8-env
    ↓
PyTorch
    ↓
Ultralytics
    ↓
ONNX Runtime
    ↓
YOLO AI检测
    ↓
fatigueDetect.py
    ↓
Systemd
    ↓
开机自动运行

对于刚开始学习树莓派 AI 视觉 + YOLOv8 的开发者来说，建议不要一开始就研究复杂的模型优化。

先完成：

摄像头能采集 → Python环境能运行 → YOLO能推理 → 程序能自动启动

这四个阶段。

当这套流程跑通以后，再进一步研究：

YOLO模型优化
ONNX部署
OpenCV加速
多线程
摄像头FPS优化
模型量化
NPU/GPU加速
MQTT数据上传
MES集成
边缘AI设备管理

最终就可以从一个简单的树莓派 AI 实验，逐步发展成真正可以部署到现场的边缘 AI 视觉终端。