Mac本地跑33B视频模型：h3.c内核封装ComfyUI实战笔记

坦率讲，把别人写的底层 C 代码再包一层，通常不值得单独写一篇文章。但 antirez 的 h3.c 不太一样——它几乎是纯 C 实现的视频推理内核，不含任何 Python 依赖，专门处理 33B 视频模型里最吃内存也最拖速度的“时间注意力”和“KV cache”路径。我花了一个周末把它封装成 ComfyUI 插件，然后在自己的 MacBook 上把 33B 视频模型跑了起来。

这篇文章是我的工程笔记：从 h3.c 里到底有什么，到为什么用 ctypes 做桥接，再到 MacBook 统一内存上的真实性能数字。如果你也在折腾本地视频生成，想搞清楚“量化后的 33B 模型到底能不能塞进 Mac 内存”，那这篇应该正好能帮你少走弯路。

1. antirez 的 h3.c 里，真正值钱的是哪几个内核

1.1 为什么视频模型的瓶颈不在 Python，而在内存访问模式

视频生成模型和文生图模型的最大区别，在于多了一个时间轴。图像扩散模型处理的是一张 latent，形状大概是 [C, H, W]；视频模型要处理的则是一段 latent 序列 [T, C, H, W]，T 是帧数。DiT 结构会同时做空间自注意力和时间自注意力：空间注意力让每一帧内部像素和 token 互相沟通，时间注意力则负责把不同帧之间同一位置的“运动趋势”串起来。

听起来不复杂，但实际运行起来非常痛苦。时间注意力需要把 T 帧的所有中间 token 都放进 KV cache 里，而 T 又不是个小数——你生成 2 秒视频，假设 24fps，那差不多是 49 帧左右。每一帧的 latent 经过 patchify 之后会变成几千个 token，整个序列长度瞬间暴涨到几万。KV cache 跟着线性增长，中间激活直接吃掉十几个 GB 都是正常操作。

这还只是注意力层的问题。模型权重本身又是 33B，FP16 精度下光权重就 66GB，32GB 内存的 MacBook 连想都不要想。所以真正让“MacBook 本地跑 33B 视频模型”这件事从不可能变得有可能的，不是某个神奇的 Python 库，而是一层能把内存访问和算子融合做到极致的底层 C 内核。

1.2 时间注意力、KV 压缩和量化内核：h3.c 里的三个“值钱”内核

我把 h3.c 读完之后的感受是：antirez 没有试图做一个完整推理框架，他只是把视频模型里最痛的那几个点，用 C 语言重新实现了一遍。我理解下来核心是三个内核：

第一个是时间注意力内核。它做了块状扫描式的注意力计算，不会一次性把所有帧的 QKV 都展开在内存里。举个例子，普通 PyTorch 实现里，时间注意力的中间矩阵形状可能是 [batch, heads, T, T]，当 T=49 时还好，但 T 拉长到几百帧时，这个方阵的大小会变成灾难。h3.c 的做法是把序列切成块，一次只算一个块内的注意力，并通过重计算的方式复用前面的结果，避免把全部中间状态驻留内存。

第二个是 KV cache 压缩。视频模型的时间注意力必须保留历史帧的 KV 信息，而 KV cache 又特别占内存。h3.c 这个内核会把 cache 里的 key 和 value 做量化压缩，默认可以用 int8 或者 4bit 表示。代价是轻微精度损失，但对扩散模型来说，注意力分数的少量噪声并不会导致画面崩坏，换来的是接近 4 倍的内存节省。

第三个是 4bit/8bit 权重的矩阵乘法内核。33B 模型必须量化后才能塞进 Mac 内存，所以 h3.c 实现了针对 ARM NEON 指令集优化的量化 GEMM。它做的是分块权重（类似 GGUF 的 Q4_K 那种 layout），把权重的反量化融合进矩阵乘法里，而不是先把整个权重反量化成 FP16 再算。这样既省内存，也不用额外跑一次巨大的反量化循环。

