---

MAGI-1: Autoregressive Video Generation at Scale

This repository contains the code for the MAGI-1 model, pre-trained weights and inference code. You can find more information on our technical report or directly create magic with MAGI-1 here . 🚀✨

🔥🔥🔥 Latest News

• May 30, 2025: Support for ComfyUI is added 🎉 — the custom nodes for MAGI-1 are now available. Try them out in your workflows!
• May 26, 2025: MAGI-1 4.5B distill and distill+quant models has been released 🎉 — we’ve updated the model weights - check it out!
• May 14, 2025: Added Dify DSL for prompt enhancement 🎉 — import it into Dify to boost prompt quality!
• Apr 30, 2025: MAGI-1 4.5B model has been released 🎉. We've updated the model weights — check it out!
• Apr 21, 2025: MAGI-1 is here 🎉. We've released the model weights and inference code — check it out!

1. 关于

我们推出了MAGI-1，这是一种世界模型，通过自回归方式预测一系列视频块来生成视频。这里的“视频块”是指由连续帧组成的固定长度片段。MAGI-1经过训练，能够逐步去噪随时间单调递增的每块噪声，从而实现因果性的时序建模，并自然支持流式生成。它在基于文本指令的图像到视频（I2V）任务中表现出色，提供了高度的时间一致性与可扩展性。这些优势得益于多项算法创新以及专门构建的基础设施栈。此外，MAGI-1还支持基于块级提示的可控生成，能够实现流畅的场景过渡、长时序合成以及细粒度的文本驱动控制。我们相信，MAGI-1为将高保真视频生成与灵活的指令控制及实时部署相结合提供了一个极具前景的方向。

2. 模型概览

基于Transformer的VAE

• 基于Transformer架构的变分自编码器（VAE），具有8倍的空间压缩和4倍的 temporal 压缩。
• 解码速度最快，且重建质量极具竞争力。

自回归去噪算法

MAGI-1是一种自回归去噪视频生成模型，它不是一次性生成整段视频，而是逐块生成。每块包含24帧，会在整体上进行去噪处理；当前块达到一定去噪程度后，便会开始生成下一帧。这种流水线设计允许同时处理最多四个视频块，从而高效地生成视频。

扩散模型架构

MAGI-1基于扩散Transformer构建，并引入了多项关键创新，以提升大规模训练的效率和稳定性。这些改进包括：块因果注意力、并行注意力块、QK归一化与GQA、FFN中的三明治归一化、SwiGLU以及Softcap调制。更多细节请参阅技术报告。

蒸馏算法

我们采用了一种快捷蒸馏方法，通过训练一个基于速度的单一模型来支持不同的推理预算。通过强制执行自我一致性约束——即让一步大步等同于两步小步——模型能够学习在不同步长下近似流匹配轨迹。在训练过程中，步长会循环从{64, 32, 16, 8}中采样，并结合无分类器指导蒸馏以保持条件对齐。这使得在不显著损失保真度的情况下，仍能高效地进行推理。

3. 模型库

我们提供了MAGI-1的预训练权重，包括24B和4.5B版本，以及对应的蒸馏版和量化蒸馏版。模型权重链接见下表。

模型	链接	推荐硬件
T5	T5	-
MAGI-1-VAE	MAGI-1-VAE	-
MAGI-1-24B	MAGI-1-24B	H100/H800 × 8
MAGI-1-24B-distill	MAGI-1-24B-distill	H100/H800 × 8
MAGI-1-24B-distill+fp8_quant	MAGI-1-24B-distill+quant	H100/H800 × 4 或 RTX 4090 × 8
MAGI-1-4.5B	MAGI-1-4.5B	RTX 4090 × 1
MAGI-1-4.5B-distill	MAGI-1-4.5B-distill	RTX 4090 × 1
MAGI-1-4.5B-distill+fp8_quant	MAGI-1-4.5B-distill+quant	RTX 4090 × 1

[!NOTE]

对于4.5B模型，任何至少拥有24GB显存的设备均可运行。 如果显存较为紧张，可以使用4.5B-distill+fp8_quant模型，只需在4.5B_distill_quant_config.json文件中将window_size参数设置为1即可。该配置可在至少12GB显存的GPU上运行。

4. 评估

内部人工评估

MAGI-1在开源模型如Wan-2.1和HunyuanVideo，以及闭源模型如Hailuo (i2v-01) 中均达到了最先进的水平，尤其在指令遵循性和运动质量方面表现突出，使其有望成为闭源商业模型如Kling的强大竞争对手。

物理行为评估

得益于自回归架构的天然优势，Magi 通过视频续写在 Physics-IQ 基准测试上对物理行为的预测精度远超现有模型。

