统一 Vision Language Model 测试环境

面向机器人视觉理解（窗户开关、积水检测）。本仓库不包含、也不自动下载模型权重。

原 SmolVLM2 相关代码与数据已收拢到 smovlm2/、data/smolvlm2_test/；四模型统一推理与评测在仓库根目录。

VLMs/
├── Qwen3-VL-2B/          # infer.py + weights/ + DOWNLOAD.md
├── Qwen2.5-VL-3B/
├── Cosmos-Reason2-2B/
├── SmolVLM2-2.2B/
├── smovlm2/              # 既有 SmolVLM2 推理/评测（历史路径）
├── datasets/             # 统一 benchmark：test.json + images/
├── data/                 # 既有测试数据（smolvlm2_test 等）
├── scripts/              # 推理 / evaluate / check_env
├── results/
├── docs/ENVIRONMENT.md
├── requirements.txt
└── requirements-jetson.txt

---

1. 环境安装

先只读体检（不装包）：

conda activate smolvlm   # 当前最接近需求的已有环境
python /home/gzz/Codes/VLMs/scripts/check_env.py

当前机器摘要见 docs/ENVIRONMENT.md。

若要新建环境（不会自动执行）：

bash scripts/setup_env.sh          # 只打印命令
conda create -n vlm-bench python=3.10 -y
conda activate vlm-bench
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124
pip install -r requirements.txt
# 可选 4bit（x86）：
pip install bitsandbytes

Qwen2.5-VL 官方还需要：

pip install qwen-vl-utils

不要修改系统 /usr/local/cuda（现为 11.8）。驱动已是 12.8，与 PyTorch cu124 可以并存。

---

2. 模型下载（请手动执行）

把权重放到各模型的 weights/，目录内需有 config.json 和完整的 *.safetensors（不能只剩 .incomplete）。

2.0 下载前注意

1. 不要用系统 Python 3.8 的 ~/.local/bin/modelscope（缺 zoneinfo）。先激活 smolvlm：

conda activate smolvlm
which modelscope   # 应为 .../envs/smolvlm/bin/modelscope

2. 新版 ModelScope CLI 是位置参数 + --local-dir（连字符）：

modelscope download Qwen/Qwen3-VL-2B-Instruct \
  --local-dir /home/gzz/Codes/VLMs/Qwen3-VL-2B/weights

3. Hugging Face CLI 推荐：

hf download <repo_id> --local-dir <dir>
# 旧写法 huggingface-cli download 仍可用，但会提示 deprecated

4. 断点续传：空间不足或超时后，不要删 *.incomplete，对同一 --local-dir 再执行同一命令即可续传。

5. 下完确认：无 .incomplete；Qwen2.5-VL-3B 应同时有 model-00001-of-00002.safetensors 与 model-00002-of-00002.safetensors。

2.1 Qwen3-VL-2B

conda activate smolvlm

# ModelScope（国内优先）
modelscope download Qwen/Qwen3-VL-2B-Instruct \
  --local-dir /home/gzz/Codes/VLMs/Qwen3-VL-2B/weights

# Hugging Face
hf download Qwen/Qwen3-VL-2B-Instruct \
  --local-dir /home/gzz/Codes/VLMs/Qwen3-VL-2B/weights

2.2 Qwen2.5-VL-3B

modelscope download Qwen/Qwen2.5-VL-3B-Instruct \
  --local-dir /home/gzz/Codes/VLMs/Qwen2.5-VL-3B/weights

hf download Qwen/Qwen2.5-VL-3B-Instruct \
  --local-dir /home/gzz/Codes/VLMs/Qwen2.5-VL-3B/weights

完整约 7.0 GB（两个 shard）。若只见一个完整 shard + 一个 .incomplete，说明未下完。

2.3 Cosmos Reason2-2B

官网：

• 模型页：https://huggingface.co/nvidia/Cosmos-Reason2-2B
• 文件列表：https://huggingface.co/nvidia/Cosmos-Reason2-2B/tree/main

通过许可后：

