本项目为腾讯混元开源的 HunyuanVideo 1.5 打造，提供 ComfyUI 官方原生节点链路、API 格式工作流、LM Studio 视频提示词智能扩写 与 命令行端到端自动化测试脚本，专门针对 Apple Silicon (Mac Studio / M4 Max) 统一内存架构调优。

上游仓库：

• 原版 13B 模型 —— https://github.com/Tencent-Hunyuan/HunyuanVideo
• 本目录对应的 1.5 版本 —— https://github.com/Tencent-Hunyuan/HunyuanVideo-1.5

• 轻量化 DiT 架构：仅 8.3B 参数（相比初代 13B 大幅瘦身），却达到开源视频模型的 SOTA 画质，是本机 (M4 Max / 128GB) 少数真正跑得动的高质量视频模型。
• 双任务统一：同一套框架同时支持文生视频 (T2V) 与图生视频 (I2V)，图生视频额外引入 SigLIP 视觉编码器做起始帧语义对齐。
• 双文本编码器：
  • Qwen2.5-VL-7B —— 主力多模态语义编码器，负责理解自然语言中的空间、动作与镜头描述；
  • ByT5-small-glyphXL —— 字形编码器，专门负责画面中文字 / 中文字形的生成与还原。
• 3D VAE：空间下采样 16 倍、时间下采样 4 倍，因此分辨率必须是 16 的整数倍、帧数必须满足 length = 4n + 1。
• 可选 1080P 超分：官方另有 1080p_sr_distilled 扩散模型 + Latent Upsampler，可把 720p 结果二次放大到 1080p（本目录默认未下载，见第 3 节）。
• MPS 友好：ComfyUI 内核已声明 supported_inference_dtypes = [fp16, bf16, fp32]，fp16 权重可在 Apple Silicon 上原生推理。

ComfyUI/hunyuan_video_1.5/
├── README.md                              # 本说明文档
├── download_models.sh                     # 模型一键下载脚本 (支持 all / t2v / i2v / lite 四种模式)
├── prompt_enhancer.py                     # 视频提示词增强引擎 (LM Studio 客户端 + 规则兜底)
├── hunyuan_video15_test.py                # 命令行端到端测试主脚本
├── workflows/
│   ├── hunyuan_video_1.5_t2v_api.json     # 文生视频 (API 格式, 供脚本直接调用)
│   └── hunyuan_video_1.5_i2v_api.json     # 图生视频 (API 格式)
├── assets/
│   └── i2v_start_sample.png               # 图生视频起始帧示例 (1280x720)
├── tests/                                 # pytest 回归测试 (56 个用例)
│   ├── conftest.py
│   ├── test_workflows.py                  # 工作流结构与连线完整性校验
│   ├── test_cli_runner.py                 # CLI 参数解析 / 参数注入 / 模型前置校验
│   └── test_prompt_enhancer.py            # 帧数换算 / 分辨率对齐 / 扩写降级
└── output/                                # 生成的 mp4、dry-run 工作流与运行报告 (已 gitignore)

说明：ComfyUI 官方内置模板中已自带 HunyuanVideo 1.5 的可视化画布工作流（含 1080P 超分分支）， 位于 ComfyUI 菜单 Workflows → Browse Templates → Video，可直接使用； 本目录提供的是可脚本化调用的 API 格式工作流，二者模型文件完全通用。

所有模型均来自 ComfyUI 官方 repackaged 仓库 Comfy-Org/HunyuanVideo_1.5_repackaged， 与 ComfyUI 内置模板引用的权重完全一致。

cd ComfyUI/hunyuan_video_1.5

./download_models.sh all     # 完整套装 T2V + I2V (~46.5GB, 默认)
./download_models.sh t2v     # 仅文生视频所需的 4 个文件 (~29GB)
./download_models.sh i2v     # 仅图生视频增量 (CLIP Vision + I2V 主模型, ~17.5GB)
./download_models.sh lite    # 额外补 480p 双档模型, 便于快速迭代

# 自定义模型根目录 (默认 /Users/frank/ComfyUI/models)
COMFY_MODELS=/path/to/ComfyUI/models ./download_models.sh all

