GLM-4源码仓库实战：从zip包到本地部署与量化调优

简介：智谱GLM-4大语言模型完整代码仓库源码zip包，面向大模型开发者、算法工程师与AI应用研究者，提供从模型推理、微调到服务化部署的全流程工程实现。压缩包共78个文件，以Python脚本为核心，覆盖OpenAI API服务、CLI/Web/视觉多模态Demo、vLLM推理加速及finetune微调等模块，并配套Markdown说明、YAML/JSON配置、PNG/JPG架构图等辅助材料，整体仅7.57MB，结构清晰便于快速二次开发。包内basic_demo、composite_demo、finetune_demo等子目录划分明确，既可一键启动对话体验，也可参照微调脚本适配自有数据集；同时提供Intel OpenVINO、ITREX等硬件适配示例，兼顾云端与本地不同部署环境。目前已有305人学习下载，适合希望深入理解GLM-4源码结构并快速落地应用的开发者。

1. 从一份 zip 包到本地跑通 GLM-4：先说结论

拿到 glm4 代码仓库源码 zip 包的那一刻，大部分人做的是解压、进目录、pip install，然后祈祷模型能一次跑通。我建议反过来。这个 zip 包不像是一个“装上就能用”的软件安装盘，智谱把 GLM-4 的推理脚本、量化实现、微调模板和 tokenizer 配置全部塞进了这套代码仓库里，谁先读懂了目录结构，谁才能在 4090 上跑出 INT4 量化、在 32G 显存里把长对话撑住。这篇笔记就是我拿到 zip 包之后，从解压到把模型服务化跑通的完整复现过程。适合三类人：被开源代码仓库从哪下手卡住的学生，给业务找本地可落地方案的应用工程师，以及想改模型行为但不想从零写训练流程的算法岗。

2. 为什么拿源码而不是直接 pip install：代码仓库里真正值钱的东西

2.1 官方仓库到底给了你什么

我以前也偷懒，模型一律用 transformers 的 from_pretrained 加载，图的是少配置。但那个方式只会拉到模型的权重和 config.json，推理脚本、量化脚本、微调样例全都不在。GLM-4 这套代码仓库的 zip 包不一样，它本身就是一个完整的开发环境模板，解压之后你能看到官方同款的基础对话 demo、模型并行配置、微调目录和模型内部实现文件。

这里先说清楚一个边界：zip 包里通常只有代码和配置，模型权重文件（几个 GB 的 pth 或 safetensors）不在这个压缩包里，需要你按仓库 README 单独下载模型文件放到本地目录。很多在校生拿到 zip 包后以为解压即用，结果跑起来报找不到权重的错，这不是资源缺少文件，而是没把权重放对位置。

我把两类东西的差别列个表：

这份资源最适合的场景不是“跑起来就行”，而是“跑起来之后你还想改配置、换量化、做微调”，那时候源码包的价值才真正体现。

2.2 模型架构与四种加载方式的取舍

第一次用 GLM-4 之前，我建议先花十分钟搞清楚它的架构选型。官方发布的信息里，GLM-4 采用 Transformer 结构，用了 GQA 减少 KV Cache 占用，位置编码用 RoPE，归一化用 RMSNorm。这套组合意味着它对显存的占用不像传统多头注意力那么离谱，但也没有到随意跑的程度，权重量和上下文长度仍然决定了你的显存预算。

加载方式上，我看过太多人一上来就全部拷进显存，然后看它 OOM。实际落地时至少有四种选择：直接用 transformers 的 AutoModel 走 bf16 全精度；走官方自带的推理脚本；挂 INT4 量化版省显存；以及后端换成 vLLM 服务化。四种方式不是替代关系，而是看你的任务阶段，调试期用第一种，部署期建议最后一种，显存紧就上 INT4。下表是我自己整理的选择依据：

我在实际跑的时候发现，向量化后的 vLLM 速度几乎是前者的三倍以上，但前提是机器别太老。如果你只是要复现对话效果，没有并发压力，完全不用上 vLLM，先跑通 transformers 版本再谈优化。

2.3 上手第一步：跑一个最小推理脚本

