# 在国产海光 DCU 上跑通腾讯 HunyuanVideo-1.5 视频生成模型 > **背景**：前面分享了 DCU 上部署 MuseTalk 唇形同步模型的经验，那个属于"改口型"的轻量任务。这次挑战的是一个量级完全不同的东西——**腾讯混元 HunyuanVideo-1.5 文生视频模型**。它要从一句文字描述直接生成一段视频，涉及文本编码、LLM 语义理解、视觉编码、文字渲染四大类预训练组件协同，权重链路长、显存压力大。这里把完整踩坑过程记录下来，给做国产算力适配的同学参考。 --- ## 一、HunyuanVideo-1.5 是什么 HunyuanVideo-1.5 是腾讯混元开源的**轻量级文生视频（Text-to-Video）模型**。输入一段 Prompt，输出一段对应画面动态视频。 相比 Sora、Runway 等动辄几十 B 参数的"重量级"方案，它的特点是： * **轻量化设计**：在控制参数量的前提下尽量保住生成质量，对国产卡的显存更友好 * **多模态组件耦合**：不是单一网络，而是文本编码器（byT5）+ LLM 语义编码器（Qwen2.5-VL-7B）+ 视觉编码器（SigLIP）+ 文字渲染模型（Glyph-SDXL-v2）的组合 * **可控生成**：支持分辨率、宽高比、随机种子、CFG 蒸馏加速等参数调节 > 一个实用亮点：它能在生成的视频画面里**渲染真实文字**。比如 Prompt 写"A girl holding a paper with words 'Hello, world!'"，最终视频中女孩举着的纸上会真的出现这行字——这是靠 Glyph-SDXL-v2 组件实现的。 --- ## 二、本次部署的硬件与软件环境 ### 2.1 硬件环境 | 项目 | 规格 | | :---------- | :--------------------------------------- | | CPU | 2× Hygon C86-4G 7490（32 Core，2.0GHz） | | 加速卡 | 8× 海光 DCU Z100（64GB/卡） | | 内存 | 256GB | | 系统/数据盘 | 各 3.6T HDD | | DCU 驱动 | 6.3.30-V1.4.1a | > 视频生成任务对显存和共享内存要求比唇形同步高不少，建议单卡预留 32GB 以上显存、容器 `--shm-size` 设到 16G。 ### 2.2 经过验证的软件版本 | 组件 | 版本 | 说明 | | :------------------------ | :----- | :------------------------------ | | Python | 3.10 | 基础镜像内置 | | diffusers | 0.35.2 | 扩散模型核心库，版本敏感 | | transformers | 4.51.3 | 文本/LLM 编码器依赖 | | loguru | 0.7.3 | 日志 | | imageio / imageio[ffmpeg] | latest | 视频读写与编解码 | | pycountry | latest | 语言代码处理 | | DTK | 26.04 | 海光 DCU 驱动工具链（镜像内置） | > 这些版本是实测可用组合，彼此有依赖约束，不建议随意升级 diffusers / transformers，容易触发 API 不兼容报错。 --- ## 三、容器环境搭建 ### 3.1 拉取镜像 海光官方维护的 DCU 基础镜像已内置 DTK 与 vLLM 运行环境： ```shell docker pull harbor.sourcefind.cn:5443/dcu/admin/base/vllm:0.9.2-ubuntu22.04-dtk26.04-0130-py3.10-20260202 ``` 镜像 ID 为 `f04dd6ead746`，后续创建容器时用。 ### 3.2 启动容器 ```bash docker run -it \ --name modelstest-5 \ --network=host \ --ipc=host \ --shm-size=16G \ --device=/dev/kfd \ --device=/dev/mkfd \ --device=/dev/dri \ -v /opt/hyhal:/opt/hyhal \ -v /data/model/:/models/ \ -v /data/home/fanwh:/workspace/ \ -v /data/scripts/bench:/bench/ \ --group-add video \ --cap-add=SYS_PTRACE \ --security-opt seccomp=unconfined \ f04dd6ead746 \ /bin/bash ``` 各挂载/设备参数的作用： | 参数 | 作用 | | :--------------------------- | :--------------------------------------- | | `--device=/dev/kfd`等 | 暴露 DCU 设备节点，容器才能识别加速卡 | | `-v /opt/hyhal:/opt/hyhal` | 挂载海光驱动运行时库，缺了会找不到设备 | | `--shm-size=16G` | 视频生成中间张量大，共享内存不够会 OOM | | `-v /data/model/:/models/` | 权重持久化到宿主机，避免重建容器重新下载 | > 视频生成容器比一般推理更吃共享内存，遇到 `Bus error` 或进程被杀，先确认 `--shm-size` 是否足够。 --- ## 四、安装 Python 依赖 进入容器后克隆仓库并安装组件： ```shell git clone https://github.com/Tencent-Hunyuan/HunyuanVideo-1.5.git cd HunyuanVideo-1.5 pip install loguru==0.7.3 -i https://mirrors.aliyun.com/pypi/simple/ pip install imageio -i https://mirrors.aliyun.com/pypi/simple/ pip install "diffusers==0.35.2" -i https://mirrors.aliyun.com/pypi/simple/ pip install pycountry -i https://mirrors.aliyun.com/pypi/simple/ pip install "transformers==4.51.3" -i https://mirrors.aliyun.com/pypi/simple/ pip install "imageio[ffmpeg]" -i https://mirrors.aliyun.com/pypi/simple/ ``` > 统一走阿里云镜像，下载稳定。注意 `diffusers` 和 `transformers` 务必锁版本，升级后 `generate.py` 里部分调用签名会变化，直接报错。 --- ## 五、模型权重准备 ### 5.1 各组件及作用 主模型之外还要补齐 4 类辅助权重，缺一不可： | 组件 | 作用 | 来源 | | :---------------------- | :------------------------ | :---------------- | | HunyuanVideo-1.5 主模型 | 视频生成主干网络 | Tencent-Hunyuan | | Glyph-SDXL-v2 | 画面内文字渲染 | AI-ModelScope | | byt5-small | 文本编码器 | google | | Qwen2.5-VL-7B-Instruct | LLM 语义编码器（约 15GB） | Qwen | | FLUX.1-Redux-dev | 视觉编码器（SigLIP） | black-forest-labs | > 如果只做纯文生视频、不需要画面里出文字，Glyph-SDXL-v2 可酌情跳过，其余三个编码器必须齐。 ### 5.2 下载辅助权重 主模型已放在 `/models/Hunyuan/HunyuanVideo-1.5/` 的前提下，补充其余组件： ```shell mkdir -p /models/Hunyuan/HunyuanVideo-1.5/text_encoder/Glyph-SDXL-v2/ # 文字渲染模型 modelscope download --model AI-ModelScope/Glyph-SDXL-v2 \ --local_dir /models/Hunyuan/HunyuanVideo-1.5/text_encoder/Glyph-SDXL-v2/ # 文本编码器 modelscope download --model google/byt5-small \ --local_dir /models/Hunyuan/HunyuanVideo-1.5/text_encoder/byt5-small/ # LLM 语义编码器（体积最大，预留下载时间） modelscope download --model Qwen/Qwen2.5-VL-7B-Instruct \ --local_dir /models/Hunyuan/HunyuanVideo-1.5/text_encoder/llm/ # 视觉编码器 modelscope download --model black-forest-labs/FLUX.1-Redux-dev \ --local_dir /models/Hunyuan/HunyuanVideo-1.5/vision_encoder/siglip/ ``` > 完整权重清单见官方文档：[checkpoints-download.md](https://github.com/Tencent-Hunyuan/HunyuanVideo-1.5/blob/main/checkpoints-download.md)。其中 Qwen2.5-VL-7B 约 15GB，建议在网络稳定时段或离线拷入。 --- ## 六、推理前必须改的一处代码 DCU 适配的 PyTorch 里，`unpad_input` 的返回值个数和原始 CUDA 版不一致，直接跑会报参数不匹配。需要改掉 `hyvideo/utils/flash_attn_no_pad.py`： ```python # 修改前 x_unpad, indices, cu_seqlens, max_s, used_seqlens_in_batch = unpad_input( # 修改后（删掉 used_seqlens_in_batch 这个返回值） x_unpad, indices, cu_seqlens, max_s = unpad_input( # x_unpad, indices, cu_seqlens, max_s, used_seqlens_in_batch = unpad_input( ``` > 这只是去掉一个多余的返回变量，不影响注意力计算逻辑，生成效果无差异。 --- ## 七、启动推理 ### 7.1 推理脚本 run.sh ```bash #!/bin/bash # ---------- 基本参数 ---------- PROMPT='A girl holding a paper with words "Hello, world!"' IMAGE_PATH=none # 纯文本生视频填 none SEED=1 ASPECT_RATIO=16:9 RESOLUTION=480p # 先用 480p 跑通，再上更高分辨率 OUTPUT_PATH=./outputs/output.mp4 MODEL_PATH=/models/Hunyuan/HunyuanVideo-1.5/ # ---------- GPU ---------- N_INFERENCE_GPU=1 # ---------- 速度相关 ---------- CFG_DISTILLED=true # CFG 蒸馏，减少推理步数 SAGE_ATTN=false # DCU 缺 sageattention 依赖，必须关 SPARSE_ATTN=false OVERLAP_GROUP_OFFLOADING=false ENABLE_CACHE=false # DCU 下关缓存最稳 CACHE_TYPE=deepcache ENABLE_STEP_DISTILL=false # ---------- 质量相关 ---------- REWRITE=false # 关提示词重写（需 vLLM，DCU 不可用） ENABLE_SR=false # 先关超分，跑通再说 # ---------- 执行 ---------- torchrun --nproc_per_node=$N_INFERENCE_GPU generate.py \ --prompt "$PROMPT" \ --image_path $IMAGE_PATH \ --resolution $RESOLUTION \ --aspect_ratio $ASPECT_RATIO \ --seed $SEED \ --rewrite $REWRITE \ --cfg_distilled $CFG_DISTILLED \ --enable_step_distill $ENABLE_STEP_DISTILL \ --sparse_attn $SPARSE_ATTN \ --use_sageattn $SAGE_ATTN \ --enable_cache $ENABLE_CACHE \ --cache_type $CACHE_TYPE \ --overlap_group_offloading $OVERLAP_GROUP_OFFLOADING \ --sr $ENABLE_SR \ --save_pre_sr_video \ --output_path $OUTPUT_PATH \ --model_path $MODEL_PATH ``` ### 7.2 关键参数说明 | 参数 | 含义 | DCU 上的建议 | | :------------------ | :-------------------- | :--------------------------------- | | `--resolution` | 输出分辨率 | 先 `480p`，稳定后再提 | | `--aspect_ratio` | 画面比例 | 支持 `16:9`/`9:16`/`1:1` | | `--cfg_distilled` | CFG 蒸馏加速 | 开 `true`可明显提速 | | `--use_sageattn` | SageAttention | **必须 false**，DCU 无此依赖 | | `--enable_cache` | 推理缓存（deepcache） | **建议 false**，兼容性更好 | | `--sr` | 超分后处理 | 先关，跑通再开 | | `--rewrite` | Prompt 重写 | 依赖 vLLM，DCU 不可用 | | `--seed` | 随机种子 | 固定值可复现 | ### 7.3 运行与结果 ```shell bash run.sh ``` 跑完视频落在 `./outputs/output.mp4`。实测 480p 下画面连贯、文字渲染准确（女孩手中纸张显示 "Hello, world!"），端到端流程打通。 --- ## 八、验证结论 | 维度 | 结论 | | :------- | :----------------------------------------------------------------------------------- | | 硬件适配 | 主干 UNet、byT5 文本编码、Qwen2.5-VL LLM 编码、SigLIP 视觉编码均可在 DCU Z100 上运行 | | 稳定性 | 端到端推理无中断，驱动与软件环境匹配 | | 生成质量 | 480p 画面流畅，画面内文字渲染正确 | | 性能取舍 | 关 SageAttention 与缓存后最稳；CFG 蒸馏可有效缩短推理步数 | **一句话结论**：HunyuanVideo-1.5 能在海光 DCU 上稳定运行，国产算力跑文生视频模型这条路是通的。 --- ## 九、踩坑记录（按出现顺序） | 现象 | 根因 | 处理 | | :------------------------------------ | :------------------------ | :--------------------------------------------------------------------------------- | | 启动报缺文字渲染/编码器权重 | 辅助组件没下全 | 按第五章补齐 Glyph-SDXL-v2、byt5、Qwen2.5-VL、SigLIP | | `unpad_input()`返回值数量不匹配 | DCU 版 PyTorch 返回值更少 | 删掉 `used_seqlens_in_batch`（见第六章） | | byT5 加载报 `mean_resizing`参数错误 | 自定义 byT5 未接收该参数 | `sed -i 's/mean_resizing=False//' hyvideo/models/text_encoders/byT5/__init__.py` | | SageAttention 依赖缺失 | DCU 环境未装该库 | `run.sh`设 `SAGE_ATTN=false` | | 开缓存后异常 | DCU 对 deepcache 兼容一般 | `run.sh`设 `ENABLE_CACHE=false` | | 进程被杀 / Bus error | 共享内存或显存不足 | 调大 `--shm-size`、先用 `480p`、单卡显存留 32GB+ | > 经验上，HunyuanVideo-1.5 上 DCU 主要过三关：**权重下齐**（组件多、体积大）、**改一行 FlashAttention 代码**（第六章）、**关掉不兼容的加速项**（SageAttention / 缓存）。三关过了基本就稳了。 --- ## 参考资料 * 项目仓库：[GitHub - Tencent-Hunyuan/HunyuanVideo-1.5](https://github.com/Tencent-Hunyuan/HunyuanVideo-1.5) * 模型页：[HunyuanVideo-1.5 · 模型库](https://www.modelscope.cn/models/Tencent-Hunyuan/HunyuanVideo-1.5) * 权重清单：[checkpoints-download.md](https://github.com/Tencent-Hunyuan/HunyuanVideo-1.5/blob/main/checkpoints-download.md) --- > 如果这份 DCU 文生视频部署记录对你有用，欢迎留言交流踩坑经历。后续还会补充更高分辨率 / 开启超分的实际表现。 >