181 lines
5.7 KiB
Markdown
181 lines
5.7 KiB
Markdown
# VLM GPU 视觉识别集成方案
|
||
|
||
> 在保留现有 YOLOv8 CPU 识别的基础上，增加运行时选项启用 GPU 本地 VLM 模型，用于 Gazebo office 场景机器人巡检与摄像头目标识别。
|
||
|
||
---
|
||
|
||
## 一、模型选型
|
||
|
||
| 模型 | 参数量 | 显存需求 | 推理速度* | 中文 | 视觉定位 | 许可证 |
|
||
|------|--------|---------|----------|------|---------|--------|
|
||
| **Qwen2.5-VL-3B-Instruct** ⭐ | 3B | ~8-10GB (BF16) | 2-4s/帧 | 原生 | ✅ bbox | Apache-2.0 |
|
||
| Qwen2.5-VL-3B-AWQ | 3B | ~3-4GB (INT4) | 1.5-3s/帧 | 原生 | ✅ bbox | Apache-2.0 |
|
||
| MiniCPM-V 2.6 | 8B | ~17GB / ~7GB(INT4) | 3-6s/帧 | 原生 | ✅ bbox | 学术/商用 |
|
||
|
||
*推理速度：单张 640×480 图像，生成 80-120 tokens，NVIDIA T4 估算值
|
||
|
||
**推荐：Qwen2.5-VL-3B-Instruct (BF16)**
|
||
- 3B 参数性价比最高，T4 16GB 刚好跑得动
|
||
- 原生支持中文视觉定位（`<|box_start|>(x1,y1),(x2,y2)<|box_end|>`）
|
||
- 支持结构化 JSON 输出，便于解析为 ROS2 Detection2DArray
|
||
- Apache-2.0 许可证，无商用限制
|
||
|
||
---
|
||
|
||
## 二、三种运行时模式
|
||
|
||
```bash
|
||
# 模式 A：YOLOv8 CPU（默认，完全兼容原有行为）
|
||
./run_all.sh mapping --explore --vision
|
||
|
||
# 模式 B：VLM GPU（异步推理，避免阻塞 Nav2）
|
||
VISION_BACKEND=vlm ./run_all.sh mapping --explore --vision
|
||
|
||
# 模式 C：混合模式 — YOLO 持续检测 + VLM 每 10s 深度分析
|
||
VISION_BACKEND=hybrid VLM_INTERVAL=10.0 ./run_all.sh mapping --explore --vision
|
||
```
|
||
|
||
### 环境变量
|
||
|
||
| 变量 | 默认值 | 说明 |
|
||
|------|--------|------|
|
||
| `VISION_BACKEND` | `yolo` | `yolo` / `vlm` / `hybrid` |
|
||
| `VLM_INTERVAL` | `5.0` | VLM 采样间隔（秒） |
|
||
| `VLM_MODEL` | `Qwen/Qwen2.5-VL-3B-Instruct` | 模型名称 |
|
||
| `VLM_MAX_NEW_TOKENS` | `256` | 最大生成 token 数 |
|
||
| `VLM_PROMPT` | `（内置）` | 自定义提示词 |
|
||
| `VLM_MIN_PIXELS` | `200704` | 图像最小像素（256×28×28） |
|
||
| `VLM_MAX_PIXELS` | `501760` | 图像最大像素（640×28×28） |
|
||
|
||
---
|
||
|
||
## 三、安装部署
|
||
|
||
### 3.1 安装依赖（GPU 容器内执行）
|
||
|
||
```bash
|
||
# 国内环境（默认）：自动使用阿里云 pip 镜像 + 魔搭 ModelScope 下载模型
|
||
bash scripts/install_vlm.sh
|
||
|
||
# 境外环境（官方源）
|
||
USE_CHINA_MIRROR=false bash scripts/install_vlm.sh
|
||
```
|
||
|
||
该脚本会自动：
|
||
- 检测 CUDA 环境，按需安装 PyTorch 2.1.2+cu121（国内优先阿里云镜像，失败则回退官方源）
|
||
- pip 包使用阿里云镜像加速（transformers、accelerate、qwen-vl-utils 等）
|
||
- Ampere 架构 GPU 自动安装 Flash Attention 2
|
||
- **国内默认通过魔搭 ModelScope 下载模型**（无需 HuggingFace 连通性）
|
||
- 预下载 Qwen2.5-VL-3B-Instruct 模型（约 6-8GB，缓存到 EFS）
|
||
|
||
### 3.2 验证安装
|
||
|
||
```bash
|
||
python3 -c "import torch; print(torch.cuda.is_available(), torch.cuda.get_device_name(0))"
|
||
```
|
||
|
||
### 3.3 启动测试
|
||
|
||
```bash
|
||
# YOLO 模式（默认）
|
||
./run_all.sh mapping --explore --vision
|
||
|
||
# VLM 模式
|
||
VISION_BACKEND=vlm VLM_INTERVAL=5.0 ./run_all.sh mapping --explore --vision
|
||
|
||
# 查看 VLM 场景描述
|
||
ros2 topic echo /vision/scene_description
|
||
```
|
||
|
||
---
|
||
|
||
## 四、硬件与成本
|
||
|
||
### 推荐 GPU 实例（AWS 中国）
|
||
|
||
| 实例 | GPU | 显存 | 按需/小时 | 适用性 |
|
||
|------|-----|------|----------|--------|
|
||
| g4dn.xlarge | T4 | 16GB | ~¥3.8 | ✅ 最佳性价比 |
|
||
| g5.xlarge | A10G | 24GB | ~¥7.2 | ✅ 性能冗余 |
|
||
|
||
### 显存占用
|
||
|
||
| 组件 | 显存 |
|
||
|------|------|
|
||
| Qwen2.5-VL-3B BF16 权重 | ~6.5GB |
|
||
| ViT 视觉编码器 | ~1.5GB |
|
||
| KV Cache | ~0.5GB |
|
||
| 激活/中间结果 | ~1-2GB |
|
||
| **总计** | **~10-11GB** |
|
||
|
||
> 若显存不足，可切换至 AWQ 量化版：`export VLM_MODEL=Qwen/Qwen2.5-VL-3B-Instruct-AWQ`
|
||
|
||
---
|
||
|
||
## 五、架构要点
|
||
|
||
### VLM 异步推理
|
||
|
||
VLM 单帧推理需 2-5 秒，若在 ROS2 回调中同步执行会阻塞 Nav2。`detector.py` 在 VLM 模式下自动使用**后台线程**执行推理，ROS executor 不会被阻塞。
|
||
|
||
### 双格式解析
|
||
|
||
VLM 输出支持两种解析策略：
|
||
1. **JSON 提取**：优先匹配 `{"objects": [...], "scene_description": "..."}`
|
||
2. **原生 grounding 兜底**：解析 `<|box_start|>(x1,y1),(x2,y2)<|box_end|>`
|
||
|
||
### 模型缓存与离线加载
|
||
|
||
- **国内模式**：模型通过魔搭 ModelScope 下载到 `/workspace/.cache/modelscope/hub/...`，同时记录本地路径到 `/workspace/.vlm_model_path`
|
||
- **境外模式**：模型通过 HuggingFace 官方源下载到 `/workspace/.cache/huggingface/hub/...`，同样记录本地路径
|
||
- `run_all.sh` 启动时会自动 `source /workspace/.vlm_model_path`，detector.py 直接使用本地路径加载，**无需运行时联网**
|
||
- 容器重启后无需重新下载（EFS 持久化）
|
||
- 可在镜像构建时预置到 `/opt/vendor/vlm_models/` 以进一步加速启动
|
||
|
||
---
|
||
|
||
## 六、性能预期
|
||
|
||
| 指标 | YOLOv8 CPU | VLM GPU (T4) |
|
||
|------|-----------|-------------|
|
||
| 单帧处理 | ~80ms | ~3-5s |
|
||
| 频率 | 1Hz | 0.2Hz (5s interval) |
|
||
| CPU | ~100% (1核) | ~50% (预处理) |
|
||
| GPU | 0 | ~90% (推理时) |
|
||
| 假阳性 | 高（COCO 预训练） | 低（语义理解） |
|
||
| 语义能力 | 无 | 场景描述、异常检测 |
|
||
|
||
---
|
||
|
||
## 七、文件清单
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `src/vision_yolo/vision_yolo/detector.py` | 修改后的检测器（支持三模式切换） |
|
||
| `scripts/install_vlm.sh` | VLM 依赖安装脚本 |
|
||
| `docs/VLM_INTEGRATION.md` | 本文档 |
|
||
|
||
---
|
||
|
||
## 八、快速验证流程
|
||
|
||
```bash
|
||
# 1. SSH 进入 GPU 实例
|
||
ssh devuser@<gpu-space>
|
||
|
||
# 2. 安装依赖
|
||
bash scripts/install_vlm.sh
|
||
|
||
# 3. 启动 Gazebo + Nav2
|
||
./run_all.sh mapping --explore
|
||
|
||
# 4. 单独测试 VLM 节点
|
||
export VISION_BACKEND=vlm
|
||
export VLM_INTERVAL=3.0
|
||
ros2 run vision_yolo detector
|
||
|
||
# 5. 观察话题
|
||
ros2 topic echo /vision/scene_description
|
||
ros2 topic hz /vision/detections
|
||
```
|