下载完成后请在 ComfyUI 界面点击右侧菜单的 刷新 按钮以识别新模型。

⚠️ 不要用 hf download CLI 下载本套权重。本机实测 hf CLI 1.9.0 在下载 qwen_2.5_vl_7b_fp8_scaled.safetensors 时会卡死在 256,000,000 字节不再前进 （进程存活但无网络活动），且均速仅约 0.8 MB/s。 本脚本改用 curl 断点续传 + stall 检测 + safetensors 结构校验后，实测稳定跑到 约 6.9 MB/s，完整 46.5GB 套装预计约 2 小时。

另一个常见陷阱：只比对文件大小无法发现损坏。多线程分块下载中断后可能留下 "大小正确但中间有空洞"的文件，ComfyUI 加载时才会报张量解析错误。 本脚本会解析 safetensors 头部 JSON，校验各张量 data_offsets 的末端是否与文件 实际大小严格吻合，从而可靠识别截断与空洞。

因此脚本默认直连 huggingface.co；若你的网络环境直连不稳，可用 HF_ENDPOINT=https://hf-mirror.com ./download_models.sh t2v 切换镜像。

文本编码器 Qwen2.5-VL-7B 官方仅提供 fp8_scaled 与全量 fp16 两个版本， 本目录沿用官方模板的 fp8_scaled（省 7GB 内存），文本编码只执行一次，反量化开销可忽略。

下表取自 ComfyUI 内置模板中 Hunyuan 官方给出的参数说明：

• shift 通过 ModelSamplingSD3 节点注入。ComfyUI 内核中 HunyuanVideo15.sampling_settings 已内置 shift=7.0， 因此 BasicScheduler 直接读取原始 UNET 输出即可得到正确的 sigma 调度（本目录工作流严格遵循官方连线方式）。
• 官方 50 步在 Apple Silicon 上耗时过长，模板与本目录均默认使用 20 步；追求画质可用 --steps 50。

视频生成对提示词的要求与生图不同：必须显式描述"动作随时间如何演变"与"镜头怎么运动"。

prompt_enhancer.py 提供两级能力：

1. LLM 扩写（优先）：调用本地 LM Studio 的 OpenAI 兼容接口，System Prompt 强制模型输出单段英文视频提示词， 必须覆盖 主体细节 / 动作时序 / 镜头语言 / 光影氛围 四个维度，并禁止输出任何前后缀说明。
2. 规则兜底（离线可用）：LM Studio 不可用时，自动降级到内置风格模板库（STYLE_PRESETS）， 把用户描述与风格化的镜头/光照/运动词汇拼装为英文提示词，零显存、零延迟、不中断流水线。

• qwen/qwen3-vl-8b（黄金首选 ⭐）：本机实测单次扩写约 2 秒，词汇分布与 Qwen2.5-VL 文本编码器同源，契合度最高。
• 低显存设备可降级 qwen2.5-3b-instruct，或直接用 --no-enhance 关闭扩写。

# 1. 文生视频 · 快速验证档 (2.5 秒 / 61 帧 / 8 步)
python hunyuan_video15_test.py --desc "雨夜霓虹街道上, 一只机甲猫抖落雨水后缓步向前" \
       --style cyberpunk --duration 2.5 --steps 8

# 2. 文生视频 · 官方画质档 (5 秒 / 121 帧 / 20 步)
python hunyuan_video15_test.py --desc "纸飞机从摩天大楼顶被抛出, 穿过城市峡谷飞向夕阳" --steps 20

# 3. 竖直构图 (9:16, 720x1280)
python hunyuan_video15_test.py --desc "雪山之巅的日出云海" --aspect 9:16 --style nature

# 4. 图生视频 (起始帧自动上传到 ComfyUI input 目录)
python hunyuan_video15_test.py --mode i2v --image assets/i2v_start_sample.png \
       --desc "霓虹城市中的剪影人物缓缓抬起手臂" --duration 2.5

# 5. 480p 提速档 (需先 ./download_models.sh lite)
python hunyuan_video15_test.py --desc "海浪拍打礁石" --model-size 480p --duration 2.5

