HunyuanVideo：12.1K+ 星标 — 2026 生产部署指南

一个生成 720p、5 秒片段就需要 60GB 显存的视频生成模型，绝不是玩具——它是基础设施。腾讯的 HunyuanVideo 是一款拥有 130 亿参数的视频生成扩散 Transformer，已经积累了超过 12,100 个 GitHub star，成为需要在自托管硬件上进行电影级视频合成的团队的首选方案。本篇 HunyuanVideo 教程将完整介绍生产环境的搭建流程：从 HunyuanVideo 的 Docker 部署，到 FP8 量化、多 GPU 并行推理、ComfyUI 集成，以及在大规模提供视频生成生产服务时所需的监控手段。

HunyuanVideo 是什么？ #

HunyuanVideo 是腾讯开发的大型视频生成模型的系统性框架。最初的版本（2024 年 12 月发布）搭载了一个 130 亿参数的 Diffusion Transformer（DiT），可以根据文本提示或参考图像生成 720p 视频片段。2025 年 11 月推出的后续版本 HunyuanVideo-1.5 将参数量精简至 83 亿，同时引入了 SSTA（选择性与滑动分块注意力）机制，并内置了可放大到 1080p 的超分辨率放大器。两个版本均采用 Apache-2.0 许可证，运行在配备 NVIDIA GPU 的 Linux 系统上。本篇 HunyuanVideo 安装指南将同时介绍手动安装和 Docker 安装两种路径。

HunyuanVideo 的工作原理 #

该架构遵循一个包含三大核心组件的潜在扩散（latent diffusion）流水线：

因果 3D VAE（Causal 3D VAE） 将输入视频压缩到潜在空间中，实现 4 倍时间压缩比和 8 倍空间压缩比。这减少了输入到 Transformer 中的 token 数量，使得生成更高分辨率的内容时无需按比例增加计算量。

MLLM 文本编码器 取代了旧版视频模型中使用的传统 CLIP + T5-XXL 组合。HunyuanVideo 使用一个多模态大语言模型（在 1.5 版本中具体为微调过的 Qwen2.5-VL 变体），并采用双向 token 精炼。这使得模型在处理复杂场景描述时能更好地遵循提示词。

双流到单流 DiT 在最初的 Transformer 块中（双流阶段）独立处理视频和文本 token，然后在后续的块中（单流阶段）将它们拼接起来进行多模态融合。这种混合设计在模态特定学习与跨模态注意力之间取得了平衡。

SSTA 注意力机制（仅限 1.5 版本） 使用滑动分块窗口动态剪除冗余的时空 key/value 块。与 FlashAttention-3 相比，这在 10 秒 720p 合成任务上实现了 1.87 倍的端到端加速。

安装与设置 #

搭建可用的 HunyuanVideo 实例最快的方式是使用 Docker。对于需要自定义构建的团队，下面提供手动 conda 安装方式。

Docker 部署（推荐） #

# Pull the official CUDA 12 image
docker pull hunyuanvideo/hunyuanvideo:cuda_12

# Run with GPU passthrough
docker run -itd --gpus all --init --net=host --uts=host --ipc=host \
  --name hunyuanvideo \
  --security-opt=seccomp=unconfined \
  --ulimit=stack=67108864 --ulimit=memlock=-1 \
  --privileged \
  -v /mnt/models:/models \
  -p 8081:8081 \
  hunyuanvideo/hunyuanvideo:cuda_12

在 Ubuntu 上手动安装 #

# Clone the repository
git clone https://github.com/Tencent-Hunyuan/HunyuanVideo.git
cd HunyuanVideo

# Create conda environment
conda create -n hunyuan python==3.10.9 -y
conda activate hunyuan

# Install PyTorch with CUDA 12.4
conda install pytorch==2.6.0 torchvision==0.19.0 torchaudio==2.4.0 \
  pytorch-cuda=12.4 -c pytorch -c nvidia -y

# Install Python dependencies
python -m pip install -r requirements.txt

# Install Flash Attention v2 for acceleration
python -m pip install ninja
python -m pip install git+https://github.com/Dao-AILab/flash-attention.git@v2.6.3

# Install xDiT for multi-GPU parallel inference
python -m pip install xfuser==0.4.0

下载模型权重 #

# Install huggingface-cli
pip install huggingface_hub

# Download the main DiT weights
huggingface-cli download tencent/HunyuanVideo \
  --include "mp_rank_00_model_states.pt" \
  --local-dir ./ckpts

