GLM4源码包部署实战：从解压配置到OpenAI兼容服务-北京尧图网络

简介这是一份围绕 GLM-4 代码仓库整理的源码压缩包面向具备一定 Python 基础、希望了解大模型工程实现、复现实验流程或开展二次开发的研究者与开发者。压缩包共 78 个文件约 7.57MB内含 28 个 Python 脚本、14 个 Markdown 文档、9 张图片以及 yaml、json、ts、txt 等配置与说明材料目录按基础演示、微调、OpenAI API 服务、vLLM、Web 与批处理演示等模块组织文档补充环境配置、使用方式和目录说明便于快速定位关键实现。已有 307 人学习下载在 GLM-4 相关实践中具备一定参考价值。读者可获得较完整的仓库源码、示例脚本和配置线索用于梳理模型调用、微调与演示程序的实现思路也可作为搭建本地实验环境、排查依赖问题与开展二次开发的参考资料对理解大模型应用从脚本到服务的组织方式也有帮助。1. 解压完 glm4 源码包先弄清它替我省掉了哪三件事上周有人把 glm4 代码仓库源码 zip 包丢过来第一句话是「解压完打开一看几十个 py 文件从哪下手」。这是拿到大模型源码包最典型的状态权重得另外下压缩包里只有代码第一眼看上去像一堆没头没尾的脚本。其实这套 glm4 源码干的是三件脏活对话模板拼接、KV cache 与位置编码处理、推理服务的接口层。没有它你得自己对着 tokenizer 配置拼|user|这类特殊 token自己处理 batch padding 和长文本外推自己造一套兼容 OpenAI 协议的转发服务。适合谁想在本机跑通多轮对话、要做私有化接口、打算改模型结构或挂 LoRA 微调的人。纯调云端接口的下这个包没意义。2. 解压后先读骨架四个目录决定这套代码能不能直接跑很多人解压之后直接去找 README 里的python demo.py跑不起来就开始怀疑包有问题。顺序反了。先看清楚它的目录骨架判断这个 zip 是「纯代码少量示例」还是「代码连同小权重一起打包」后面所有环境准备的动作都取决于这个判断。我一般会花十分钟做三件事量体积、列目录、读配置文件。这三步做完这套代码大概什么水平、能不能直接进生产、缺哪些外部依赖心里就有数了。2.1 先量体积再列目录区分纯代码包和带权重的包压缩包解压到独立目录别和已有工程混在一起否则后面import冲突排查起来非常痛苦。# 解压到独立工作目录避免与已有工程混在一起 mkdir -p ~/workspace/glm4-src cd ~/workspace/glm4-src unzip ~/Downloads/glm4-code.zip -d . # 先看总体积几十 MB 是纯代码几个 GB 大概率带了权重或示例数据 du -sh . # 只看两层目录层级再深就不是骨架问题了 find . -maxdepth 2 -type d | sort # 按体积排前 20 的文件能立刻发现是不是塞了 .safetensors 或 .bin du -ah . | sort -rh | head -20du -sh那一步是分水岭。如果总体积只有几十兆说明权重得单独去模型托管仓库下载代码包里通常只留一个config.json之类的占位如果体积到了几个 GB包内可能带了量化权重或者示例数据集这时候要注意解压后的磁盘占用会翻倍先确认剩余空间。find -maxdepth 2看的是顶层组织方式常见的有两种一种是把推理、微调、量化、服务端各放一个目录另一种是所有 py 文件平铺在根目录靠文件名区分。前者好办后者要额外读一遍__init__.py和入口脚本的 import 关系才知道哪些文件是核心、哪些是临时脚本。2.2 config.json 里七个字段读完就知道能不能上长文本config.json是这套代码的说明书。结构文件长得再花最终都是照着这个配置实例化的。下面这几个字段建议逐个对一遍{ architectures: [Glm4ForCausalLM], hidden_size: 4096, num_hidden_layers: 40, num_attention_heads: 32, num_key_value_heads: 2, max_position_embeddings: 8192, rope_theta: 10000.0, torch_dtype: bfloat16, eos_token_id: [151329, 151336, 151338] }字段读它干什么踩错会怎样architectures决定AutoModel走哪个类类和权重不匹配加载直接报 KeyErrornum_hidden_layers算 KV cache 显存、定 LoRA 挂载层数层数算错长上下文必 OOMnum_attention_heads/num_key_value_heads判断是不是 GQA、几个 query 共享一个 KV 头自己改推理代码时 head 数对不上输出全是乱码max_position_embeddings原生支持的上下文长度上限超长输入不报错但效果断崖式下跌rope_theta/rope_scaling长文本外推的依据缺缩放配置硬拉长文本句子重复torch_dtype决定加载时用 bf16 还是 fp16老卡上 bf16 起不来fp16 又容易溢出eos_token_id可能是数组不止一个停止符只认一个 eos模型停不下来一直生成重点说num_key_value_heads。这个值和num_attention_heads不相等就说明用了分组查询注意力KV cache 的显存只跟前者相关。很多人按全量 head 数去估算显存算出来吓自己一跳实际部署时发现余量很大就是这里读错了。eos_token_id是数组这点也值得单独记一笔GLM-4 系列的对话结束符通常不止一个推理时如果自己写停止条件只判断单个 id模型会一直续写下去表现出来的现象是「回答完了还在自言自语」。还有一个隐藏位置对话模板不一定在config.json里可能在tokenizer_config.json的chat_template字段也可能是一个独立的.jinja文件。找到它后面跑推理能省掉一半调试时间。2.3 依赖清单核对torch 和 transformers 的版本是第一个雷源码包里的requirements.txt通常只锁了宽松的上下界直接pip install -r装出来不一定能跑。我的习惯是先确认三件事再装# 1. 确认显卡驱动和 CUDA 运行时版本决定装哪个 torch 轮子 nvidia-smi | head -15 # 2. 看依赖清单里有没有写死版本尤其是 transformers 和 torch cat requirements.txt # 3. 看代码里实际用到的 API反推最低版本要求 grep -rn from transformers import\|from peft import\|import flash_attn --include*.py . | head -20第 3 步是关键。如果代码里出现了较新的AutoModelForCausalLM参数或者attn_implementation这类开关而你的 transformers 版本偏老报错信息会非常含糊常见的是TypeError: __init__() got an unexpected keyword argument看着像源码有 bug实际是版本不匹配。反过来版本太新也可能翻车一些自定义建模文件用了内部 API新版本一升级就失效。经验做法是先用requirements.txt给定的范围装一遍跑通之后再考虑升级别一上来就装最新版。trust_remote_codeTrue这件事要提前想清楚。如果模型结构是用仓库里的modeling_*.py自定义实现的加载时必须开这个开关而且那个 py 文件必须和权重放在同一个目录或者用--model-path指到包含它的路径。这一步没做对报错通常是「找不到类」或者「权重里有 unexpected key」后面第五章会细说。3. 跑通第一条推理从 config.json 到 chat template 对齐骨架读完了接着是最有成就感也最容易卡住的一步让它吐出一句人话。卡点基本不在模型本身而在两个地方——精度和模板。精度决定能不能加载模板决定输出像不像对话。这一章给的是能直接抄的流程跑通之后再谈参数调优。3.1 建环境三步把依赖装到不打架独立环境是底线别往系统 Python 里装。CUDA 版本和 torch 轮子的对应关系搞错会得到一堆看起来毫不相关的报错。# 1. 建独立环境Python 版本按 requirements.txt 的要求来 conda create -n glm4 python3.10 -y conda activate glm4 # 2. 先装 torch要和自己驱动支持的 CUDA 版本对齐 # cu121 只是示例按 nvidia-smi 右上角的版本号改 pip install torch --index-url https://download.pytorch.org/whl/cu121 # 3. 再装其余依赖避免 pip 顺手把 torch 降级 pip install -r requirements.txt pip install accelerate peft # 多卡切分和 LoRA 常用缺了会很别扭 # 4. 自检四行输出里任何一行不对先别往下走 python -c import torch, transformers; \ print(torch, torch.__version__); \ print(transformers, transformers.__version__); \ print(cuda, torch.version.cuda); \ print(device, torch.cuda.get_device_name(0) if torch.cuda.is_available() else CPU only)第 2 步和第 3 步的顺序不能换。先装requirements.txt再装 torchpip 的依赖解析很可能给你换一个不带 CUDA 的 CPU 版 torch症状是torch.cuda.is_available()返回 False但驱动明明正常这个坑非常浪费时间。另外accelerate不装的话device_mapauto会直接抛异常提示你缺包peft不装后面想做 LoRA 还得回头补。3.2 加载模型并跑通第一条输出权重目录和源码包是两个东西路径别写混。下面这段是最小可运行版本import torch from transformers import AutoModelForCausalLM, AutoTokenizer MODEL_PATH ./glm4-model # 权重目录必须包含 config.json 和自定义建模文件 # trust_remote_codeTrue结构是仓库自带 py 文件实现的必须开 tok AutoTokenizer.from_pretrained(MODEL_PATH, trust_remote_codeTrue) model AutoModelForCausalLM.from_pretrained( MODEL_PATH, torch_dtypetorch.bfloat16, # 老卡不支持 bf16 时改成 torch.float16 device_mapauto, # 多卡自动切分单卡也行 trust_remote_codeTrue, ).eval() messages [ {role: system, content: 你是一个严谨的代码助手。}, {role: user, content: 把一个左连接的 SQL 改写成子查询说明为什么这么改。}, ] # 关键用模型自带的模板拼 prompt别手写特殊 token inputs tok.apply_chat_template( messages, add_generation_promptTrue, # 补上让模型开始回答的前缀 return_tensorspt, return_dictTrue, # 同时拿到 attention_mask ).to(model.device) with torch.no_grad(): out model.generate(**inputs, max_new_tokens512, do_sampleFalse) # 只解码新生成的部分输入部分要切掉 new_tokens out[0][inputs[input_ids].shape[1]:] print(tok.decode(new_tokens, skip_special_tokensTrue))这段代码有三个易错点。第一个是apply_chat_template它按模型自带的模板把messages拼成带特殊分隔符的字符串。自己手拼|user|这类标记格式差一个空格模型表现就会明显变差而且不会报错只会让你怀疑模型能力不行。第二个是return_dictTrue它同时返回input_ids和attention_maskgenerate接收字典参数注意力掩码传不进去的话有 padding 的场景会算错。第三个是解码切片out里包含完整输入只 decode 全部内容会把你的问题也打出来一遍看起来像模型在复读。torch_dtype这里也给个判断依据安培架构之后的卡用 bf16更老的卡只能用 fp16但 fp16 容易在长序列上数值溢出表现为输出突然变成重复字符或者nan。不确定就先试 bf16加载报错再退回 fp16不要一开始就为了兼容性牺牲稳定性。3.3 生成参数与对话模板输出像不像人话全在这跑通之后输出质量就由生成参数和模板对齐决定了。下面这几个参数是我每次都要调的参数常用值作用与调法do_sample代码任务 False创作任务 True关闭采样就是贪婪解码同一输入输出稳定temperature0.1 到 0.7越低越保守超过 1 容易跑题top_p0.8 到 0.95和 temperature 二选一为主别同时拧到极端repetition_penalty1.05 到 1.15高了会前言不搭后语低了容易绕圈子max_new_tokens按业务给是新生成长度不是总长度别和max_length混用eos_token_id从 config 取需要传列表时不能只传单个 id最容易被误解的是max_new_tokens和max_length。前者是「最多新生成多少 token」后者是「输入加输出的总长度上限」。给一个很长的 prompt 又设了较小的max_length模型还没开始回答就停了输出是空字符串第一次遇到会以为是加载失败。我在代码里一律用max_new_tokens避免这个歧义。多轮对话的模板处理也要说清楚。正确做法是每轮把完整历史重新喂进messages让apply_chat_template统一处理而不是自己把上一轮的输出拼成一个字符串再塞进新问题。后者会把角色标记搞乱聊到第三四轮模型开始忘记系统提示词或者把用户的话当成自己说的这类问题排查起来非常费劲因为它不报错。4. 起一个兼容 OpenAI 协议的服务启动参数与并发边界本地脚本跑通只解决了一半问题真正落地要把它变成服务。好消息是这类 glm4 源码包通常自带一个 OpenAI 兼容的 API 入口前端和现有 SDK 几乎不用改就能接。麻烦的是启动参数和并发边界配错了要么起不来要么一上量就报错。4.1 找到真正的服务入口别照着 README 瞎猜不同仓库里服务脚本名字差异很大openai_api_server.py、api_server.py、serving/openai_api.py都有可能。与其一个个试不如直接从 argparse 定义反查# 找出所有定义了命令行参数的 py 文件服务入口一定有 grep -rln add_argument --include*.py . | head -20 # 再从候选里筛出带 uvicorn / FastAPI / 端口参数的 grep -rn uvicorn.run\|FastAPI\|--port\|--host --include*.py . | head -20筛出入口之后先跑--help看它接受哪些参数比读 README 可靠python openai_api_server.py --help # 常见的一组启动参数 python openai_api_server.py \ --model-path ./glm4-model \ --host 0.0.0.0 \ --port 8000 \ --device cuda:0 \ --dtype bfloat16 \ --max-model-len 8192--host 0.0.0.0是给容器或内网其它机器访问用的只在本机自测写127.0.0.1更安全。--device在多卡机器上要显式指定不指定有时会默认吃 0 号卡和别人的任务抢显存。--max-model-len直接决定 KV cache 能开多大这个值设得比实际需要大显存会被提前占掉设小了长输入会被截断且不报错属于典型的静默失败。4.2 用 curl 和 SDK 各打一次确认协议兼容服务起来之后先用最原始的方式确认它能返回再用 SDK 确认协议兼容# 最简请求先确认能返回 JSON不纠结内容质量 curl http://127.0.0.1:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: glm4, messages: [{role: user, content: 用一句话解释什么是 KV cache}], temperature: 0.2, max_tokens: 256, stream: false }from openai import OpenAI # base_url 指到服务的 /v1api_key 随便填本地服务通常不校验 client OpenAI(base_urlhttp://127.0.0.1:8000/v1, api_keyEMPTY) resp client.chat.completions.create( modelglm4, # 必须和服务端注册的模型名一致 messages[{role: user, content: 写一个 Python 的单例装饰器}], temperature0, max_tokens512, ) print(resp.choices[0].message.content) print(resp.usage) # 重点看 prompt_tokens 和 completion_tokens 是否符合预期SDK 这一层要是能通基本说明字段映射没问题。resp.usage值得单独看一眼如果prompt_tokens明显偏小说明模板没被正确应用服务端可能走了裸文本通道如果completion_tokens每次都贴着max_tokens说明停止符没生效模型在硬撑长度长期跑会明显拖慢吞吐。流式和同步两种模式的返回结构不同前端接入前要确认服务端支持哪一种。很多自带的实现只做了非流式前端传streamtrue会直接 500这个在联调阶段很常见。4.3 显存与并发的边界先把 max_model_len 算清楚服务能不能扛住并发取决于 KV cache 还剩多少显存。这个可以粗算KV cache 字节数 ≈ 2 × 层数 × kv_heads × head_dim × 序列长度 × 并发数 × 精度字节其中 head_dim ≈ hidden_size / num_attention_heads按num_hidden_layers40、num_key_value_heads2、head_dim128、序列 8192、并发 8、bf162 字节来算KV cache 大约 2.7 GB。权重按 9B 量级、bf16 算约 18 GB加起来二十出头一张 24 GB 的卡刚好卡在边缘。这也是为什么max_model_len不要一上来就拉到模型支持的上限先把并发和长度乘一遍再填。参数影响调法dtype权重显存优先 bf16老卡退 fp16max_model_lenKV cache 上限按真实业务长度设加大 20% 余量gpu_memory_utilization允许占用的显存比例和其它任务共卡时降到 0.8 以下最大并发数队列长度与排队延迟从 4 起压观察首 token 延迟张量并行度多卡切分单卡放不下再开切分有通信开销并发这块有个血泪经验单进程单模型的推理服务请求进来是排队串行处理的四五个并发还能忍十几个一起打首 token 延迟会爆炸。要真正提吞吐要么上框架自带的批处理调度要么起多个实例在前面做负载均衡别指望一个实例撑住几十个并发。压测时重点看两个指标首 token 延迟和整体吞吐前者决定体验后者决定成本只看平均响应时间没有意义。5. 排查清单六个把新手卡在下班前的坑下面这六条是我在几套不同的大模型源码包上反复遇到的按出现频率排。每条按现象、原因、解决来写对着改就行。5.1 加载与环境类的三个坑坑一开不开trust_remote_code都能加载但报错完全不同。现象AutoModel.from_pretrained报ValueError: ... requires you to execute the configuration file或者加载成功但输出全是乱码。原因这套 glm4 的模型结构是用仓库自带的modeling_*.py定义的不在 transformers 内置映射表里不开开关会走错分支开了开关但自定义文件没和权重放同一目录也会拿到不完整的结构。解决确认权重目录里同时存在config.json、modeling_*.py加载时统一加trust_remote_codeTrue如果用--model-path传路径确保路径指向的是这个目录而不是它的父目录。坑二显存够但加载阶段就 OOM。现象nvidia-smi看着还有十几 G 空闲from_pretrained却报CUDA out of memory。原因多数是 dtype 没指定默认按 fp32 加载权重显存直接翻倍另一部分是没有device_map所有层先往一张卡上堆。解决显式写torch_dtypetorch.bfloat16和device_mapauto后者需要accelerate。如果还是不够先用device_mapbalanced或者手动分层的max_memory参数把负载摊开。坑三tokenizer 找不到 chat template。现象调用apply_chat_template报TemplateError或者拼出来的字符串里一个特殊 token 都没有。原因模板可能放在独立的.jinja文件里也可能是老版本 tokenizer 配置里没有这个字段。解决先在目录里搜*.jinja和tokenizer_config.json里的chat_template键找到模板文件后用tokenizer.chat_template open(...).read()手动挂上去实在没有就照仓库里的示例脚本硬拼一遍但要把每个特殊 token 的 id 打印出来核对。5.2 输出质量与接口类的三个坑坑四回答完了还在自言自语。现象内容已经结束了后面还跟着一串对话标记或者重复内容。原因停止符判断不全eos_token_id在配置里是数组自己写推理逻辑时只判了一个 id或者解码时没加skip_special_tokensTrue把角色标记也当正文打出来了。解决从config.json或generation_config.json读出完整的eos_token_id列表传进去解码统一加skip_special_tokensTrue。坑五多轮对话聊到第三轮就失忆。现象前两轮正常第三轮开始忘记系统提示或者把用户的问题当成自己的回答。原因手工拼接历史角色标记顺序错乱或者把模型上一轮的输出错误地追加成了assistant之外的角色。解决每轮都重传完整的messages数组由apply_chat_template统一生成不要维护一个不断增长的字符串调试时把模板拼出来的原始字符串打印一次角色顺序一眼就能看出来。坑六本地脚本正常起服务一波并发就 500。现象curl单条请求正常压测几十个并发开始零星报错日志里是显存不足或者请求超时。原因单实例串行推理撑不住并发或者max_model_len按最长可能的输入设了KV cache 预留过大导致可用余量不足。解决先把max_model_len降到业务真实长度的 1.2 倍把gpu_memory_utilization留出 10% 余量并发需求确实高就起多实例做前面一层分发或者换用带连续批处理的服务框架。别在单实例上硬扛。6. 微调与量化落地用一份自测集验证改完的权重源码包真正的价值在后面它把训练侧脚本也放进来了。挂 LoRA 时我一般只改三处——数据格式、目标模块、输出目录。数据用 jsonl一行一条{messages:[...]}和推理时的模板保持一致这一步不一致训出来的模型在推理时表现会莫名其妙地差。目标模块常见的选择是注意力里的四个投影加 MLP 的三个投影# 典型的 LoRA 启动参数按仓库脚本的参数名微调 python finetune.py \ --model_path ./glm4-model \ --data_path ./data/train.jsonl \ --output_dir ./out-lora \ --lora_rank 16 \ --lora_alpha 32 \ --lora_dropout 0.05 \ --target_modules q_proj k_proj v_proj o_proj gate_proj up_proj down_proj \ --per_device_batch_size 2 \ --gradient_accumulation_steps 8 \ --learning_rate 1e-4 \ --num_train_epochs 2lora_rank和lora_alpha的比例大致保持 1:2dropout别超过 0.1否则小数据集上学不动。gradient_accumulation_steps是拿来凑等效批大小的显存吃紧时优先加大它而不是减小学习率。训练结束后千万别只看 loss 曲线就上线准备一份 30 到 50 条的固定自测集改前改后各跑一遍用do_sampleFalse保证可比逐条对比。量化环节同理。4bit 加载之后最该验证的不是「能不能跑」而是「行为有没有漂移」from transformers import BitsAndBytesConfig import torch bnb BitsAndBytesConfig( load_in_4bitTrue, bnb_4bit_compute_dtypetorch.bfloat16, # 计算精度别跟着降到 4bit bnb_4bit_quant_typenf4, )bnb_4bit_compute_dtype保持 bf16 是个关键细节把它也降下去生成质量会掉得很难看。量化后跑同一份自测集重点看两类指标格式化输出JSON、SQL、代码块是否还合法以及长回答有没有提前截断。前者对精度最敏感后者能暴露停止符判断的问题。从那以后我每次改完权重或者换量化配置都强制走一遍「固定自测集贪婪解码逐条 diff」这套流程宁可多花二十分钟也不在上线后被业务方拿着一条退化样本找上门。这套 glm4 源码包本身不复杂难的是把每一步的验证做扎实。希望帮到你。本文还有配套的精品资源点击获取

