---

LightX2V 是一款先进的轻量级图像/视频生成推理框架，旨在提供高效、高性能的图像/视频合成解决方案。该统一平台集成了多种最先进的图像/视频生成技术，支持多样化的生成任务，包括文本到视频（T2V）、图像到视频（I2V）、文本到图像（T2I）以及图像编辑（I2I）。X2V 代表将不同输入模态（X，如文本或图像）转换为视觉输出（Vision）的过程。

🌐 立即在线体验！ 无需安装即可体验 LightX2V：LightX2V 在线服务 - 免费、轻量且快速的 AI 数字人视频生成平台。

🎉 全新发布：GenRL 来了！ 欢迎查看我们全新的 GenRL 框架，用于通过强化学习训练视觉生成模型！高性能 RL 训练检查点现已在 HuggingFace 上发布。

👋 加入我们的微信交流群！LightX2V 机器人微信号：random42seed

🧾 社区代码贡献指南

在提交代码之前，请确保代码格式符合项目标准。您可以通过以下命令来保证项目代码格式的一致性：

pip install ruff pre-commit
pre-commit run --all-files

除了 LightX2V 团队的贡献外，我们还收到了一些社区开发者的贡献，其中包括但不限于：

• zhtshr
• triple-Mu
• vivienfanghuagood
• yeahdongcn
• kikidouloveme79
• ziyanxzy

:fire: 最新消息

• 2026年3月5日: 🚀 现已支持在Intel AIPC PTL上部署。感谢Intel团队！

• 2026年3月5日: 🚀 现已支持基于Mooncake的分布式部署。更多关于分布式部署的改进和文档正在开发中。感谢Mooncake团队的帮助！

• 2026年2月27日: 🚀 现已支持自回归视频生成模型（Self Forcing）的FP8和NVFP4量化！您可以在以下链接找到量化后的模型：Self-Forcing-FP8, Self-Forcing-NVFP4。

• 2026年2月11日: 🎉 我们很高兴地宣布推出**GenRL**——一个用于视觉生成的可扩展强化学习框架！GenRL支持使用GRPO算法，通过多奖励优化（HPSv3、VideoAlign等）训练扩散/流模型。我们发布了在多节点多GPU环境下训练的高性能LoRA检查点，展示了在美学质量、运动连贯性和文本与视频对齐方面的显著提升。请查看我们在HuggingFace上的模型合集！如果您觉得有用，请给我们点个赞⭐！

• 2026年1月20日: 🚀 我们支持LTX-2音视频生成模型，该模型具备CFG并行、块级卸载以及每张张量FP8量化等功能。使用示例可在examples/ltx2和scripts/ltx2中找到。

• 2026年1月6日: 🚀 我们更新了针对Qwen-Image-2512和Qwen/Qwen-Image-Edit-2511的8步CFG/步骤蒸馏模型。您可以从Qwen-Image-Edit-2511-Lightning和Qwen-Image-2512-Lightning下载相应权重以供使用。使用教程可在这里找到。

• 2026年1月6日: 🚀 支持在Enflame S60（GCU）上部署。

• 2025年12月31日: 🚀 自第一天起，我们就支持Qwen-Image-2512文本到图像模型。我们的HuggingFace已更新为CFG/步骤蒸馏的LoRA版本。使用示例可在这里找到。

• 2025年12月27日: 🚀 支持在MThreads MUSA上部署。

• 2025年12月25日: 🚀 支持在AMD ROCm和Ascend 910B上部署。

• 2025年12月23日: 🚀 自第一天起，我们就支持Qwen-Image-Edit-2511图像编辑模型。在单张H100 GPU上，LightX2V可带来约1.4倍的速度提升。我们支持CFG并行、Ulysses并行以及高效的卸载技术。我们的HuggingFace已更新为CFG/步骤蒸馏的LoRA和FP8权重。使用示例可在这里找到。结合LightX2V、4步CFG/步骤蒸馏以及FP8模型，最高加速可达约42倍。欢迎试用LightX2V在线服务，体验“图片转图片”和“Qwen-Image-Edit-2511”模型。

