02 开发环境搭建
1 环境搭建概览
在开始之前，让我们先了解整个开发环境的架构：
┌─────────────────┐ 网络连接 ┌─────────────────┐
│ 主机开发端 │ ←----------→ │ GM-3568JHF │
│ │ │ 开发板 │
│ • RKNN-Toolkit2 │ │ • RKNN Runtime │
│ • Python │ │ • NPU 驱动 │
│ • 开发工具 │ │ • Linux 系统 │
└─────────────────┘ └─────────────────┘开发流程：
- 在 PC 端使用 RKNN-Toolkit2 转换模型
- 将转换后的模型传输到开发板
- 在开发板上使用 RKNN Runtime 运行模型
2 开发板端环境准备
2.1 安装 Python 和 Conda
# 下载并安装 Anaconda 或 Miniconda
# 创建名为 ‘rknn’ 的 Python 3.9 环境（RKNN-Toolkit2 通常兼容 Python 3.6-3.9）
conda create -n rknn python=3.9 -y
conda activate rknn
在命令行前出现了(rknn)，表示成功激活 rknn 环境。
2.2 安装 Pytorch 和 YOLOv5 依赖
安装 CPU 版本的 Pytorch 即可（模型转换不需要 GPU）：
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu
克隆 YOLOv5 仓库并安装其依赖：
git clone https://github.com/ultralytics/yolov5.git
cd yolov5
pip install -r requirements.txt
安装其他必要的库：
pip install opencv-python numpy onnx onnxsim onnxruntime
2.3 安装 RKNN-Toolkit2
步骤①：获取安装包
访问 https://github.com/rockchip-linux/rknn-toolkit2。 在 rknn-toolkit2 / docker / docker_file /ubuntu_20_04_cp38 目录下下载适用于 Linux x86_64 的 wheel 文件(rknn_toolkit2-1.6.0+81f21f4d-cp38-cp38-linux_x86_64.whl)。
pip install rknn-toolkit2
2.4 系统优化配置
为什么需要系统优化？
优化系统配置可以提高 NPU 的性能，减少推理延迟，确保模型运行的稳定性。
内存优化
步骤 1: 检查当前内存使用
# 查看内存使用情况
free -h
# 查看详细内存信息
cat /proc/meminfo | head -10步骤 2: 创建 Swap 空间 (如果内存不足)
# 检查是否已有 swap
swapon --show
# 如果内存小于 4GB，建议创建 2GB swap
sudo fallocate -l 2G /swapfile
# 设置正确的权限
sudo chmod 600 /swapfile
# 创建 swap 文件系统
sudo mkswap /swapfile
# 启用 swap
sudo swapon /swapfile
# 验证 swap 已启用
free -h步骤 3: 永久启用 Swap
# 添加到 fstab 以便开机自动挂载
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
# 验证 fstab 配置
cat /etc/fstab | grep swap步骤 4: 调整内存参数
# 调整 swap 使用倾向 (降低 swap 使用频率)
echo 'vm.swappiness=10' | sudo tee -a /etc/sysctl.conf
# 调整缓存压力
echo 'vm.vfs_cache_pressure=50' | sudo tee -a /etc/sysctl.conf
# 应用配置 (重启后自动生效)
sudo sysctl -pNPU 性能优化
步骤 1: 查看 NPU 当前状态
# 查看 NPU 当前频率
cat /sys/class/devfreq/fdab0000.npu/cur_freq
# 查看 NPU 调频策略
cat /sys/class/devfreq/fdab0000.npu/governor
# 查看可用频率列表
cat /sys/class/devfreq/fdab0000.npu/available_frequencies步骤 2: 设置 NPU 性能模式
# 设置为性能模式 (最高性能)
echo performance | sudo tee /sys/class/devfreq/fdab0000.npu/governor
# 验证设置
cat /sys/class/devfreq/fdab0000.npu/governor步骤 3: 创建性能优化脚本
# 创建优化脚本
sudo nano /usr/local/bin/npu_performance.sh输入以下内容：
#!/bin/bash
# NPU 性能优化脚本
echo "正在优化 NPU 性能..."
# 设置 NPU 为性能模式
echo performance > /sys/class/devfreq/fdab0000.npu/governor
# 设置 CPU 为性能模式 (可选)
echo performance > /sys/devices/system/cpu/cpufreq/policy0/scaling_governor
# 禁用 CPU 空闲状态 (可选，会增加功耗)
# echo 1 > /sys/devices/system/cpu/cpu0/cpuidle/state1/disable
echo "NPU 性能优化完成"
echo "当前 NPU 频率: $(cat /sys/class/devfreq/fdab0000.npu/cur_freq)"# 设置执行权限
sudo chmod +x /usr/local/bin/npu_performance.sh
# 测试脚本
sudo /usr/local/bin/npu_performance.sh3 PC 端环境搭建
3.1 确认 PC 系统要求
系统兼容性检查
支持的操作系统 (按推荐程度排序)：
Ubuntu 20.04/22.04 LTS
- 最佳兼容性
- 官方主要测试平台
- 包管理简单
Windows 10/11 (x64)
- 用户最多
- 开发工具丰富
- 需要额外配置
macOS 10.15+
- 开发体验好
- 部分功能可能受限
硬件要求检查
最低配置：
- CPU: Intel i5 或 AMD Ryzen 5
- 内存: 8GB RAM
- 存储: 20GB 可用空间
- 网络: 稳定的互联网连接
推荐配置：
- CPU: Intel i7 或 AMD Ryzen 7
- 内存: 16GB+ RAM
- 存储: 50GB+ SSD
- 显卡: 独立显卡 (用于大模型训练)
3.2 安装 Python 环境
为什么选择 Python？
Python 是 RKNN 开发的主要语言，拥有丰富的机器学习库生态，学习成本低，适合快速原型开发。
Windows 环境安装
步骤 1: 下载 Python
- 访问 Python 官网
- 下载 Python 3.9.x (推荐版本，兼容性最好)
- 重要: 安装时勾选 "Add Python to PATH"
步骤 2: 验证安装
# 打开命令提示符 (Win+R, 输入 cmd)
python --version
pip --version
# 如果显示版本号，说明安装成功步骤 3: 升级 pip
# 升级 pip 到最新版本
python -m pip install --upgrade pip步骤 4: 创建虚拟环境
# 创建项目目录
mkdir C:\rknn_project
cd C:\rknn_project
# 创建虚拟环境
python -m venv rknn_env
# 激活虚拟环境
rknn_env\Scripts\activate
# 激活后，命令提示符前会显示 (rknn_env)Linux (Ubuntu) 环境安装
步骤 1: 更新系统
# 更新包列表
sudo apt update
sudo apt upgrade -y步骤 2: 安装 Python
# 安装 Python 3.9 和相关工具
sudo apt install -y python3.9 python3.9-venv python3.9-dev python3-pip
# 设置 Python 3.9 为默认 python3
sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.9 1步骤 3: 创建虚拟环境
# 创建项目目录
mkdir ~/rknn_project
cd ~/rknn_project
# 创建虚拟环境
python3 -m venv rknn_env
# 激活虚拟环境
source rknn_env/bin/activate
# 升级 pip
pip install --upgrade pip3.3 安装 RKNN-Toolkit2
什么是 RKNN-Toolkit2？
RKNN-Toolkit2 是瑞芯微提供的模型转换工具，可以将 TensorFlow、PyTorch、ONNX 等格式的模型转换为 RKNN 格式，以便在 RK 芯片的 NPU 上运行。
安装 RKNN-Toolkit2
步骤 1: 确保虚拟环境已激活
# Linux/macOS
source rknn_env/bin/activate
# Windows
rknn_env\Scripts\activate
# 确认虚拟环境已激活 (命令提示符前应显示 (rknn_env))步骤 2: 安装 RKNN-Toolkit2
# 安装 RKNN-Toolkit2
pip install rknn-toolkit2
# 如果网络较慢，使用国内镜像
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple rknn-toolkit2步骤 3: 安装依赖包
# 安装必要的依赖包
pip install numpy>=1.19.0
pip install opencv-python>=4.5.0
pip install pillow>=8.0.0
pip install matplotlib>=3.3.0
# 安装深度学习框架 (可选)
pip install torch>=1.8.0 torchvision>=0.9.0
pip install onnx>=1.8.0
# 安装其他有用的工具
pip install tqdm # 进度条
pip install paramiko # SSH 连接步骤 4: 验证安装
# 创建测试脚本
cat > test_rknn_toolkit.py << 'EOF'
#!/usr/bin/env python3
"""
RKNN-Toolkit2 安装验证脚本
"""
print("RKNN-Toolkit2 环境检测")
print("=" * 40)
# 测试 RKNN-Toolkit2 导入
try:
from rknn.api import RKNN
print("RKNN-Toolkit2: 导入成功")
# 创建 RKNN 对象
rknn = RKNN(verbose=False)
print("RKNN 对象: 创建成功")
# 显示支持的目标平台
print("支持的目标平台:")
platforms = ['rk3566', 'rk3568', 'rk3588']
for platform in platforms:
print(f" - {platform}")
except ImportError as e:
print(f"RKNN-Toolkit2: 导入失败 - {e}")
except Exception as e:
print(f"RKNN 对象: 创建失败 - {e}")
# 测试其他依赖包
print("\n依赖包检查:")
packages = {
'numpy': 'NumPy',
'cv2': 'OpenCV',
'PIL': 'Pillow',
'matplotlib': 'Matplotlib'
}
for module, name in packages.items():
try:
if module == 'cv2':
import cv2
print(f"{name}: {cv2.__version__}")
elif module == 'PIL':
import PIL
print(f"{name}: {PIL.__version__}")
else:
imported = __import__(module)
version = getattr(imported, '__version__', '已安装')
print(f"{name}: {version}")
except ImportError:
print(f"{name}: 未安装")
print("\n环境检测完成!")
EOF
# 运行测试
python test_rknn_toolkit.py3.4 配置开发板连接
为什么需要配置连接？
配置好 PC 到开发板的连接后，您可以：
- 远程传输文件
- 远程执行命令
- 远程调试程序
- 实时查看运行结果
测试连接
# 安装 paramiko (如果还没安装)
pip install paramiko pyyaml
# 运行连接测试
python src/utils/board_connection.py常见问题解决方案
Python 环境问题
问题 1: pip 安装速度慢
# 解决方案: 使用国内镜像源
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple rknn-toolkit2
# 永久配置镜像源
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple问题 2: 权限问题 (Linux/macOS)
# 解决方案: 使用用户安装模式
pip install --user rknn-toolkit2
# 或者修复 pip 权限
sudo chown -R $(whoami) ~/.local问题 3: 虚拟环境问题
# 删除旧的虚拟环境
rm -rf rknn_env
# 重新创建
python3 -m venv rknn_env
source rknn_env/bin/activate
pip install --upgrade pipRKNN 工具问题
问题 1: 导入 RKNN 失败
# 检查 Python 版本兼容性
python --version
# 确保使用正确的 Python 版本 (3.8-3.10)
# 重新安装 RKNN-Toolkit2
pip uninstall rknn-toolkit2
pip install rknn-toolkit2问题 2: 模型转换失败
# 检查模型格式和版本
# 确保模型文件完整且格式正确
# 更新到最新版本的 RKNN-Toolkit2
pip install --upgrade rknn-toolkit2问题 3: 内存不足
# 增加虚拟内存
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
# 或者使用更小的 batch size 进行转换NPU 驱动问题
问题 1: NPU 设备不存在
# 检查内核模块
lsmod | grep rknpu
# 手动加载驱动
sudo modprobe rknpu
# 检查设备树配置
cat /proc/device-tree/npu*/status问题 2: 权限不足
# 检查设备权限
ls -la /dev/rknpu*
# 修复权限
sudo chmod 666 /dev/rknpu*
# 或者将用户添加到 video 组
sudo usermod -a -G video $USER新手提醒: 如果在环境搭建过程中遇到问题，请不要着急。仔细阅读错误信息，查看故障排除部分，或者在社区寻求帮助。RKNN 开发需要一定的学习曲线，但一旦掌握，您将能够充分发挥 NPU 的强大性能！
下一章我们将通过运行官方的 YOLOv5 示例来验证环境配置的正确性，并开始您的第一个 RKNN 项目。