h3lite README

The project's README from github.com/Rimagination/h3lite. As one markdown file: README.md.

H3 Lite

H3 Lite — MiniMax H3 本地部署与视频生成 Skill

License MIT Hosts Codex Route Low VRAM Fast

中文 | English | 参考资料

H3 Lite 是给 Codex、WorkBuddy 等 AI Agent 使用的 MiniMax H3 本地视频生成 Skill。描述想看的画面后,Agent 会根据电脑配置选择 ComfyUI 路线、准备组件、生成带原生声音的视频并检查结果。

模型定位与适用范围

H3 Lite 面向 Windows + NVIDIA + ComfyUI 的低显存本地视频生成。Set A 使用 W4A8 扩散模型和 4B INT4 文本编码器,Set B 使用 4B FP8 文本编码器;两套组件分别对应低显存快速路线和 FP8 兼容路线。

当前已验证的主路线是 Windows + NVIDIA + ComfyUI:

平台 支持状态 指导
Windows + NVIDIA 主支持路线 使用本仓库的 ComfyUI、doctor、planner 和 fastpath。
macOS Apple Silicon 社区路线 可参考 MLX/Metal 的 mmh3turbo。
macOS Intel 未验证 使用托管/API 或其他后端。
Linux + NVIDIA 实验路线 需自行适配路径、节点和运行参数。

Mac 社区路线可参考社区权重包和 uvx mmh3turbo,与本 Skill 的 ComfyUI 组件分开使用。

从需求到成片:四步工作流

复杂视频按“意图路由 → 参考图锚点 → 提示词增强 → 生成与验收”处理。

你的目标 优先路线 关键做法
纯文字描述完整视频 T2VA 先写开场状态,再按时间顺序写动作、镜头和声音。
指定视频第一帧 I2VA 把参考图锁定在 0.00s,只描述后续变化。
指定首尾画面 FL2VA 描述两个锚点之间连续、可见的变化。
多张图/视频/音频参考 Ref2VA 先定义每份素材的角色、保留项和可变项,再写分镜。

人物或多镜头任务先建立锚点卡,固定角色、服装、道具、场景和光线,并为参考素材使用稳定名称,如 Subject A、Picture 1。若 Ref2VA 组件不完整,Agent 会改用 I2VA 或标记为实验路线。

运行时会把锚点卡保存为 anchors.json,并在 manifest.json 记录路径。anchor_qa 用首/中/尾帧检查画面连续性,身份、服饰和构图仍需人工复核。

提示词按“意图 → 场景与角色 → 动作与分镜 → 运镜与声音 → 防漂移约束”增强,最后转换为 H3 的 integrated_multimodal_description、overall_soundscape、non_diegetic_music 字段。

模糊需求可参考 references/prompt-assist.md 补齐场景、动作、运镜和声音。

快速开始

把下面这句话发给 Codex 或 WorkBuddy:

请帮我安装 H3 Lite,并根据我的电脑配置准备本地 MiniMax H3 视频生成环境:
https://github.com/Rimagination/h3lite

如果不想占用系统盘,把目标位置写进同一条消息:

请把 MiniMax H3 和 ComfyUI 安装到 F:\MiniMax-H3;如果那里已经有健康环境就直接复用。

首次安装时间取决于模型大小、网络和硬盘速度。

硬件与路线选择

主支持配置为 Windows + NVIDIA。显存、系统内存、pagefile、磁盘和笔记本功耗都会影响速度。

已验证电脑 GPU 内存 路线
机械革命翼龙 15 Pro RTX 4070 Laptop 8 GB Ryzen 7 8845H / 32 GB LOW_VRAM;Set A T2VA/I2VA,Set B 兼容 T2VA
Windows 10 台式机 RTX 4060 Ti 16 GB i5-13400F / 32 GB Set B;NORMAL_VRAM;T2VA/I2VA

同一套 Set B、兼容工作流、提示词、seed 和 640×352 / 4 步 参数下,RTX 4060 Ti 16 GB 约 77.08 秒,RTX 4070 Laptop 8 GB 约 591.22 秒。

默认使用 fast:4 步、原生音频、640×352。需要更高画质时使用 balanced(6 步)或 quality(8 步)。

Set A 路线对比

下面六条视频都使用红球滚动场景、同一套提示词、Set A 组件和 640×352 / 4 步 / 原生音频,只改变加速节点组合。点击海报打开播放器。

场景:一颗小型哑光红色橡胶球从画面左侧进入,在灰色混凝土地面上向右滚动并滚出画面。

