# 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
bash scripts/install_vlm.sh
```

该脚本会自动：
- 检测 CUDA 环境，按需安装 PyTorch 2.1.2+cu121
- 安装 transformers、accelerate、qwen-vl-utils
- Ampere 架构 GPU 自动安装 Flash Attention 2
- 预下载 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|>`

### 模型缓存

- 首次下载约 6-8GB，缓存到 `/workspace/.cache/huggingface`（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
```