• 2025年12月22日: 🚀 新增Wan2.1 NVFP4量化感知的4步蒸馏模型；权重已在HuggingFace上发布：Wan-NVFP4。

• 2025年12月15日: 🚀 支持在Hygon DCU上部署。

• 2025年12月4日: 🚀 支持GGUF格式模型在Cambricon MLU590/MetaX C500上的推理与部署。

• 2025年11月24日: 🚀 我们发布了HunyuanVideo-1.5的4步蒸馏模型！这些模型无需CFG即可实现超快速4步推理，相比标准50步推理，速度提升约25倍。基础版和FP8量化版现已上线：Hy1.5-Distill-Models。

• 2025年11月21日: 🚀 自第一天起，我们就支持Tencent的HunyuanVideo-1.5视频生成模型。在相同数量的GPU下，LightX2V可将速度提升至2倍以上，并支持在显存较低的GPU（如24GB RTX 4090）上部署。它还支持CFG/Ulysses并行、高效卸载、TeaCache/MagCache等技术。我们将在不久的将来更新更多模型至我们的HuggingFace页面，包括步骤蒸馏、VAE蒸馏等相关模型。量化模型和轻量级VAE模型现已上线：Hy1.5-Quantized-Models用于量化推理，而LightTAE for HunyuanVideo-1.5则用于快速VAE解码。使用教程请参考这里，或查看示例目录获取代码示例。

🏆 性能基准测试（更新于2025年12月1日）

📊 跨框架性能对比（H100）

框架	GPU数量	每步耗时	加速比
Diffusers	1	9.77秒/步	1x
xDiT	1	8.93秒/步	1.1x
FastVideo	1	7.35秒/步	1.3x
SGL-Diffusion	1	6.13秒/步	1.6x
LightX2V	1	5.18秒/步	1.9x 🚀
FastVideo	8	2.94秒/步	1x
xDiT	8	2.70秒/步	1.1x
SGL-Diffusion	8	1.19秒/步	2.5x
LightX2V	8	0.75秒/步	3.9x 🚀

📊 跨框架性能对比（RTX 4090D）

框架	GPU数量	每步耗时	加速比
Diffusers	1	30.50秒/步	1x
FastVideo	1	22.66秒/步	1.3x
xDiT	1	OOM	OOM
SGL-Diffusion	1	OOM	OOM
LightX2V	1	20.26秒/步	1.5x 🚀
FastVideo	8	15.48秒/步	1x
xDiT	8	OOM	OOM
SGL-Diffusion	8	OOM	OOM
LightX2V	8	4.75秒/步	3.3x 🚀

📊 LightX2V 性能对比

框架	GPU	配置	步骤时间	加速比
LightX2V	H100	8 GPUs + cfg	0.75s/it	1x
LightX2V	H100	8 GPUs + no cfg	0.39s/it	1.9x
LightX2V	H100	8 GPUs + no cfg + fp8	0.35s/it	2.1x 🚀
LightX2V	4090D	8 GPUs + cfg	4.75s/it	1x
LightX2V	4090D	8 GPUs + no cfg	3.13s/it	1.5x
LightX2V	4090D	8 GPUs + no cfg + fp8	2.35s/it	2.0x 🚀

注: 以上所有性能数据均在 Wan2.1-I2V-14B-480P（40 步，81 帧）上测试。此外，我们还在 HuggingFace 页面 上提供了 4 步蒸馏模型。

💡 快速入门

有关完整的使用说明，请参阅我们的文档：英文文档 | 中文文档

我们强烈建议使用 Docker 环境，因为这是设置环境最简单、最快捷的方式。详情请参阅文档中的快速入门部分。

从 Git 安装

pip install -v git+https://github.com/ModelTC/LightX2V.git

从源码构建

git clone https://github.com/ModelTC/LightX2V.git
cd LightX2V
uv pip install -v . # pip install -v .

（可选）安装注意力/量化算子

关于注意力算子的安装，请参阅我们的文档：英文文档 | 中文文档