Set A LightX2V 兼容基线
兼容基线
640×352 · 5 秒 · 原生音频
Set A LightX2V Sage
仅 Sage
640×352 · 5 秒 · 原生音频
Set A LightX2V FFN
仅 FFN
640×352 · 5 秒 · 原生音频
Set A LightX2V Block Cache
仅 Block Cache
640×352 · 5 秒 · 原生音频
Set A LightX2V Sol
仅 Sol
640×352 · 5 秒 · 原生音频
Set A LightX2V 全加速
全加速
Sage + Sol + FFN + Block Cache

展示页使用 GitHub Pages 播放器、docs/videos/ 中的 MP4 和仓库内海报;assets-rolling-redball Release 提供这六条路线的下载备份。

常见视频分辨率

分辨率使用 32 的倍数。不指定时默认 640×352;864×480 是 16:9、约 0.4 MP 的常用质量档。

预设用途 实际分辨率 MP
6 GB/8 GB 低显存预览 608×352 0.21
H3 Lite 默认快速路线 640×352 0.23
复杂动作实验档 736×416 0.31
约 480p、16:9 864×480 0.41
约 704p、16:9 1216×704 0.86
约 720p、16:9 1280×704 0.90
约 768p、16:9 1376×768 1.06
约 1080p、16:9 1920×1056 2.03

高分辨率或多镜头任务先用低分辨率预览,再提升画布。

安装与组件

先确定安装位置

方式 位置 适合情况
复用现有环境 已有 <ComfyUI> 保留现有模型和节点
独立目录 如 F:\MiniMax-H3\ComfyUI 推荐,避免占用系统盘或污染项目
当前项目 <项目>\.h3lite\ComfyUI 环境随项目保存

下载前先确定 ComfyUI、模型、节点和输出目录。

只选择一套组件

Set A 与 Set B 各自包含匹配的模型、节点、工作流和清单,选择一套即可:

组件集 已验证起点 分享链接 提取码
Set A RTX 4070 Laptop 8 GB + 32 GB,低显存快速路线 百度网盘 4hri
Set B RTX 4060 Ti 16 GB + 32 GB,FP8 兼容路线;T2VA 也在 RTX 4070 Laptop 8 GB 上验证 百度网盘 1hjx

将包内 models 和 custom_nodes 合并到 <ComfyUI>,导入工作流 JSON,并保留 component-manifest.json。上游文件清单见 references/component-sets.md。

Ref2VA 使用同一组件集。 多图工作流复用 W4A8、文本编码器、ClipProj、双 VAE 和 Turbo LoRA。

手动安装 Skill

打开仓库页面,选择 Code → Download ZIP。解压后把 h3lite 文件夹放入 Codex 的 skills 文件夹,再重新打开 Codex。

第一次验证

安装完成后,先用动作简单、声音明确的 5 秒视频检查整条链路:

请使用 H3 Lite,生成一个 5 秒横屏视频:一颗小型哑光红色橡胶球,在灰色混凝土地面上弹跳两次,然后向右滚出画面。低机位固定镜头,阴冷的多云日光,浅景深、35mm 电影质感;保留两次撞击地面的声音和滚动声,不配音乐。

H3 Lite 红球弹跳视频封面

点击封面打开播放器。

检查视频、动作、画面运动和原生声音,确认后再提高画布或复杂度。

提示词与案例

短视频提示词按三部分组织:

  1. 画面与氛围:主体、环境、光线、景别和风格。
  2. 动作与镜头:按播放顺序描述动作和运镜。
  3. 声音:环境声、动作声、音乐或对白。

“不要对白”保留环境声和动作声;“完全静音”才关闭音频。中文提示词补充主体、环境、镜头、光线和动作。

模糊需求的提示词辅助

模糊需求先补齐主体、动作、运镜和声音;写作模板见 references/prompt-assist.md。

分段提示:金毛幼犬醒来

请使用 H3 Lite 生成一个 5 秒视频:

[0s-2s] 一只金毛幼犬蜷缩着睡在洒满阳光的木地板上,晨光透过窗户倾泻而入,尘埃微粒在空气中漂浮。

[2s-5s] 幼犬慢慢醒来,前爪向前伸展,打了个带着细小吱声的哈欠,然后坐起身,用明亮好奇的眼睛环顾四周,尾巴开始摇晃。

H3 Lite 金毛幼犬视频封面

点击封面打开播放器。

文生视频:星舰跃迁

这个 8 秒 T2VA 案例化用自 MiniMax H3 官方可复现案例,适合观察复杂时序、转场和声音设计:

请使用 H3 Lite,生成一个 8 秒 16:9 视频:昏暗而宽阔的星舰舰桥内,一位短发女舰长背对镜头站在弧形观察窗前,窗外的深紫色星云中排列着庞大的黑色舰队。镜头先缓慢推近,舰队尾部的蓝色引擎逐渐增强;约 3.5 秒时切到舰长面部特写,舰队突然跃迁,强烈白光淹没舰桥,冲击使镜头剧烈震动,舰长踉跄后重新站稳。白光消退,窗外只剩空旷星云,她缓缓闭上眼睛。保留舰桥低沉嗡鸣、引擎蓄能声、跃迁爆响和金属震动声,配以逐渐增强的太空歌剧管弦乐。

