Lego VLM-Agent Benchmark

本仓库当前的工作内容是一套基于 VLM（视觉语言大模型）的 LEGO 砖块结构识别评测框架，统一入口是：

src/benchmark/benchmark_cli.py

benchmark_cli.py 读取一份 YAML 配置（runner + args 结构），按 runner 字段把任务派发到对应实现：agent / compare / perspective。

---

1. 环境准备

conda activate lego

lego 环境（Python 3.12）已经预装 httpx / anyio / pillow / pydantic / volcengine-python-sdk 等。其余依赖按需补装：

pip install pyyaml numpy networkx matplotlib open3d openai gurobipy

设置 VLM API Key（默认使用 DashScope / Qwen 兼容接口）：

export DASHSCOPE_API_KEY=<your_key>
# 或火山引擎 ARK：
export ARK_API_KEY=<your_key>

---

2. 使用方式

进入 benchmark 目录后，统一通过 benchmark_cli.py --config <yaml> 启动：

conda activate lego
cd /workspace/hechangjing/BrickGPT/src/benchmark

python benchmark_cli.py --config configs/vlm_multi_step.yaml
python benchmark_cli.py --config configs/vlm_one_shot.yaml
python benchmark_cli.py --config configs/run_compare.yaml
python benchmark_cli.py --config configs/test_perspective.yaml

配置优先级：

1. YAML 中的 args: 字段先加载；
2. 命令行额外参数（--key value）会覆盖 YAML 同名字段；
3. 可用 --runner {agent,compare,perspective} 在命令行强制切换 runner；
4. 对于 runner: agent，可用 --mode {iterative,one_shot} 在命令行覆盖。

---

3. 三种 runner

3.1 runner: agent（iterative / one_shot）

配置：configs/vlm_multi_step.yaml / configs/vlm_one_shot.yaml

• iterative：每步预测并移除顶层一块砖，直到结构清空。
• one_shot：一次性预测整张图中的全部砖块。

两个模板默认 gen_first: true，即先随机生成结构再评测；可通过 gen_grid_size / gen_num_voxels / gen_attempts / gen_support_mode 控制生成。

产物目录：

• iterative：runs_multi_step/<时间戳>_effort-*/{init,step_XXX,try_summary.{txt,json}}
• one_shot：runs_one_shot/<时间戳>_effort-*/one_shot/... + one_shot_summary.{txt,json}

3.2 runner: compare（成对评测）

配置：configs/run_compare.yaml

每道题先随机生成一个结构，再分别跑 one_shot 与 iterative (multi_step)，并按 (h, w, x, y, z) 元组对比正确块数。

产物目录：

run_compare/<时间戳>/
├── task1/
│   ├── problem/                # output.png / output.txt / output.json
│   ├── one_shot/               # one_shot 推理产物
│   ├── multi_step/             # iterative 推理产物
│   └── compare_metrics.json    # 单任务正确块统计
├── task2/ ...
└── compare_summary.json        # 全任务正确块统计汇总

3.3 runner: perspective（多视角实验）

配置：configs/test_perspective.yaml

围绕同一结构生成 4 个顺时针视角（0/90/180/270°）：

• perspective_mode: basic：单视角整体预测全部砖块；
• perspective_mode: interactive：模型可主动请求新视角，最多 max_turns 次；
• perspective_mode: both：两种都跑。

Ground truth 统一保存为 gt_bricks.json。

产物目录：

runs_perspective/<时间戳>_effort-*/
└── test_perspective/
    ├── problem/                # 4 视角图 + output.txt / output.json
    ├── gt_bricks.json
    ├── basic/                  # 单视角预测
    ├── interactive/            # 多视角交互预测
    └── result_summary.{txt,json}

---

4. 关键参数速查

YAML args: 下可设置（命令行同名覆盖）：

参数	适用 runner	说明
mode	agent	iterative 或 one_shot
model	全部	VLM 模型名称（如 qwen3.6-plus、doubao-seed-2-0-pro-260215）
reasoning_effort	全部	low / medium / high
ark_timeout	全部	单次请求最大等待秒数
retries	全部	VLM 输出不合法时重试次数
max_steps	agent (iterative) / compare	iterative 最大步数
skip_render	agent (iterative)	跳过中间步骤重渲染
gen_first	全部	启用随机结构生成
gen_grid_size / gen_num_voxels / gen_seed / gen_attempts / gen_support_mode	全部	随机生成参数
num_tasks / start_seed	compare	任务数量与起始 seed
perspective_mode	perspective	basic / interactive / both
initial_view_idx	perspective	起始视角索引 (0~3)
max_turns	perspective	interactive 最大交互轮数
out_root	全部	输出根目录
mock_vlm_text	全部	本地调试，跳过真实 VLM 调用

---

5. 本地调试（无 API）

通过命令行覆盖 mock_vlm_text 即可跳过真实 VLM 调用：

python benchmark_cli.py --config configs/vlm_one_shot.yaml \
    --mock_vlm_text '{"bricks":[{"brick":"1*1:(0,0,0)","z":0,"color":"brown"}]}'

python benchmark_cli.py --config configs/vlm_multi_step.yaml \
    --max_steps 1 --skip_render \
    --mock_vlm_text '{"brick":"1*1:(0,0,0)","z":0,"color":"brown"}'