使用示例

# examples/wan/wan_i2v.py
"""
Wan2.2 图像转视频生成示例。
本示例演示如何使用 LightX2V 和 Wan2.2 模型进行 I2V 生成。
"""

from lightx2v import LightX2VPipeline

# 初始化用于 Wan2.2 I2V 任务的管道
# 对于 wan2.1，使用 model_cls="wan2.1"
pipe = LightX2VPipeline(
    model_path="/path/to/Wan2.2-I2V-A14B",
    model_cls="wan2.2_moe",
    task="i2v",
)

# 另一种方式：从配置 JSON 文件创建生成器
# pipe.create_generator(
#     config_json="configs/wan22/wan_moe_i2v.json"
# )

# 启用卸载功能，以显著减少显存占用，同时对速度影响较小。
# 适用于 RTX 30/40/50 消费级 GPU
pipe.enable_offload(
    cpu_offload=True,
    offload_granularity="block",  # 对于 Wan 模型，支持 "block" 和 "phase"
    text_encoder_offload=True,
    image_encoder_offload=False,
    vae_offload=False,
)

# 使用指定参数手动创建生成器
pipe.create_generator(
    attn_mode="sage_attn2",
    infer_steps=40，
    height=480，  # 可设置为 720 以获得更高分辨率
    width=832，  # 可设置为 1280 以获得更高分辨率
    num_frames=81，
    guidance_scale=[3.5, 3.5]，  # 对于 wan2.1，guidance_scale 是一个标量（例如 5.0）
    sample_shift=5.0，
)

# 生成参数
seed = 42
prompt = "夏日海滩度假风格，一只戴着太阳镜的白猫坐在冲浪板上。这只毛茸茸的小猫神情放松地直视着镜头。背景是模糊的海滩景色，清澈见底的海水、远处的青山以及点缀着白云的蓝天。猫咪的姿态自然放松，仿佛正在享受海风和温暖的阳光。特写镜头突出了猫咪的精致细节和海滨的清新氛围。"
negative_prompt = "镜头晃动，色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走"
image_path="/path/to/img_0.jpg"
save_result_path = "/path/to/save_results/output.mp4"

# 生成视频
pipe.generate(
    seed=seed，
    image_path=image_path，
    prompt=prompt，
    negative_prompt=negative_prompt，
    save_result_path=save_result_path，
)

NVFP4（量化感知 4 步）资源

• 推理示例：examples/wan/wan_i2v_nvfp4.py（I2V）和 examples/wan/wan_t2v_nvfp4.py（T2V）。
• NVFP4 算子构建/安装指南：请参阅 lightx2v_kernel/README.md。

💡 更多示例：有关量化、卸载、缓存及其他高级配置的更多使用示例，请参阅 examples 目录。

🤖 支持的模型生态

官方开源模型

• ✅ LTX-2
• ✅ HunyuanVideo-1.5
• ✅ Wan2.1 & Wan2.2
• ✅ Qwen-Image
• ✅ Qwen-Image-Edit
• ✅ Qwen-Image-Edit-2509
• ✅ Qwen-Image-Edit-2511

量化与蒸馏模型/LoRA（🚀 推荐：4 步推理）

• ✅ Wan2.1-Distill-Models
• ✅ Wan2.2-Distill-Models
• ✅ Wan2.1-Distill-Loras
• ✅ Wan2.2-Distill-Loras
• ✅ Wan2.1-Distill-NVFP4
• ✅ Qwen-Image-Edit-2511-Lightning

轻量级自编码器模型（🚀 推荐：快速推理 & 低内存占用）

• ✅ Autoencoders

自回归模型

• ✅ Wan2.1-T2V-CausVid
• ✅ Self-Forcing
• ✅ Matrix-Game-2.0

🔔 关注我们的 HuggingFace 页面，了解我们团队发布的最新模型。

💡 请参阅 模型结构文档，以便快速上手 LightX2V。

🚀 前端界面

我们提供了多种前端界面部署选项：

