Qwen3文本编码器FP8/GGUF加载报错修复指南
加载Qwen3文本编码器时，如果用了FP8或GGUF量化版，很容易在加载Z-Image模型时直接崩溃。这其实是典型的权重缺失和数据类型不匹配导致的，不用大改模型，在加载逻辑里加几行处理就能解决。
下一篇
分享一个把 LLM 上下文变成“可编辑图谱”的骚操作 →
一、解决FP8 Safetensors 缺少 lm_head.weight 报错
很多FP8权重为了省空间，把 lm_head.weight 删了（因为它和 model.embed_tokens.weight 是一回事）。但 fast_load_transformers_model 检查太死板，找不到这个Key直接抛异常。
实操方法：
写一个预处理器在加载 state_dict 时动态拦截，把 embed_tokens 的引用直接指给 lm_head。
def _fix_qwen_fp8_sd(state_dict):
# 如果缺少 lm_head 但有 embed_tokens，直接做内存映射，不增加显存占用
if 'lm_head.weight' not in state_dict and 'model.embed_tokens.weight' in state_dict:
state_dict['lm_head.weight'] = state_dict['model.embed_tokens.weight']
return state_dict二、解决GGUF格式的 SDPA Dtype 不匹配
用 GGUF（比如 Q4_K_M）时，经常碰到一个极其恶心的报错：RuntimeError: Expected query, key, and value to have the same dtype。
这是因为 GGUF 提供的 Value 张量是 bfloat16，但 HF 的 transformers 在计算 RoPE 时把 Query 和 Key 变成了 float32。PyTorch 的 SDPA 只要类型不统一就直接罢工。
修复方案：
在 offload.fast_load_transformers_model 执行完之后，立刻强制对整个 text_encoder 做一次类型转换，把所有投影层统一到同一个精度。
# 在 z_image_main.py 中加载完成后立即执行
text_encoder = offload.fast_load_transformers_model(...)
text_encoder.to(dtype) # 强制统一精度，消除 SDPA 冲突这套组合拳下来，FP8 的权重缺失和 GGUF 的精度冲突就都解决了。对于追求部署速度的开发者来说，这种在加载层做兼容的方案比重新量化模型要高效得多。
