GLM 5.2 在 Hugging Face 上：用 Transformers 加载与运行

Zhipu AI 的 GLM-4 家族已成为 Hugging Face 上能力最强的开放权重模型系列之一。无论你是想在本地跑推理、为特定领域微调，还是想在不把数据发送到外部 API 的情况下做边缘部署，Hugging Face 上的 THUDM checkpoints 都提供了实用的入门路径。本教程覆盖你需要的全部内容：正确的模型 ID、硬件要求、量化选项，以及可运行的推理代码。

痛点：为什么本地 GLM 推理很重要

大多数开发者第一次接触 GLM-4 是通过智谱 AI 的 API，它提供全尺寸的 GLM-4-Plus 前沿模型（753B 总参 / 40B 激活的 MoE 架构）。这个 API 很适合生产使用——速度快达 158 token/秒，1M token 上下文窗口——但它并非适合所有场景的工具。

开发者想要本地 checkpoint 的常见原因：

• 隐私与合规 —— 许多组织在政策上禁止把代码、文档或用户数据发送给第三方 API。
• 微调 —— 用专有数据适配模型需要访问权重。
• 边缘与嵌入式部署 —— 对延迟敏感或离线的场景，API 往返不可接受。
• 成本控制 —— 持续高吞吐的工作负载，用自有硬件运行可能比按 token 计费的 API 更便宜。

Hugging Face 生态同时解决了这四点。THUDM 组织在 MIT 协议下发布 GLM-4 开放权重 checkpoint，给你使用、修改和再分发的最大灵活性。

该用哪个模型？

写任何代码之前，你需要选对 checkpoint。Hugging Face 上的 GLM-4 系列有几个变体：

**对大多数开发者来说，THUDM/glm-4-9b-chat 是正确的起点。**它针对对话做了指令微调，单张消费级 GPU 以全精度即可运行，并且与更大的前沿模型属于同一架构家族。完整的 GLM-4-Plus 规模模型不提供开放权重——那项能力只能通过 API 使用。

想深入了解 API 版本及其基准对比，请看本博客的 GLM 5.2 API 指南。

竞争优势

**GLM-4-9B-Chat 是中英双语任务上最强的开放权重 9B 模型之一。**发布时，它在标准中文基准上超过了多款同类 9B 模型，同时英文任务完全能打。对这样一个质量的模型来说，MIT 协议宽松得不寻常——不像一些以自定义研究协议发布的竞品 checkpoint，你可以在商业产品中毫无限制地使用 GLM-4-9B-Chat。而且因为它原生集成 Hugging Face Transformers 库，你可以把它直接放进任何现有 Transformers 流水线，无需自定义推理代码。

硬件要求

安装任何东西之前，先确认你的环境能扛住 checkpoint：

• **全精度（bfloat16）：**约 18 GB 显存。单张 NVIDIA RTX 3090 或 RTX 4090（24 GB）即可。
• **8-bit 量化：**约 9-10 GB 显存。
• **4-bit 量化：**约 5-6 GB 显存。RTX 3060 12 GB 或 RTX 4070 这类显卡可容纳。
• **仅 CPU：**可以通过 Accelerate 的磁盘 offload 实现，但推理会非常慢——只适合测试。

生产级本地部署，单张 RTX 4090 开 4-bit 量化能在质量与速度之间取得很好的平衡。

安装

安装所需包。建议使用全新的虚拟环境，避免依赖冲突。

pip install transformers torch accelerate bitsandbytes

• transformers —— Hugging Face 模型中心客户端与推理工具
• torch —— PyTorch 后端（GPU 支持请从 pytorch.org 安装 CUDA 版本）
• accelerate —— 设备映射与多 GPU 支持
• bitsandbytes —— 4-bit 与 8-bit 推理的量化后端

全精度加载模型

如果你的 GPU 有 24 GB 显存，最简单的方式是 bfloat16 全精度加载、不做量化。这样输出质量最好。

from transformers import AutoModelForCausalLM, AutoTokenizer
import torch

MODEL_ID = "THUDM/glm-4-9b-chat"

tokenizer = AutoTokenizer.from_pretrained(MODEL_ID, trust_remote_code=True)

model = AutoModelForCausalLM.from_pretrained(
    MODEL_ID,
    torch_dtype=torch.bfloat16,
    device_map="auto",          # automatically assigns layers across available GPUs
    trust_remote_code=True,
)
model.eval()

# Build a simple chat prompt using the model's chat template
messages = [
    {"role": "user", "content": "Explain the difference between MoE and dense transformer architectures in two paragraphs."}
]

inputs = tokenizer.apply_chat_template(
    messages,
    add_generation_prompt=True,
    return_tensors="pt",
).to(model.device)

with torch.no_grad():
    output_ids = model.generate(
        inputs,
        max_new_tokens=512,
        do_sample=True,
        temperature=0.7,
        top_p=0.9,
    )

# Decode only the newly generated tokens
generated = output_ids[0][inputs.shape[1]:]
print(tokenizer.decode(generated, skip_special_tokens=True))

几点注意：

• trust_remote_code=True 是必须的，因为 GLM-4 包含自定义 tokenizer 和 modeling 代码，Transformers 需要从模型仓库加载。
• device_map="auto" 让 Accelerate 处理放置。单 GPU 时它会全放到该设备；多 GPU 系统会自动分片。
• apply_chat_template 按 GLM-4 期望的指令格式格式化消息——如果手搓字符串格式，容易让模型混乱。

4-bit 量化加载