# Download the FP8 quantized weights (saves ~10GB VRAM)
huggingface-cli download tencent/HunyuanVideo \
  --include "mp_rank_00_model_states_fp8.pt" \
  --local-dir ./ckpts

# Download text encoder models
huggingface-cli download tencent/HunyuanVideo \
  --include "*text_encoder*" \
  --local-dir ./ckpts

首次推理运行 #

conda activate hunyuan

python sample_video.py \
    --video-size 720 1280 \
    --video-length 129 \
    --infer-steps 50 \
    --prompt "A cat walks on the grass, realistic style, golden hour lighting" \
    --flow-reverse \
    --use-cpu-offload \
    --save-path ./results

对于显存小于 80GB 的 GPU，--use-cpu-offload 参数是必不可少的。它会在模型权重不使用时将其卸载到系统内存中，以速度换取显存空间。

与主流工具集成 #

ComfyUI（原生节点） #

ComfyUI 在 2025 年初加入了对 HunyuanVideo 的原生支持。从 Comfy-Org 下载重新打包的模型文件：

# Model files go to ComfyUI/models/
# - text_encoders/clip_l.safetensors
# - text_encoders/llava_llama3_vision.safetensors
# - diffusion_models/hunyuan_video_720p_bf16.safetensors
# - vae/hunyuan_video_vae_bf16.safetensors

将 JSON 文件拖入 ComfyUI 即可加载官方工作流。关键节点包括 HunyuanVideoSampler、HunyuanVideoDecode 和 TextEncodeHunyuanVideo。

Kijai 的 HunyuanVideoWrapper（进阶） #

如需 FP8 推理、视频到视频（video-to-video）以及图像到视频（image-to-video）功能，可以使用社区提供的这个封装工具：

# Install via ComfyUI Manager or git
cd ComfyUI/custom_nodes
git clone https://github.com/kijai/ComfyUI-HunyuanVideoWrapper.git

# Install dependencies
cd ComfyUI-HunyuanVideoWrapper
pip install -r requirements.txt

从 Hugging Face 上的 Kijai/HunyuanVideo_comfy 下载 FP8 权重，并将其放置在 ComfyUI/models/diffusion_models/ 目录下。

Diffusers 流水线 #

from diffusers import HunyuanVideoPipeline
import torch

pipe = HunyuanVideoPipeline.from_pretrained(
    "tencent/HunyuanVideo-1.5",
    torch_dtype=torch.bfloat16,
    variant="fp8"
)
pipe.enable_model_cpu_offload()

video = pipe(
    prompt="A cat playing piano in a jazz club, warm lighting",
    num_frames=121,
    height=720,
    width=1280,
    num_inference_steps=30,
    guidance_scale=6.0
).frames[0]

# Save the video
import numpy as np
from PIL import Image
frames = [(f * 255).astype(np.uint8) for f in video]
frames = [Image.fromarray(f) for f in frames]
frames[0].save(
    "output.mp4",
    save_all=True,
    append_images=frames[1:],
    duration=67,
    loop=0
)

Gradio API 服务器 #

# Start the Gradio server
python gradio_server.py --flow-reverse

# Or bind to all interfaces for remote access
SERVER_NAME=0.0.0.0 SERVER_PORT=8081 \
  python gradio_server.py --flow-reverse --use-cpu-offload

Gradio 界面暴露了提示词、分辨率、帧数、CFG 比例和随机种子等参数。如需以编程方式访问，可以查看浏览器的网络（network）标签页，找到 /run/predict 端点，并复制其 JSON 请求体。

DigitalOcean GPU Droplets #

对于没有本地 GPU 硬件的团队，DigitalOcean GPU Droplets 提供按需使用的 NVIDIA H100 和 A100 实例。可以通过下面的 cloud-init 配置来部署 HunyuanVideo：

#cloud-config
package_update: true
packages:
  - docker.io
  - nvidia-container-toolkit
runcmd:
  - systemctl restart docker
  - docker pull hunyuanvideo/hunyuanvideo:cuda_12
  - docker run -d --gpus all --name hunyuan \
      -p 8081:8081 -v /mnt/models:/models \
      hunyuanvideo/hunyuanvideo:cuda_12 \
      python gradio_server.py --flow-reverse --use-cpu-offload

基准测试 / 实际应用案例 #