GLM4源码包部署实战：从解压配置到OpenAI兼容服务

相关推荐

模拟CMOS平方律曲线全链路：Cox、工作区、gm与ro

Oracle迁移KingbaseES实战指南与优化策略

iOS 自定义通知 UI：UNNotificationContentExtension 从配置到排错落地

更多资讯

Python基础：第 10 篇 · for 循环与 range：遍历的正确姿势

Python基础：第 09 篇 · while 循环：重复直到不满足

自动化测试学习全攻略：从零到精通

急热急冷热流道：省下多少成本，提多少良率

华为校招机考真题 AI方向 2026-10-23 选择题【真题及答案解析】

一键完整导出微信聊天记录：留痕 WeChatMsg

今日更新

GUI自动化测试中的ScreenLayout：从硬编码坐标到声明式画面地图

LLC谐振变换器12V25A 300W开关电源设计与调试全攻略

ESP32多应用Flash数据隔离：分区表与NVS namespace实战

本周精选

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

基于DRV8818与STM32的双极步进电机驱动方案实战解析

DRV8818PWPR+PIC18F45K80双极步进电机控制方案实战

本月热门

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

基于DRV8818与STM32的双极步进电机驱动方案实战解析

DRV8818PWPR+PIC18F45K80双极步进电机控制方案实战

读完文章，想聊聊您的网站？