拿到 zip 包之后我一般先解压，然后立刻跑一个最小的加载脚本，不调参、不量化，先确认环境和权重路径是通的。注意这里要先把模型权重下载好，按仓库 README 的提示放在 model 目录下。

import torch from transformers import AutoTokenizer, AutoModelForCausalLM # 换成你本地 zip 包解压后的模型权重目录 model_path = "./model/glm-4-9b-chat" tokenizer_path = "./model/glm-4-9b-chat" tokenizer = AutoTokenizer.from_pretrained( tokenizer_path, trust_remote_code=True, # GLM-4 的 tokenizer 需要执行本地代码 encode_special_tokens=True ) model = AutoModelForCausalLM.from_pretrained( model_path, trust_remote_code=True, torch_dtype=torch.bfloat16, # 9B 模型用 bf16 比 fp16 更稳 device_map="auto", # 自动分配模型层到可用的 GPU/CPU ) response, history = model.chat( tokenizer, "用三句话解释一下 KV Cache", history=[], max_new_tokens=256, top_p=0.8, temperature=0.6, ) print(response)

这段代码里三个参数最值得注意。trust_remote_code=True 是必须的，因为 GLM-4 的模型实现文件不在 transformers 官方主干里，需要执行仓库自带的 modeling 文件；device_map="auto" 是让 accelerate 自动把不同层分配到可用设备，单卡时等价于整卡加载；torch_dtype=torch.bfloat16 在 9B 规模下比 fp16 稳定，尾巴上的 top_p 和 temperature 则是控制随机性的，调试时建议先把 temperature 拉低到 0.5 左右。

这个脚本跑通之后，你才算是把环境打通了。后面再去做量化、微调或服务化，都是在这个基础上加东西。

3. 拆解源码仓库：目录结构、配置文件和一次完整推理链路

3.1 先从目录导读开始：哪些目录该读、哪些不该动

我把 zip 包解压之后，第一件事不是看 README 有没有讲清楚，而是敲一条 tree 命令把目录结构拉出来。GLM-4 代码仓库的目录结构跟其他大模型开源仓库大体一致，但有几个文件的作用容易被新手误判。我一般会先看这几个地方：

glm4-code-repo/ ├── basic_demo/ # 入口：cli_demo.py、web_demo.py、api_demo.py ├── finetune_demo/ # 微调样例：LoRA、P-Tuning v2，含数据处理脚本 ├── inference/ # 推理相关脚本，包含模型并行与量化说明 ├── configs/ # 各模型的 config 配置样例 ├── model/ # 自建的权重目录，zip 包里是空的 ├── requirements.txt # 环境依赖版本 └── README.md # 官方说明，第一步应该读它

我先说哪些目录第一时间要读。basic_demo 里的 cli_demo.py 是最短路径的官方样例，它把 tokenizer 加载、模型加载、多轮对话封装好了，适合第一次跑通；configs 目录放着不同模型的 config.json 模板，拿来和实际下载的权重里的 config 做对比，能看出官方意图。finetune_demo 里的数据格式说明是你做微调前必须读的，后面第 5 章会说这里容易出什么事。

哪些不要碰？model 目录是放权重的，别把它当成代码目录写逻辑；requirements.txt 里锁定的版本别自作主张升到最新，GLM-4 这类代码对 transformers 版本敏感，升一个大版本很容易触发不兼容。另外如果你习惯用 git 管理，把解压后的源码单独建仓推到 gitee 管理完全可行，但建仓前一定要写好 .gitignore，把 model 目录和.safetensors、.pth 过滤掉，否则几个 GB 的权重文件会直接把仓库撑爆，推不上去。

3.2 config.json 与 tokenizer：模型卡里最容易被忽略的参数

很多同学打开 config.json 只看 model_type 和 architectures，觉得这就完事了。实际上这个文件里藏着几个和资源占用直接相关的关键字段，每个部署前都值得过一遍。

