# https://github.com/Tencent-Hunyuan/HunyuanVideo 项目说明书 生成时间：2026-06-25 06:30:08 UTC ## 目录 - [项目概览与整体架构](#page-overview) - [推理与部署指南](#page-inference) - [核心模型组件](#page-model) - [社区资源与故障排查](#page-community) ## 项目概览与整体架构 ### 相关页面 相关主题：[推理与部署指南](#page-inference), [核心模型组件](#page-model)
相关源码文件 以下源码文件用于生成本页说明： - [hyvideo/modules/models.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/modules/models.py) - [hyvideo/vae/autoencoder_kl_causal_3d.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/vae/autoencoder_kl_causal_3d.py) - [hyvideo/vae/unet_causal_3d_blocks.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/vae/unet_causal_3d_blocks.py) - [hyvideo/text_encoder/__init__.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/text_encoder/__init__.py) - [hyvideo/diffusion/schedulers/scheduling_flow_match_discrete.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/diffusion/schedulers/scheduling_flow_match_discrete.py) - [hyvideo/diffusion/pipelines/pipeline_hunyuan_video.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/diffusion/pipelines/pipeline_hunyuan_video.py) - [hyvideo/modules/attenion.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/modules/attenion.py) - [hyvideo/prompt_rewrite.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/prompt_rewrite.py) - [hyvideo/constants.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/constants.py) - [ckpts/README.md](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/ckpts/README.md) - [LICENSE.txt](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/LICENSE.txt)
# 项目概览与整体架构 ## 项目简介与定位 HunyuanVideo 是腾讯混元团队开源的视频生成基础模型项目，目标是从文本提示词（text prompt）直接生成高质量视频。整个仓库以 `hyvideo` 作为顶层 Python 包，提供从模型定义、文本编码、潜在空间扩散到视频解码的端到端推理能力，并附带分发的模型权重与提示词改写工具，支持开箱即用的视频创作流程。 在许可层面，仓库随附的 `LICENSE.txt` 采用「Tencent Hunyuan Community License Agreement」。需要特别注意的限制包括：分发地域不覆盖欧盟、英国与韩国境内用户；以及当产品的月活用户超过 1 亿时，许可方需向腾讯申请商业授权，否则不得行使本协议授予的权利。 资料来源：[LICENSE.txt:1-50]() 资料来源：[LICENSE.txt:87-96]() ## 整体架构 下图展示了 HunyuanVideo 推理流程中各核心模块的协作关系： ```mermaid flowchart LR A[用户提示词] --> B[prompt_rewrite.py
Normal / Master] B --> C[Text Encoder
CLIP-L + LLM] C --> D[文本嵌入 +
Token Refiner] D --> E[DiT 主干
MMDoubleStreamBlock
MMSingleStreamBlock] F[VAE Encoder
Causal 3D] --> E E --> G[Flow Matching
Scheduler] G --> H[潜在视频张量] H --> I[VAE Decoder
Causal 3D] I --> J[输出视频帧] ``` **架构解读**： 1. **文本侧**：原始提示词先经过 `hyvideo/prompt_rewrite.py` 中的「Normal / Master」模式改写，再送入双文本编码器。 2. **潜空间侧**：`autoencoder_kl_causal_3d.py` 提供 3D 因果 VAE，编码器将视频压缩为潜变量，解码器在末尾还原为可播放的视频帧。 3. **扩散主干**：`modules/models.py` 实现基于 DiT 的多模态双流/单流块，使用 RoPE 位置编码与双模态调制。 4. **调度器**：`scheduling_flow_match_discrete.py` 实现离散时间的 flow matching 采样。 5. **集成管线**：`pipeline_hunyuan_video.py` 将以上模块封装为 `HunyuanVideoPipeline`，并提供 `output_type`、`guidance_rescale` 等参数。 资料来源：[hyvideo/prompt_rewrite.py:1-30]() 资料来源：[hyvideo/vae/autoencoder_kl_causal_3d.py:1-80]() 资料来源：[hyvideo/modules/models.py:1-60]() 资料来源：[hyvideo/diffusion/schedulers/scheduling_flow_match_discrete.py:1-60]() 资料来源：[hyvideo/diffusion/pipelines/pipeline_hunyuan_video.py:1-40]() ## 关键模块职责 ### 双流与单流 DiT 块 `MMDoubleStreamBlock` 与 `MMSingleStreamBlock` 是 HunyuanVideo 主干网络的核心算子。两者均实现了「文本/视觉分别调制 + 拼接后联合注意力」的模式，灵感来自 SD3 与 Flux.1 设计。模块的构造参数与默认配置集中在 `HunyuanVideo` 类的 `__init__` 中：默认 `mm_double_blocks_depth=20`、`mm_single_blocks_depth=40`、`hidden_size=3072`、`heads_num=24`，并在 `qk_norm_type="rms"` 时启用 QK 归一化。文本提示通过 `SingleTokenRefiner` 进一步精化后再注入主干的注意力。 资料来源：[hyvideo/modules/models.py:1-100]() ### 文本编码与提示模板 `text_encoder/__init__.py` 同时管理 CLIP-L 与 LLM 两种文本编码路径，前者来自 OpenAI 的 `clip-vit-large-patch14`（按 `ckpts/README.md` 中的 `huggingface-cli download` 指令获取），后者使用 `AutoModel.from_pretrained` 加载。`constants.py` 中的 `PROMPT_TEMPLATE` 区分 `dit-llm-encode` 与 `dit-llm-encode-video` 两套模板，分别设置 `crop_start=36` 与 `crop_start=95` 以裁掉系统提示部分、保留用户内容。`NEGATIVE_PROMPT` 默认值为 `"Aerial view, aerial view, overexposed, low quality, deformation, a poor composition, bad hands, bad teeth, bad eyes, bad limbs, distortion"`，用于无分类器引导。 资料来源：[hyvideo/text_encoder/__init__.py:1-80]() 资料来源：[hyvideo/constants.py:30-70]() 资料来源：[ckpts/README.md:1-20]() ### Flow Matching 调度器 `FlowMatchDiscreteScheduler` 继承自 `diffusers` 的 `SchedulerMixin` 与 `ConfigMixin`，通过 `@register_to_config` 暴露可配置超参数；其前向 `step` 函数返回 `FlowMatchDiscreteSchedulerOutput`，内含 `prev_sample` 作为下一轮的模型输入。该调度器使 HunyuanVideo 在保持高质量的同时，可与少步采样策略配合。 资料来源：[hyvideo/diffusion/schedulers/scheduling_flow_match_discrete.py:1-60]() ### 3D 因果 VAE `autoencoder_kl_causal_3d.py` 在 `diffusers==0.29.2` 基础上改造而成，兼容 `ModelMixin` 与 `FromOriginalVAEMixin`。`unet_causal_3d_blocks.py` 中的 `prepare_causal_attention_mask` 实现了时序上的因果注意力掩码——对于第 `i_frame` 帧内的 token，仅允许其关注前 `i_frame + 1` 帧以内的内容，从而保证视频生成的时序一致性。 资料来源：[hyvideo/vae/autoencoder_kl_causal_3d.py:1-100]() 资料来源：[hyvideo/vae/unet_causal_3d_blocks.py:1-40]() ### 高效注意力与并行推理 `modules/attenion.py` 根据不同后端（`torch`、`flash`）切换 `MEMORY_LAYOUT`：在 `torch` 模式下按 `cu_seqlens_q` 拆分区间分别做 `scaled_dot_product_attention`，在 `flash` 模式下调用 `flash_attn_varlen_func`。这一抽象让单卡推理与多卡 Ulysses 序列并行都能复用同一组注意力算子。 资料来源：[hyvideo/modules/attenion.py:1-50]() ## 社区关注点与生态 围绕该项目的社区讨论主要集中在以下三方面： 1. **图像到视频（I2V）模型**：[Issue #180](https://github.com/Tencent-Hunyuan/HunyuanVideo/issues/180)、[#128](https://github.com/Tencent-Hunyuan/HunyuanVideo/issues/128)、[#172](https://github.com/Tencent-Hunyuan/HunyuanVideo/issues/172)、[#198](https://github.com/Tencent-Hunyuan/HunyuanVideo/issues/198) 与 [#131](https://github.com/Tencent-Hunyuan/HunyuanVideo/issues/131) 等多条高互动议题都在询问 I2V 模型的发布时间，I2V 已成为 HunyuanVideo 路线图中呼声最高的功能。 2. **多卡并行推理**：[Issue #249](https://github.com/Tencent-Hunyuan/HunyuanVideo/issues/249) 报告了使用 `torchrun --nproc_per_node=2` 配合 `--ulysses-degree` 启动并行推理时遇到的版本问题，提示分布式推理需匹配 CUDA 12.4、CUBLAS ≥ 12.4.5.8 与 CUDNN ≥ 9.00。 3. **官方微调代码**：[Issue #302](https://github.com/Tencent-Hunyuan/HunyuanVideo/issues/302) 提出了对官方微调示例的需求，社区希望仓库补充针对风格、运动模式、垂类领域的训练脚本，以降低二次开发门槛。 ## 参见 - 模型权重与依赖下载说明：[ckpts/README.md](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/ckpts/README.md) - 提示词改写工具：[hyvideo/prompt_rewrite.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/prompt_rewrite.py) - 推理管线参数定义：[hyvideo/diffusion/pipelines/pipeline_hunyuan_video.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/diffusion/pipelines/pipeline_hunyuan_video.py) - 调度器实现细节：[hyvideo/diffusion/schedulers/scheduling_flow_match_discrete.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/diffusion/schedulers/scheduling_flow_match_discrete.py) --- ## 推理与部署指南 ### 相关页面 相关主题：[项目概览与整体架构](#page-overview), [社区资源与故障排查](#page-community)
相关源码文件 以下源码文件用于生成本页说明： - [sample_video.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/sample_video.py) - [gradio_server.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/gradio_server.py) - [scripts/run_sample_video.sh](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/scripts/run_sample_video.sh) - [scripts/run_sample_video_fp8.sh](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/scripts/run_sample_video_fp8.sh) - [scripts/run_sample_video_multigpu.sh](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/scripts/run_sample_video_multigpu.sh) - [hyvideo/inference.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/inference.py) - [hyvideo/modules/models.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/modules/models.py) - [hyvideo/diffusion/pipelines/pipeline_hunyuan_video.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/diffusion/pipelines/pipeline_hunyuan_video.py) - [hyvideo/diffusion/schedulers/scheduling_flow_match_discrete.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/diffusion/schedulers/scheduling_flow_match_discrete.py) - [hyvideo/text_encoder/__init__.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/text_encoder/__init__.py) - [hyvideo/constants.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/constants.py) - [hyvideo/vae/autoencoder_kl_causal_3d.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/vae/autoencoder_kl_causal_3d.py) - [hyvideo/prompt_rewrite.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/prompt_rewrite.py) - [ckpts/README.md](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/ckpts/README.md) - [LICENSE.txt](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/LICENSE.txt)
# 推理与部署指南 ## 概述 HunyuanVideo 是一个基于扩散 Transformer（DiT）的文本生成视频（T2V）开源项目，其推理与部署围绕"加载预训练权重 → 文本编码 → 潜空间去噪 → VAE 解码 → 写出视频"这一主流程展开。整个推理管线在 `hyvideo/inference.py` 中以 `inferrence` 函数形式串联起来，依赖 DiT 主干、3D 因果 VAE、双文本编码器（CLIP-L 与 LLM）以及 Flow-Matching 调度器协同工作。资料来源：[hyvideo/inference.py:1-50]() 模型权重遵循非商业友好的 [LICENSE.txt](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/LICENSE.txt) 协议分发，月活超过 1 亿的产品需另行申请商业授权，这是在大规模部署前必须评估的合规前置条件。资料来源：[LICENSE.txt:1-40]() ## 模型与组件构成 ### 主干网络 核心生成器 `HunyuanVideoDiT` 由 20 个 `MMDoubleStreamBlock` 与 40 个 `MMSingleStreamBlock` 级联组成，隐藏维度 3072、注意力头数 24，并在文本与视觉分支采用分别独立的调制（modulation）机制，这与 Stable Diffusion 3 / Flux 的设计一脉相承。资料来源：[hyvideo/modules/models.py:1-80]() ### 3D 因果 VAE 视频帧的时空压缩由 `AutoencoderKLCausal3D` 完成，模块定义在 `hyvideo/vae/autoencoder_kl_causal_3d.py`，其 `forward` 通过 `encode` 取得潜变量后由 `decode` 重建视频，伴随 `s_ratio` 与 `t_ratio` 两个下采样倍率被透传到生成流程。资料来源：[hyvideo/vae/autoencoder_kl_causal_3d.py:1-60]() ### 文本编码与提示词模板 `text_encoder` 子包统一封装了 `clipL` 与 `llm` 两种编码器入口，并在 `encode` 方法中根据 `prompt_template` 套用 Llama-3 风格的对话模板。`constants.py` 内置了 `dit-llm-encode`（图像描述，crop_start=36）与 `dit-llm-encode-video`（视频描述，crop_start=95）两套提示词模板，以及用于无分类器引导的默认负向提示词。资料来源：[hyvideo/text_encoder/__init__.py:1-80]() 资料来源：[hyvideo/constants.py:1-80]() ### 调度器 `FlowMatchDiscreteScheduler`（位于 `scheduling_flow_match_discrete.py`）实现了离散流匹配过程，其 `step` 函数输出 `prev_sample`，与社区常见的 EulerDiscrete 调度器不同，应避免直接套用其他扩散模型的 `set_timesteps` 参数语义。资料来源：[hyvideo/diffusion/schedulers/scheduling_flow_match_discrete.py:1-60]() ## 推理主流程 ```mermaid flowchart TD A[加载 HunyuanVideoDiT] --> B[加载 3D 因果 VAE] A --> C[加载双文本编码器] D[原始 Prompt] --> E[Prompt 重写 可选] E --> F[Tokenizer + LLM/CLIP] F --> G[text_embeds 与 pooled output] G --> H[随机采样潜变量] H --> I[Flow-Matching 去噪循环] I --> J[DiT 推理] B --> I I --> K[VAE decode] K --> L[MP4 写出] ``` 入口脚本 `sample_video.py` 与 `gradio_server.py` 共用 `hyvideo/inference.py` 中的 `inferrence`，其关键步骤包括：构造保存目录、按 `--video-size` 与 `--video-length` 计算潜空间尺寸、调用 `load_vae` 取得 VAE 与时空下采样比、调用 `TextEncoder` 取得条件嵌入、执行 50 步 Flow-Matching 采样、最后用 VAE 解码并通过 imageio 写出 mp4。资料来源：[hyvideo/inference.py:1-80]() 提示词改写模块 `prompt_rewrite.py` 提供 `Normal` 与 `Master` 两种重写模式，会调用外部大模型把简短的中文或英文描述扩写为包含镜头、风格、氛围信息的英文长提示。资料来源：[hyvideo/prompt_rewrite.py:1-40]() ## 部署模式与配置选项 `scripts/` 目录下的几个 shell 脚本封装了三种典型部署形态： | 部署形态 | 脚本 | 关键参数 / 适用场景 | | --- | --- | --- | | 单 GPU 标准推理 | [run_sample_video.sh](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/scripts/run_sample_video.sh) | `torchrun --nproc_per_node=1`，默认 bf16 | | 单 GPU FP8 量化推理 | [run_sample_video_fp8.sh](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/scripts/run_sample_video_fp8.sh) | 加载 `mp_rank_00_model_states_fp8.pt`，降低显存占用 | | 多 GPU 并行推理 | [run_sample_video_multigpu.sh](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/scripts/run_sample_video_multigpu.sh) | `--ulysses-degree` 等分布式参数，跨卡拆分序列 | FP8 权重需在 `ckpts/hunyuan-video-t2v-720p/transformers/` 下同时提供 `mp_rank_00_model_states_fp8.pt` 与 `mp_rank_00_model_states_fp8_map.pt`，下载入口见 `ckpts/README.md`。资料来源：[ckpts/README.md:1-40]() `inference.py` 通过 `args.use_cpu_offload` 控制是否将 VAE 与文本编码器卸载到 CPU，从而在消费级显卡上也能完成 720p 视频生成。资料来源：[hyvideo/inference.py:30-80]() ## 社区关注的常见问题 - **I2V（图像到视频）模型尚未发布**：多个高互动 issue（#180、#128、#172、#198、#131）集中询问图生视频的开源计划，目前仓库仅包含 T2V 权重与脚本，需以官方 roadmap 为准。 - **并行推理报错**：[Issue #249](https://github.com/Tencent-Hunyuan/HunyuanVideo/issues/249) 反馈 `torchrun --nproc_per_node=2` 启动失败，常见原因是未设置正确的 `MASTER_ADDR`/`MASTER_PORT`，或与单机 8 卡环境相冲突，建议先以 `--nproc_per_node=1` 验证管线再扩容。 - **CUDA 库版本不匹配**：[Issue #317](https://github.com/Tencent-Hunyuan/HunyuanVideo/issues/317) 指出 `libcublas.so` 版本低于 12.4.5.8 时推理会崩溃，可通过 `pip install nvidia-cublas-cu12==12.4.5.8` 并将 `LD_LIBRARY_PATH` 指向 conda 包目录解决。 - **微调代码缺失**：[Issue #302](https://github.com/Tencent-Hunyuan/HunyuanVideo/issues/302) 询问官方微调示例，目前仓库没有训练入口，社区只能基于 `hyvideo/modules/models.py` 中的 DiT 类自行封装。 部署前应核对权重目录、CUDA/cuBLAS 版本以及显存规划，并在受限环境下优先尝试 FP8 量化与 CPU offload 组合。 ## See Also - 模型架构（`hyvideo/modules/models.py`） - 3D 因果 VAE（`hyvideo/vae/autoencoder_kl_causal_3d.py`） - Flow-Matching 调度器（`hyvideo/diffusion/schedulers/scheduling_flow_match_discrete.py`） - 提示词改写（`hyvideo/prompt_rewrite.py`） --- ## 核心模型组件 ### 相关页面 相关主题：[项目概览与整体架构](#page-overview), [推理与部署指南](#page-inference) # 核心模型组件
相关源码文件 以下源码文件用于生成本页说明： - [hyvideo/modules/models.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/modules/models.py) - [hyvideo/modules/attenion.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/modules/attenion.py) - [hyvideo/modules/embed_layers.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/modules/embed_layers.py) - [hyvideo/modules/posemb_layers.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/modules/posemb_layers.py) - [hyvideo/modules/mlp_layers.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/modules/mlp_layers.py) - [hyvideo/modules/norm_layers.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/modules/norm_layers.py) - [hyvideo/vae/autoencoder_kl_causal_3d.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/vae/autoencoder_kl_causal_3d.py) - [hyvideo/diffusion/schedulers/scheduling_flow_match_discrete.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/diffusion/schedulers/scheduling_flow_match_discrete.py) - [hyvideo/diffusion/pipelines/pipeline_hunyuan_video.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/diffusion/pipelines/pipeline_hunyuan_video.py) - [hyvideo/inference.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/inference.py)
## 1. 概述 HunyuanVideo 的核心模型组件是一个完整的视频生成系统，采用了基于 DiT (Diffusion Transformer) 的架构，配合专用的 3D 因果 VAE、文本编码器以及流匹配调度器。整体设计遵循 Stability AI 团队提出的 MM-DiT 框架，并在其基础上进行了视频领域的深度优化。该项目核心目标是提供一个可扩展、高质量的开源视频生成基础模型 [资料来源：[hyvideo/modules/models.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/modules/models.py)]。 ## 2. 视频变分自编码器（Video VAE） 视频 VAE 组件位于 [hyvideo/vae/autoencoder_kl_causal_3d.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/vae/autoencoder_kl_causal_3d.py)，采用了 Causal 3D 卷积结构，专为视频数据的时空压缩而设计： ```mermaid graph LR A[视频输入] --> B[3D Encoder] B --> C[Latent Space] C --> D[3D Decoder] D --> E[重建视频] C --> F[DiT 处理] ``` 该 VAE 的核心特性包括： - **因果卷积**：使用因果 3D 卷积（Causal 3D Convolution），确保时间维度上的因果性，避免未来帧的信息泄露到当前帧的重建过程中 - **潜空间压缩**：通过 [AutoencoderKL](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/vae/autoencoder_kl_causal_3d.py) 实现高效的视频压缩，便于后续扩散模型处理 - **支持缓存（Cache）**：使用 `self.enable_tiling()` / `enable_slicing()` 等方法以减少显存占用 [资料来源：[hyvideo/vae/autoencoder_kl_causal_3d.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/vae/autoencoder_kl_causal_3d.py)] ## 3. 视频生成变换器（Video DiT） 视频生成的核心变换器定义在 [hyvideo/modules/models.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/modules/models.py) 中，包括 `HunyuanVideoTransformer3DModel`、`MMDoubleStreamBlock` 和 `MMSingleStreamBlock` 三个核心类。架构设计采用多模态双流注意力（MM-DiT），参考了 SD3 和 Flux.1 的设计思路。 ### 3.1 主要配置参数 | 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | `patch_size` | `List[int]` | `[1, 2, 2]` | 时空分块大小 | | `in_channels` | `int` | `4` | 输入潜空间通道数（需与 VAE 一致） | | `out_channels` | `int` | `None` | 输出通道数 | | `hidden_size` | `int` | `3072` | Transformer 隐藏层维度 | | `heads_num` | `int` | `24` | 注意力头数 | | `mlp_width_ratio` | `float` | `4.0` | MLP 宽度比 | | `qk_norm` | `bool` | `True` | 是否对 QK 进行归一化 | | `rope_dim_list` | `List[int]` | `[16, 56, 56]` | RoPE 各维度分配 | [资料来源：[hyvideo/modules/models.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/modules/models.py)] ### 3.2 注意力机制 注意力机制的实现位于 [hyvideo/modules/attenion.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/modules/attenion.py)，支持多种注意力后端： - **MEMORY_LAYOUT = {"torch": "SDPA", "flash": "Flash Attention"}**：根据硬件支持自动选择最优注意力实现 - **变量长度注意力**：通过 `flash_attn_varlen_func` 支持可变长度的序列处理，提高长视频生成效率 - **3D RoPE**：使用 [hyvideo/modules/posemb_layers.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/modules/posemb_layers.py) 中的 `apply_rotary_emb` 对时间、高度、宽度三个维度分别应用旋转位置编码 ### 3.3 双流与单流块 - **MMDoubleStreamBlock**：双流块，将文本和视频的潜向量分离处理，在注意力计算后进行调制（Modulation），支持独立的文本和视频特征提取 - **MMSingleStreamBlock**：单流块，将文本和视频特征拼接后进行联合处理，实现更深层次的跨模态交互 [资料来源：[hyvideo/modules/models.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/modules/models.py)] ## 4. 流匹配调度器（Flow Matching Scheduler） 流匹配调度器位于 [hyvideo/diffusion/schedulers/scheduling_flow_match_discrete.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/diffusion/schedulers/scheduling_flow_match_discrete.py)，基于 Flow Matching 框架，提供了 `FlowMatchDiscreteScheduler` 和 `FlowMatchEulerDiscreteScheduler` 两个类。核心特性包括： - **离散时间步采样**：使用 `linspace` 在 `num_train_timesteps` 范围内均匀采样时间步 - **Euler 离散化**：通过 `step()` 函数实现一步 Euler 积分，将速度场（velocity）转换为潜空间样本 - **支持动态时间步转换**：`set_timesteps()` 方法允许在推理时灵活调整采样步数 ```python @dataclass class FlowMatchDiscreteSchedulerOutput(BaseOutput): prev_sample: torch.FloatTensor ``` [资料来源：[hyvideo/diffusion/schedulers/scheduling_flow_match_discrete.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/diffusion/schedulers/scheduling_flow_match_discrete.py)] ## 5. 文本编码器 文本编码器模块位于 [hyvideo/modules/text_encoder/](https://github.com/Tencent-Hunyuan/HunyuanVideo/tree/main/hyvideo/modules/text_encoder)，使用 CLIP 模型作为文本特征提取器： - **CLIPTextModel**：作为主要文本编码器，提取文本的语义特征 - **CLIPTokenizer**：处理输入文本的 tokenization - **Prompt 重写**：通过 [hyvideo/diffusion/pipelines/prompt_rewrite.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/diffusion/pipelines/prompt_rewrite.py) 中的 LLM 进行提示词重写，将简单的用户输入扩展为更详细的视频描述 - **双文本编码器配置**：支持通过 `text_encoder_2` 配置第二个文本编码器以增强文本理解能力 [资料来源：[hyvideo/diffusion/pipelines/pipeline_hunyuan_video.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/diffusion/pipelines/pipeline_hunyuan_video.py)] ## 6. 推理流水线 整体推理流水线整合在 [hyvideo/inference.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/inference.py) 中，完整流程如下： ```mermaid graph TD A[用户提示词] --> B[Prompt 重写] B --> C[CLIP 文本编码] C --> D[视频 VAE 编码
可选：图像到视频] D --> E[DiT 视频生成] E --> F[流匹配采样] F --> G[视频 VAE 解码] G --> H[输出视频] ``` ### 6.1 关键参数 | 参数 | 默认值 | 说明 | |------|--------|------| | `video_size` | `1280 720` | 生成视频的分辨率 | | `video_length` | `129` | 视频帧数 | | `infer_steps` | `50` | 流匹配采样步数 | | `prompt` | `"A astronaut..."` | 用户输入提示词 | | `flow_reverse` | `False` | 是否使用反向流 | | `use_cpu_offload` | `False` | 是否使用 CPU 卸载以节省显存 | | `enable_parallel_attention` | `False` | 是否启用并行注意力（来自社区 #249）| [资料来源：[hyvideo/inference.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/inference.py)] ### 6.2 图像到视频模式 根据社区讨论 [issue #198](https://github.com/Tencent-Hunyuan/HunyuanVideo/issues/198) 和 [issue #131](https://github.com/Tencent-Hunyuan/HunyuanVideo/issues/131)，HunyuanVideo 计划支持图像到视频（I2V）模式。该模式将使用初始图像作为条件，通过 VAE 编码后与文本特征一起输入到 DiT 中。 ## 7. 提示词模板系统 提示词模板定义在 [hyvideo/constants.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/constants.py) 中，包含两个主要模板： - `PROMPT_TEMPLATE_ENCODE`：用于 DiT 编码视频的模板 - `PROMPT_TEMPLATE_ENCODE_VIDEO`：用于视频编码的模板 模板使用特定的标记（如 `<|start_header_id|>`、`<|eot_id|>`）来引导 LLM 进行更细致的视频描述生成。 [资料来源：[hyvideo/constants.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/constants.py)] ## 8. 常见问题与社区反馈 根据社区讨论，以下是用户在使用核心模型组件时经常遇到的问题： 1. **微调代码缺失** [issue #302](https://github.com/Tencent-Hunyuan/HunyuanVideo/issues/302)：用户希望获得官方的微调代码以适配自定义数据集（如风格适配、运动调优、领域特定视频生成等） 2. **并行推理问题** [issue #249](https://github.com/Tencent-Hunyuan/HunyuanVideo/issues/249)：在尝试并行推理时遇到问题，建议参考 `torchrun` 多卡配置 3. **图像到视频功能** [issue #198](https://github.com/Tencent-Hunyuan/HunyuanVideo/issues/198) 和 [issue #180](https://github.com/Tencent-Hunyuan/HunyuanVideo/issues/180)：用户期待图像到视频模型的开源发布 ## 参见 - [HunyuanVideo 官方仓库](https://github.com/Tencent-Hunyuan/HunyuanVideo) - [HunyuanVideo 图生视频讨论](https://github.com/Tencent-Hunyuan/HunyuanVideo/issues/198) - [微调代码请求](https://github.com/Tencent-Hunyuan/HunyuanVideo/issues/302) - [Diffusers 框架文档](https://huggingface.co/docs/diffusers) --- ## 社区资源与故障排查 ### 相关页面 相关主题：[推理与部署指南](#page-inference), [项目概览与整体架构](#page-overview)
相关源码文件 以下源码文件用于生成本页说明： - [LICENSE.txt](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/LICENSE.txt) - [ckpts/README.md](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/ckpts/README.md) - [hyvideo/constants.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/constants.py) - [hyvideo/prompt_rewrite.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/prompt_rewrite.py) - [hyvideo/text_encoder/__init__.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/text_encoder/__init__.py) - [hyvideo/modules/models.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/modules/models.py) - [hyvideo/diffusion/schedulers/scheduling_flow_match_discrete.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/diffusion/schedulers/scheduling_flow_match_discrete.py) - [hyvideo/diffusion/pipelines/pipeline_hunyuan_video.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/diffusion/pipelines/pipeline_hunyuan_video.py) - [hyvideo/vae/autoencoder_kl_causal_3d.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/vae/autoencoder_kl_causal_3d.py) - [hyvideo/vae/unet_causal_3d_blocks.py](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/hyvideo/vae/unet_causal_3d_blocks.py)
# 社区资源与故障排查 ## 概述 本页是 HunyuanVideo 项目的运维与排错速查手册，集中整理社区最常关注的四类问题：许可证条款、模型权重获取渠道、与文本编码/提示词模板相关的运行时错误，以及 `torchrun` 并行推理的失败模式。这些问题在 GitHub Issues 中反复出现，包括 [Issue #317](https://github.com/Tencent-Hunyuan/HunyuanVideo/issues/317) 中报告的 CUDA/cuBLAS 依赖问题、[Issue #249](https://github.com/Tencent-Hunyuan/HunyuanVideo/issues/249) 中复现的 `torchrun --nproc_per_node=2` 崩溃，以及 [Issue #302](https://github.com/Tencent-Hunyuan/HunyuanVideo/issues/302) 中提出的官方微调代码诉求。本页不引入未在仓库中验证的修改建议，所有结论都基于 `hyvideo/` 子包与 `ckpts/README.md` 中已有的实现。 ## 许可证与使用条款 仓库根目录的 `LICENSE.txt` 为 Tencent Hunyuan Community License Agreement 全文，所有分发/部署行为必须以原文为准，本节仅为关键摘要： - **地域限制**：`Territory` 明确将 **欧盟、英国与韩国** 排除在许可范围之外 资料来源：[LICENSE.txt](). - **MAU 触发条款**：若发布当月许可方产品的月活用户超过 1 亿，必须另行向 Tencent 申请商业授权，否则无权行使本协议下的任何权利 资料来源：[LICENSE.txt](). - **使用红线**：协议第 5 条列出 20 类禁止用途，覆盖非法内容、冒充他人、高风险自动决策、军事用途、基于受保护特征的歧视、对弱势群体的剥削等 资料来源：[LICENSE.txt](). - **再分发要求**：第 3 条规定对第三方的非托管分发必须附带 NOTICE 文件，内容为 "Tencent Hunyuan is licensed under the Tencent Hunyuan Community License Agreement, Copyright © 2024 Tencent" 资料来源：[LICENSE.txt](). - **托管服务标记**：通过 Hosted Service 提供时必须在 UI 中显著标注 "Powered by Tencent Hunyuan" 资料来源：[LICENSE.txt](). 在 EU/UK/KR 区域部署、面向 1 亿 MAU 商业化、或任何受第 5 条约束的用途，应直接阅读 `LICENSE.txt` 全文确认可行性。 ## 社区资源、模型权重获取与常见故障 ### 模型权重与文本编码器 仓库内的下载说明集中在 [ckpts/README.md]()，官方推荐 `huggingface-cli download tencent/HunyuanVideo --local-dir ./ckpts`，完成后 `ckpts/` 应包含 `hunyuan-video-t2v-720p/transformers/`、`vae/`、`text_encoder/` 与 `text_encoder_2/` 四个子目录 资料来源：[ckpts/README.md]()。其中 `text_encoder_2` 为 OpenAI 的 `clip-vit-large-patch14`，由 `load_text_encoder` 通过 `CLIPTextModel.from_pretrained` 加载 资料来源：[ckpts/README.md](), [hyvideo/text_encoder/__init__.py]()。当 Hugging Face 不可达时，文档给出 `huggingface-cli` 镜像替代方案 资料来源：[ckpts/README.md]()。 ### 排查决策流 ```mermaid flowchart TD A[出现运行时错误] --> B{是否 CUDA / cuBLAS 报错?} B -- 是 --> C[升级 nvidia-cublas-cu12==12.4.5.8
并核对 CUDNN >= 9.0] B -- 否 --> D{是否 torchrun 并行推理?} D -- 是 --> E[核对 MASTER_ADDR / PORT
与 --ulysses-degree] D -- 否 --> F{是否文本编码 / 模板错误?} F -- 是 --> G[检查 PROMPT_TEMPLATE
与 crop_start 设置] F -- 否 --> H[搜索 / 提交 GitHub Issue] C --> I[Issue #317] E --> J[Issue #249] ``` ### 故障类别与代码定位 - **CUDA / cuBLAS 不匹配**：`PRECISIONS` 与 `PRECISION_TO_TYPE` 表明模型支持 `fp32`/`fp16`/`bf16` 三种精度 资料来源：[hyvideo/constants.py]()。若 `sample_video.py` 入口出现 cuBLAS 段错误，与 [Issue #317](https://github.com/Tencent-Hunyuan/HunyuanVideo/issues/317) 中方案一致：升级到 `nvidia-cublas-cu12==12.4.5.8` 并设置 `LD_LIBRARY_PATH` 指向 `site-packages/nvidia/cublas/lib`。 - **并行推理崩溃**：`HunyuanVideoPipeline` 显式 `import torch.distributed as dist`，依赖 `torchrun` 启动多进程 资料来源：[hyvideo/diffusion/pipelines/pipeline_hunyuan_video.py]()。复现 [Issue #249](https://github.com/Tencent-Hunyuan/HunyuanVideo/issues/249) 的 `torchrun --nproc_per_node=2` 失败时，需确认 `MASTER_ADDR`/`MASTER_PORT` 环境变量、`--ulysses-degree` 与可用 GPU 数量一致。 - **文本编码器加载失败**：`load_text_encoder` 区分 `clipL` 与 `llm` 两种类型 资料来源：[hyvideo/text_encoder/__init__.py]()。`clipL` 会重新绑定 `final_layer_norm` 指向 `text_model.final_layer_norm`，`llm` 则指向 `text_encoder.norm`，checkpoint 与该命名约定不一致时即会抛错。 - **提示词模板不生效**：`PROMPT_TEMPLATE` 字典分别为 `dit-llm-encode` 与 `dit-llm-encode-video` 准备了 `template` 与 `crop_start`（36 / 95）资料来源：[hyvideo/constants.py]()。`text2tokens` 在 `data_type=="video"` 时会选用视频模板 资料来源：[hyvideo/text_encoder/__init__.py]()，自行绕过该分支会破坏上下文截断与对齐。 - **CAUSAL 3D VAE 显存峰值过高**：`prepare_causal_attention_mask` 构造 `(n_frame*n_hw, n_frame*n_hw)` 的注意力偏置矩阵 资料来源：[hyvideo/vae/unet_causal_3d_blocks.py]()。当分辨率与帧数较大时（如 1280×720×129 帧），该矩阵显著占用显存，可通过降低 `video-length` 或 `video-size` 缓解 资料来源：[hyvideo/vae/unet_causal_3d_blocks.py]()。 ## 已知限制与社区关注 仓库当前以 T2V 为主线：`HYVideoDiffusionTransformer` 的默认 `patch_size=[1,2,2]`、`in_channels=4`、`mm_double_blocks_depth=20`、`mm_single_blocks_depth=40` 均面向文生视频训练 资料来源：[hyvideo/modules/models.py]()。`AutoencoderKLCausal3D` 在编码阶段使用 3D causal 注意力，意味着解码时无法修改历史帧 资料来源：[hyvideo/vae/autoencoder_kl_causal_3d.py]()。`FlowMatchDiscreteScheduler` 派生自 Stability AI 的 flow matching 实现 资料来源：[hyvideo/diffusion/schedulers/scheduling_flow_match_discrete.py]()。 社区当前持续追踪的开放项： - **I2V 模型权重**：[Issue #128](https://github.com/Tencent-Hunyuan/HunyuanVideo/issues/128)、[#180](https://github.com/Tencent-Hunyuan/HunyuanVideo/issues/180)、[#172](https://github.com/Tencent-Hunyuan/HunyuanVideo/issues/172)、[#198](https://github.com/Tencent-Hunyuan/HunyuanVideo/issues/198)、[#131](https://github.com/Tencent-Hunyuan/HunyuanVideo/issues/131) 持续请求图生视频权重。 - **官方微调脚本**：[Issue #302](https://github.com/Tencent-Hunyuan/HunyuanVideo/issues/302) 请求仓库提供 LoRA / 全参数微调示例；当前仓库未提供 `train.py` 等训练入口。 - **多语种 Prompt 改写**：`prompt_rewrite.py` 的 `Normal` 与 `Master` 模式已内建中→英翻译逻辑 资料来源：[hyvideo/prompt_rewrite.py]()，但仍依赖外部 LLM 服务，需用户自行配置 endpoint。 ## 另请参见 - [ckpts/README.md](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/ckpts/README.md) — 模型下载、目录结构与网络受限时的镜像方案 - [LICENSE.txt](https://github.com/Tencent-Hunyuan/HunyuanVideo/blob/main/LICENSE.txt) — Tencent Hunyuan Community License Agreement 完整条款 - 在 GitHub Issues 中以 `I2V`、`fine-tune`、`torchrun` 为关键词可快速定位未解决问题 --- --- ## Doramagic 踩坑日志 项目：Tencent-Hunyuan/HunyuanVideo 摘要：发现 12 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安装坑 - 来源证据：I met a problem when i tried to parallel inference。 ## 1. 安装坑 · 来源证据：I met a problem when i tried to parallel inference - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：I met a problem when i tried to parallel inference - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/Tencent-Hunyuan/HunyuanVideo/issues/249 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 2. 安装坑 · 来源证据：Request for Official Fine-Tuning Code / Training Example - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Request for Official Fine-Tuning Code / Training Example - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/Tencent-Hunyuan/HunyuanVideo/issues/302 | 来源类型 github_issue 暴露的待验证使用条件。 ## 3. 安装坑 · 依赖 Docker 环境 - 严重度：medium - 证据强度：runtime_trace - 发现：安装/运行入口包含 Docker 命令：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 hunyuanvideo/hunyuanvideo:cuda_12 # For CUDA - 对用户的影响：非工程用户可能没有 Docker，启动成本明显增加。 - 复现命令：`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 hunyuanvideo/hunyuanvideo:cuda_12 # For CUDA` - 证据：identity.distribution | https://github.com/Tencent-Hunyuan/HunyuanVideo | 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 hunyuanvideo/hunyuanvideo:cuda_12 # For CUDA ## 4. 安装坑 · 来源证据：Tirkey voice - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Tirkey voice - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/Tencent-Hunyuan/HunyuanVideo/issues/317 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 5. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://github.com/Tencent-Hunyuan/HunyuanVideo | README/documentation is current enough for a first validation pass. ## 6. 运行坑 · 来源证据：Diário de obra como ancorar forro em nuvem em estruturas de telhadooo - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Diário de obra como ancorar forro em nuvem em estruturas de telhadooo - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/Tencent-Hunyuan/HunyuanVideo/issues/311 | 来源类型 github_issue 暴露的待验证使用条件。 ## 7. 维护坑 · 来源证据：BMW - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：BMW - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/Tencent-Hunyuan/HunyuanVideo/issues/313 | 来源类型 github_issue 暴露的待验证使用条件。 ## 8. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://github.com/Tencent-Hunyuan/HunyuanVideo | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://github.com/Tencent-Hunyuan/HunyuanVideo | no_demo; severity=medium ## 10. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://github.com/Tencent-Hunyuan/HunyuanVideo | no_demo; severity=medium ## 11. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://github.com/Tencent-Hunyuan/HunyuanVideo | issue_or_pr_quality=unknown ## 12. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://github.com/Tencent-Hunyuan/HunyuanVideo | release_recency=unknown