madebyollin/taehv

🥮 用于 Hunyuan 视频的微型自动编码器（TAEHV）

是什么 – TAEHV 是一个紧凑的自动编码器，能够将视频帧编码为潜在表示，并以比 Hunyuan Video、MiniMax-H3、Wan-Video、CogVideoX、Open-Sora、LTX-2 等模型自带的原始全尺寸 VAE 快得多的速度和远低得多的 GPU 内存，将这些潜在表示解码回视频。

为何重要 – 全尺寸视频 VAE 通常需要 6–9 GB GPU 内存和数秒时间来解码一段短视频（例如 61 帧的 512×320 视频）。TAEHV 将其降至 <0.5 GB 和 ≈0.5 秒（在 NVIDIA GH200 上），使实时预览、交互式生成或直播处理成为可能。

支持的视频模型

模型	加载的权重标签	示例笔记本
MiniMax H3	`taeh3`	–
Hunyuan Video 1.5	`taehv1_5`（更高画质可使用 `taehv1_5_super`）	`TAEHV1.5_Encoding_Decoding_Demo.ipynb`
Wan 2.1	`taew2_1`	–
Wan 2.2 5B	`taew2_2`（或 `taew2_2_super`）	`TAEW2.2_T2I_Demo.ipynb`
Wan 2.2 14B	`taew2_1`（使用 Wan 2.1 VAE）	–
Qwen Image	`taew2_1`	–
CogVideoX	`taecvx`	`TAECVX_T2I_Demo.ipynb`
Hunyuan Video 1	`taehv`	`TAEHV_T2I_Demo.ipynb`
Open-Sora 1.3	`taeos1_3`	–
LTX-2	`taeltx_2`	`TAELTX2_Encoding_Decoding_Demo.ipynb`
LTX-2.3 / 2.5	`taeltx2_3`（减少模糊可使用 `taeltx2_3_wide`）	–
Mochi 1 & SVD	参见配套仓库 TAEM1 和 TAESDV

仓库在根目录提供 .pth 权重文件，./safetensors 文件夹中提供等效的 .safetensors 文件。TAEHV 会根据检查点名称自动选择正确的架构；若重命名文件，可手动传入 arch_name=。

如何使用

from taehv import TAEHV

# 加载检查点（例如 Hunyuan-Video-1.5）
vae = TAEHV("taehv1_5.pth")

# 编码视频张量（N, C, T, H, W）→ 潜在表示
latents = vae.encode_video(video_tensor)

# 解码回视频
decoded = vae.decode_video(latents)

加速技巧 – 禁用上采样：

vae = TAEHV(decoder_time_upscale=(False, False),
            decoder_space_upscale=(False, False, False))

并行解码 – 在 decode_video 中设置 parallel=True 可一次性处理所有帧（需要更多内存）。
流式处理 – 用于直播或分步处理，请使用 StreamingTAEHV 包装器，解码后立即输出每一帧。参见 流式演示 笔记本。
Diffusers 集成 – 提供了一个小包装器（参见 TAEW2.1_Diffusers_Encoding_and_Decoding_Demo.ipynb），用于适配不同的值范围（[0,1] 与 [-1,1]）和张量布局（NTCHW 与 NCTHW）。

位置

ComfyUI – 主分支（PR #10884）原生支持，以及社区节点：ComfyUI-WanVideoWrapper、ComfyUI-VideoHelperSuite、ComfyUI-Bleh。
stable-diffusion.cpp – 通过 PR #937 添加。
SDNext – 由 vladmandic 集成。
Wan-Video 自我强制演示 – 官方 Wan 2.1 演示中使用。

若在其他地方添加支持，作者欢迎提交 PR 列出。

局限性

画质权衡 – TAEHV 更快更轻量，但未达到原始 VAE 的视觉保真度。作者提供了基准测试（MoViRec）和对比图展示差距。
超重模型 – 部分模型存在更高画质变体（*_super）；它们消耗稍多计算和内存。

入门资源

性能分析笔记本 – examples/TAEHV_Profiling.ipynb（运行时间和内存数据）。
演示笔记本 – 各类 *_Demo.ipynb 文件，展示文本到视频、编码/解码、流式处理和 Diffusers 使用。
模型权重 – 从仓库根目录或 safetensors/ 文件夹下载。
引用 – 提供可直接粘贴的 BibTeX 条目，适用于学术用途。

TL;DR

TAEHV 是一系列中文和开源视频扩散模型的即插即用、轻量级 VAE 替代品。它将解码时间从秒级降至亚秒级，内存从约 8 GB 降至 <0.5 GB，实现实时预览和交互式视频生成，代价是适度的画质下降，可通过可选的“超”检查点缓解。