--- language: - en - zh tags: - robotics - microduck - fastwam - lightx2v - mujoco - simulation base_model: Wan-AI/Wan2.2-TI2V-5B --- # LightX2V × MicroDuck — FastWAM navigation inference bundle Deployment files for [fuheaven/LightX2V-microduck](https://github.com/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. ```text 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 ```bash 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](https://github.com/fuheaven/LightX2V-microduck/blob/main/docs/microduck/deployment.md), [visualization guide](https://github.com/fuheaven/LightX2V-microduck/blob/main/docs/microduck/visualization.md), and [optimization guide](https://github.com/fuheaven/LightX2V-microduck/blob/main/docs/microduck/optimization.md). ## 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](https://github.com/fuheaven/LightX2V-microduck/tree/main/docs/microduck/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](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.