上个周末我干了一件在外人看来挺拧巴的事：把 antirez 的一个单文件 C 程序 h3.c，封装成了 ComfyUI 的自定义节点，然后在自己的 MacBook 上把一个 33B 参数的视频生成模型完整跑了起来。整个过程完全在本地，没有云端参与。写这篇工程笔记，是想给同样在 Apple Silicon 上折腾视频模型的人一条能直接抄的路径：h3.c 这样一个体量很小的 C 工具，怎么一步步变成 ComfyUI 里可拖拽的插件，33B 模型又如何靠量化、缓存和精细的内存预算在本地站稳脚跟。你若也想在 Mac 上真正摸到视频模型，而不是只看各种云上跑分截图，这篇东西应该比某些官方文档更能救你。
1. 为什么在 MacBook 上跑 33B 视频模型值得折腾
1.1 能跑和跑得舒服是两码事
先说结论：33B 视频模型在 MacBook 上跑起来不是梦，但从“能跑”到“能稳定出片”，中间隔着大量内存和调度问题。
视频生成模型这几年迭代很快，很多开源权重都往 30B 以上走。这个量级的模型放在过去，基本意味着需要多卡数据中心才能推理。而到了 Apple Silicon 这一代 MacBook，统一内存架构让笔记本可以一次性容纳几十 GB 的权重文件，加上 Metal 的 MPS 后端也能承担大部分矩阵运算，理论上就有了本地跑大模型的基础。
但“基础”和“可用的工作流”差得很远。ComfyUI 本身是张量流调度器，节点与节点之间传递的是大张量，一次视频采样会产生多个中间 latent，还要经过 VAE 解码、文本编码、跨帧 attention 等步骤。任何一个环节出现峰值内存暴涨，macOS 就会开始疯狂用交换空间，然后你看到的就是风扇起飞、采样进度条卡死、最后 kernel panic。
我手上这台是 M2 Max 64GB 的 MacBook Pro，很多人以为 64GB 跑 33B 模型绰绰有余，实际上如果直接把 fp16 权重塞进去，还没开始采样就会撞到内存墙。视频模型比 LLM 更吃内存，因为 LLM 的 KV cache 是线性增长的，视频模型则要同时维护文本嵌入、帧序列 latent、VAE 缓存和 cross-attention 中间结果。
1.2 为什么非要和 33B 较劲
有人可能会问：本地跑个 7B、14B 不香吗？为什么非要盯着 33B？
因为生成质量真的不一样。33B 级别的视频模型在动作连贯性、物体一致性、光影变化上，明显比小参数量版本高出不少。特别是文字描述里包含多个物体交互时，小模型容易出现“缺手指、多尾巴、面部漂移”这类问题，大模型虽然也会有，但概率低很多。
另外一个更现实的原因是生态。现在 ComfyUI 的工作流大多按模型规格组织，33B 模型对应的 LoRA、ControlNet、提示词模板都是围绕这个档位设计的。你如果长期用小模型，会在社区资源上处处受限。与其绕路，不如直接把目标定为 33B，然后解决工程问题。
所以我这次的立场很明确：默认目标是 33B，MacBook 只是载体，一切封装工作都围绕“如何在有限内存里把模型托住、把采样继续下去”展开。
1.3 本地跑通的实际收益
本地跑模型不只是为了省云费用。对做创作的人来说，本地推理意味着帧序列、提示词、参数都可以反复调，不用担心 API 限流，也不用把素材传给别人。对做工程的人来说，本地能跑通 33B，意味着你可以在这个基础上做推理优化、量化测试、自定义采样策略。
另外，MPS 后端现在虽然还不够成熟，但 Apple 的 uni 内存带宽在跑大 batch 时反而有优势。N 卡用户经常因为显存不足把 batch 拆得很碎，而 MacBook 的 unified memory 可以一次性容纳较大的帧 batch，这在视频推理场景里是实打实的福利。
2. antirez 的 h3.c 到底帮我解决了哪部分痛点
2.1 一段被低估的 C 代码
先给不了解 antirez 的读者交代一下背景。antirez 是 Redis 的原作者，也是那种“喜欢把什么东西都写成极简 C 代码”的开发者。他的很多小项目都遵循单文件风格，h3.c 就是其中之一。
h3.c 从内容上看并不是一个复杂的框架，它本质上是提供了一套紧凑的哈希索引和路由逻辑。我在最初看这个文件时想到的是：ComfyUI 的视频生成流程中，大量的时间其实没有被花在真正的模型推理上，而是花在了 Python 层反复分配张量、做索引、做条件切换。比如视频模型的 conditioning 可能有几千个嵌入 token，跨帧使用时还要做 token 级别的重排和筛选。如果用纯 Python 写，每个节点都会复制一遍数据，内存峰值在这些地方悄悄涨上去。
h3.c 的定位就是把这些高频、低逻辑复杂度的操作下沉到 C 层，通过 flat buffer 一次性算完，只返回一个紧凑的索引结果。这正是视频采样流程里需要的东西：帧与帧之间做内容路由时，不需要把整个大张量搬来搬去。
2.2 我具体用 h3.c 做的逻辑
在我的场景里，h3.c 被用来处理视频帧的相似度聚合。视频模型在采样阶段会生成多个 latent 帧，如果每一帧都完整参与所有后续计算，内存消耗是灾难性的。合理做法是先对帧序列做一次快速索引，把内容相近的帧分组，然后在后续 attention 计算中复用共享的表示。
h3.c 提供的哈希函数和路由函数正好能嵌入这个流程。我把 latent 特征传入 C 函数，它会算出一组 token 索引，告诉上层哪些帧可以共享计算。这个结果只是一个整型数组，不会给 Python 侧增加额外的张量负担。
uint32_t h3_route(const float *feat, uint32_t nfeat, uint32_t dim, uint32_t k, uint32_t *out_idx);这个函数签名很直白：传入特征数组，返回最多 k 个索引。C 侧内部不开临时数组、不使用堆分配，所有中间变量都放在栈上。如果你写过 Python 层的大循环，就会知道这种 abs 不搞分配的风格有多舒服。
2.3 为什么不用 PyTorch 现成函数
ComfyUI 内部有很多 torch 操作可以完成索引和筛选，比如torch.topk、torch.cat，乍看没必要引入 C 代码。但问题在于，这些操作在 MPS 后端上会把数据从 CPU 搬到 GPU，算完再搬回来，来回两次 PCIe 开销。在 MacBook 上虽然是统一内存，但 MPS 的数据缓冲仍然有同步成本，小操作频繁调用时，这个成本会被放大。
更重要的是，torch 的索引操作会创建临时张量，临时张量的生命周期由 Python 的引用计数管理，无法精确控制释放时机。视频采样本来就紧张，一旦临时张量叠加，内存峰值可能瞬间上涨几个 GB。
h3.c 这种 C 方案直接在 CPU 侧跑完，返回的只是索引数组。上层拿到索引后，可以把对应的 latent 张量重新组织，但不会产生多余的中间张量。这种“把数据留在 C 层处理，只把决定交给 Python”的套路，是我在采样流程里最爱用的一种优化手段。
3. 封装成 ComfyUI 插件的完整链路
3.1 目录结构与编译
先交代一下最终的插件目录结构：
custom_nodes/comfy-h3cache/ __init__.py nodes.py lib/libh3.dylib vendor/h3.ch3.c 源文件放在 vendor 目录，编译产物放在 lib 目录。这样做的目的是把源码和二进制分开，升级 h3.c 时直接重新编译，不需要动 Python 代码。
在 macOS 上编译很简单，Apple 的 clang 已经自带：
cd comfy-h3cache/vendor cc -O3 -fPIC -shared -o ../lib/libh3.dylib h3.c -arch arm64-arch arm64是必须的，如果你机器是 Apple Silicon，想要避免链接时出现 x86_64 架构问题，就显式指定。编译完后可以用file命令确认：
file ../lib/libh3.dylib输出里应该能看到arm64字样。这个步骤虽然基础，但不少第一次接触 ctypes 封装的人会卡在这里，因为默认编译器可能会生成多架构二进制，ComfyUI 在加载时反而不知道该用哪个 slice。
3.2 用 ctypes 加载动态库
ComfyUI 节点是纯 Python 文件，加载 C 库最直接的方式就是 ctypes。注意路径别用相对路径，ComfyUI 在加载自定义节点时工作目录不一定是仓库根目录，踩过一次坑之后就学乖了，用os.path.dirname(__file__)拿绝对路径：
import ctypes import os LIB_PATH = os.path.join(os.path.dirname(__file__), "lib", "libh3.dylib") lib = ctypes.CDLL(LIB_PATH)光加载还不够，因为 ctypes 默认不知道函数的参数类型和返回类型。两个函数调用之间如果类型不匹配，轻则TypeError，重则直接段错误。所以，函数使用前一定要手动声明：
lib.h3_route.argtypes = [ ctypes.POINTER(ctypes.c_float), ctypes.c_uint32, ctypes.c_uint32, ctypes.c_uint32, ctypes.POINTER(ctypes.c_uint32), ] lib.h3_route.restype = ctypes.c_uint32argtypes和restype的声明顺序一个都不能少。我最初漏了restype，结果函数返回的索引全是垃圾值，排查了很久才发现 ctypes 默认返回值是c_int，而 C 侧返回uint32_t在高位字节会有符号扩展问题。
3.3 节点类与输入输出设计
ComfyUI 节点的标准结构是定义INPUT_TYPES、RETURN_TYPES和FUNCTION。我设计的节点接收一个CONDITIONING和一个控制参数top_k，输出经过索引路由后的CONDITIONING：
class H3Routing: @classmethod def INPUT_TYPES(cls): return { "required": { "conditioning": ("CONDITIONING",), "top_k": ("INT", {"default": 256, "min": 1, "max": 4096}), } } RETURN_TYPES = ("CONDITIONING",) FUNCTION = "route" CATEGORY = "video/h3" def route(self, conditioning, top_k): # Convert conditioning tensor list to flat float buffer # Call h3_route, get indices # Reorder conditioning based on indices ...签名设计成输入 CONDITIONING 输出的还是 CONDITIONING，好处是可以直接插在现有的采样工作流中间，不用改动上游的模型加载节点。你只需要在 Text Encode 和 KSampler 之间插入这个节点，采样器拿到的就是经过路由重构的条件信息。
top_k是一个很有意思的参数。它控制保留多少 token。调小了，内存更稳但生成质量可能下降；调大了，保留的信息多但内存压力上升。我默认设 256，这个值在大部分视频提示词下表现稳定。
3.4 注册节点与修改init.py
自定义节点的__init__.py里需要做节点注册：
from .nodes import H3Routing NODE_CLASS_MAPPINGS = { "H3Routing": H3Routing } NODE_DISPLAY_NAME_MAPPINGS = { "H3Routing": "H3 Cache Routing" }这里有个细节：NODE_DISPLAY_NAME_MAPPINGS的 key 必须和NODE_CLASS_MAPPINGS一致，我见过有朋友把显示名 key 写成中文字符串，结果节点列表里出现两个同名元素，一个能加载、一个报错，排查起来特别恼火。
注册完重启 ComfyUI，刷新页面后在节点列表里搜索 “H3” 就能看到新节点。如果节点没出现，多半是 Python 语法错误或动态库没加载成功，查看控制台输出比看浏览器界面更直接。
4. MacBook 上把 33B 视频模型抬起来的实操参数
4.1 模型下载与权重格式选择
跑 33B 视频模型的第一步是拿到权重。社区里常见的有两种：原版.safetensors和量化后的 GGUF 格式。原版权重精度高，但体积很大，33B 模型直接下 fp16 大约需要 66GB，我的 64GB 机器连加载都费劲。
我的第一选择是从 Hugging Face 拉权重，不同格式对照如下：
| 方案 | 权重体积 | 采样缓存需求 | 推荐度 |
|---|---|---|---|
| fp16 原版 | 约 66GB | 超过 80GB，推荐 128GB 机器 | 低 |
| fp8 量化 | 约 36GB | 64GB 勉强可跑，但建议关掉其他应用 | 中 |
| GGUF Q4/K 量化 | 约 19-21GB | 32GB 可跑，64GB 很宽松 | 高 |
| GGUF Q2/Q3 量化 | 约 12-15GB | 16GB 可尝试，画质损失明显 | 低 |
我最后用的是 GGUF Q4_K_M 这档量化，权重解压后实际占用约 20GB，加上采样缓存和 VAE 解码，整机内存峰值大约在 45GB。这个数字对 64GB 的 MacBook 来说还有余量，不会触发严重的 swap。
如果是第一次下载，建议直接用huggingface-cli或者git lfs拉取。网络和磁盘都要提前准备好，33B 模型即便量化后也是 20GB 级别的下载量，不要用浏览器下载，断点续传会让你崩溃。
4.2 采样分辨率和帧数取舍
视频模型对显存的需求，除了权重本身，另一个大头是 latent 的分辨率和帧数。很多人一上来就设置 720p、81 帧，结果采样器刚开始就跑 OOM。
我实测下来的安全线是：分辨率 512x512，帧数 16-24 帧。在这个范围内，M2 Max 64GB 配合量化权重可以稳定出片。如果你坚持要 81 帧，建议分辨率降到 448 或者把 batch size 拆到 1，否则内存峰值容易突破 60GB。
这里面有个关键概念：视频模型的实际采样分辨率不是最终输出分辨率，而是 latent 分辨率。VAE 会把画面压缩到 1/8 左右的空间尺寸，但解码阶段仍需要把完整分辨率恢复到像素空间。所以输出 512x512 的视频，latent 其实是 64x64，解码时每一步也要在 512x512 的尺度上操作。这样算下来，视频生成的内存开销比静态图像生成高很多，这是因为帧之间还有时序注意力。
4.3 MPS 后端和 CPU offload 的分界线
MacBook 上跑 PyTorch 模型，默认是走 MPS 后端。MPS 已经支持了大部分常用算子，但视频模型里有些操作还没有原生实现，比如某些版本的 flash attention、部分自定义归一化层。遇到这种情况，PyTorch 会尝试回退到 CPU，再把结果搬回 GPU，这一步最容易导致瓶颈。
我的做法是设置环境变量，让 MPS 的算子回退更果断：
export PYTORCH_ENABLE_MPS_FALLBACK=1但单纯靠环境变量不够，还需要在采样设置里控制设备分配。ComfyUI 的采样器中，建议把部分文本编码器和 VAE 解码放在 CPU 侧执行，只把 DiT 主干留在 MPS。理论上所有东西都可以塞进 GPU，但 MPS 的统一内存分配策略有时会把可释放内存拖到很晚才释放，CPU offload 反而能让内存波动更平滑。
4.4 量化模型加载的坑
GGUF 量化模型需要 ComfyUI 的 GGUF loader 节点来加载，不能直接用常规的 CheckpointLoader。加载方式不对的话，模型权重虽然能读进来，但 forward 时会出现维度不对、类型不匹配这类错误。
另外，GGUF 的量化是分层的，不同层可能用了不同的量化等级。K 系列量化通常会在 attention 层保留更高精度，在 FFN 层用低精度。如果你发现生成画面出现奇怪的色带或者物体边缘闪烁，问题大概率出在 VAE 精度，而不是 DiT 主干量化。这时可以考虑单独加载高精度的 fp16 VAE 文件，只对 DiT 使用 GGUF。
4.5 热管理和性能的平衡
MacBook 的散热能力就那样，长时间跑 33B 视频模型时，机身温度会明显上升。风扇策略对帧率影响很大，如果让系统手动切换到低噪音模式，性能会下降 20% 到 30%。
我的做法是把电源连接到插座，然后在终端里用pmset把系统性能模式恢复为最高档。注意，这一步不需要额外安装任何工具，系统自带。环境温度也有影响，夏天室温 30 度以上时，M2 Max 会主动降频，同样的工作流生成一帧的时间可能从 2 秒涨到 3 秒半。如果你对速度敏感，放置一个散热垫比任何软件优化都有效。
5. 我踩过的坑和排查技巧
5.1 ctypes 参数类型不对，节点直接崩溃
症状是 ComfyUI 控制台报Segmentation fault，浏览器里节点红了一大片。排查后发现是 C 函数期望uint32_t*，而我在 ctypes 里传了c_int的数组，两者内存布局虽然相同，但 C 侧写入时按 4 字节无符号处理，Python 侧读出来成了有符号数，高位被截断。
解决方式是统一使用ctypes.c_uint32数组，并且初始化时通过ctypes.cast确保指针类型完全匹配。这类问题在 Mac 上尤其隐蔽，因为 arm64 架构下某些数据结构要对齐到 16 字节，一旦对齐错位，不会立刻报错，而是某次访问随机崩溃。
5.2 动态库找不到，随机目录套娃
第一次测试时，节点报FileNotFoundError，但文件明明存在。排查发现是因为我在__init__.py里用了相对路径./lib/libh3.dylib，而 ComfyUI 启动自定义节点时，当前工作目录是 ComfyUI 根目录，不是插件目录。PyTorch 和 ComfyUI 自己的加载逻辑都不承诺工作目录，所以只要涉及文件路径，一律用os.path.dirname(os.path.abspath(__file__))拼接。
5.3 内存峰值暴涨
节点接入后，采样速度没有变慢，但内存监控显示样本开始几秒内就从 20GB 冲到 58GB。原因是我在 Python 层做 conditioning 重排时，把整个张量拷贝了一份，旧张量还没来得及释放。
解决办法是把大张量操作改成视图操作，尽量复用内存。ComfyUI 的 conditioning 内部是元组列表，我不需要生成新的列表，只需要对列表顺序做调整，然后把 embedding 张量原地索引。如果确实需要新建张量，就要及时把旧引用置空，让 macOS 的内存压力控制器有机会回收。
5.4 MPS 上 bfloat16 支持不佳
视频模型很多操作默认使用 bfloat16 精度。MPS 对 bfloat16 的支持一直不太完善，某些层会触发 CPU fallback，拖慢整体速度。更麻烦的是，CPU fallback 回来的张量类型是 fp32，和 MPS 侧的 bf16 张量做 concat 时会直接报类型错误。
我的最终方案是在模型加载时把所有涉及时间维度的张量统一转成 fp16，只保留文本编码器的 bf16。fp16 在 MPS 上支持很好，精度损失在这个场景下可以接受。如果你发现某些层必须用 bf16，至少要保证同类操作在同一个设备上完成，不要混着来。
5.5 采样过程中断，进度条卡死
这个坑和 h3.c 的调用方式有关。我在节点里用了线程池并发执行h3_route，和 ComfyUI 的图执行器抢线程，结果在采样中途出现死锁。原因是 ComfyUI 的节点调度默认不重入，而我们节点的锁和其他节点的内存分配锁形成了竞争。
解决方式是去掉线程池，让h3_route在调用线程里串行执行。反正函数本身耗时只有毫秒级，并发收益不明显，反而徒增复杂度。如果未来需要处理更大 batch，再考虑用concurrent.futures包一层，但必须确保不依赖 ComfyUI 内部状态。
5.6 量化模型画面偏色
用 GGUF 量化跑出来的视频颜色明显发灰，像蒙了一层雾。检查后发现是 VAE 文件也被量化了。VAE 对颜色保真度要求极高，量化后色彩漂移非常明显。
解决方式很简单：单独加载一个 fp16 的 VAE 文件，和量化后的 DiT 配合使用。ComfyUI 的 VAE Loader 节点支持自定义 VAE 路径，直接把 fp16 的 VAE 放进去，采样时自动替代默认 VAE。
5.7 macOS 交换空间疯狂增长
跑长视频时会发现系统盘空间越来越少，这是 macOS 在把内存页换到磁盘。短时间交换还能撑住，但长时间运行会让 SSD 寿命受损，采样速度也会断崖式下降。
我的排查结论是：问题通常不是瞬时峰值，而是内存泄漏。ComfyUI 的某些管理节点会在循环中保留中间结果，比如 prompt 索引缓存。所以每跑完一批视频，我会手动清理 graph，或者直接重启进程。相比在代码里找泄漏，重启是最快的解法。
6. 后续还能怎么玩
封装 h3.c 这个工程做完之后，我最大的体会是：ComfyUI 插件并不一定要做大而全的东西，很多时候你把一个 C 语言里解决得很漂亮的小问题搬进来，就能撬动整个工作流的稳定性。h3.c 体积小、无依赖、行为可预期，非常符合“工具型节点”的定位。
如果你也想在 Mac 上复现这套玩法，我的建议是不要一上来就追求全套 33B。先拿一个 7B 或者 14B 的视频模型把 ComfyUI 工作流跑通，确认 MPS 后端、量化加载、VAE 解码这些环节都没有问题，再切换到 33B 权重。大模型环境下的变量太多，一次性引入全部新东西，你真的不知道是 C 代码出了问题、量化出了问题，还是 Mac 的散热程序在捣乱。
最后再分享一个小技巧：封装 C 函数时，在restype和argtypes上多花五分钟写好类型声明，这五分钟能帮你省下后面五个小时的调试时间。我在这篇文章里遇到的绝大多数崩溃，最后都回到了类型声明不严谨这个问题上。把 C 层当成一个严格的外部 API 来看待，Python 侧的代码就会安全很多。