我踩过一回 rope_theta 的坑。早期某些第三方量化脚本为了拉长上下文，会把 rope_theta 从 10000 调到 100000，如果模型没有针对长文本微调过，输出会变得前言不搭后语。所以遇到量化后质量下降，先别怪量化本身，回去看一眼 config.json 是否被动过。tokenizer 那边也有一个容易误会的点：GLM-4 的对话模板和 ChatGLM 家族一脉相承，使用 gMASK、sop 这类特殊逻辑 token，用户输入还要包在 user 和 assistant 标识里。你在手写对话历史的时候，必须按这个格式拼字符串，否则多轮记忆会断。官方 demo 里都是把 tokenizer.build_chat_input 封装好的，自己写推理循环时最容易漏掉这一步。

3.3 一条推理请求从 chat 到输出的完整链路

弄清楚目录和配置之后，我建议你完整走一遍推理链路，而不是直接跳到量化。下面的脚本是官方 cli_demo.py 的精简版，它展示了多轮对话最核心的循环逻辑：每轮把历史拼进 prompt，调用模型的 chat 方法，再把新回复追加到 history 里。

from transformers import AutoTokenizer, AutoModelForCausalLM model_path = "./model/glm-4-9b-chat" tokenizer = AutoTokenizer.from_pretrained(model_path, trust_remote_code=True) model = AutoModelForCausalLM.from_pretrained( model_path, trust_remote_code=True, torch_dtype=torch.bfloat16, device_map="auto", ) history = [] while True: query = input("用户：") if query.strip().lower() in {"exit", "quit"}: break # chat 方法内部会拼接 gMASK、sop 等特殊 token，不用自己拼 response, history = model.chat( tokenizer, query, history=history, max_new_tokens=512, top_p=0.7, temperature=0.6, repetition_penalty=1.1, ) for token in response: print(token, end="", flush=True) print("\n")

逻辑上这段做了三件事：维护一个 history 列表，每轮把新问答追加进去；调用 model.chat 返回新回复和更新后的完整历史；控制台循环。参数上值得说明的是 repetition_penalty，它默认在 GLM-4 的实现里是 1.0，遇到生成重复词段时拉高到 1.1 或 1.2 往往立竿见影；max_new_tokens 不要设满到 max_position_embeddings，留 20% 余量给输入 token 数，否则会截断回复尾部。

我特别提醒一点：model.chat 的返回值 history 是已经更新过的，你不要再手动 append 一遍，否则第二轮回话历史里会出现重复的上一轮内容，模型回答会越来越乱。这条是我在最初接触 ChatGLM 系代码时踩过的真实教训，直到现在每次写新脚本都会检查一遍 history 是否被重复维护。

4. 本地部署与对话实测：加载方式、量化选型与生成参数调优

4.1 模型加载与设备分配：从单卡到多卡

部署这个话题，最常被问的就是一张 24G 显卡到底能不能跑 9B。答案是可以，但阈值卡得很紧。9B 模型在 bf16 下的权重量化大约占 18G 到 20G，你再给 KV Cache 和激活值留 6G 到 8G，24G 基本贴线。我的习惯是部署前先看一眼显卡剩余显存，再决定加载策略。

