メインコンテンツへ移動
AIチュートリアル

Code-as-Worldモデルを実行して定量的な物理推論を行う

Code-as-Worldのインストール方法、4Bおよび9Bの視覚言語チェックポイントのダウンロード方法、QuantiPhyの動画評価の実行方法、vLLMによるモデルの公開方法、付属のMuJoCo弾道サッカー例の実行方法を学びます。

約12分で読了
Code-as-Worldモデルで定量的な物理推論を実行

Code-as-Worldとは？

Code-as-Worldは、実行可能なコードを通じて物理世界を表現する研究プロジェクトです。中心となる考え方は、ピクセルはシーンに関する証拠を提供するものの、観測されたものを生み出したオブジェクト、状態、構造、動態、メカニズムを直接定義するものではないということです。

このプロジェクトでは、反復的なシミュレーションと検証に基づくエージェント型プロセスを使用し、観測から実行可能な世界表現を発見します。これらの表現は、視覚的証拠を再利用可能な物理データに変換し、定量的な物理推論を可能にします。

Code-as-Worldプロジェクトの概要

このリリースでは、2つの視覚言語チェックポイント、Code-as-World-VL-4BとCode-as-World-VL-9Bについて、ローカル推論と評価をサポートしています。また、vLLMによるOpenAI互換サービングと、MuJoCoで構築された動画ベースの物理抽象化の例も含まれています。

主な機能

  • 実行可能な世界表現：ピクセルをシーンの完全なオントロジーとして扱うのではなく、物理状態、動態、メカニズムをモデル化します。
  • 2つの公開チェックポイント：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系シェル向けです。有効化したら、プロジェクトが提供する推論用依存関係をインストールします。

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に配置されます。1つのモデルだけを使用する場合は、対応するチェックポイントのみをダウンロードしてください。

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/に3種類の成果物が書き出されます。評価器互換の予測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

このコマンドは、outputs/quantiphyにある予測ファイルをquantiphy_validation.csvと照合して評価し、結果のメトリクスを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シミュレーションを実行したりできます。これらのワークフローを組み合わせることで、視覚的な観測が明示的で検証可能な物理推論をどのように支援できるかが示されます。