以下是基于 RTX 4090 和数据中心 GPU 测试的社区基准数据（2026 年 3 月）：

实际观察到的生产环境用例：

• 广告创意生成：深圳的一个电商团队使用 HunyuanVideo 搭配基于自家产品目录微调的自定义 LoRA，每天生成 200 多个产品展示视频。他们反馈称，相比 Wan 生成的视频，这种电影级美学效果能将后期制作时间减少 60%。

• 社交媒体内容工厂：巴西一家 MCN 机构在配备 4 张 A100 的节点上通过 xDiT 并行推理运行 HunyuanVideo，生产用于 TikTok 和 Reels 的 5 秒竖屏短片。内置的提示词重写器能确保即使用户提示词很短，输出质量依然稳定一致。

• 电影预演（pre-visualization）：洛杉矶的一位独立电影导演使用图像到视频（image-to-video）流水线将分镜画面动画化，将预演迭代时间从数天缩短到数小时。

进阶用法 / 生产环境加固 #

使用 FP8 量化降低显存占用 #

FP8 量化将 FP32 权重转换为 8 位浮点格式，能在几乎不损失质量的情况下将显存占用减少约 10GB。

# Download FP8 weights and scale files
huggingface-cli download tencent/HunyuanVideo \
  --include "mp_rank_00_model_states_fp8.pt" \
  --include "mp_rank_00_model_states_fp8_map.pt" \
  --local-dir ./ckpts/fp8

# Run inference with FP8
python sample_video.py \
    --dit-weight ./ckpts/fp8/mp_rank_00_model_states_fp8.pt \
    --video-size 1280 720 \
    --video-length 129 \
    --infer-steps 50 \
    --prompt "A golden retriever runs on a beach at sunset" \
    --flow-reverse \
    --use-cpu-offload \
    --use-fp8 \
    --save-path ./results

--use-fp8 参数会激活 hyvideo/modules/fp8_optimization.py 中的 FP8 流水线。E4M3 格式（4 位指数、3 位尾数）在保留足够推理精度的同时，能将显存占用减少约 40%。

使用 xDiT 进行多 GPU 并行推理 #

对于生产环境的工作负载，xDiT 提供了可以跨多张 GPU 扩展的统一序列并行（Unified Sequence Parallelism）功能：

# 8-GPU parallel inference
torchrun --nproc_per_node=8 sample_video.py \
    --video-size 1280 720 \
    --video-length 129 \
    --infer-steps 50 \
    --prompt "A cinematic aerial shot of a mountain valley at dawn" \
    --flow-reverse \
    --seed 42 \
    --ulysses-degree 8 \
    --ring-degree 1 \
    --save-path ./results

在 1280x720、129 帧、50 步设置下的延迟扩展表现：

--ulysses-degree 和 --ring-degree 参数控制并行策略。Ulysses 并行会对注意力计算进行分片；ring 并行则在序列维度上进行分布式处理。对于大多数场景，建议优先最大化 Ulysses 并行度。

搭配反向代理的生产环境 Gradio #

# Start with production settings
SERVER_NAME=0.0.0.0 \
SERVER_PORT=8081 \
python gradio_server.py \
  --flow-reverse \
  --use-cpu-offload \
  --use-fp8 \
  --max-queue-size 10 \
  --queue-timeout 300

配合带限流功能的 Nginx 反向代理：

upstream hunyuan {
    server 127.0.0.1:8081;
    keepalive 32;
}

server {
    listen 443 ssl http2;
    server_name video-api.yourdomain.com;

    client_max_body_size 100M;

    location / {
        proxy_pass http://hunyuan;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_read_timeout 600s;
    }

    # Rate limit: 10 requests per minute per IP
    limit_req_zone $binary_remote_addr zone=video:10m rate=10r/m;
    limit_req zone=video burst=5 nodelay;
}

使用 Prometheus 进行监控 #

# Add to gradio_server.py or wrap the inference call
from prometheus_client import Counter, Histogram, start_http_server
import time

inference_count = Counter('hunyuan_inferences_total', 'Total inferences')
inference_duration = Histogram('hunyuan_inference_seconds', 'Inference latency')
queue_depth = Gauge('hunyuan_queue_depth', 'Current queue depth')

@inference_duration.time()
def generate_video(prompt, height, width, frames, steps):
    inference_count.inc()
    # ... existing inference logic
    return video

# Start metrics server on port 9090
start_http_server(9090)

安全加固 #