H3 Lite 星舰跃迁视频封面

点击封面打开播放器。

图生视频:恶搞之家式客厅换台

下载或直接附上示例首帧,并明确指定它为视频第一帧。这个案例使用原创角色和原创场景,保留美式成人动画的粗黑轮廓、平涂色彩与夸张表情,展示 I2VA 如何在保持人物、服装和客厅构图的同时推进连续动作。

H3 Lite I2VA 恶搞之家式客厅示例首帧

当前示例:864×480 · 5 秒 · 8 步 · Set A 兼容路线 · 原生音频。

请使用 H3 Lite,将我在这条消息中附上的图片作为视频 0 秒的第一帧,生成一个 5 秒横屏视频。保持原创美式成人动画风格、四位家庭成员、服装、客厅布局、电视位置、粗黑轮廓、平涂色彩和中广角固定构图。父亲突然前倾,用遥控器对着电视换台;母亲抱臂翻白眼;儿子和女儿转向父亲,露出夸张的不耐烦表情。电视光轻微闪烁,爆米花碗轻轻晃动;结尾父亲得意地指着电视,其他人一起盯着他。保留电视环境声、遥控器按键声、沙发摩擦声、爆米花碗轻响和短促的非语言反应,配轻快的情景喜剧音乐,不要清晰对白。

H3 Lite 恶搞之家式客厅 8 步视频封面

点击封面打开播放器。

Ref2VA:视频与声音参考

下载 MiniMax 官方案例的参考视频和男声音色参考,分别指定画面、动作、声音和对白的参考来源。

多镜头任务先用低分辨率跑完整分镜,再提升画布;长任务保留每个镜头的日志。

Ref2VA:多张图片参考

把图片按提示词中的顺序重复附加为 Picture 1、Picture 2、Picture 3。建议一张主图负责人物身份,其余图片分别负责场景、服装/道具或姿势;不要让每张图片都要求“完整复制”。对应的命令形式是:

python scripts/h3_fastpath.py `
  --comfyui F:\MiniMax-H3\ComfyUI `
  --prompt-file prompts/ref2va.txt `
  --ref-image identity.png `
  --ref-image scene.png `
  --ref-image wardrobe.png `
  --mode ref2va `
  --resolution 640x352 `
  --profile fast `
  --json

当前 Ref2VA 模板使用 ClipProj resident 模式,显存占用高于 I2VA。提示词和角色分配见 references/prompt-writing.md 与 references/agent-workflow.md。

底层 MiniMaxH3ReferenceToVideo 也支持参考视频和音频,可通过原生工作流接入。

不打开网页也能看进度

Windows 上运行 fastpath 时会弹出原生进度窗口,显示:

窗口读取 ComfyUI 的 WebSocket 节点进度,并显示节点阶段、采样步骤、耗时、ETA、显存、内存、pagefile 和输出路径。默认大小 760×620,内容区带滚动条。节点完成度是结构进度,ETA 使用实测耗时估计。终端-only 运行加 --no-monitor-gui。

窗口直接连接 ComfyUI,关闭窗口不会中断生成。也可以独立打开:

python scripts/h3_monitor_gui.py `
  --comfyui F:\MiniMax-H3\ComfyUI

没有任务时显示等待状态;--once --no-websocket 可用于诊断。

组件完整性与故障排查

H3 Lite 将扩散模型、文本编码器、ClipProj、Turbo LoRA、双 VAE、工作流和节点版本作为一套组件管理。Set B 的关键文件首次使用或发生变化时校验 SHA-256,并缓存结果。

排查顺序:磁盘/pagefile → 模型和节点 → 模型路径/文件名 → CUDA/PyTorch/custom node → OOM/CPU 卸载 → H3 音视频流程 → 提示词和参考素材。灰屏或马赛克优先检查权重、VAE、sigma-shift 和可选补丁。

同机其他 CUDA 程序抢占显存

ComfyUI 队列清空后仍可能让模型常驻显存;Windows WDDM 驱动下 nvidia-smi --query-compute-apps 查不到单进程占用,CUDA 会在“看似空闲”时连几 MiB 的分配都失败,甚至直接访问违例(退出码 0xC0000005)而不是报 OOM。诊断用 python scripts/h3_vram.py --json 查看进程显存、WDDM LUID 和适配器范围;不要把不同适配器的 WDDM 计数器直接当成同一张 CUDA 卡的占用。提交脆弱任务前,用 --check-free-gb <阈值> 作门禁;范围无法比较时脚本返回 2,只有明确接受全局 nvidia-smi 检查时才加 --allow-scope-mismatch。确认对方的队列空闲后才能停止它,空队列不等于模型已释放。详见 references/gpu-contention.md。

