Chạy các mô hình Code-as-World để suy luận vật lý định lượng

Code-as-World là gì?

Code-as-World là một dự án nghiên cứu nhằm biểu diễn thế giới vật lý bằng mã có thể thực thi. Ý tưởng cốt lõi là các pixel cung cấp bằng chứng về một cảnh, nhưng không trực tiếp xác định các đối tượng, trạng thái, cấu trúc, động lực học hoặc cơ chế tạo ra những gì được quan sát.

Dự án sử dụng một quy trình tác tử dựa trên mô phỏng và xác minh lặp để khám phá các biểu diễn thế giới có thể thực thi từ những quan sát. Các biểu diễn này chuyển bằng chứng hình ảnh thành dữ liệu vật lý có thể tái sử dụng và hỗ trợ suy luận vật lý định lượng.

Bản phát hành cung cấp khả năng suy luận và đánh giá cục bộ cho hai mô hình ngôn ngữ-thị giác: Code-as-World-VL-4B và Code-as-World-VL-9B. Bản phát hành cũng bao gồm dịch vụ tương thích với OpenAI thông qua vLLM và một ví dụ về trừu tượng hóa vật lý dựa trên video được xây dựng bằng MuJoCo.

Khả năng chính

• Biểu diễn thế giới có thể thực thi: Mô hình hóa các trạng thái, động lực học và cơ chế vật lý thay vì coi pixel là toàn bộ bản thể học của một cảnh.
• Hai mô hình được phát hành: Lựa chọn giữa các mô hình Code-as-World-VL 4B và 9B.
• Đánh giá QuantiPhy: Chạy đánh giá suy luận vật lý định lượng trên các video xác thực và tạo các tệp dự đoán tương thích với trình đánh giá.
• Dịch vụ tương thích với OpenAI: Cung cấp một trong hai mô hình thông qua máy chủ API vLLM tiêu chuẩn.
• Ví dụ mô phỏng: Chạy trường hợp bóng đá đạn đạo đi kèm và lưu video kết xuất cùng quỹ đạo của nó.

Điều kiện tiên quyết

Sử dụng Python 3.10 hoặc 3.11 trên máy chủ hỗ trợ CUDA. Bạn cũng cần Git và CLI của Hugging Face được sử dụng trong các lệnh hf download. Yêu cầu về dung lượng lưu trữ mô hình và bộ nhớ GPU phụ thuộc vào việc bạn sử dụng mô hình 4B, mô hình 9B hay cả hai.

Thực hiện các lệnh của kho mã trong môi trường CUDA. README không cung cấp công thức suy luận chỉ dành cho CPU.

Cài đặt Code-as-World

1. Sao chép kho mã

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

2. Tạo và kích hoạt môi trường ảo

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

Lệnh kích hoạt ở trên dành cho các shell kiểu Unix. Sau khi kích hoạt, cài đặt các phần phụ thuộc suy luận do dự án cung cấp:

pip install -r requirements/inference.txt

3. Tải các mô hình

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

Các lệnh này đặt mô hình 4B và 9B vào weights/4b và weights/9b. Nếu chỉ định sử dụng một mô hình, bạn chỉ cần tải mô hình tương ứng.

Chạy đánh giá QuantiPhy

QuantiPhy là bộ công cụ đánh giá định lượng được sử dụng trong bản phát hành. Trước khi chạy đánh giá Code-as-World, hãy sao chép QuantiPhy và tải các video xác thực của bộ dữ liệu.

1. Chuẩn bị dữ liệu đánh giá

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

Thay /path/to/QuantiPhy và /path/to/QuantiPhy-validation bằng các vị trí thực trên hệ thống của bạn.

2. Đánh giá mô hình 4B

Từ kho mã Code-as-World, chạy:

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

3. Đánh giá mô hình 9B

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

Mỗi lần chạy ghi ba loại tệp vào outputs/quantiphy/: một CSV dự đoán tương thích với trình đánh giá, bản tóm tắt chỉ số cho lần chạy riêng lẻ và các kết quả sinh thô của mô hình. Việc giữ lại đầu ra thô rất hữu ích khi kiểm tra các phản hồi đứng sau từng điểm số.

4. Chạy trình đánh giá chính thức