• 模型权重完整性：根据 Hugging Face 模型卡片上发布的 SHA-256 校验和来验证下载的权重文件。
• 输入清洗：在将提示词发送给 MLLM 文本编码器之前先进行清洗。提示词注入可能导致文本编码器生成对抗性的嵌入向量。
• GPU 隔离：在多租户环境中，使用 NVIDIA MIG（Multi-Instance GPU）对 A100/H100 GPU 进行分区，避免某个用户的生成任务耗尽其他用户所需的显存。
• 网络隔离：将 Gradio 容器运行在内部 VPC 中，仅通过带身份验证的 API 网关对外暴露。

与其他方案的对比 #

在 HunyuanVideo 与 Wan 的对比中，HunyuanVideo 最主要的差异化优势在于其电影级美学效果和运动真实感。它的"招牌风格"开箱即用就能呈现丰富的调色、自然的散景（bokeh）以及电影般的运动效果。Wan 2.2 在照片级真实感的人脸和精细细节方面略胜一筹。CogVideoX-5B 依然是 12GB 显存 GPU 上易用性最好的选择，尽管质量稍逊一筹。Open-Sora 则为想要从头训练模型的研究人员提供了最灵活的训练流水线。

局限性 / 客观评价 #

HunyuanVideo 并不适用于所有视频生成任务。以下是它表现欠佳的方面：

速度：即便用上了 FP8 和 SSTA，HunyuanVideo 依然比 Wan 2.2 慢，比 LTX-Video 更是慢了不少。如果你的工作流需要快速迭代（每小时生成数百个片段），LTX-Video 或商业 API 会是更合适的选择。

显存需求：原始的 130 亿参数模型生成 720p 视频需要 60GB 显存。只有搭配 INT8 量化的 1.5 版本才能将需求降到 24GB。没有 A100、H100 或 RTX 4090 级别硬件的团队，应该考虑 CogVideoX 或云端推理方案。

对提示词的依赖：简短或含糊的提示词会导致输出结果不稳定。模型期望得到详细、结构化的描述（30-60 个单词），并将主体、动作和环境分别描述清楚。内置的提示词重写器虽然有帮助，但会增加延迟。

分辨率上限：原生生成能力的上限是 720p。1.5 版本中的 1080p 超分辨率网络会增加处理时间，并且在复杂纹理上可能引入伪影。若需要原生 1080p 生成能力，Sora 或 Kling 等商业模型仍然领先。

片段长度：实际可用的生成长度被限制在 5-10 秒。更长的序列所需的计算资源甚至超出了 H100 的规格，而且超过 10 秒后时间一致性会明显下降。

仅支持 Linux：官方没有提供 Windows 或 macOS 支持。WSL2 可能可以运行，但维护者并未对此进行文档说明或测试。

常见问题 #

Q：运行 HunyuanVideo 实际需要多少显存？

A：原始的 130 亿参数模型生成 720p 视频需要 60GB 显存，540p 需要 45GB。HunyuanVideo-1.5 通过 INT8 量化将需求降至 24GB，若启用 CPU 卸载则可降至 14GB。相比 FP16，FP8 权重能节省约 10GB 显存。生产环境建议使用 NVIDIA A100 80GB 或 H100；用于实验的话，单张 RTX 4090（24GB）配合量化就能运行 1.5 模型。

Q：我能在 Windows 上运行 HunyuanVideo 吗？

A：官方来说不行——该项目只支持 Linux。部分用户反馈通过 WSL2（Windows Subsystem for Linux）配合 CUDA 直通能够成功运行，但腾讯团队并未对此提供文档说明或支持。对于使用 Windows 的团队来说，采用 WSL2 后端的 Docker Desktop 是最可行的路径，不过要做好排查 CUDA 兼容性问题的准备。

Q：HunyuanVideo 与 Sora、Kling 等商业 API 相比如何？

A：在人工评估中，HunyuanVideo 在运动质量和综合排名上超过了 Runway Gen-3 和 Luma 1.6。与领先的商业模型（Sora 2、Kling 2.5）之间的差距已经大幅缩小，但在照片级真实感人物和复杂多物体场景上仍然存在可衡量的差距。两者的权衡在于成本：商业 API 每秒视频收费 0.10-0.50 美元，而自托管的 HunyuanVideo 只需承担 GPU 算力成本（在 H200 云实例上大约每秒 0.14-0.21 美元，若使用自有硬件则成本接近于零）。

