运行 Code-as-World 模型进行定量物理推理

什么是 Code-as-World？

Code-as-World 是一个通过可执行代码表示物理世界的研究项目。其核心理念是：像素能够提供场景的证据，但无法直接定义产生所观察现象的对象、状态、结构、动力学或机制。

该项目采用基于迭代模拟与验证的智能体流程，从观察结果中发现可执行的世界表示。这些表示将视觉证据转化为可复用的物理数据，并支持定量物理推理。

此版本为两个视觉语言检查点提供本地推理与评估支持：Code-as-World-VL-4B 和 Code-as-World-VL-9B。它还支持通过 vLLM 提供兼容 OpenAI 的服务，并包含一个使用 MuJoCo 构建、由视频驱动的物理抽象示例。

主要功能

• 可执行的世界表示：对物理状态、动力学和机制进行建模，而不是将像素视为场景的完整本体。
• 两个已发布的检查点：可在 4B 和 9B Code-as-World-VL 模型之间选择。
• QuantiPhy 评估：对验证视频运行定量物理推理评估，并生成与评估器兼容的预测文件。
• 兼容 OpenAI 的服务：使用标准 vLLM API 服务器提供任一检查点的服务。
• 模拟示例：运行随附的弹道足球案例，并保存其渲染视频和轨迹。

前提条件

请在支持 CUDA 的主机上使用 Python 3.10 或 3.11。你还需要 Git，以及供 hf download 命令使用的 Hugging Face CLI。模型存储空间和 GPU 显存需求取决于你使用 4B 检查点、9B 检查点，还是同时使用两者。

请在 CUDA 环境中执行仓库中的命令。README 未提供仅使用 CPU 的推理方案。

安装 Code-as-World

1. 克隆仓库

git clone https://github.com/MirroS-Lab/Code-as-World.git
cd Code-as-World

2. 创建并激活虚拟环境

python -m venv .venv
source .venv/bin/activate

上述激活命令适用于类 Unix shell。激活后，安装项目提供的推理依赖项：

pip install -r requirements/inference.txt

3. 下载检查点

hf download MirroS-Lab/Code-as-World-VL-4B --local-dir weights/4b
hf download MirroS-Lab/Code-as-World-VL-9B --local-dir weights/9b

这些命令会将 4B 和 9B 模型分别放入 weights/4b 和 weights/9b。如果只打算使用其中一个模型，请仅下载对应的检查点。

运行 QuantiPhy 评估

QuantiPhy 是此版本使用的定量评估套件。在运行 Code-as-World 评估之前，请克隆 QuantiPhy 并下载其验证视频。

1. 准备评估数据

git clone https://github.com/Paulineli/QuantiPhy.git /path/to/QuantiPhy
hf download PaulineLi/QuantiPhy-validation \
  --repo-type dataset \
  --local-dir /path/to/QuantiPhy-validation

请将 /path/to/QuantiPhy 和 /path/to/QuantiPhy-validation 替换为系统中的实际路径。

2. 评估 4B 模型

在 Code-as-World 仓库中运行：

python -m code_as_world.evaluation 4b \
  --input-csv /path/to/QuantiPhy/quantiphy_validation.csv \
  --video-dir /path/to/QuantiPhy-validation/validation_videos

3. 评估 9B 模型

python -m code_as_world.evaluation 9b \
  --input-csv /path/to/QuantiPhy/quantiphy_validation.csv \
  --video-dir /path/to/QuantiPhy-validation/validation_videos

每次运行都会向 outputs/quantiphy/ 写入三类产物：与评估器兼容的预测 CSV、单次运行的指标摘要，以及模型的原始生成结果。在检查各项分数背后的响应时，保留原始输出非常有用。

4. 运行官方评估器

生成预测 CSV 文件后，安装 pandas 并调用官方 QuantiPhy 评估器：

pip install pandas
python /path/to/QuantiPhy/evaluator.py \
  outputs/quantiphy \
  outputs/quantiphy_metrics \
  --gt_file /path/to/QuantiPhy/quantiphy_validation.csv

此命令会根据 quantiphy_validation.csv 评估 outputs/quantiphy 中的预测文件，并将所得指标写入 outputs/quantiphy_metrics。

使用 vLLM 提供模型服务

这些检查点可通过兼容 OpenAI 的 vLLM 端点提供服务。以下命令会在 GPU 0 上提供 4B 检查点的服务：

CUDA_VISIBLE_DEVICES=0 vllm serve weights/4b \
  --served-model-name code-as-world-4b \
  --chat-template code_as_world/templates/qwen3_5_no_think.jinja \
  --chat-template-content-format openai \
  --default-chat-template-kwargs '{"enable_thinking":false}' \
  --max-model-len 4608 \
  --gpu-memory-utilization 0.90 \
  --media-io-kwargs '{"video":{"num_frames":16,"fps":-1,"video_backend":"openpangu"}}' \
  --mm-processor-kwargs '{"do_sample_frames":false}' \
  --mm-processor-cache-gb 0 \
  --generation-config vllm

服务器以 code-as-world-4b 名称注册模型。它使用项目的无思考聊天模板，将最大模型长度设置为 4608，并通过 openpangu 后端将视频输入配置为 16 帧。

若要提供更大检查点的服务，请将 weights/4b 替换为 weights/9b，并将 code-as-world-4b 替换为 code-as-world-9b。

运行视频驱动的抽象示例

该仓库包含一个基于 MuJoCo 的弹道足球示例。请先安装单独的模拟依赖项：

pip install -r requirements/simulation.txt

然后启动模拟：

python -m code_as_world.simulation

模拟会将渲染视频和轨迹写入 outputs/simulations/。

仅生成轨迹

如果不需要渲染视频，请禁用渲染：

python -m code_as_world.simulation --no-render

当只需要轨迹数据，或渲染会带来不必要的开销时，此模式非常有用。

高级使用技巧

• 谨慎选择模型：评估参数 4b 或 9b 应始终与下载的检查点保持一致。
• 仅下载所需内容：如果工作流只使用一种模型规模，请避免同时存储两个检查点。
• 保留原始生成结果：在诊断预测为何获得特定分数时，请检查 outputs/quantiphy/ 中的文件。
• 运行两层评估：Code-as-World 命令会创建单次运行摘要，而官方 QuantiPhy 评估器可以统一评估生成的预测 CSV 文件。
• 保留所提供的聊天模板：服务方案明确使用 code_as_world/templates/qwen3_5_no_think.jinja 并禁用思考。复现文档中的配置时，请保留这些设置。
• 谨慎调整 GPU 选择：服务示例使用 CUDA_VISIBLE_DEVICES=0，GPU 显存利用率设置为 0.90。请根据 CUDA 主机选择可见设备，同时注意，其他更改将偏离发布版本提供的方案。
• 适时跳过渲染：如果只需要输出轨迹，请在模拟命令中添加 --no-render。

延伸阅读

有关研究背景和方法，请参阅技术报告、项目页面和 MirroS 博客文章。

总结

Code-as-World 为探索物理场景的可执行表示提供了实用版本。安装推理环境并下载检查点后，你可以复现 QuantiPhy 评估、通过 vLLM 提供模型服务，或运行随附的 MuJoCo 模拟。这些工作流共同展示了视觉观察如何支持明确且可验证的物理推理。