模型	Phys. IQ 分数 ↑	空间 IoU ↑	空间-时间 IoU ↑	加权空间 IoU ↑	MSE ↓
V2V 模型
Magi-24B (V2V)	56.02	0.367	0.270	0.304	0.005
Magi-4.5B (V2V)	42.44	0.234	0.285	0.188	0.007
VideoPoet (V2V)	29.50	0.204	0.164	0.137	0.010
I2V 模型
Magi-24B (I2V)	30.23	0.203	0.151	0.154	0.012
Kling1.6 (I2V)	23.64	0.197	0.086	0.144	0.025
VideoPoet (I2V)	20.30	0.141	0.126	0.087	0.012
Gen 3 (I2V)	22.80	0.201	0.115	0.116	0.015
Wan2.1 (I2V)	20.89	0.153	0.100	0.112	0.023
Sora (I2V)	10.00	0.138	0.047	0.063	0.030
GroundTruth	100.0	0.678	0.535	0.577	0.002

5. 如何运行

环境准备

我们提供了两种运行 MAGI-1 的方式，推荐使用 Docker 环境。

使用 Docker 环境运行（推荐）

docker pull sandai/magi:latest

docker run -it --gpus all --privileged --shm-size=32g --name magi --net=host --ipc=host --ulimit memlock=-1 --ulimit stack=6710886 sandai/magi:latest /bin/bash

使用源代码运行

# 创建新环境
conda create -n magi python==3.10.12

# 安装 PyTorch
conda install pytorch==2.4.0 torchvision==0.19.0 torchaudio==2.4.0 pytorch-cuda=12.4 -c pytorch -c nvidia

# 安装其他依赖
pip install -r requirements.txt

# 安装 FFmpeg
conda install -c conda-forge ffmpeg=4.4

# 对于基于 Hopper 架构的 GPU（如 H100/H800），建议安装 MagiAttention（https://github.com/SandAI-org/MagiAttention）以加速。对于非 Hopper 架构的 GPU，无需安装 MagiAttention。
git clone git@github.com:SandAI-org/MagiAttention.git
cd MagiAttention
git submodule update --init --recursive
pip install --no-build-isolation .

推理命令

要运行 MagiPipeline，可以通过修改 example/24B/run.sh 或 example/4.5B/run.sh 脚本中的参数来控制输入和输出。以下是关键参数的说明：

参数说明

• --config_file: 指定配置文件路径，包含模型配置参数，例如 example/24B/24B_config.json。
• --mode: 指定运行模式。可选值包括：
  • t2v: 文本到视频
  • i2v: 图像到视频
  • v2v: 视频到视频
• --prompt: 用于视频生成的文本提示，例如 "Good Boy"。
• --image_path: 图像文件路径，仅在 i2v 模式下使用。
• --prefix_video_path: 前缀视频文件路径，仅在 v2v 模式下使用。
• --output_path: 生成的视频文件保存路径。

Bash 脡脚本

#!/bin/bash
# 运行 24B MAGI-1 模型
bash example/24B/run.sh

# 运行 4.5B MAGI-1 模型
bash example/4.5B/run.sh

自定义参数

您可以根据需要修改 run.sh 中的参数。例如：

• 如果要使用图像到视频模式 (i2v)，将 --mode 设置为 i2v 并提供 --image_path：

  --mode i2v \
  --image_path example/assets/image.jpeg \
  

• 如果要使用视频到视频模式 (v2v)，将 --mode 设置为 v2v 并提供 --prefix_video_path：

  --mode v2v \
  --prefix_video_path example/assets/prefix_video.mp4 \
  

通过调整这些参数，您可以灵活地控制输入和输出，以满足不同的需求。

一些有用的配置（针对 config.json）

[!NOTE]

• 如果您使用 RTX 4090 * 8 运行 24B 模型，请设置 pp_size:2 cp_size: 4。

• 我们的模型支持任意分辨率。为了加速推理过程，4.5B 模型的默认分辨率在 4.5B_config.json 中被设置为 720×720。

配置	说明
seed	用于视频生成的随机种子
video_size_h	视频的高度
video_size_w	视频的宽度
num_frames	控制生成视频的时长
fps	每秒帧数，4 帧视频对应 1 个潜在帧
cfg_number	基础模型使用 cfg_number==3，蒸馏和量化模型使用 cfg_number=1
load	包含模型检查点的目录。
t5_pretrained	预训练 T5 模型的加载路径
vae_pretrained	预训练 VAE 模型的加载路径

6. 提示词增强

为了提升提示词质量，我们提供了一个 Dify DSL 文件，可以直接导入 Dify 来设置提示词增强流程。如果您是 Dify 的新手，请参阅 如何从 DSL 文件创建应用 以开始使用。

7. 许可证