• 🎨 Gradio 界面: 简洁友好的网页界面，非常适合快速体验和原型开发
  • 📖 Gradio 部署指南
• 🎯 ComfyUI 界面: 强大的节点式工作流界面，支持复杂的视频生成任务
  • 📖 ComfyUI 部署指南
• 🚀 Windows 一键部署: 专为 Windows 用户设计的便捷部署方案，具备自动环境配置和智能参数优化功能
  • 📖 Windows 一键部署指南

💡 推荐方案：

• 初次使用者: 建议使用 Windows 一键部署方案
• 高级用户: 建议使用 ComfyUI 界面以获得更多自定义选项
• 快速体验: Gradio 界面提供最直观的操作体验

🚀 核心特性

🎯 极致性能优化

• 🔥 SOTA 推理速度: 通过步骤蒸馏与系统优化实现 ~20倍 加速（单 GPU）
• ⚡️ 革命性 4 步骤蒸馏: 在无需 CFG 的情况下，将原本 40–50 步的推理压缩至仅 4 步
• 🛠️ 先进算子支持: 集成前沿算子，包括 Sage Attention、Flash Attention、Radial Attention、q8-kernel、sgl-kernel、vllm

💾 资源高效部署

• 💡 打破硬件限制: 仅需 8GB VRAM + 16GB RAM 即可运行 14B 参数模型进行 480P/720P 视频生成
• 🔧 智能参数卸载: 先进的磁盘-CPU-GPU 三层卸载架构，支持阶段/块级精细化管理
• ⚙️ 全面量化支持: 支持 w8a8-int8、w8a8-fp8、w4a4-nvfp4 等多种量化策略

🎨 丰富功能生态

• 📈 智能特征缓存: 智能缓存机制，消除冗余计算
• 🔄 并行推理: 多 GPU 并行处理，提升性能
• 📱 灵活部署选项: 支持 Gradio、服务部署、ComfyUI 等多种部署方式
• 🎛️ 动态分辨率推理: 自适应分辨率调整，优化生成质量
• 🎞️ 视频帧插值: 基于 RIFE 的帧插值技术，平滑提升帧率

📚 技术文档

📖 方法教程

• 模型量化 - 量化策略全面指南
• 特征缓存 - 智能缓存机制
• 注意力机制 - 最先进的注意力算子
• 参数卸载 - 三层存储架构
• 并行推理 - 多 GPU 加速策略
• 变分辨率推理 - U型分辨率策略
• 步骤蒸馏 - 4 步骤推理技术
• 视频帧插值 - 基于 RIFE 技术

🛠️ 部署指南

• 低资源部署 - 优化后的 8GB VRAM 解决方案
• 低延迟部署 - 超快速推理优化
• Gradio 部署 - Web 界面搭建
• 服务部署 - 生产级 API 服务部署
• Lora 模型部署 - 灵活的 Lora 部署

🤝 致谢

我们衷心感谢所有启发并推动 LightX2V 发展的模型仓库和研究社区。本框架建立在开源社区的共同努力之上，其中包括但不限于：

• Tencent-Hunyuan
• Wan-Video
• Qwen-Image
• LightLLM
• sglang
• vllm
• flash-attention
• SageAttention
• flashinfer
• MagiAttention
• radial-attention
• xDiT
• FastVideo
• Mooncake

🌟 星标历史

✏️ 引用

如果您在研究中使用了 LightX2V，请考虑引用我们的工作：

