WSL系统下免费使用SpireCV-Pro教程

WSL 系统下免费使用 SpireCV-Pro 教程

本教程将带你从零开始，在 Windows 的 WSL2 环境中搭建 SpireCV-Pro 智能感知平台，并运行一个 YOLO11 目标检测可视化示例。

1. 安装 WSL2 + Ubuntu 22.04

1.1 启用 WSL

以管理员身份打开 PowerShell，执行：

powershell 复制代码

wsl --install

该命令会自动启用 WSL2 并安装默认的 Ubuntu 发行版。安装完成后重启电脑。

如果已安装过旧版 WSL，先升级到 WSL2：
powershell 复制代码
wsl --update
wsl --set-default-version 2

1.2 安装 Ubuntu 22.04

如果上一步没有自动安装 Ubuntu 22.04，手动安装：

powershell 复制代码

wsl --install -d Ubuntu-22.04

安装过程中会提示创建用户名和密码（牢记此密码，后续 sudo 需要）。

1.3 进入 WSL

在 PowerShell 中输入：

powershell 复制代码

wsl

即可进入 Ubuntu 22.04 终端。后续所有操作都在此终端中进行。

2. 安装 WSL 版 CUDA

WSL2 支持直接使用 Windows 宿主机的 NVIDIA 驱动，无需在 WSL 内安装显卡驱动。

2.1 确认 Windows 端已安装 NVIDIA 驱动

在 Windows 的 PowerShell 中执行：

powershell 复制代码

nvidia-smi

如果显示 GPU 信息，说明驱动已就绪。如果没有，请从 NVIDIA 官网下载安装。

2.2 在 WSL 内安装 CUDA Toolkit

回到 WSL 终端，执行以下命令安装 CUDA 12.6（WSL 专用版本）：

bash 复制代码

wget https://developer.download.nvidia.com/compute/cuda/repos/wsl-ubuntu/x86_64/cuda-wsl-ubuntu.pin
sudo mv cuda-wsl-ubuntu.pin /etc/apt/preferences.d/cuda-repository-pin-600
wget https://developer.download.nvidia.com/compute/cuda/12.8.2/local_installers/cuda-repo-wsl-ubuntu-12-8-local_12.8.2-1_amd64.deb
sudo dpkg -i cuda-repo-wsl-ubuntu-12-8-local_12.8.2-1_amd64.deb
sudo cp /var/cuda-repo-wsl-ubuntu-12-8-local/cuda-*-keyring.gpg /usr/share/keyrings/
sudo apt-get update
sudo apt-get -y install cuda-toolkit-12-8

2.3 配置环境变量

bash 复制代码

echo 'export PATH=/usr/local/cuda-12.8/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda-12.8/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrc

验证安装：

bash 复制代码

nvcc --version

3. 安装 Python 3.10

Ubuntu 22.04 默认 Python 版本为 3.10，确认版本：

bash 复制代码

python3 --version

如果未安装或版本不对：

bash 复制代码

sudo apt update
sudo apt install -y python3.10 python3.10-venv python3.10-dev python3-pip

建议创建虚拟环境：

bash 复制代码

python3.10 -m venv ~/spirecv_env
source ~/spirecv_env/bin/activate

4. 安装 PyTorch（CUDA 版）

bash 复制代码

pip install torch torchvision --index-url https://download.pytorch.org/whl/cu128
# 如果速度慢，可以添加镜像源
# -i https://repo.huaweicloud.com/repository/pypi/simple

验证 PyTorch 能否使用 CUDA：

bash 复制代码

python3 -c "import torch; print('CUDA available:', torch.cuda.is_available())"

输出 CUDA available: True 即表示成功。

5. 安装 SpireMS

SpireMS 是 SpireCV-Pro 的通信框架，需要先安装。

bash 复制代码

sudo apt update
sudo apt install -y build-essential cmake git python3-pip libcurl4-openssl-dev libeigen3-dev libssl-dev libncurses-dev

cd ~
git clone https://gitee.com/spirecv/spirecv-pro.git
cd spirecv-pro/scripts/spirecv2/
./opencv4110-install.sh

pip install opencv-python==4.11.0.86 opencv-contrib-python==4.11.0.86 yacs

cd ~
wget https://spireai.top/download/spirems/spirems-0.8.1_ubuntu_x86_64.deb
sudo dpkg -i spirems-0.8.1_ubuntu_x86_64.deb

# 注意如果自己的Python版本不是3.10，则修改下面命令中的cp310即可，支持cp38-cp313
wget https://spireai.top/download/spirems/spirems-0.8.1-cp310-cp310-linux_x86_64.whl
pip install spirems-0.8.1-cp310-cp310-linux_x86_64.whl
# 如果 sms ls 命令不能正常使用，再次用sudo安装一遍
# sudo pip install spirems-0.8.1-cp310-cp310-linux_x86_64.whl
# 如果安装较慢，可以添加以下命令，换成华为云的服务器
# -i https://repo.huaweicloud.com/repository/pypi/simple

