LightX2V × MicroDuck — FastWAM navigation inference bundle

Deployment files for fuheaven/LightX2V-microduck, including the trained MicroDuck navigation checkpoint and its minimal Wan inference dependencies.

This release contains simulation development weights. It has not passed independent full capability acceptance or real-hardware validation. It is a task-specific high-level controller, not a general-purpose autonomous robot brain.

本仓库提供 MicroDuck 视觉寻球模型的完整推理文件。使用代码仓库的 Docker 环境即可运行推理测速、MuJoCo 仿真与独立 MicroDuck Studio 页面；无需先训练 TinyVLA、安装 ROS2 或取得作者私有权重。

Included model and behavior

• Model: clear-room-realtime-control-pilot-v1 / step 250.
• Model SHA256: 8ea7793290f0a22bff56ec4e44168232564ec5d57a9e21515a8a8c4a989114ea.
• Inputs: head-camera RGB history, a supported target instruction, and 48-dimensional robot state.
• History: control-tick offsets [300, 150, 50, 0], composed into a 512 × 512 image.
• Output: 32 × 5 high-level action chunk: forward velocity, lateral velocity, turning, head yaw, and standing.
• Supported instructions/tasks: find_red_ball, find_blue_ball, find_yellow_ball.
• The official ONNX locomotion policy executes walking/balancing at 50 Hz; this FastWAM checkpoint does not directly generate joint angles.
• Tested deployment family: a single NVIDIA H200, BF16, 20 flow-sampling steps. Consumer-GPU compatibility is not established by the on-disk size.

Files

The ten required model files total 26,244,309,246 bytes (26.24 GB / 24.44 GiB). Downloading the models/ directory directly into your deployment data directory preserves the expected paths.

models/
  microduck/
    model.pt                          # 12.04 GB; complete trained task weights
    dataset_stats.json                # original training-set normalization
    navigation_checkpoint.json        # exact checkpoint/history/statistics binding
  Wan2.2-TI2V-5B/
    config.json
    models_t5_umt5-xxl-enc-bf16.pth     # 11.36 GB
    Wan2.2_VAE.pth                     # 2.82 GB
    google/umt5-xxl/
      special_tokens_map.json
      spiece.model
      tokenizer.json
      tokenizer_config.json

model-files.lock.json and SHA256SUMS specify byte counts and hashes. The checkpoint receipt retains its original training provenance paths; the deployment code resolves model files from your local data directory and does not require access to those original server paths.

Training data, optimizer/DeepSpeed states, unused Wan diffusion shards, TinyVLA checkpoints, and later experimental navigation candidates are not included or required for this inference release.

Download and deploy

git clone https://github.com/fuheaven/LightX2V-microduck.git
cd LightX2V-microduck
docker build -f deploy/microduck/fastwam/Dockerfile \
  -t lightx2v-microduck:fastwam-v1 .
export FASTWAM_DATA=/absolute/path/to/microduck-data

# Download the inference bundle; no GPU required.
GPU_ID=none deploy/microduck/fastwam/run.sh python -c \
  'from huggingface_hub import snapshot_download; snapshot_download("lightx2v/microduck", local_dir="/data", allow_patterns=["models/**", "model-files.lock.json", "SHA256SUMS", "NOTICE.md", "licenses/**"])'

# Fetch the pinned official robot and ONNX policies from their original sources.
GPU_ID=none deploy/microduck/fastwam/run.sh \
  python scripts/microduck/fastwam_handoff.py fetch --component sim

# Verify the exact checkpoint, normalizer, receipt, and backbone hashes.
GPU_ID=none deploy/microduck/fastwam/run.sh \
  python scripts/microduck/fastwam_handoff.py verify

# Select an available GPU and start the independent visualization service.
export GPU_ID=0
WEB_BIND=0.0.0.0 WEB_PORT=8770 deploy/microduck/fastwam/web.sh

Open http://YOUR_SERVER_IP:8770/. The gallery includes recorded successes and failures; live simulation loads the model on request. The code repository pins releases for repeatable downloads. If manually using snapshot_download, record and reuse the full Hugging Face commit with revision="FULL_COMMIT_SHA".

See the deployment guide, visualization guide, and optimization guide.

Evidence and limits

These are historical simulation development results, not guaranteed scores for a new machine, runtime, or driver:

Development condition	Result	Interpretation
Clear room, 7 layouts × 3 colors, offline	19/21	Development set
Additional clear-room layouts, accelerated real time	59/60	Single H200; 500 ms observation-age limit
Same historical real-time cohort, optimizations disabled	0/60	Stale actions caused standing fallback; not proof that the model cannot act
Unaccelerated, no observation-age rejection, separate cross-host run	17/60	Different runtime condition; not a strict acceleration-only comparison
Single static obstacle, original action range, offline recheck	27/60	Experimental and below target

The exported runtime includes subsequent execution fixes. Its new live smoke run exposed camera/latency-related fallback and failed the strict task test; historical successes must not be presented as acceptance of that deployment. Reports and failure examples are included in the code repository evidence.

Do not infer arbitrary object understanding, reliable obstacle avoidance, general language planning, real-time acceptance, or hardware readiness from these results. Model inference speed, camera delivery, control timing, and fallback all affect closed-loop behavior.

Sources and licensing

Wan inference components are preserved from Wan-AI/Wan2.2-TI2V-5B at revision 921dbaf3f1674a56f47e83fb80a34bac8a8f203e and retain their upstream Apache-2.0 terms. FastWAM and LightX2V attribution is retained in NOTICE.md and licenses/.

The project-specific navigation weights do not yet have a separately designated license; publishing the files does not automatically extend the code repository's Apache-2.0 license to every model or asset. Contact the repository owner to clarify permitted uses. Official robot meshes and official ONNX policy bundles are fetched separately with their own upstream terms, including the robot asset restrictions. No simulator mesh bundle is republished here.