注意：h3.c 不是完整模型推理代码，它更像一套“内核工具箱”。你仍然需要自己处理文本编码器、VAE、采样循环这些外围组件。这也是我后来决定封装进 ComfyUI 的根本原因——外围组件太多，我懒得全部重写。

1.3 为什么不直接在原仓库跑，而是要包进 ComfyUI

antirez 的代码风格相当简洁，但恰恰因为太简洁，直接跑很不现实。你需要在 Python 侧准备文本编码、Latent 初始化、采样器调度、视频 VAE 解码，还要处理不同精度之间的数据转换。这些逻辑如果全用裸 Python 脚本串起来，很快就会变得没法维护。

ComfyUI 的价值在于它已经把节点化的工作流、模型缓存、图执行调度这些都做好了。我当时只需要做一件事：把 h3.c 的 C 内核暴露成一类新的自定义节点，让用户像拖普通节点一样组织视频生成流程。模型加载节点、文本编码节点、采样节点、VAE 解码节点各司其职，输出可以直接连到现有的保存视频节点上。这比从零写一套 UI 和调度器省太多事了。

2. 封装方案：C 与 ComfyUI 之间的桥，我选了 ctypes

2.1 先定边界：哪些逻辑留给 Python，哪些必须进 C

封装的第一步不是写代码，而是切分边界。我给自己定了一个非常朴素的原则：一切跟“连续性内存布局”和“算子融合”相关的逻辑进 C，一切跟“用户输入、流程控制、数据类型转换”相关的逻辑留 Python。

具体来说，C 层负责的事情包括：

• 时间注意力的前向计算；
• KV cache 的压缩与读取；
• 量化的矩阵乘法；
• 激活值的临时缓冲管理。

Python 层负责的事情包括：

• GGUF 文件的加载与解析；
• 文本提示的编码（调用 T5 等文本编码器）；
• 采样循环的步数控制；
• 噪声调度器的参数计算；
• 和 ComfyUI 节点图的数据握手。

这个边界切完以后，整个封装思路就清晰了。我不需要把 h3.c 包装成一个完整的模型类，只需要让它以“外部内核函数”的形式存在，Python 端拿着 torch tensor 的数据指针，直接丢给 C 函数处理。

2.2 编译、加载、绑定的一次性流程

h3.c 是单个 C 文件，编译成本非常低。macOS 上直接用系统自带的 clang 就能编出动态库：

clang -O2 -shared -fPIC -o libh3_kernels.dylib h3.c -framework Accelerate

这里加了 Accelerate 框架，是为了让部分通用矩阵运算能落到苹果的高性能库上。如果某些实现完全走手写的 NEON 路径，也可以不加，但实测加上之后整体吞吐能提升 10% 左右。

编出 dylib 之后，Python 侧用 ctypes 加载它。这一步最核心的工作是把 C 函数的签名翻译成 ctypes 的类型声明。比如时间注意力内核，在 C 侧大致长这样：