@misc{lightx2v,
 author = {LightX2V Contributors},
 title = {LightX2V: 轻量级视频生成推理框架},
 year = {2025},
 publisher = {GitHub},
 journal = {GitHub 仓库},
 howpublished = {\url{https://github.com/ModelTC/lightx2v}},
}

📞 联系与支持

如有任何问题、建议或需要支持，请随时通过以下方式联系我们：

• 🐛 GitHub Issues - 用于提交 Bug 和功能请求

---

LightX2V 快速上手指南

LightX2V 是一个先进的高性能图像/视频生成推理框架，支持文生视频 (T2V)、图生视频 (I2V)、文生图 (T2I) 及图像编辑 (I2I) 等多种任务。该框架通过集成 CFG 并行、块级卸载 (Offload)、FP8/NVFP4 量化及步数蒸馏等技术，显著提升了生成速度并降低了显存需求。

1. 环境准备

系统要求

• 操作系统: Linux (推荐 Ubuntu 20.04+)
• GPU: NVIDIA GPU (支持 H100, A100, RTX 4090 等)，或国产算力卡 (华为 Ascend 910B, 海光 DCU, 摩尔线程 MUSA, 天数智芯 GCU 等)。
• Python: 3.8 - 3.11
• CUDA: 建议 12.1+ (根据具体显卡驱动版本调整)

前置依赖

确保已安装 git 和 pip (或 uv 以加速安装)。

提示：国内开发者建议使用国内镜像源加速 Python 包下载。

2. 安装步骤

推荐优先使用 Docker 部署（最简单且环境隔离最好），若需源码安装请参考以下方式。

方式一：Docker 部署（推荐）

直接从 Docker Hub 拉取预构建镜像，避免环境配置冲突：

docker pull lightx2v/lightx2v:latest
# 启动容器示例（需映射模型路径和 GPU）
docker run --gpus all -it -v /path/to/models:/models lightx2v/lightx2v:latest

方式二：从 Git 直接安装

pip install -v git+https://github.com/ModelTC/LightX2V.git
# 国内加速建议：
# pip install -v git+https://github.com/ModelTC/LightX2V.git -i https://pypi.tuna.tsinghua.edu.cn/simple

方式三：源码构建安装

适合需要修改代码或开发贡献的用户：

git clone https://github.com/ModelTC/LightX2V.git
cd LightX2V
# 推荐使用 uv 加速安装，也可使用 pip
uv pip install -v . 
# 或
pip install -v . -i https://pypi.tuna.tsinghua.edu.cn/simple

注意：如需启用特定的注意力算子优化或量化功能，请参考官方文档安装额外的算子库。

3. 基本使用

以下是一个基于 Wan2.2 模型的图生视频 (I2V) 最小化使用示例。该示例展示了如何初始化管道并开启显存卸载以适应消费级显卡。

# examples/wan/wan_i2v.py
"""
Wan2.2 image-to-video generation example.
This example demonstrates how to use LightX2V with Wan2.2 model for I2V generation.
"""

from lightx2v import LightX2VPipeline

# 初始化 Wan2.2 I2V 任务管道
# 若使用 wan2.1 模型，请将 model_cls 设置为 "wan2.1"
pipe = LightX2VPipeline(
    model_path="/path/to/Wan2.2-I2V-A14B",
    model_cls="wan2.2_moe",
    task="i2v",
)

# 可选：通过 JSON 配置文件创建生成器
# pipe.create_generator(
#     config_json="configs/wan22/wan_moe_i2v.json"
# )

# 启用卸载功能 (Offload)
# 显著降低显存占用，轻微影响速度，非常适合 RTX 30/40/50 系列消费级显卡
pipe.enable_offload(
    cpu_offload=True,
    offload_granularity="block",  # Wan 模型支持 "block" 和 "phase"
    text_encoder_offload=True,
)

# 执行生成
# 请根据实际模型要求替换 prompt, image_path, num_steps 等参数
output_video = pipe(
    prompt="A cat walking on the street",
    image_path="input_image.jpg",
    num_steps=4,  # 若使用蒸馏模型可设为 4 步，否则通常为 30-50 步
    guidance_scale=1.0, # 蒸馏模型通常不需要 CFG 或设为 1.0
)

# 保存结果
output_video.save("output.mp4")

关键优化提示

• 极速推理：若使用 HuggingFace 上提供的 4-step distilled models (如 Hy1.5-Distill-Models 或 Wan-NVFP4)，可将 num_steps 设为 4，实现约 25 倍以上的加速。
• 低显存方案：在单张 24GB 显存显卡 (如 RTX 4090) 上运行大模型时，务必调用 pipe.enable_offload() 并配合 FP8 量化权重。