对于显存较小的 GPU，用 BitsAndBytesConfig 以 4-bit 精度加载。这会把内存占用降到约 5-6 GB，同时为对话任务保留模型的大部分能力。

from transformers import AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig
import torch

MODEL_ID = "THUDM/glm-4-9b-chat"

# Configure 4-bit quantization
bnb_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_quant_type="nf4",          # NormalFloat4 — best quality for LLM weights
    bnb_4bit_compute_dtype=torch.bfloat16,
    bnb_4bit_use_double_quant=True,     # secondary quantization for extra compression
)

tokenizer = AutoTokenizer.from_pretrained(MODEL_ID, trust_remote_code=True)

model = AutoModelForCausalLM.from_pretrained(
    MODEL_ID,
    quantization_config=bnb_config,
    device_map="auto",
    trust_remote_code=True,
)
model.eval()

messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Write a Python function that checks whether a string is a palindrome."}
]

inputs = tokenizer.apply_chat_template(
    messages,
    add_generation_prompt=True,
    return_tensors="pt",
).to(model.device)

with torch.no_grad():
    output_ids = model.generate(
        inputs,
        max_new_tokens=256,
        do_sample=False,   # greedy decoding for code generation
    )

generated = output_ids[0][inputs.shape[1]:]
print(tokenizer.decode(generated, skip_special_tokens=True))

nf4 量化类型加双重量化（double quantization）是推理质量上的推荐配置。如果你在为 QLoRA 微调做准备而不是仅做推理，这也是正确的起始配置——peft 可以直接集成这种加载方式。

要改用 8-bit，把 load_in_4bit=True 换成 load_in_8bit=True 并删除 bnb_4bit_* 参数。8-bit 质量略好，显存开销大约是 4-bit 的两倍。

流式输出

对于交互式应用，等完整输出生成完再显示会带来很差的用户体验。Hugging Face Transformers 通过 TextIteratorStreamer 支持流式。

from transformers import TextIteratorStreamer
from threading import Thread

streamer = TextIteratorStreamer(
    tokenizer,
    skip_prompt=True,
    skip_special_tokens=True,
)

generation_kwargs = dict(
    input_ids=inputs,
    max_new_tokens=512,
    do_sample=True,
    temperature=0.7,
    streamer=streamer,
)

# Run generation in a background thread so we can iterate the streamer in the main thread
thread = Thread(target=model.generate, kwargs=generation_kwargs)
thread.start()

for token_text in streamer:
    print(token_text, end="", flush=True)

thread.join()
print()  # newline after streaming ends

TextIteratorStreamer 在生成的同时产出解码后的文本片段。这个模式对全精度和量化模型都适用，streamer 代码无需任何改动。

理解 HF 模型与 GLM-4-Plus 的关系

值得明确说明这些 Hugging Face checkpoint 是什么、不是什么。

glm-4-9b-chat checkpoint 是 90 亿参数模型。生产 API 模型 glm-4-plus 是 Mixture-of-Experts 架构，总参 753B、每次前向激活 40B——规模根本不同。截至写作时，完整 MoE 模型没有公开的开放权重。

9B checkpoint 属于同一研究谱系，与更大模型共享架构 DNA，但在困难基准上的表现会有差异。API 版本在 GPQA Diamond 上达到 89%、SWE-bench Pro 上 62.1%。9B 本地变体能胜任广泛任务——尤其是中英对话、编程辅助和指令跟随——但你应在自己的具体用例上评估它，而不是假设基准相当。

如果你需要前沿质量、又不介意 API，直接在 glm5.app 试用 GLM 5.2 —— 无需任何基础设施配置即可访问完整的 GLM-4-Plus 模型。

常见问题与修复

**加载时内存不足：**使用 device_map="auto" 并开启量化。如果显存仍然不够，在 from_pretrained 里加 offload_folder="offload" 把层 spill 到磁盘（慢，但可用来测试）。

**trust_remote_code 警告：**这是预期行为。GLM-4 的仓库包含 Transformers 需要执行的自定义代码。只为可信来源的模型开启此标志——THUDM 组织是 Zhipu AI 在 Hugging Face 的官方账号。

**输出包含意外 token：**确保使用 apply_chat_template 而不是手工拼接 prompt 字符串。模型对回合边界的精确格式很敏感。

**首次运行分词很慢：**tokenizer 首次使用时会下载并缓存词表。后续调用会变快。

下一步

模型在本地跑起来之后，常见的下一步包括：

• 用 QLoRA 微调 —— 以 load_in_4bit=True 加载模型，加一个 PEFT adapter，在自有数据上做任务专属训练。
• vLLM 部署 —— 为多个并发用户提供服务时，vLLM 的吞吐远高于朴素的 model.generate() 调用。
• 评估 —— 在确定部署架构之前，先用你的领域专属测试用例跑一遍模型。

对于不需要本地控制的场景，在 glm5.app 探索 GLM 5.2 的能力 —— 在决定部署策略之前，这是对全尺寸模型做原型验证的最快方式。

Sources

• Zhipu AI GLM-4 technical blog and model card: https://huggingface.co/THUDM/glm-4-9b-chat
• THUDM organization on Hugging Face: https://huggingface.co/THUDM
• Zhipu AI open platform API documentation: https://open.bigmodel.cn/api/paas/v4/
• Hugging Face Transformers documentation: https://huggingface.co/docs/transformers
• BitsAndBytes quantization documentation: https://huggingface.co/docs/bitsandbytes
• Hugging Face Accelerate documentation: https://huggingface.co/docs/accelerate
• Artificial Analysis GLM-4-Plus benchmark data: https://artificialanalysis.ai