zing-world-model README

The project's README from github.com/seedleap/zing-world-model. As one markdown file: README.md.

Zing  Loopit

Zing-0.5: An Efficient Real-Time Interactive World Model

Play Zing interactive world model case 0 Play Zing interactive world model case 1 Play Zing interactive world model case 2

English | 简体中文

Project Page · GitHub · Hugging Face · ModelScope · Technical Report (Coming soon)

License Python PyTorch

Developed by the Seedleap.ai team (涌跃智能), Zing 0.5 is an efficient causal world model built for real-time interaction. It continuously rolls out a visual world from its current state while text prompts and keyboard actions alter the world's semantics, motion, and future state as it unfolds.

Text prompts can initialize the world or change it during a rollout. Continuous W/A/S/D/I/J/K/L keyboard actions steer movement and interaction. A causal KV cache and four-step DMD sampling support responsive, long-horizon world rollouts in a compact single-GPU pipeline.

This inference release represents an interaction session as timestamped prompt and keyboard controls in JSONL. The model consumes those controls causally and records the resulting world rollout as video; interactive applications can map their prompt and keyboard events to the same control schema.

The runtime expects a model directory with this layout:

Zing-0.5/
├── generator/
│   └── model.pt
└── pretrained/
    ├── text_encoder/
    ├── tokenizer/
    └── vae/

generator/model.pt must directly contain the generator state dict. Parameter names and shapes are matched strictly; wrapped checkpoints, renamed parameter prefixes, adapters, and partial state dicts are not accepted.

News

Requirements

Quick Start

Run commands from the repository root:

CUDA_VISIBLE_DEVICES=0 \
ZING_PYTHON=/path/to/python \
bash run.sh \
  --pretrained-dir /path/to/Zing-0.5/pretrained \
  --checkpoint /path/to/Zing-0.5/generator/model.pt \
  --messages examples/case3_action_t2v.jsonl \
  --output-dir outputs/case3 \
  --seed 0

ZING_PYTHON defaults to python3. The runtime configuration is loaded from config/zing.yaml.

Ready-to-Run World Rollouts

Every JSONL file under examples/ defines a complete world rollout and can be passed directly to run.sh. Image-initialized examples use their bundled reference images under examples/assets/.

Example Input Command
Long action T2V rollout case3_action_t2v.jsonl bash run.sh ... --messages examples/case3_action_t2v.jsonl --output-dir outputs/case3
Action TI2V rollout case4_action_ti2v.jsonl bash run.sh ... --messages examples/case4_action_ti2v.jsonl --output-dir outputs/case4
Prompt-switched T2V rollout case6_prompt_switch_t2v.jsonl bash run.sh ... --messages examples/case6_prompt_switch_t2v.jsonl --output-dir outputs/case6
Combined action + prompt-switch T2V rollout case7_action_prompt_switch_t2v.jsonl bash run.sh ... --messages examples/case7_action_prompt_switch_t2v.jsonl --output-dir outputs/case7

Replace ... with the same --pretrained-dir and --checkpoint arguments shown in Quick Start.

Input Format

The input is a JSONL interaction timeline with one independent world rollout per line. The user/text message defines the initial world, while the target/video message defines the rollout and its controls.

{"sample_id":"demo","messages":[{"role":"user","type":"text","content":"A quiet lake at sunrise"},{"role":"target","type":"video","reference_frame_count":0,"output":{"frames":31,"height":480,"width":832},"controls":[]}]}

Text-Prompt Rollout

Set reference_frame_count to 0 and omit uri. The text prompt initializes the visual world.

Image-Initialized Rollout

Set reference_frame_count to 1 and provide a local image path in uri. The image initializes the world state. output.frames excludes the reference image, while the recorded rollout includes it as its first frame.

Keyboard Action Control

Add one keyboard_direction_frame_interval control to steer the world as it runs. actions must have shape [N, 8], with values in [0, 1] ordered as W/A/S/D/I/J/K/L. For a text-initialized rollout, N = output.frames - 1; for an image-initialized rollout, N = output.frames.

Prompt-Driven State Changes

Add one text_prompt_interval control to change the world's semantics and future evolution during a rollout. It uses [start, end) pixel-frame intervals. Intervals must be ordered, gap-free, non-overlapping, and valid after conversion to the latent timeline.