conda activate smolvlm
# 建议 unset 镜像后再下 gated 模型
unset HF_ENDPOINT
hf download nvidia/Cosmos-Reason2-2B \
  --local-dir /home/gzz/Codes/VLMs/Cosmos-Reason2-2B/weights

或在网页手动下载，必下（约 4.6 GB）：

• model.safetensors（~4.5 GB）
• config.json、generation_config.json
• preprocessor_config.json、video_preprocessor_config.json
• tokenizer.json、tokenizer_config.json、chat_template.json
• merges.txt、vocab.json

可不下：README.md、.gitattributes、三张 PNG 展示图。

2.4 SmolVLM2-2.2B

modelscope download HuggingFaceTB/SmolVLM2-2.2B-Instruct \
  --local-dir /home/gzz/Codes/VLMs/SmolVLM2-2.2B/weights

hf download HuggingFaceTB/SmolVLM2-2.2B-Instruct \
  --local-dir /home/gzz/Codes/VLMs/SmolVLM2-2.2B/weights

各模型目录还有 DOWNLOAD.md。

2.5 下载排障

---

3. 推理方法

默认 只读本地 weights（local_files_only=True）。不要加 --allow-download，除非你明确要联网。

单张图片

conda activate smolvlm
cd /home/gzz/Codes/VLMs

python scripts/infer_qwen3_vl.py \
  --image datasets/images/window/placeholder_closed.jpg \
  --task window --precision bf16 --attn sdpa

python scripts/infer_qwen25_vl.py \
  --image datasets/images/puddle/placeholder_water.jpg \
  --task puddle --precision fp16 --quant 4bit

python scripts/infer_cosmos_reason2.py \
  --image datasets/images/window/placeholder_open.jpg \
  --task window --max-new-tokens 256

python scripts/infer_smolvlm2.py \
  --image datasets/images/puddle/placeholder_dry.jpg \
  --task puddle

也可在模型目录：python Qwen3-VL-2B/infer.py --image ...

图片文件夹

python scripts/infer_qwen3_vl.py \
  --image datasets/images/window \
  --task window \
  --output results/qwen3_window.json

精度与量化

统一 JSON 字段：

{
  "image": "",
  "prompt": "",
  "response": "",
  "latency": "",
  "gpu_memory": ""
}

机器人任务还会附加 pred_label 与：

{
  "object": "",
  "state": "",
  "confidence": "",
  "location_description": ""
}

---

4. Benchmark 方法

标注格式见 datasets/test.json 与 datasets/README.md。

python scripts/evaluate_vlm.py \
  --model qwen3-vl \
  --dataset datasets/test.json \
  --skip-missing \
  --output results/qwen3-vl_eval.json

--model：qwen3-vl | qwen25-vl | cosmos-reason2 | smolvlm2

输出 summary：

• accuracy
• confusion_matrices（按 task）
• average_latency_sec
• average_gpu_memory_gb / max_gpu_memory_gb

占位图只用于通路检查，不能报真实准确率。

---

5. Jetson AGX Orin 64GB 注意事项

1. PyTorch 必须用 JetPack 对应 wheel，不要拷 x86 的 +cu124 包。
2. 不要编译 flash-attn；全程 --attn sdpa。
3. bitsandbytes 在 aarch64 经常不可用。4bit 接口已预留，Orin 上改用 AWQ、TensorRT-LLM 或 GGUF。
4. 64GB 统一内存够跑 2B/3B FP16，但仍建议：
   • 先上 SmolVLM2-2.2B
   • Qwen3-VL-2B / Cosmos-Reason2-2B 次之（Cosmos 务必截断生成长度）
   • Qwen2.5-VL-3B 限制 max_pixels（Qwen 官方 256×28×28 ~ 1280×28×28）
5. Cosmos 官方表格写 2B 需 24GB，针对长 reasoning；机载短指令用 256 tokens。
6. 电源模式：nvpmodel 拉到 MAXN，并注意散热；否则 token/s 会腰斩。
7. 相机图先缩放到 640–1024 长边再送 VLM，比原图 4K 更稳。
8. 本仓库脚本在 x86 上开发；迁 Orin 时只换 torch wheel 与 --quant none。

---

6. 官方加载对照