From 2dc184d46cc3dce876b503585db4960c89e522ae Mon Sep 17 00:00:00 2001
From: Bug <bug@coolje.com>
Date: Fri, 8 May 2026 09:21:49 +0800
Subject: [PATCH] docs: update README with VLM demo suite, YOLO/VLM/hybrid
 modes

---
 README.md | 83 ++++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 73 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index 84b895e..f94ab25 100644
--- a/README.md
+++ b/README.md
@@ -8,12 +8,14 @@
 - Nav2 导航栈（速度优化版）
 - SLAM Toolbox 在线建图
 - explore_lite 自动探索（调优版）
-- YOLOv8 视觉检测（640×480，中文输出，带图像归档）
+- **YOLOv8 CPU 视觉检测**（640×480，中文输出，带图像归档）
+- **Qwen2.5-VL-3B GPU 视觉检测**（VLM 语义理解，中文 JSON 输出，场景描述）
 - gzweb 网页端 3D 可视化
 - 循环探索模式（永不退出，自动保存地图后重启）
 - 一键停止脚本
 
 核心目标：一条命令启动，机器人自动探索、检测、建图，循环运行直到手动停止。
+支持三种视觉模式切换：**无视觉 / YOLO CPU / VLM GPU**。
 
 ---
 
@@ -106,21 +108,52 @@ touch /workspace/.run_all_stop
 
 ---
 
-## 视觉检测输出
+## 视觉检测
 
-YOLO 检测结果保存在 `/workspace/vision_output/YYYYMMDD_HHMMSS/` 目录下：
+支持三种模式，通过 `VISION_BACKEND` 环境变量切换：
+
+| 模式 | 命令 | 说明 |
+|------|------|------|
+| 关闭 | `./run_mapping.sh` | 不运行 detector，纯制图 |
+| YOLO CPU | `./run_yolo.sh` | YOLOv8n，~80ms/帧，COCO 80 类 |
+| VLM GPU | `./run_vlm.sh` | Qwen2.5-VL-3B，~6.6s/帧，语义理解 |
+
+### YOLO 输出
+
+保存于 `/workspace/vision_output/YYYYMMDD_HHMMSS/`：
 
 - `frame_0001.jpg` — 原始相机图像
 - `frame_0001_annotated.jpg` — 带检测框和中文标签的图像
 - `/workspace/camera_latest.jpg` — 最新一帧快速查看
 
-日志输出示例：
+日志示例：
 
 ```
 [vision] 第42帧 | 位置(1.23, 0.87, 0.15rad) | 检测到 3 个目标: 椅子(87%), 沙发(92%), 人(76%)
-[vision] 第43帧 | 位置(1.25, 0.89, 0.16rad) | 未检测到目标
 ```
 
+### VLM 输出
+
+Qwen2.5-VL-3B 返回中文 JSON：
+
+```json
+{
+  "objects": [
+    {"label": "饮水机", "bbox": [438, 72, 521, 256], "confidence": 0.95}
+  ],
+  "scene_description": "办公室茶水间"
+}
+```
+
+基准性能（Tesla T4）：
+
+| 指标 | 数值 |
+|------|------|
+| 模型加载 | ~4s |
+| 单帧推理 | **~6.6s**（640×480） |
+| VRAM 占用 | 7.5GB / 15.6GB |
+| 输出 token | ~70 个 |
+
 实时查看检测日志：
 
 ```bash
@@ -131,6 +164,22 @@ tail -f /workspace/logs/run_all_*/D_vision_yolo.log
 
 ## 常用脚本参数
 
+### 便捷脚本
+
+```bash
+# 纯制图（无 detector）
+./run_mapping.sh
+
+# YOLO CPU 视觉巡检
+./run_yolo.sh
+
+# VLM GPU 视觉巡检（需要 GPU 实例）
+./run_vlm.sh
+
+# VLM 混合模式（YOLO 持续 + VLM 定期深度分析）
+VISION_BACKEND=hybrid ./run_vlm.sh
+```
+
 ### `run_all.sh`
 
 ```bash
@@ -138,8 +187,11 @@ tail -f /workspace/logs/run_all_*/D_vision_yolo.log
 ./run_all.sh localization [--gzweb] [--no-gzweb-vite] [--no-rviz] [--map PATH] [--world PATH]
 ```
 
-可配置环境变量：
+可配置环境变量（`.env.defaults`）：
 
+- `VISION_BACKEND`（`yolo` / `vlm` / `hybrid`）
+- `VLM_INTERVAL`（默认 `5.0` 秒）
+- `VLM_MODEL`（默认 `Qwen/Qwen2.5-VL-3B-Instruct`）
 - `ROBOT_MODEL`（默认 `waffle`）
 - `GZ_PARTITION`（默认 `tb3_office_gz`）
 - `SLEEP_NAV2`（默认 `18` 秒）
@@ -214,6 +266,8 @@ tail -f /workspace/logs/run_all_*/D_vision_yolo.log
 - **纹理丢失/颜色异常**：检查 `ColladaLoader.js` 与 `GZ_SIM_RESOURCE_PATH`
 - **探索长期不结束**：`EXPLORE_WAIT_TIMEOUT` 超时后自动强制收尾并保存地图，30 秒后重启
 - **YOLO 误识别多**：预训练模型基于 COCO 真实照片，Gazebo 3D 渲染场景存在 domain gap，属于正常现象
+- **VLM 首次加载慢**：模型 7GB，首次加载约 4-5 秒，后续复用缓存
+- **VLM 推理慢**：单帧约 6-6.5 秒，属于正常范围，设计为定期采样而非每帧
 - **机器人不动**：Nav2 生命周期初始化需要 20-40 秒，请耐心等待
 
 ---
@@ -235,21 +289,30 @@ tail -f /workspace/logs/run_all_*/D_vision_yolo.log
 ## 快速命令参考
 
 ```bash
-# 启动（推荐，循环模式）
+# 启动（推荐，默认循环制图，无 detector）
 ./autorun.sh
 
 # 停止全部
 ./run_all_stop.sh
 
+# 纯制图
+./run_mapping.sh
+
+# YOLO CPU 视觉巡检
+./run_yolo.sh
+
+# VLM GPU 视觉巡检
+./run_vlm.sh
+
 # 仅 A+B（不含 explore/vision/gzweb）
 ./run_ab.sh mapping
 
 # 实时查看视觉检测日志
- tail -f /workspace/logs/run_all_*/D_vision_yolo.log
+tail -f /workspace/logs/run_all_*/D_vision_yolo.log
 
 # 查看最新相机图像
- ls -lh /workspace/camera_latest.jpg
+ls -lh /workspace/camera_latest.jpg
 
 # 查看视觉归档目录
- ls -la /workspace/vision_output/
+ls -la /workspace/vision_output/
 ```