Height and width must be divisible by 32. The reference frame count plus generated frame count must follow the 1 + 4N temporal structure.

Sliding-Window Inference

The default sliding-window configuration is 97/9. It is recommended for offline inference on an NVIDIA H100 or a GPU with at least 80 GB of memory. Both values follow the VAE's 4N+1 temporal structure:

bash run.sh ... --local-attn-size 97 --sink-size 9

For GPUs with less memory or for online real-time inference, use the 33/5 configuration:

bash run.sh ... --local-attn-size 33 --sink-size 5

Use full-history attention with:

bash run.sh ... --local-attn-size -1 --sink-size 0

The sink remains visible throughout the rollout. After a prompt-driven state change, the first block of the new prompt is pinned when it leaves the regular tail window. These options affect only runtime cache behavior and do not change checkpoint parameter names.

License

Zing is released under the Apache License 2.0.

Loopit

Make Everything Playable

Download the Loopit app

Scan to download the Loopit app
Official Website · Download Loopit

Acknowledgements

We thank the teams behind Wan2.2 TI2V-5B, minWM, WBench, and LongLive for their open-source work.

zing-world-model (seedleap/zing-world-model)

Searching Database…

170 ·GitHub
Zing-world-model
Что это?Zing-0.5 — эффективная каузальная модель мира, генерирующая видеомир в реальном времени, которым можно управлять на лету текстовыми промптами и нажатиями клавиш W/A/S/D/I/J/K/L.
Это обученная модель с кодом для инференса или полноценный фреймворк для обучения?Это релиз для инференса: вы загружаете предобученный чекпоинт генератора и запускаете генерации (rollout), кода для обучения в комплекте нет.
Как запустить генерацию мира?Выполните bash run.sh из корня репозитория, указав JSONL-файл из examples/ (например case3-action-t2v.jsonl), а также --pretrained-dir и --checkpoint; итоговое видео запишется в --output-dir.
Какое железо и ПО нужны для запуска?Нужны Linux, GPU NVIDIA с поддержкой CUDA, Python 3.11 и пакеты из requirements.txt; конфигурация по умолчанию для оффлайн-режима требует GPU уровня H100 с 80 ГБ памяти, а облегчённая конфигурация со скользящим окном 33/5 работает на меньших GPU в реальном времени.
Принимает ли он любой формат чекпоинтов?Нет, чекпоинт генератора должен быть «развёрнутым» state dict с точно совпадающими именами и размерностями параметров; обёрнутые чекпоинты, переименованные префиксы, адаптеры или частичные state dict отклоняются.
Действительно ли нужен топовый GPU?Для оффлайн-инференса конфигурация по умолчанию требует NVIDIA H100 или GPU минимум с 80 ГБ памяти, но для GPU с меньшим объёмом памяти и работы в реальном времени предусмотрена облегчённая конфигурация со скользящим окном 33/5.
Как устроен входной формат JSONL?Каждая строка — одна генерация: сообщение user/text задаёт начальный мир (текстовый промпт или референсное изображение), а сообщение target/video определяет выходные кадры плюс опциональные элементы управления keyboard-direction и text-prompt-interval, которые направляют или меняют мир в процессе генерации.
Насколько модель быстрая и способна к длинной генерации?Используются каузальный KV-кэш и четырёхшаговое DMD-сэмплирование для отзывчивых длинных генераций на одном GPU; сейчас модель занимает 2-е место в общем зачёте и 1-е среди моделей мира реального времени в рейтинге WBench.
Какие клавиши управления?Непрерывные действия W/A/S/D/I/J/K/L управляют движением и взаимодействием и кодируются массивом [N, 8] со значениями от 0 до 1 для каждой клавиши.
Есть ли потребительское приложение на базе этой модели?Да, у команды есть сопутствующее приложение Loopit, которое можно скачать по QR-коду; оно построено на той же концепции «Make Everything Playable».
What are similar projects?SolarWM, TalkLikeYou-Streaming-RealTime-Demo, PersonaLive, vllm-omni, H3-World, Evoke, FreeVideo, ComfyUI-Ref2VA-VSA
Which topics is it in?world-models, diffusion, pretrained-models, gpu-acceleration, video-generation, real-time, inference, nvidia, generative-ai, cuda, deep-learning, research
Creator
seedleap
Size
26.4 MB
Stars
170
Updated
CommitSep 17
Age
1mo
Commits · 90 Days