验证安装：

bash 复制代码

python3 -c "import spirems; print(spirems.__version__)"

6. 安装 SpireCV-Pro

6.1 进入SpireCV-Pro仓库

bash 复制代码

cd ~/spirecv-pro

6.2 安装依赖

bash 复制代码

pip install ultralytics
pip install -e .
# 如果 smsrun ls 命令不能正常使用，再次用sudo安装一遍
# sudo pip install -e .
./build_spirecv2_x86_cuda.sh

pip install -e . 会以开发模式安装 SpireCV-Pro，同时注册 smsrun 命令行工具。

6.3 验证安装

bash 复制代码

smsrun ls

如果看到节点列表和 Launch 列表，说明安装成功。显示结果如下：

7. 运行示例

以下两个示例均使用内置视频文件，无需摄像头。

7.1 启动 SpireMS Core

打开一个 WSL 终端，激活虚拟环境后启动 Core：

bash 复制代码

source ~/spirecv_env/bin/activate
smscore

保持此终端运行，Core 是所有节点通信的中心。

7.2 示例一：YOLO11 目标检测可视化

打开另一个 WSL 终端，执行：

bash 复制代码

source ~/spirecv_env/bin/activate
smsrun viddet_yolo11_vis_cuda

这个 Launch 文件会自动启动三个节点：

节点	作用
`pvid`	读取内置无人机航拍视频（自动下载）
`pyolo11cuda`	使用 YOLO11 模型进行目标检测（CUDA 加速）
`pdetvis`	将检测结果绘制到图像上并弹出窗口显示

预期效果 ：弹出 OpenCV 窗口，画面中的车辆、行人等目标被红色框标出，显示类别名称和置信度。按 q 键或 Ctrl+C 退出。

自定义参数：

bash 复制代码

smsrun viddet_yolo11_vis_cuda confidence=0.3 pt_model=sms::yolo11m.pt

参数	说明	默认值
`confidence`	检测置信度阈值	0.2
`pt_model`	模型（`sms::` 前缀自动下载）	`sms::visdrone2019_det-yolo11s...`
`imgsz`	推理图像尺寸	1280

7.3 示例二：ArUco 二维码检测与位姿估计

bash 复制代码

source ~/spirecv_env/bin/activate
cd ~/spirecv-pro
smsrun viddet_aruco_det

启动的节点：

节点	作用
`pvid`	读取内置二维码视频（自动下载）
`paruco`	检测 ArUco 二维码并估计 3D 位姿
`pdetvis`	绘制检测框和坐标轴，弹出窗口显示

预期效果 ：弹出 OpenCV 窗口，二维码被绿色框标出，并绘制 3D 坐标轴（红X/绿Y/蓝Z），显示二维码 ID。按 q 键或 Ctrl+C 退出。

自定义参数：

bash 复制代码

smsrun viddet_aruco_det marker_lengths=[0.05] dictionary_id=4

参数	说明	默认值
`marker_lengths`	二维码实际边长（米），用于位姿估计	`[0.039]`
`dictionary_id`	ArUco 字典 ID（10=DICT_6X6_250）	10

8. 常见问题

Q: `smsrun ls` 看不到 CUDA 节点？

确认 PyTorch CUDA 可用：

bash 复制代码

python3 -c "import torch; print(torch.cuda.is_available())"

如果返回 False，检查 Windows NVIDIA 驱动是否安装，WSL 版本是否为 WSL2。

Q: 提示 `spirems` 找不到？

确认已激活虚拟环境并安装了 spirems：

bash 复制代码

source ~/spirecv_env/bin/activate
pip install spirems

Q: 如何查看所有可用的 Launch 和节点？

bash 复制代码

smsrun ls        # 查看当前平台可用的节点和 Launch
smsrun ls -a     # 查看所有节点（包括不兼容当前平台的）

9. 下一步

查看 SpireCV-Pro 使用手册了解更多功能

查看 SpireMS 使用手册了解通信框架
rems

Q: 如何查看所有可用的 Launch 和节点？

bash 复制代码

smsrun ls        # 查看当前平台可用的节点和 Launch
smsrun ls -a     # 查看所有节点（包括不兼容当前平台的）

9. 下一步

查看 SpireCV-Pro 使用手册了解更多功能
查看 SpireMS 使用手册了解通信框架
尝试其他 Launch 文件，如多目标跟踪、RTSP 推流等

WSL系统下免费使用SpireCV-Pro教程