Sau khi tạo các tệp CSV dự đoán, cài đặt pandas và gọi trình đánh giá QuantiPhy chính thức:

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

Lệnh này đánh giá các tệp dự đoán trong outputs/quantiphy dựa trên quantiphy_validation.csv và ghi các chỉ số thu được vào outputs/quantiphy_metrics.

Cung cấp mô hình bằng vLLM

Các mô hình có thể được cung cấp thông qua một endpoint vLLM tương thích với OpenAI. Lệnh sau cung cấp mô hình 4B trên GPU 0:

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

Máy chủ đăng ký mô hình với tên code-as-world-4b. Mô hình sử dụng mẫu trò chuyện không suy nghĩ của dự án, đặt độ dài tối đa của mô hình là 4608 và cấu hình đầu vào video gồm 16 khung hình thông qua backend openpangu.

Để phục vụ checkpoint lớn hơn, hãy thay weights/4b bằng weights/9b và thay code-as-world-4b bằng code-as-world-9b.

Chạy ví dụ trừu tượng hóa dựa trên video

Kho mã nguồn bao gồm một ví dụ bóng đá đạn đạo được hỗ trợ bởi MuJoCo. Trước tiên, hãy cài đặt các yêu cầu riêng cho mô phỏng:

pip install -r requirements/simulation.txt

Sau đó khởi chạy mô phỏng:

python -m code_as_world.simulation

Mô phỏng ghi video đã kết xuất và quỹ đạo vào outputs/simulations/.

Chỉ tạo quỹ đạo

Nếu không cần video đã kết xuất, hãy tắt tính năng kết xuất:

python -m code_as_world.simulation --no-render

Chế độ này hữu ích khi chỉ cần dữ liệu quỹ đạo hoặc khi việc kết xuất tạo thêm chi phí không cần thiết.

Mẹo sử dụng nâng cao

• Chọn mô hình một cách có chủ đích: Sử dụng đối số đánh giá 4b hoặc 9b nhất quán với checkpoint bạn đã tải xuống.
• Chỉ tải xuống những gì cần thiết: Tránh lưu trữ cả hai checkpoint nếu quy trình của bạn chỉ sử dụng một kích thước mô hình.
• Bảo toàn các kết quả sinh thô: Kiểm tra các tệp trong outputs/quantiphy/ khi phân tích lý do một dự đoán nhận được điểm số cụ thể.
• Chạy cả hai lớp đánh giá: Lệnh Code-as-World tạo bản tóm tắt cho một lần chạy, trong khi trình đánh giá QuantiPhy chính thức có thể đánh giá đồng thời các tệp CSV dự đoán đã tạo.
• Giữ nguyên mẫu trò chuyện được cung cấp: Công thức phục vụ sử dụng rõ ràng code_as_world/templates/qwen3_5_no_think.jinja và tắt tính năng suy nghĩ. Hãy giữ các cài đặt này khi tái tạo cấu hình được ghi lại.
• Điều chỉnh lựa chọn GPU cẩn thận: Ví dụ phục vụ sử dụng CUDA_VISIBLE_DEVICES=0 và giá trị sử dụng bộ nhớ GPU 0.90. Chọn thiết bị hiển thị phù hợp với máy chủ CUDA của bạn, đồng thời xem các thay đổi khác là sai lệch so với công thức phát hành.
• Bỏ qua kết xuất khi phù hợp: Thêm --no-render vào lệnh mô phỏng khi đầu ra duy nhất cần thiết là quỹ đạo.

Đọc thêm

Để tìm hiểu bối cảnh nghiên cứu và phương pháp luận, hãy tham khảo báo cáo kỹ thuật, trang dự án và bài viết trên blog MirroS.

Kết luận

Code-as-World cung cấp một bản phát hành thực tiễn để khám phá các biểu diễn có thể thực thi của những cảnh vật lý. Sau khi cài đặt môi trường suy luận và tải xuống một checkpoint, bạn có thể tái tạo các phép đánh giá QuantiPhy, phục vụ mô hình thông qua vLLM hoặc chạy mô phỏng MuJoCo đi kèm. Kết hợp lại, các quy trình này cho thấy cách những quan sát trực quan có thể hỗ trợ việc suy luận vật lý rõ ràng và có thể kiểm chứng.