office_gzweb/docs/VLM_INTEGRATION.md

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 许可证，无商用限制

---

二、三种运行时模式

# 模式 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 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 验证安装

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

3.3 启动测试

# 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	本文档

---

八、快速验证流程

# 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