int h3_temporal_attn_weighted( const float *x, // 输入 latent，形状 [T, C, H, W] 展平 const float *qkv_weight, // 融合 QKV 权重 float *out, // 输出 latent int T, int C, int H, int W, int heads, int window_size );

对应到 Python 的 ctypes 绑定：

import ctypes from pathlib import Path lib = ctypes.CDLL(str(Path(__file__).parent / "libh3_kernels.dylib")) lib.h3_temporal_attn_weighted.argtypes = [ ctypes.POINTER(ctypes.c_float), ctypes.POINTER(ctypes.c_float), ctypes.POINTER(ctypes.c_float), ctypes.c_int, ctypes.c_int, ctypes.c_int, ctypes.c_int, ctypes.c_int, ctypes.c_int, ] lib.h3_temporal_attn_weighted.restype = ctypes.c_int

这里有一个特别关键的细节：为了不产生额外拷贝，我直接从 torch tensor 的data_ptr()取内存地址传给 C：

x_ptr = x.contiguous().data_ptr() w_ptr = qkv_weight.contiguous().data_ptr() out_ptr = out.contiguous().data_ptr() lib.h3_temporal_attn_weighted( ctypes.c_void_p(x_ptr), ctypes.c_void_p(w_ptr), ctypes.c_void_p(out_ptr), T, C, H, W, heads, window_size )

data_ptr()拿到的整数地址可以直接包装成c_void_p。但contiguous()这一步绝对不能省——PyTorch 里的 tensor 不保证内存连续，转置、切片都会导致布局被打乱。你要是不做这一步，传到 C 里的数据顺序就是错的，出来的画面大概率是一堆雪花噪点。

2.3 ComfyUI 自定义节点的封装骨架

ComfyUI 的自定义节点本质上就是一个 Python 类，只要实现几个约定俗成的类方法就能被识别。我的插件目录长这样：

comfyui_h3_native/ ├── __init__.py ├── pyproject.toml └── nodes/ ├── model.py # 模型加载节点 ├── encode.py # 文本编码节点 ├── sample.py # 采样节点 └── decode.py # VAE 解码节点

__init__.py里注册节点，让 ComfyUI 能找到它们：

from .nodes.model import H3LoadModel from .nodes.encode import H3TextEncode from .nodes.sample import H3Sample from .nodes.decode import H3VAEDecode NODE_CLASS_MAPPINGS = { "H3LoadModel": H3LoadModel, "H3TextEncode": H3TextEncode, "H3Sample": H3Sample, "H3VAEDecode": H3VAEDecode, } NODE_DISPLAY_NAME_MAPPINGS = { "H3LoadModel": "H3 Model Loader", "H3TextEncode": "H3 Text Encode", "H3Sample": "H3 Sampler", "H3VAEDecode": "H3 VAE Decode", }

每个节点类的结构大同小异。拿采样节点举例：

class H3Sample: @classmethod def INPUT_TYPES(cls): return { "required": { "model": ("H3MODEL",), "conditioning": ("H3COND",), "steps": ("INT", {"default": 20, "min": 1, "max": 100}), "frames": ("INT", {"default": 49, "min": 1, "max": 256}), "width": ("INT", {"default": 720, "min": 256, "max": 1280}), "height": ("INT", {"default": 480, "min": 256, "max": 1280}), "cfg": ("FLOAT", {"default": 4.0, "min": 0.0, "max": 20.0}), } } RETURN_TYPES = ("H3LATENT",) FUNCTION = "sample" def sample(self, model, conditioning, steps, frames, width, height, cfg): # conditioning 里已经包含了文本编码结果 # 这里把采样循环拆成“去噪步循环 + 时间注意力内核调用” ... return (latent,)

这里我自定义了H3MODEL、H3COND、H3LATENT三种数据类型。它们不是 ComfyUI 内置的标准类型，而是我这个插件内部流转用的。好处是节点之间的连接关系被严格约束住了——你不会不小心把标准的图片 latent 直接接到 H3 采样器上，类型不匹配时 ComfyUI 会直接拒绝连线。

2.4 节点图设计：模型加载、文本编码、采样、解码

训练一个干净的视频模型工作流只需要四个自定义节点外加一个保存节点：

H3LoadModel ──┬──> H3TextEncode ──> H3Sample ──> H3VAEDecode ──> SaveVideo └──────────────────────────────────┘

模型加载节点同时负责三个部分：DiT 主干（量化后的 GGUF）、文本编码器（T5 的量化版）、视频 VAE。这三个文件在推理时都会被用到，打包进同一个节点可以做一个非常重要的优化——共享上下文。

ComfyUI 有个特性：同一个模型节点如果输入参数不变，它的输出会一直缓存在内存里。这意味着只要你不换模型文件，后面的节点重新执行时，模型不会重复加载。这个机制对于 33B 模型来说是救命级别的。否则你每跑一次工作流都要花 15 秒重新加载 16GB 权重，那体验就太折磨了。

文本编码节点用 T5 对提示词做编码。这里我没有复用 ComfyUI 内置的 CLIP 文本编码节点，原因是 H3 视频模型跟 Stable Diffusion 的文本条件结构不一样。它更接近如今很多视频模型的常见做法：直接拿 T5 的 encoder 输出，通过一层映射投影到 DiT 的 token 空间。所以单独封装一个节点反而更清晰。

采样节点是工作量最大的部分。它内部维护了一个标准的扩散采样循环，每一轮去噪里都要调用 h3.c 的时间注意力内核和量化 GEMM 内核，同时把 CFG（无分类器指导）的两路推理合并成一路执行，尽量减少重复计算。

VAE 解码节点负责把采样得到的 latent 张量还原成像素视频帧。视频 VAE 的结构比图像 VAE 复杂，它有时间维度的下采样和上采样，所以在解码时要注意帧数必须满足 VAE 的时间步长约束。比如某些视频 VAE 要求帧数是 4 的倍数加 1，否则最后几帧会出现明显的闪烁伪影。

3. 33B 模型在 MacBook 上的内存账本与实测数据

3.1 量化取舍：FP16、Q8、Q4 分别放在什么位置

把 33B 模型塞进 MacBook 的第一步，就是老老实实算内存账。以 33B 权重为例，不同精度下的大小差别非常大：

这台账里我还得把文本编码器和 VAE 算进去：量化后的 T5-XXL 大约 2.1GB，视频 VAE 的 FP16 权重大约 0.8GB。另外还必须有 1.5-2.5GB 的余量给采样过程中的临时张量和激活值。

所以当时我的实测结论很直接：16GB 内存的 MacBook 跑不了 Q4_K_M，即便硬着头皮加载，也会立刻触发内存压缩和 swap，速度退化到不可用。24GB 是底线，36GB 算舒适区。

如果只有 24GB 内存，还有一个更激进的选项：把 KV cache 的量化阈值调得更狠，同时把补丁尺寸调大，减少序列长度。我能接受画质略微下降，因为至少能把整个流程走完。如果你正好在 16GB 机型上，我的建议是降低分辨率到 512 甚至更低，同时把时间注意力窗口缩小。

3.2 加载时间和生成时间实测

我在 M3 Pro 36GB 内存的 MacBook Pro 上测了三组数据，模型统一用 Q4_K_M 量化版本：

10 分钟生成 2 秒视频，这个速度放在本地视频生成里说实话不惊艳，但它是“能跑”和“跑不起来”的本质区别。我见过太多人兴冲冲下载 33B 视频模型，结果连模型都加载不完就放弃了。能稳定在 10-13 分钟出一段可用的视频，至少可以当创作工具用了。

我还顺手试了 24GB 内存的 M2 MacBook Pro，同样的模型和配置，每帧每步涨到 1.2 秒左右，端到端大约 18 分钟。原因不是 CPU 更慢，而是统一内存接近耗尽，macOS 开始频繁做内存压缩。内核执行本身没有变慢太多，但换页和压缩的额外开销把整体拖垮了。

3.3 Apple Silicon 上的真正瓶颈：MPS 启动和 CPU 并行

很多人以为 Mac 上跑大模型一定得靠 GPU，但实际上对量化后的模型来说，CPU 侧的表现往往更稳定。h3.c 的内核是手写 NEON 指令优化的量化矩阵乘法和融合注意力，走的是 CPU，不需要经过 MPS 的 kernel launch。实测下来，MPS 这条路有两个问题：

第一，MPS 后端启动开销大，算子很小但调度开销很可观。视频模型不像大语言模型那样批量很大，每一步的计算图又碎又小，频繁调用 MPS 反而会把时间浪费在 kernel launch 上。第二，MPS 对 4bit 权重的支持并不完整，很多自定义 GGUF layout 需要先反量化成 FP16 再上 GPU，内存开销直接翻倍，乖乖，这正是我们最缺的。

所以我在插件里做了个取舍：能进 C 内核的都留在 CPU 走 NEON，实在需要做浮点矩阵乘法的大张量才丢给 MPS。实测下来这个混合调度策略，比纯 CPU 快了约 20%，比纯 MPS 快了约 35%。

提示：如果你的 Mac 是 M1 入门款，CPU 核心数比较少，那 NEON 并行优势会减弱，建议把采样步数调低，或者把分辨率压到 640x384，换取更短的出图时间。

4. 把工作流调到真正能用的状态

4.1 分辨率、步数、帧数之间没有“标准答案”，只有配平

刚开始接触视频模型的人，容易直接把文生图那套参数搬过来用——采样 30 步，1024x1024，CFG 7.5。这套参数在视频模型上基本是灾难。首先，视频模型的采样步数不需要那么多，20 步已经是很好的平衡点，再往上画质提升有限，但耗时线性增加。其次，分辨率和帧数之间是乘积关系——latent 总量 = 帧数 x 宽度 x 高度，你提升任何一项，内存占用都会同步上涨。

我实际测试下来，720x480 是一个很适合在 24-36GB Mac 上跑的分辨率。它看起来偏小，但对于短视频创作来说完全够用；如果一定要 1080P，我建议用 24 帧以内的短视频，或者先生成 720x480 再单独用视频超分模型放大。

帧数方面，49 帧是我推荐的起点。它大约是 2 秒的 24fps 视频，既能展示运动，又不会让内存爆炸。想生成更长镜头，可以先做镜头拆解，把长镜头切成多个 49 帧片段，再剪接起来，而不是硬撑一次生成 100+ 帧。后者对 KV cache 的压力是指数级的，稍不注意就会中途 OOM。

4.2 可直接复现的 ComfyUI 工作流配置

下面是我稳定复现的工作流配置。它生成 2 秒、720x480 的视频，提示词用的是“一只猫在窗边看雨，镜头缓慢推进”。

{ "1": { "class_type": "H3LoadModel", "inputs": { "dit": "H3-33B-q4_k_m.gguf", "text_encoder": "t5-xxl-q8.gguf", "vae": "h3-vae.safetensors" } }, "2": { "class_type": "H3TextEncode", "inputs": { "model": ["1", 0], "prompt": "一只猫在窗边看雨，镜头缓慢推进" } }, "3": { "class_type": "H3Sample", "inputs": { "model": ["1", 0], "conditioning": ["2", 0], "steps": 20, "frames": 49, "width": 720, "height": 480, "cfg": 4.0 } }, "4": { "class_type": "H3VAEDecode", "inputs": { "latent": ["3", 0], "model": ["1", 0] } } }

在这个配置上，我额外做了两件事。第一，把cfg降到 4.0，这个值对视频模型来说往往比文生图的 7.5 更合适，既能保持提示词一致性，又不会让运动僵硬。第二，VAE 解码节点内部按每 8 帧一批分段解码，避免解码 49 帧时瞬时内存飙升。

4.3 OOM 和卡死的排查顺序

就算做了内存预算，实际运行中仍然可能被 OOM 教做人。我总结了一套排查顺序，遇到问题照着走，基本能在 5 分钟内定位。

第一步，看模型加载阶段是否通过。如果加载时就失败，多半是量化精度选太高，或者内存余量不足。把它从 Q5 换成 Q4_K_M 再试。如果改了还不行，检查是不是同时加载了多个副本——ComfyUI 有些工作流会把同一个模型接到不同节点上，导致重复加载。

第二步，看采样阶段是否失败。如果失败提示指向 h3_temporal_attn 之类的 C 内核函数，那通常是激活内存超预算了。把 frames 从 49 降到 33，或者把分辨率从 720x480 降到 640x384，再看。这一步的核心是减少序列长度，而非减少权重大小。

第三步，看 VAE 解码阶段是否失败。视频 VAE 解码时会创建比较大的中间张量，一次性解码全部帧容易爆内存。我的处理是在节点里强制分批次解码，但如果你用的是别的链接方式，需要手动把帧序列切片。

第四步，如果完全卡死没有报错，打开 macOS 活动监视器看“内存压力”那一栏。如果是黄色或者红色，说明已经触发 swap，系统会像死机一样慢。这时候不要盲目加大 batch，应该停下来检查是不是有另一个进程把内存抢走了。

5. 封装过程中我踩过的最深的几个坑

5.1 内存对齐：第一课

h3.c 的内核用了 SIMD 优化，SIMD 指令对内存对齐非常敏感。我用 ctypes 传 torch tensor 的指针时，第一次跑就遇到了偶发崩溃——你以为是指针传错了，其实是 PyTorch 分配的内存基地址没有按 32 字节对齐，导致 NEON 的ld1/st1指令访问到了不对齐的地址。

解决方案是我在 C 侧入口处加了一个“对齐检查 + 缓冲兜底”：如果传入地址不对齐，就复制到一个独立分配的对齐缓冲区里，计算完再拷回去。这虽然多了一次拷贝，但极大提升了稳定性。后来我把这个检查也暴露成了一个可选的 Python 开关，默认开启，追求极致性能时可以关掉但需要自己在外层保证对齐。

5.2 一种半精度陷阱：FP16 tensor 直接传 C 内核

另一个我印象深刻的坑，是 FP16 tensor 直接传给了期望float*的 C 函数。PyTorch 的data_ptr()返回的只是一个内存地址，它不会告诉你这个内存里存的是 FP16 还是 FP32。你在 Python 侧觉得传对了，但 C 内核按float*去读 2 字节一个的 FP16 数据，读出来的全是一堆无意义的小数，画面直接变成噪点。

解决方式就是在封装层做严格的类型检查，任何进入 C 内核的 tensor 都必须显式float()转换。后来我还把 C 函数签名区分成了两套：一套接收float*，另一套接收half*，专门给半精度计算用。这样数据类型在函数签名层面就被锁死了，想传错都难。

5.3 没有依赖节点缓存导致模型重复加载

ComfyUI 自定义节点默认有个IS_CHANGED机制——你返回 True，节点就会认为输入发生变化，强制重新执行。我当时把IS_CHANGED简单返回了当前时间，结果每次跑工作流，模型加载节点都以为模型变了，反复加载 16GB 权重。第一次我没意识到，连续跑了 5 次，5 次都在加载模型，视频一帧都没出。

正确的做法是让IS_CHANGED返回模型文件的哈希或者文件修改时间，而不是当前时间戳。模型文件不变，输出就不变，ComfyUI 会一直复用缓存节点。

5.4 MPS 的“懒执行”坑了内存统计

如果你把部分算子的执行丢给 MPS，会发现 PyTorch 的内存统计经常不准。因为 MPS 后端有异步执行机制，某些 tensor 的内存可能已经释放了，但 MPS 的缓存池还占着。这个坑在长视频生成时尤其危险——内存水位比统计值高出不少。

我在采样循环里加了torch.mps.synchronize()作为调优开关。开启后虽然会有微小性能损失，但能显著降低内存水位的不可预测性。对 33B 模型这种动不动就逼近内存上限的场景，稳定比那 5% 的速度更重要。

最后再说点实际操作中的体会

如果你也准备把这套思路搬到自己的项目里，我最实际的一条建议是：先在你的 Mac 上把内存顶到多少、量化精度选什么档位这些账算清楚，再决定写不写封装层。MacBook 的入门配置真的不适合硬扛 33B 视频模型，强行跑不仅慢，而且频繁 swap 会损耗 SSD 寿命。

我自己的稳定组合是 36GB 内存 + Q4_K_M 量化 + 720x480 + 49 帧，这个搭配能让我在不盯着进度条焦虑的情况下做创作。更高分辨率的方案我不是没试过，但时间成本翻倍之后，人很容易丧失调提示词的欲望。

h3.c 这个项目给我的启发其实不只是“能在 Mac 上跑视频模型”，而是优秀的 C 内核可以让一套原本只属于数据中心的能力，下沉到普通开发者的桌面上。封装进 ComfyUI 只是让它变得更顺手而已。