项目简介与定位

HunyuanVideo 是腾讯混元团队开源的视频生成基础模型项目，目标是从文本提示词（text prompt）直接生成高质量视频。整个仓库以 hyvideo 作为顶层 Python 包，提供从模型定义、文本编码、潜在空间扩散到视频解码的端到端推理能力，并附带分发的模型权重与提示词改写工具，支持开箱即用的视频创作流程。

在许可层面，仓库随附的 LICENSE.txt 采用「Tencent Hunyuan Community License Agreement」。需要特别注意的限制包括：分发地域不覆盖欧盟、英国与韩国境内用户；以及当产品的月活用户超过 1 亿时，许可方需向腾讯申请商业授权，否则不得行使本协议授予的权利。

资料来源：LICENSE.txt:1-50 资料来源：LICENSE.txt:87-96

整体架构

下图展示了 HunyuanVideo 推理流程中各核心模块的协作关系：

flowchart LR
    A[用户提示词] --> B[prompt_rewrite.py<br/>Normal / Master]
    B --> C[Text Encoder<br/>CLIP-L + LLM]
    C --> D[文本嵌入 +<br/>Token Refiner]
    D --> E[DiT 主干<br/>MMDoubleStreamBlock<br/>MMSingleStreamBlock]
    F[VAE Encoder<br/>Causal 3D] --> E
    E --> G[Flow Matching<br/>Scheduler]
    G --> H[潜在视频张量]
    H --> I[VAE Decoder<br/>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、#128、#172、#198 与 #131 等多条高互动议题都在询问 I2V 模型的发布时间，I2V 已成为 HunyuanVideo 路线图中呼声最高的功能。
2. 多卡并行推理：Issue #249 报告了使用 torchrun --nproc_per_node=2 配合 --ulysses-degree 启动并行推理时遇到的版本问题，提示分布式推理需匹配 CUDA 12.4、CUBLAS ≥ 12.4.5.8 与 CUDNN ≥ 9.00。
3. 官方微调代码：Issue #302 提出了对官方微调示例的需求，社区希望仓库补充针对风格、运动模式、垂类领域的训练脚本，以降低二次开发门槛。

参见

• 模型权重与依赖下载说明：ckpts/README.md
• 提示词改写工具：hyvideo/prompt_rewrite.py
• 推理管线参数定义：hyvideo/diffusion/pipelines/pipeline_hunyuan_video.py
• 调度器实现细节：hyvideo/diffusion/schedulers/scheduling_flow_match_discrete.py

概述

HunyuanVideo 是一个基于扩散 Transformer（DiT）的文本生成视频（T2V）开源项目，其推理与部署围绕"加载预训练权重 → 文本编码 → 潜空间去噪 → VAE 解码 → 写出视频"这一主流程展开。整个推理管线在 hyvideo/inference.py 中以 inferrence 函数形式串联起来，依赖 DiT 主干、3D 因果 VAE、双文本编码器（CLIP-L 与 LLM）以及 Flow-Matching 调度器协同工作。资料来源：hyvideo/inference.py:1-50

模型权重遵循非商业友好的 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

推理主流程

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 脚本封装了三种典型部署形态：

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 反馈 torchrun --nproc_per_node=2 启动失败，常见原因是未设置正确的 MASTER_ADDR/MASTER_PORT，或与单机 8 卡环境相冲突，建议先以 --nproc_per_node=1 验证管线再扩容。
• CUDA 库版本不匹配：Issue #317 指出 libcublas.so 版本低于 12.4.5.8 时推理会崩溃，可通过 pip install nvidia-cublas-cu12==12.4.5.8 并将 LD_LIBRARY_PATH 指向 conda 包目录解决。
• 微调代码缺失：Issue #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）

1. 概述

HunyuanVideo 的核心模型组件是一个完整的视频生成系统，采用了基于 DiT (Diffusion Transformer) 的架构，配合专用的 3D 因果 VAE、文本编码器以及流匹配调度器。整体设计遵循 Stability AI 团队提出的 MM-DiT 框架，并在其基础上进行了视频领域的深度优化。该项目核心目标是提供一个可扩展、高质量的开源视频生成基础模型 资料来源：[hyvideo/modules/models.py]。

2. 视频变分自编码器（Video VAE）

视频 VAE 组件位于 hyvideo/vae/autoencoder_kl_causal_3d.py，采用了 Causal 3D 卷积结构，专为视频数据的时空压缩而设计：

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 实现高效的视频压缩，便于后续扩散模型处理
• 支持缓存（Cache）：使用 self.enable_tiling() / enable_slicing() 等方法以减少显存占用 资料来源：[hyvideo/vae/autoencoder_kl_causal_3d.py]

3. 视频生成变换器（Video DiT）

视频生成的核心变换器定义在 hyvideo/modules/models.py 中，包括 HunyuanVideoTransformer3DModel、MMDoubleStreamBlock 和 MMSingleStreamBlock 三个核心类。架构设计采用多模态双流注意力（MM-DiT），参考了 SD3 和 Flux.1 的设计思路。

3.1 主要配置参数

资料来源：[hyvideo/modules/models.py]

3.2 注意力机制

注意力机制的实现位于 hyvideo/modules/attenion.py，支持多种注意力后端：

• MEMORY_LAYOUT = {"torch": "SDPA", "flash": "Flash Attention"}：根据硬件支持自动选择最优注意力实现
• 变量长度注意力：通过 flash_attn_varlen_func 支持可变长度的序列处理，提高长视频生成效率
• 3D RoPE：使用 hyvideo/modules/posemb_layers.py 中的 apply_rotary_emb 对时间、高度、宽度三个维度分别应用旋转位置编码

3.3 双流与单流块

• MMDoubleStreamBlock：双流块，将文本和视频的潜向量分离处理，在注意力计算后进行调制（Modulation），支持独立的文本和视频特征提取
• MMSingleStreamBlock：单流块，将文本和视频特征拼接后进行联合处理，实现更深层次的跨模态交互

资料来源：[hyvideo/modules/models.py]

4. 流匹配调度器（Flow Matching Scheduler）

流匹配调度器位于 hyvideo/diffusion/schedulers/scheduling_flow_match_discrete.py，基于 Flow Matching 框架，提供了 FlowMatchDiscreteScheduler 和 FlowMatchEulerDiscreteScheduler 两个类。核心特性包括：

• 离散时间步采样：使用 linspace 在 num_train_timesteps 范围内均匀采样时间步
• Euler 离散化：通过 step() 函数实现一步 Euler 积分，将速度场（velocity）转换为潜空间样本
• 支持动态时间步转换：set_timesteps() 方法允许在推理时灵活调整采样步数

@dataclass
class FlowMatchDiscreteSchedulerOutput(BaseOutput):
    prev_sample: torch.FloatTensor

资料来源：[hyvideo/diffusion/schedulers/scheduling_flow_match_discrete.py]

5. 文本编码器

文本编码器模块位于 hyvideo/modules/text_encoder/，使用 CLIP 模型作为文本特征提取器：

• CLIPTextModel：作为主要文本编码器，提取文本的语义特征
• CLIPTokenizer：处理输入文本的 tokenization
• Prompt 重写：通过 hyvideo/diffusion/pipelines/prompt_rewrite.py 中的 LLM 进行提示词重写，将简单的用户输入扩展为更详细的视频描述
• 双文本编码器配置：支持通过 text_encoder_2 配置第二个文本编码器以增强文本理解能力

资料来源：[hyvideo/diffusion/pipelines/pipeline_hunyuan_video.py]

6. 推理流水线

整体推理流水线整合在 hyvideo/inference.py 中，完整流程如下：

graph TD
    A[用户提示词] --> B[Prompt 重写]
    B --> C[CLIP 文本编码]
    C --> D[视频 VAE 编码<br>可选：图像到视频]
    D --> E[DiT 视频生成]
    E --> F[流匹配采样]
    F --> G[视频 VAE 解码]
    G --> H[输出视频]

6.1 关键参数

资料来源：[hyvideo/inference.py]

6.2 图像到视频模式

根据社区讨论 issue #198 和 issue #131，HunyuanVideo 计划支持图像到视频（I2V）模式。该模式将使用初始图像作为条件，通过 VAE 编码后与文本特征一起输入到 DiT 中。

7. 提示词模板系统

提示词模板定义在 hyvideo/constants.py 中，包含两个主要模板：

• PROMPT_TEMPLATE_ENCODE：用于 DiT 编码视频的模板
• PROMPT_TEMPLATE_ENCODE_VIDEO：用于视频编码的模板

模板使用特定的标记（如 <|start_header_id|>、<|eot_id|>）来引导 LLM 进行更细致的视频描述生成。

资料来源：[hyvideo/constants.py]

8. 常见问题与社区反馈

根据社区讨论，以下是用户在使用核心模型组件时经常遇到的问题：

1. 微调代码缺失 issue #302：用户希望获得官方的微调代码以适配自定义数据集（如风格适配、运动调优、领域特定视频生成等）
2. 并行推理问题 issue #249：在尝试并行推理时遇到问题，建议参考 torchrun 多卡配置
3. 图像到视频功能 issue #198 和 issue #180：用户期待图像到视频模型的开源发布

参见

• HunyuanVideo 官方仓库
• HunyuanVideo 图生视频讨论
• 微调代码请求
• Diffusers 框架文档

概述

本页是 HunyuanVideo 项目的运维与排错速查手册，集中整理社区最常关注的四类问题：许可证条款、模型权重获取渠道、与文本编码/提示词模板相关的运行时错误，以及 torchrun 并行推理的失败模式。这些问题在 GitHub Issues 中反复出现，包括 Issue #317 中报告的 CUDA/cuBLAS 依赖问题、Issue #249 中复现的 torchrun --nproc_per_node=2 崩溃，以及 Issue #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。

排查决策流

flowchart TD
    A[出现运行时错误] --> B{是否 CUDA / cuBLAS 报错?}
    B -- 是 --> C[升级 nvidia-cublas-cu12==12.4.5.8<br/>并核对 CUDNN >= 9.0]
    B -- 否 --> D{是否 torchrun 并行推理?}
    D -- 是 --> E[核对 MASTER_ADDR / PORT<br/>与 --ulysses-degree]
    D -- 否 --> F{是否文本编码 / 模板错误?}
    F -- 是 --> G[检查 PROMPT_TEMPLATE<br/>与 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 中方案一致：升级到 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 的 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、#180、#172、#198、#131 持续请求图生视频权重。
• 官方微调脚本：Issue #302 请求仓库提供 LoRA / 全参数微调示例；当前仓库未提供 train.py 等训练入口。
• 多语种 Prompt 改写：prompt_rewrite.py 的 Normal 与 Master 模式已内建中→英翻译逻辑 资料来源：hyvideo/prompt_rewrite.py，但仍依赖外部 LLM 服务，需用户自行配置 endpoint。

另请参见

• ckpts/README.md — 模型下载、目录结构与网络受限时的镜像方案
• LICENSE.txt — Tencent Hunyuan Community License Agreement 完整条款
• 在 GitHub Issues 中以 I2V、fine-tune、torchrun 为关键词可快速定位未解决问题

Pitfall Log / 踩坑日志

项目：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