gemma-4常见问题一次解决:下载失败、加载报错与显存不足排查清单
gemma-4常见问题一次解决:下载失败、加载报错与显存不足排查清单
gemma-4 是面向 ComfyUI 的 Gemma 4 文本编码器(text encoder)模型仓库,提供 E2B / E4B / 12B 三个规格共 7 个量化版本。本文围绕 下载失败、加载报错、显存不足 三大高频问题,给出一份可直接对照执行的排查清单,帮你快速定位原因、一次解决。
一、先搞清 gemma-4 的模型文件结构 📦
gemma-4 的全部模型文件都存放在 text_encoders/ 目录,安装说明见 README.md。7 个文件 = 3 个基座模型 × 不同精度/量化方式,各文件真实大小如下:
| 模型文件 | 基座 | 精度 | 文件大小 |
|---|---|---|---|
| gemma4_e2b_it_bf16.safetensors | E2B | BF16 | ≈ 10.3 GB |
| gemma4_e2b_it_int8_convrot.safetensors | E2B | INT8 (convrot) | ≈ 5.2 GB |
| gemma4_e4b_it_bf16.safetensors | E4B | BF16 | ≈ 16.0 GB |
| gemma4_e4b_it_fp8_scaled.safetensors | E4B | FP8 | ≈ 9.1 GB |
| gemma4_e4b_it_int8_convrot.safetensors | E4B | INT8 (convrot) | ≈ 8.1 GB |
| gemma4_12b_bf16.safetensors | 12B | BF16 | ≈ 24.0 GB |
| gemma4_12b_int8_convrot.safetensors | 12B | INT8 (convrot) | ≈ 12.1 GB |
💡 全部下载约 85 GB。一般不需要全下,按显卡配置只选 1 个即可。
二、下载失败排查清单 ⬇️
1. 下载中断或文件不完整
下载后先核对文件大小是否与上表一致(允许 ±1% 误差)。大小明显偏小、或 ComfyUI 提示 safetensors 解析失败,多半是下载中断导致文件截断,建议重新下载,不要直接拼接断点。
2. clone 得到 136 字节的"LFS 指针文件"
这是最常见的下载坑:仓库用 Git LFS 存储模型。若直接 git clone 而未正确拉取 LFS 大文件,text_encoders/ 里得到的只是约 136 字节的指针文件(内容以 version https://git-lfs.github.com/spec/v1 开头),不是真实模型。
处理方法(只拉取你需要的单个文件,可节省流量与磁盘):
git clone https://gitcode.com/hf_mirrors/Comfy-Org/gemma-4.git
cd gemma-4
git lfs install
git lfs pull
# 或只拉取指定文件:
git lfs pull --include="text_encoders/gemma4_e4b_it_int8_convrot.safetensors"
判断技巧:真实文件应为 GB 级;若只有百来字节,读一下内容,出现 LFS 指针字样即可确认是此类问题。
3. 磁盘空间不足
单个最大文件 gemma4_12b_bf16.safetensors 达 24.0 GB,请至少预留 2 倍目标文件体积 的空闲空间(下载临时缓冲 + 正式文件)。
三、加载报错排查清单 ⚙️
1. 文件没有放在正确目录
按 README.md 的要求,文件必须放在 ComfyUI/models/text_encoders/ 下:
ComfyUI/
└── models/
└── text_encoders/
├── gemma4_e2b_it_bf16.safetensors
├── gemma4_e4b_it_int8_convrot.safetensors
└── …
放进 checkpoints/、diffusion_models/ 等其他目录,ComfyUI 不会将其识别为文本编码器。
2. 模型下拉列表里看不到
- 重启 ComfyUI:模型扫描发生在启动时,放好文件后必须重启才能出现;
- 确认文件名完整,不要改名、不要出现
.safetensors.safetensors双扩展名; - 确认磁盘对 ComfyUI 有读权限(Linux 下常见)。
3. 加载时报"损坏 / unknown model"
依次核对:文件大小是否与上表一致(排除截断)→ 是否为真实 LFS 文件(排除 136 字节指针文件)→ 文件扩展名是否为 .safetensors。
四、显存不足排查清单 🧠
1. 各版本显存需求速查
文本编码器权重需完整载入显存,文件体积是最直观的估算基准(下表为权重占用的参考值,实际生成时还需与扩散模型、KV 缓存等共享显存,请再留出 2~4 GB 余量):
| 版本 | 权重占用参考 | 建议最低显存 |
|---|---|---|
| E2B INT8 | ≈ 5 GB | 8 GB |
| E4B INT8 / FP8 | ≈ 8~9 GB | 12 GB |
| E2B BF16 | ≈ 10 GB | 12 GB |
| 12B INT8 | ≈ 12 GB | 16 GB |
| E4B BF16 | ≈ 16 GB | 24 GB |
| 12B BF16 | ≈ 24 GB | 32 GB |
2. 低显存怎么选?
- 8 GB 及以下:选 gemma4_e2b_it_int8_convrot.safetensors(≈5.2 GB),是显存友好的入门之选;
- 12 GB:选 gemma4_e4b_it_int8_convrot.safetensors 或 fp8 版,量化版体积约为 BF16 的一半;
- 16 GB 及以上:可用 gemma4_12b_int8_convrot.safetensors 获得更好的文本理解能力。
3. 显存不够时的通用缓解手段
- 开启 ComfyUI 的 模型卸载(model offload) 功能,让权重在显存与内存间按需换入换出,牺牲速度换可行性;
- 调短上下文长度、减少并发生成数量;
- 生成前关闭浏览器硬件加速等占用 GPU 的程序;
- 优先使用 INT8 / FP8 量化版,同规格下比 BF16 省约一半显存。
五、60 秒快速自检清单 ✅
- 文件大小与本文表格一致?(排除下载不完整)
- 是真实 LFS 文件,而非 136 字节指针文件?(
git lfs pull修复) - 文件位于
ComfyUI/models/text_encoders/? - 放好后是否重启过 ComfyUI?
- 所选版本是否满足显卡显存?(不满足则换 INT8/FP8 版本)
按以上顺序逐项排查,gemma-4 的下载失败、加载报错与显存不足问题基本都能一次定位解决。