# 6. Dry-Run: 仅做扩写与工作流装配校验, 不提交生成 (模型未下载也可运行)
python hunyuan_video15_test.py --desc "赛博朋克飞行汽车" --dry-run

1. 服务连通性检查 —— ComfyUI 离线直接报错并给出启动命令；LM Studio 离线仅告警并自动降级扩写。
2. 模型文件前置校验 —— 生成前逐个检查 6 个权重文件是否就位，缺失时直接列出文件名与目标目录，避免浪费一次漫长的排队。
3. 产物落盘 + 运行报告 —— 从 /history/{prompt_id} 解析 SaveVideo 节点产物并用 /view 下载 mp4， 同时写出 output/report_<id>.json（含步数、cfg、shift、种子、耗时、引擎等完整元数据，便于回归对比）。

1. 启动 ComfyUI 后打开 http://127.0.0.1:8188；
2. 菜单 Workflows → Browse Templates → Video，选择 Hunyuan Video 1.5 720p T2V / I2V；
3. 若节点缺模型，工作流内的 Markdown 便签会给出下载链接；
4. Ctrl+Enter 排队生成。

内置模板额外包含 1080P 超分分支与 EasyCache 加速节点（默认处于 Bypass 状态）， 选中节点按 Ctrl+B 即可启用。

workflows/*_api.json 是 API 格式（用于脚本调用），与画布格式不通用。 如需在画布中查看图形化版本，请直接使用内置模板，二者的模型文件与参数完全一致。

在 MPS 后端运行 8.3B 级 DiT 视频模型，耗时由以下因素共同支配：

1. 帧数是线性成本，分辨率是平方成本 EmptyHunyuanVideo15Latent 中 1280x720 的 token 数远高于 848x480（后者约 1/2.3）， 注意力计算量为 $O(N^2)$。先把 --duration 降到 2.5 秒（61 帧）、必要时再降分辨率，收益最直接。
2. 步数直接线性影响总时长 官方 50 步 → 默认 20 步可省 60% 时间；快速验证可压到 --steps 8。
3. VAE 解码是独立瓶颈，且是"全帧一次解码" 121 帧 720p 的解码本身就可能占用数分钟。工作流中另有 VAEDecodeTiled 分支（官方模板默认 Bypass）， 内存吃紧时可改用它。
4. CFG 双前向 cfg=6 且提供负向提示词时，每步需执行正向 + 负向两次完整 DiT 前向。 代价换来了明显的画质与指令遵循度，不建议在 720p 画质档关闭。
5. 内存占用粗算（128GB 完全够用） 主模型 16.65GB + 文本编码器 9.38GB + 字形 0.44GB + VAE 2.52GB ≈ 29GB 常驻， 加上注意力激活与 VAE 解码峰值，建议预留 40–50GB。 ComfyUI 默认的智能显存管理会在文本编码后卸载 CLIP，实际峰值更友好。

# 在仓库根目录执行
python3.13 -m pytest ComfyUI/hunyuan_video_1.5/tests/ -v

覆盖范围（56 个用例，全部离线，不发起网络请求）：

状态：待实跑填充。模型下载完成后由 hunyuan_video15_test.py 实测写入， 每次运行同时会落盘 output/report_<prompt_id>.json。

你最初提供的 https://github.com/Tencent-Hunyuan/HunyuanVideo 是 2024 年 12 月开源的初代 13B 模型， 其权重体积与算力需求都远超本机舒适区（fp16 主模型 25.65GB，且为全注意力架构）。 ComfyUI 目前仍然保留它的节点类型（DualCLIPLoader 的 hunyuan_video 类型、 EmptyHunyuanLatentVideo 节点、hunyuan_video_text_to_video 内置模板）。

本目录聚焦 1.5 版本：参数量减少 36%，画质反而更强，且原生支持 I2V 与 1080P 超分， 是 Apple Silicon 上更现实的选择。若后续确实需要对照初代 13B，可参考 city96/HunyuanVideo-gguf 的 Q4_K_M 量化（7.88GB）版本。