视频超分(后处理,Topaz 主推)

本仓库的低显存 H3 路线已验证约 0.5 MP(960x544),这不是模型或所有硬件的全局上限;需要 1080p/4K 时不要把“放大”交给重新生成——超分是明确的、用户主动请求的后处理步骤,不改变生成图。若本机已安装并授权 Topaz Video AI,可按 GUI 中实际可用的 Starlight/Astra Fast、Proteus 或 Rhea 路线处理;不要假设模型名称、安装目录或授权状态。导出前用 scripts/h3_vram.py --json 确认目标适配器范围和显存,再确认 ComfyUI 的 /queue 为空;文件名对不代表权重完整。导出后校验视频、音频、帧数和 videoai=Enhanced using ... 元数据,不要对已增强视频再次超分。

备选(可脚本化、离线):只有在本机先发现并验证 FlashVSR 根目录、Python 环境、CLI 分支/提交和模型包后,才使用 <FlashVSR_ROOT>。调用时必须传入实际的绝对脚本路径(例如 <FlashVSR_ROOT>\ComfyUI-FlashVSR_Stable\cli_main.py),不要在任意工作目录直接运行裸的 cli_main.py,也不要把某台机器的启动器或模型清单当成通用依赖。文档中的 --tile_size 256 --tile_overlap 64 --frame_chunk_size 50 --keep_models_on_cpu 是一组已测案例参数,不是所有显卡的固定答案;输出不含音轨,需用本机发现的 ffmpeg 从源复制。ComfyUI venv + 4x-UltraSharp 也必须使用实际的 <ComfyUI>\models\upscale_models\4x-UltraSharp.pth 和 Python 路径。所有路线跑完都要用 ffprobe 校验 nb_frames、尺寸、帧率和音频流,避免把截断输出误判为画质问题。详见 references/video-upscale.md。

参考资料

License

H3 Lite 使用 MIT License。MiniMax 模型权重、ComfyUI、第三方 custom nodes 和上游资料分别遵循各自许可证。

Star History

Star History Chart

Interactive/live chart: Star History

h3lite (Rimagination/h3lite)

Searching Database…

459 ·GitHub
What is this?H3 Lite is a Codex/WorkBuddy AI agent skill that drives local MiniMax H3 video generation through ComfyUI, picking a hardware-aware route and producing videos with native audio from a description.
Is this a standalone app or a skill for an existing AI agent?It is an Agent Skill — a folder of instructions, scripts and ComfyUI workflows that Codex or WorkBuddy loads to orchestrate local video generation, not a standalone application.
How do I install the skill and get it running?Download the repo ZIP, unzip, and drop the h3lite folder into Codex's skills directory, then reopen Codex; ComfyUI and one of the model component sets (Set A or Set B) must be installed separately in their own folder.
Do I need a specific GPU or OS to run this?Yes — the only fully verified route is Windows with an NVIDIA GPU running ComfyUI; the skill depends on either the Set A (W4A8 + 4B INT4 encoder) or Set B (4B FP8 encoder) component package.
How well does it run on lower-end hardware?Speed varies a lot even at the same settings: the identical Set B workflow at 640x352/4 steps takes about 77 seconds on an RTX 4060 Ti 16GB versus about 591 seconds on an RTX 4070 Laptop 8GB.
Can I use this on Mac or Linux?Only unofficially — macOS Apple Silicon is a community route that points to a separate MLX/Metal port, macOS Intel is unverified, and Linux + NVIDIA is an experimental route requiring manual path and node adaptation.
What resolutions and video lengths does it support?Default fast mode renders 640x352 clips with native audio in 4 steps; documented presets range from a 608x352 low-VRAM preview up to roughly 1920x1056 (1080p), with higher resolutions recommended only after a low-res preview run.
Can it upscale videos to 1080p or 4K afterward?Yes, as a separate post-processing step — finished clips can be handed off to a locally installed Topaz Video AI (Starlight/Astra Fast, Proteus or Rhea) or a FlashVSR CLI setup, but the skill never substitutes upscaling for regenerating the video itself.
Can I track generation progress without opening a web browser?On Windows, the fastpath launcher pops up a native progress window that reads ComfyUI's own WebSocket feed to show queueing, sampling and decoding steps plus elapsed time, ETA, VRAM, RAM and pagefile use.
What kinds of inputs can it turn into video — just text, or images and reference clips too?Four workflows cover different inputs: pure text (T2VA), a locked first frame (I2VA), matched first/last frames (FL2VA), and multi-reference images, video or audio (Ref2VA), each needing differently structured prompts.
Size
31.1 MB
Stars
459
Age
2mo
Commits · 90 Days