本项目采用 Apache License 2.0 许可证——详情请参阅 LICENSE 文件。

8. 引用

如果您在研究中使用了我们的代码或模型，请引用以下文献：

@misc{ai2025magi1autoregressivevideogeneration,
      title={MAGI-1：大规模自回归视频生成},
      author={Sand.ai 和 Hansi Teng、Hongyu Jia、Lei Sun、Lingzhi Li、Maolin Li、Mingqiu Tang、Shuai Han、Tianning Zhang、W. Q. Zhang、Weifeng Luo、Xiaoyang Kang、Yuchen Sun、Yue Cao、Yunpeng Huang、Yutong Lin、Yuxin Fang、Zewei Tao、Zheng Zhang、Zhongshu Wang、Zixun Liu、Dai Shi、Guoli Su、Hanwen Sun、Hong Pan、Jie Wang、Jiexin Sheng、Min Cui、Min Hu、Ming Yan、Shucheng Yin、Siran Zhang、Tingting Liu、Xianping Yin、Xiaoyu Yang、Xin Song、Xuan Hu、Yankai Zhang、Yuqiao Li},
      year={2025},
      eprint={2505.13211},
      archivePrefix={arXiv},
      primaryClass={cs.CV},
      url={https://arxiv.org/abs/2505.13211},
}

9. 联系方式

如果您有任何问题，欢迎随时提交 issue 或通过电子邮件 research@sand.ai 与我们联系。

MAGI-1 快速上手指南

MAGI-1 是一款基于自回归架构的大规模视频生成模型，支持文生视频（T2V）和图生视频（I2V），具备出色的时间一致性和流式生成能力。本指南将帮助您快速部署并运行该模型。

1. 环境准备

系统要求

• 操作系统: Linux (推荐 Ubuntu 20.04+)
• GPU:
  • 24B 模型: 推荐 8x H100/H800；量化版需 4x H100/H800 或 8x RTX 4090。
  • 4.5B 模型: 单张 RTX 4090 (24GB 显存) 即可运行基础版。
  • 低显存方案: 若显存低于 24GB (最低 12GB)，请使用 4.5B-distill+fp8_quant 模型，并修改配置文件中的 window_size 为 1。
• CUDA: 12.1 或更高版本
• Python: 3.10+

前置依赖

确保已安装 Git 和 Conda (推荐使用 Miniconda)。

2. 安装步骤

步骤 1: 克隆仓库

git clone https://github.com/SandAI-org/MAGI-1.git
cd MAGI-1

步骤 2: 创建虚拟环境并安装依赖

conda create -n magi python=3.10 -y
conda activate magi

# 安装 PyTorch (根据 CUDA 版本调整，此处以 CUDA 12.1 为例)
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

# 安装项目依赖
pip install -r requirements.txt

提示: 国内用户可使用清华源加速 pip 安装： pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

步骤 3: 下载模型权重

从 Hugging Face 下载所需模型权重至 ckpt 目录。以下以 4.5B 蒸馏量化版 (适合单卡用户) 为例：

# 创建目录
mkdir -p ckpt/magi/4.5B_distill_quant

# 使用 huggingface-cli 下载 (需安装 huggingface_hub)
pip install huggingface_hub
huggingface-cli download sand-ai/MAGI-1 --local-dir ckpt --include "ckpt/magi/4.5B_distill_quant/*"

注：还需下载 T5 编码器 和 VAE 权重，位于 ckpt/t5 和 ckpt/vae 目录。

3. 基本使用

以下是一个最简单的命令行推理示例，生成一段视频。

配置低显存模式 (可选)

如果您使用的是 12GB-16GB 显存的显卡运行量化模型，请先修改配置文件： 编辑 ckpt/magi/4.5B_distill_quant_config.json (具体文件名请以实际为准)，将 window_size 设置为 1。

运行推理

执行以下命令生成视频：

python infer.py \
    --config_path configs/4.5B_distill_quant.yaml \
    --ckpt_path ckpt/magi/4.5B_distill_quant \
    --prompt "A cyberpunk cat walking in the rain, neon lights reflecting on wet streets, cinematic lighting" \
    --output_dir outputs \
    --num_frames 96 \
    --fps 24

参数说明：

• --config_path: 对应模型的配置文件路径。
• --ckpt_path: 下载的模型权重文件夹路径。
• --prompt: 视频生成的提示词。
• --num_frames: 生成帧数 (MAGI-1 按块生成，每块 24 帧，建议设为 24 的倍数)。
• --output_dir: 输出视频保存目录。

生成完成后，视频文件将保存在 outputs 目录中。

---

更多高级功能（如 ComfyUI 集成、Dify 工作流、图生视频）请参考官方文档或 GitHub 仓库。