Q：HunyuanVideo 最佳的提示词格式是什么？

A：使用结构化的提示词，清晰地区分主体、动作和环境，字数控制在 30-60 个单词左右。例如：“一只金毛猎犬在日落时分沿着沙滩奔跑。背景中海浪拍打着海岸。狗的毛发在风中飘动。温暖的黄金时刻光线。广角镜头，电影级调色。“启用提示词重写功能（Normal 模式追求准确性，Master 模式追求视觉精致度），可以自动将简短的提示词扩展成模型更偏好的详细描述。

Q：如何在生产环境中加快推理速度？

A：可以组合使用多种优化手段：(1) 使用 FP8 量化权重来降低显存占用并提升批处理吞吐量。(2) 启用 xDiT 多 GPU 并行推理——8 张 A100 相比单卡可实现 5.6 倍加速。(3) 使用经过 CFG 蒸馏的模型变体，能以较小的质量代价换取约 2 倍的加速。(4) 启用特征缓存（TeaCache）来跳过多个步骤间的冗余计算。(5) 对于 1.5 版本，SSTA 注意力机制会自动带来 1.87 倍加速，且不损失质量。

Q：我可以在哪里获取帮助或与其他用户讨论 HunyuanVideo？

A：腾讯团队维护着一个 Discord 服务器和微信群，链接可以在 GitHub README 中找到。对于英语开发者来说，Hugging Face 社区论坛和 ComfyUI Discord 都有活跃的 HunyuanVideo 讨论频道。如需报告 bug 或提出功能需求，请在官方仓库使用 GitHub Issues。

结语 #

HunyuanVideo 是一款达到生产级水准的视频生成框架，弥合了闭源商业 API 与开源可及性之间的鸿沟。随着 1.5 版本带来 83 亿参数、SSTA 注意力机制以及对消费级 GPU 的兼容性，它已经成为工作室和独立创作者都能实际使用的选择。

以下是今天就可以开始上手的行动清单：

1. 克隆代码仓库，在 GPU 实例上运行 Docker 镜像——官方 CUDA 12 镜像是最快的上手路径。
2. 下载 FP8 权重，使用 sample_video.py 完成你的第一次 720p 生成。
3. 使用 Kijai 的封装工具与 ComfyUI 集成，以可视化方式编辑工作流。
4. 加入 dibi8 Telegram 群组，与社区一起讨论部署策略、分享你生成的视频。

本文中的部分链接为联盟链接。如果你通过这些链接购买服务，我们可能会获得佣金——这在不增加你任何额外成本的情况下，帮助支持了 dibi8 开源项目。

推荐主机与基础设施 #

在将上述任何工具部署到生产环境之前，你都需要可靠的基础设施。以下两个选项是 dibi8 实际在用并推荐的：

• DigitalOcean — 60 天内 200 美元免费额度，覆盖 14+ 个全球节点。是独立开发者运行开源 AI 工具的默认选择。
• HTStack — 香港 VPS，从中国大陆访问延迟低。这正是承载 dibi8.com 的同一家 IDC——经过生产环境的实战检验。

联盟链接——不会给你增加额外费用，同时帮助 dibi8.com 持续运营。

来源与延伸阅读 #

• 官方仓库：https://github.com/Tencent-Hunyuan/HunyuanVideo
• HunyuanVideo-1.5 仓库：https://github.com/Tencent-Hunyuan/HunyuanVideo-1.5
• 项目主页：https://aivideo.hunyuan.tencent.com
• Hugging Face 模型卡片：https://huggingface.co/tencent/HunyuanVideo
• ComfyUI Wiki 教程：https://comfyui-wiki.com/en/tutorial/advanced/hunyuan-text-to-video-workflow-guide-and-example
• 技术报告（arXiv）：https://arxiv.org/abs/2412.03603
• HunyuanVideo 1.5 技术报告：https://arxiv.org/abs/2511.18870
• xDiT 并行推理：https://github.com/xdit-project/xDiT
• Kijai ComfyUI 封装工具：https://github.com/kijai/ComfyUI-HunyuanVideoWrapper
• DigitalOcean GPU Droplets：https://www.digitalocean.com/products/gpu-droplets?refcode=eca87ac14ee0

参考文献与来源 #

• HunyuanVideo
• HunyuanVideo-1.5
• xDiT
• ComfyUI-HunyuanVideoWrapper (Kijai)
• FlashAttention