import torch model_path = "./model/glm-4-9b-chat" max_memory = { 0: "18GiB", # GPU 0 分配 18G 1: "18GiB", # GPU 1 分配 18G，双卡并行 "cpu": "32GiB" # CPU 兜底放一部分层 } model = AutoModelForCausalLM.from_pretrained( model_path, trust_remote_code=True, torch_dtype=torch.bfloat16, device_map="auto", max_memory=max_memory, offload_folder="./offload", # 显存不足时把层挪到这里 )

这段代码的核心是 max_memory 和 offload_folder 的组合。max_memory 不是把全部显存都填满，我一般留 10% 给推理时的 KV Cache，不然会 OOM；offload_folder 是把实在放不下的层临时写到磁盘，但代价是访问磁盘会让推理变慢，我建议它只作为兜底，不作为常规部署方案。多卡场景下 device_map="auto" 会按上面的 dict 自动分片，各卡显存不均衡也没关系，accelerate 会按照你给的阈值做平衡。

跑完加载脚本后，看一眼打印出来的模型层级分配日志，确认每一层落在哪张卡上。这一步很重要，很多部署问题都出在“以为分配均匀，实际全堆在卡 0”上。

4.2 量化选型：FP16、BF16、INT4 的取舍

量化是让 GLM-4 跑进小显存的关键，但选错量化方式，模型输出会肉眼可见地变笨。GLM-4 官方针对 9B 模型提供过 INT4 量化版本，同时也兼容 bitsandbytes 的 4bit/8bit 加载。

实际体验下来，8G 显存的卡跑 INT4 可以做到长对话不崩，但回复质量在复杂推理上会明显下滑，比如让它解数学题，步骤会跳。如果你只是做文本摘要、代码补全这种低难度任务，INT4 完全够用；做逻辑推理和长文档分析，我宁可减少上下文长度也要保住 BF16。

还有一个常见误用是把 bitsandbytes 的 load_in_4bit 和 GLM-4 官方 INT4 混为一谈，这两者的量化粒度和后端并不完全一样。如果官方给了对应版本，优先用官方裁剪好的权重，外部转换脚本容易在 tokenizer 和 config 上出兼容问题。

4.3 生成参数调优：让回答不再生硬和复读

模型能跑起来之后，很多人会进入一个新阶段：开始嫌弃它回答生硬、有官腔、偶尔复读。这个阶段靠调参能解决一大半问题。我总结了一套在 GLM-4 上多次验证过的参数组合模板，适合中文问答和写作类任务：

generation_config = { "max_new_tokens": 512, # 控制回复长度上限 "do_sample": True, # 开启采样才有随机性 "top_k": 40, # 从概率最高的 40 个 token 中采样 "top_p": 0.8, # 累积概率截断 "temperature": 0.7, # 越高越发散，越低越确定 "repetition_penalty": 1.1, # 抑制重复词段 }

这套参数里，温度和 top_p 是配合使用的，不是两个独立旋钮。我在本地试过 temperature=0.2 加 top_p=0.5 时输出极稳但像念说明书；调到 temperature=0.9、top_p=0.9 会开始出现口语化表达，但也会偶尔跑题。做客服类场景我建议偏保守，做文案创作可以偏激进。repetition_penalty 是 GLM-4 上最容易见效的参数，只要看到一段话反复绕圈，先把它从 1.0 提到 1.15，九成情况能解。注意 do_sample 为 False 时，top_p 和 temperature 不会生效，这条检查不到，脚本就会“改了参数没反应”，我犯过这种低级错误。

5. 避坑记录：GLM-4 源码跑到一半最容易翻车的五个问题

5.1 transformers 版本不匹配导致 import 直接报错

现象：按 requirements.txt 装完环境，import 模型时抛 AttributeError，提示某个类或方法找不到；有时甚至报 “The 'tokenizer' parameter is required” 这类跟代码行对不上的错误。

原因：GLM-4 的 modeling 文件是配合特定版本的 transformers 写的，版本太旧缺少新方法，版本太新某些接口被重构，都会在加载时炸开。我当时翻车是因为本机早有一个 transformers 4.36，直接跑新代码就撞上版本断层。

解决：严格按 README 或 requirements.txt 里锁定的版本创建虚拟环境，我一般用pip install "transformers>=4.39.3,<5.0"先装一个明确区间，再回头验证加载。

5.2 device_map="auto" 也会 OOM

现象：明明显卡显存足够，加载时却报 CUDA out of memory，且报错位置在权重加载阶段。

原因：device_map="auto" 的全卡模式会把权重全部放进显存，但它预留的 KV Cache 空间不够；如果同时有别的进程占显存，也会叠加导致溢出。

解决：加载前先用 nvidia-smi 看剩余显存；然后用 max_memory 参数给推理留缓冲，不要全用完。如果单卡 24G 跑 9B BF16 很勉强，优先切换到 INT4 权重而不是硬扛。

5.3 量化后输出质量断崖式下降

现象：同一句话，BF16 输出正常，INT4 输出逻辑混乱，中文回答出现语义跳变。

原因：两种可能。一是量化方案对激活值离群点敏感，导致部分层误差被放大；二是有人调过 config.json 里的 rope_theta，量化后这个误差被进一步放大。

解决：先用官方 INT4 权重替换自转格式的权重；把 temperature 微调低，减少采样放大量化噪声；最后对比 config.json 和官方模板，发现 rope_theta 被动过就回滚。

5.4 微调训练 loss 一直不降

现象：用 finetune_demo 训练 LoRA，跑了几个 epoch，loss 数值纹丝不动，甚至发散。

原因：数据格式不符合要求。GLM-4 微调数据的每一行要求 conversations 字段，首条消息必须是 user，assistant 回复放在第二条；字段名写错或多轮角色标签拼错，模型等于在看乱码。

解决：我每次都会先取一条 JSONL 样本，用 zip 包里的数据处理脚本校验并打印生成结果，确认 role 和 content 结构无误再喂给 trainer。训练时把 per_device_train_batch_size 从大调到 1，排除显存溢出导致的静默失败。

5.5 GPU 利用率低，生成速度慢得离谱

现象：模型跑起来了，但 nvidia-smi 显示 GPU 利用率只有 20% 左右，每生成一个字要等半天。

原因：一是数据预处理阶段在 CPU 上反复执行 tokenizer，GPU 空转；二是生成时开了 do_sample 又不设置 top_k，导致采样路径变长；三是 max_model_len 设置过大，KV Cache 碎片化严重。

解决：把 tokenizer 预处理移出循环体，一次性编码；采样时固定 top_k=40；如果服务化场景，把 max_model_len 调整到实际业务长度的 1.2 倍即可，不要直接拉满到模型上限。

6. 进阶玩法：把 GLM-4 源码变成本地 API 服务并做端到端验证

6.1 用 vLLM 起一个 OpenAI 兼容 API

本地对话脚本验证完毕，下一步就是把模型从命令行变成服务。vLLM 是目前把 GLM-4 服务化最省事的后端，尤其是它直接支持 OpenAI 兼容协议，前端不用改任何代码就能接进来。我一般用下面的命令把模型托管在 8000 端口：

python -m vllm.entrypoints.openai.api_server \ --model ./model/glm-4-9b-chat \ --served-model-name glm4 \ --port 8000 \ --gpu-memory-utilization 0.85 \ --max-model-len 8192 \ --tensor-parallel-size 1

几个参数值得逐个说明。served-model-name 是给客户端看的模型名字，随意取但别和路径混淆；gpu-memory-utilization 表示允许 vLLM 使用多少显卡显存，0.85 的意思是预留 15% 给运行时开销和处理。max-model-len 是这次服务能接受的最大上下文长度，我设为 8192，如果业务全是短对话，可以压到 4096 换取更快的首 token 延迟。tensor-parallel-size 是并行张量的显卡数，单卡写 1，双卡写 2。注意服务起来的日志里有一个 “Prompt 吞吐/Sample 吞吐” 的输出，这些指标就是后面的验证依据。

6.2 用 curl 验证一次完整的对话链路

服务起来之后，我用一个最小请求做端到端验证，确认路径、tokenizer、采样参数全部通了一遍：

curl http://localhost:8000/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "glm4", "messages": [ {"role": "system", "content": "你是克制的助手。"}, {"role": "user", "content": "用一句话解释什么是 KV Cache"} ], "temperature": 0.7, "max_tokens": 256 }'

这个请求验证的是 vLLM 是否真正把消息传给了模型，以及返回是否满足 OpenAI 协议结构。我建议重点关注三处：返回的 choices[0].message.content 是否是基于中文的正常回复，usage 字段里的 prompt_tokens 和 completion_tokens 是否合理，以及响应耗时。如果返回结构缺少 usage，说明你接的可能是老的非 OpenAI 兼容路径，端口或路由不对。

6.3 部署后的验证清单：别等服务崩了再救

我把这套流程沉淀成了一张检查清单，每次部署完都会按顺序过一遍，避免漏掉那些“看似正常实则暗病”的配置。

从那以后，我每次拿到一份新的 GLM-4 源码 zip 包，都会强制走一遍同样的流程：先读 config.json，跑最小推理，再量化、再服务化，最后用这六项清单收尾。这不是仪式感，是这套流程每次都能在半小时内暴露 80% 的潜在问题，尤其是第 4 项多轮记忆，问题隐藏得最深。希望这些经验能帮你在自己的机器上少走几步弯路。

本文还有配套的精品资源，点击获取