CodeGeeX2 实战指南:多语言代码生成模型的部署、推理与评测(基于 ChatGLM2 架构)
CodeGeeX2 实战指南:多语言代码生成模型的部署、推理与评测(基于 ChatGLM2 架构)
导读:CodeGeeX2 是智谱 AI 推出的第二代多语言代码生成模型,基于 ChatGLM2-6B 架构并在 600B 代码数据上继续预训练,以 60 亿参数实现了超越 150 亿参数 StarCoder-15B 的代码生成能力。本文以官方 README(英文、中文及法语版本)为核心,结合本仓库的 demo、evaluation、scripts 与 docs 目录源码,系统讲解模型的快速调用、Prompt 语言标签规范、多精度/量化推理、多 GPU 推理、Mac 推理、fastllm 与 ChatGLM.cpp 加速方案,以及 HumanEval-X 评测复现方法,让读者既能快速上手,也能深入理解底层实现。
1. 模型定位与核心特性
CodeGeeX2 是多语言代码生成模型 CodeGeeX(KDD'23)的第二代迭代,基于 ChatGLM2 架构并针对代码语料做进一步预训练。相比完全在华为昇腾芯片平台上训练的一代模型,CodeGeeX2 借助 ChatGLM2 更优的架构与训练策略,在多项指标上取得显著提升(整体提升 +107%,仅 6B 参数即超过 15B 参数的 StarCoder-15B 近 10%)。官方 README 明确了以下四大特性:
- 更强的代码能力:在 ChatGLM2-6B 基座之上继续经过 600B 代码 token 预训练,在 HumanEval-X 六种语言上全面超越一代(Python +57%、C++ +71%、Java +54%、JavaScript +83%、Go +56%、Rust +321%);Python 上 Pass@1 达 35.9%。
- 更优的模型特性:支持中英文输入、最大 8192 token 序列长度;推理速度较 CodeGeeX-13B 大幅提升,INT4 量化后仅需约 5.5GB 显存即可本地部署。
- 更全面的 AI 编程助手:CodeGeeX 插件(VS Code、JetBrains)升级后支持超过 100 种编程语言,提供上下文补全、跨文件补全、Ask CodeGeeX 交互式问答(代码解释、翻译、纠错、文档生成等)。
- 更开放的协议:仓库代码遵循 Apache-2.0,模型权重遵循 Model License,学术研究完全开放,商业使用需填写登记表申请。
CodeGeeX2-6B 是一个**基座代码生成模型**,可完成代码补全 / 翻译 / 解释等任务,但未针对聊天做指令微调;如需聊天能力,请使用 CodeGeeX 插件中的 Ask CodeGeeX 功能。
2. 快速开始:使用 transformers 调用 CodeGeeX2-6B
2.1 环境准备
先克隆仓库并安装依赖(requirements.txt):
git clone https://github.com/THUDM/CodeGeeX2 # 或直接下载本仓库
cd CodeGeeX2
pip install -r requirements.txt
依赖清单中关键项包括:transformers>=4.30.2、torch>=2.0、accelerate、cpm_kernels、sentencepiece、gradio、protobuf。
2.2 最小推理示例
from transformers import AutoTokenizer, AutoModel
tokenizer = AutoTokenizer.from_pretrained("THUDM/codegeex2-6b", trust_remote_code=True)
model = AutoModel.from_pretrained("THUDM/codegeex2-6b", trust_remote_code=True, device='cuda') # CPU 推理则 device='cpu'
model = model.eval()
# TIP: 加入语言标签,引导模型生成指定语言的代码
prompt = "# language: Python\n# write a bubble sort function\n"
inputs = tokenizer.encode(prompt, return_tensors="pt").to(model.device)
outputs = model.generate(inputs, max_length=256, top_k=1) # 示例使用 greedy decoding
response = tokenizer.decode(outputs[0])
>>> print(response)
# language: Python
# write a bubble sort function
def bubble_sort(list):
for i in range(len(list) - 1):
for j in range(len(list) - 1):
if list[j] > list[j + 1]:
list[j], list[j + 1] = list[j + 1], list[j]
return list
print(bubble_sort([5, 2, 1, 8, 4]))
from_pretrained 会自动从 Hugging Face 下载权重;也可手动下载后改用本地路径:
git clone https://huggingface.co/THUDM/codegeex2-6b
model_path = "/path/to/codegeex2-6b"
tokenizer = AutoTokenizer.from_pretrained(model_path, trust_remote_code=True)
model = AutoModel.from_pretrained(model_path, trust_remote_code=True)
2.3 启动 Gradio Demo
仓库提供了开箱即用的 Gradio 界面(demo/run_demo.py):
python ./demo/run_demo.py
usage: run_demo.py [-h] [--model-path MODEL_PATH] [--example-path EXAMPLE_PATH] [--quantize QUANTIZE]
[--chatglm-cpp] [--fastllm] [--n-gpus N_GPUS] [--gpu GPU] [--cpu] [--auth] [--username yourname]
[--password yourpassword]
[--port PORT] [--listen ADDRESS]
常用参数(均来自 demo/run_demo.py 的参数定义):
| 参数 | 默认值 | 说明 |
|---|---|---|
--model-path |
THUDM/codegeex2-6b |
模型路径(HF ID 或本地目录) |
--quantize |
None |
量化位数,支持 4 / 8 |
--chatglm-cpp |
关闭 | 启用 chatglm-cpp 量化加速后端 |
--fastllm |
关闭 | 启用 fastllm 加速后端 |
--n-gpus |
1 |
使用多张显卡加载模型(需配合 demo/gpus.py) |
--gpu |
0 |
指定使用哪张 GPU |
--cpu |
关闭 | 强制使用 CPU 推理 |
--listen |
127.0.0.1 |
监听地址 |
--port |
7860 |
服务端口 |
--auth / --username / --password |
关闭 | 启用 HTTP Basic 身份认证 |
启动后浏览器打开 http://127.0.0.1:7860 即可交互式生成代码;--auth 启用认证示例:
python run_demo.py --auth --username user --password password # 若要监听所有地址请指定 --listen 0.0.0.0
Demo 界面的 Generation 参数滑块(demo/run_demo.py)对应:Seed(默认 8888)、Output Sequence Length(默认 128,最大 8192)、Temperature(默认 0.2)、Top K(默认 0)、Top P(默认 0.95),以及 Programming Language 下拉框(语言列表即 LANGUAGE_TAG)。
2.4 启动 FastAPI 服务(含 CPU 推理)
仓库还提供了 FastAPI 服务入口 demo/fastapicpu.py:
python ./demo/fastapicpu.py
usage: fastapicpu.py [-h] [--model-path MODEL_PATH] [--listen ADDRESS] [--port PORT] [--workers NUM] [--cpu] [--half] [--quantize QUANTIZE] [--chatglm-cpp]
# --cpu 启用 CPU 推理;--half 启用 .half()
HTTP 接口测试(POST 到 /):
curl -X POST "http://127.0.0.1:7860" \
-H 'Content-Type: application/json' \
-d '{"lang": "Python", "prompt": "# Write a quick sort function"}'
从源码可见,请求体支持 lang、prompt、max_length(默认 128)、top_p(默认 0.95)、temperature(默认 0.2)、top_k(默认 0)字段(demo/fastapicpu.py);若 lang != "None",服务端会自动拼接 LANGUAGE_TAG[lang] 语言标签后调用 model.chat(...) 生成。
3. Prompt 规范:语言标签与注释格式
这是影响生成质量最重要的实践细节。 CodeGeeX2 支持 100+ 种编程语言,调用时必须按特定格式组织 prompt:
- 在 prompt 开头添加语言标签,格式为
# language: Python这样的注释行,其中注释符随语言变化(如//、--、<!--等); - 以所选语言注释的形式书写描述,效果最佳。
示例(来自 demo/example_inputs.jsonl):
{"code": "# Write a quick sort function\n", "langauge": "Python"}
{"code": "// 写一个冒泡排序函数\n", "langauge": "C++"}
{"code": "// 写一个二叉树的类\npublic class", "langauge": "Java"}
{"code": "-- 查询品类最多的三种食品,但是不包含出现时间在2014年及之后\n", "langauge": "SQL"}
{"code": "// Write a simple file system that allows parallel read/write in Golang\n", "langauge": "Go"}
完整语言标签表维护在 evaluation/utils.py 的 LANGUAGE_TAG 字典中(含 c/c++/c#、go、rust、js、typescript、java、kotlin、sql、html、css、vue、solidity、fortran、matlab 等上百种)。Demo 侧维护了面向 UI 的独立映射 demo/run_demo.py(LANGUAGE_TAG),两者一致。调用时例如:
prompt = "# language: Python\n# write a bubble sort function\n"
若显卡不支持 `bfloat16`,直接以默认 BF16 精度推理会输出乱码,必须显式转为 FP16:`model = AutoModel.from_pretrained("THUDM/codegeex2-6b", trust_remote_code=True).half().cuda()`。
4. 推理优化与部署方案
4.1 多精度 / 量化推理(BF16/FP16/INT8/INT4)
CodeGeeX2 以 BF16 训练,推理支持 BF16/FP16/INT8/INT4。官方 README 给出不同精度下的显存占用(PyTorch 2.0 + torch.nn.functional.scaled_dot_product_attention 高效 Attention 计算条件下测得):
| 模型 | FP16/BF16 | INT8 | INT4 |
|---|---|---|---|
| CodeGeeX-13B | 26.9 GB | 14.7 GB | - |
| CodeGeeX2-6B | 13.1 GB | 8.2 GB | 5.5 GB |
INT4 量化推理示例(可下载官方转换好的 INT4 权重 THUDM/codegeex2-6b-int4,也可手动转换):
# 方式一:使用转换好的权重
model = AutoModel.from_pretrained("THUDM/codegeex2-6b-int4", trust_remote_code=True)
# 方式二:手动转换
model = AutoModel.from_pretrained("THUDM/codegeex2-6b", trust_remote_code=True).quantize(4).to("cuda")
# 方式三:显卡不支持 BF16 时,先转 FP16 再量化
model = AutoModel.from_pretrained("THUDM/codegeex2-6b", trust_remote_code=True).half().quantize(4).to("cuda")
若显卡不支持 BF16,务必先转为 FP16 再加载 / 量化,否则推理输出会出现乱码。量化逻辑在模型源码的 .quantize() 中实现(demo/run_demo.py 展示了 --quantize 4/8 时的调用:model.half().quantize(args.quantize))。
4.2 多 GPU 推理
使用仓库自带的 demo/gpus.py 实现多卡加载:
from gpus import load_model_on_gpus
model = load_model_on_gpus("THUDM/codegeex2-6b", num_gpus=2)
底层实现(demo/gpus.py)说明:模型共 30 个可分配单元(word_embeddings 1 层 + final_layernorm 和 lm_head 1 层 + encoder.layers 28 层),auto_configure_device_map 会按 GPU 数量均匀切分 28 个 transformer 层,并把 embedding、final_layernorm、lm_head、rotary_pos_emb 固定放置在第一张卡上,通过 accelerate.dispatch_model 完成分发。若同时启用 Gradio Demo,则使用 --n-gpus 2:
python ./demo/run_demo.py --n-gpus 2
4.3 Mac 推理(MPS 后端)
Apple Silicon / AMD GPU 的 Mac 可使用 PyTorch MPS 后端。先安装 nightly 版 PyTorch(版本形如 2.x.x.dev2023xxxx,如 2.1.0.dev20230729,参考 Apple 官方文档):
pip3 install --pre torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/nightly/cpu
MacOS 上仅支持从本地路径加载模型(需提前下载 codegeex2-6b / codegeex2-6b-int4 权重),支持 FP16/INT8/INT4,并使用 mps 设备:
model = AutoModel.from_pretrained(model_path, trust_remote_code=True).half().to('mps')
(demo/run_demo.py 的设备选择逻辑同样兼容 mps:在无 CUDA 且 mps 可用时自动回退到 mps。)
4.4 fastllm 加速推理
fastllm 是当时支持 GLM 架构的最快开源推理框架。安装步骤:
git clone https://github.com/ztxz16/fastllm
cd fastllm
mkdir build && cd build
# GPU 编译需先设置 CUDA 路径:export CUDA_HOME=/usr/local/cuda/bin:$PATH && export PATH=$PATH:$CUDA_HOME/bin
cmake .. -DUSE_CUDA=ON # 纯 CPU 编译则 cmake .. -DUSE_CUDA=OFF
make -j
cd tools && python setup.py install # 验证:python -c "import fastllm_pytools"
常见编译问题与修复(官方文档给出的两个坑):
- 架构不支持时,注释掉
CMakeLists.txt中的set(CMAKE_CUDA_ARCHITECTURES "native"); - E5 系列 CPU 报
error: inlining failed in call to 'always_inline' ... target specific option mismatch时,将CMakeLists.txt第 20 行改为:set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -pthread --std=c++17 -O2")。
将 Hugging Face 模型转换为 fastllm 格式并推理:
from transformers import AutoTokenizer, AutoModel
tokenizer = AutoTokenizer.from_pretrained("THUDM/codegeex2-6b", trust_remote_code=True)
model = AutoModel.from_pretrained("THUDM/codegeex2-6b", trust_remote_code=True)
from fastllm_pytools import llm
model = llm.from_hf(model, tokenizer, dtype="float16") # dtype 支持 "float16" / "int8" / "int4"
fastllm 的调用接口与 HF 不完全相同,参考 demo/run_demo.py 中的实现:
model.direct_query = True
outputs = model.chat(tokenizer, prompt, max_length=out_seq_length,
top_p=top_p, top_k=top_k, temperature=temperature)
response = outputs[0]
4.5 ChatGLM.cpp 量化加速(CPU/CUDA/Metal 全平台)
ChatGLM.cpp 是类似 LLaMA.cpp 的全平台量化加速方案,支持 q4_0/q4_1/q5_0/q5_1/q8_0 多种量化精度与 CPU/CUDA/Metal 后端。安装(如需 CUDA 加速,设置 CMAKE_ARGS="-DGGML_CUBLAS=ON"):
CMAKE_ARGS="-DGGML_CUBLAS=ON" pip install chatglm-cpp -v
一行代码加载并量化 HF 模型(dtype 可取 q4_0、q4_1、q5_0、q5_1、q8_0、f16):
import chatglm_cpp
pipeline = chatglm_cpp.Pipeline("THUDM/codegeex2-6b", dtype="q4_0") # 加载并量化为 int4
print(pipeline.generate("# language: Python\n# write a bubble sort function\n", do_sample=False))
仓库已集成该方案,Gradio Demo 与 FastAPI 服务均可一键启用:
python ./demo/run_demo.py --quantize 4 --chatglm-cpp # Gradio 开启 int4 (q4_0)
python ./demo/fastapicpu.py --quantize 4 --chatglm-cpp # FastAPI 同样支持
curl -X POST "http://127.0.0.1:7860" \
-H 'Content-Type: application/json' \
-d '{"lang": "Python", "prompt": "# Write a bubble sort function", "max_length": 512}'
从源码看,启用 chatglm-cpp 时 --quantize 取值 4/5/8 会映射为 q{quantize}_0 dtype(demo/run_demo.py),Gradio 的 predict 逻辑也会自动切换为该后端的 generate 调用(demo/run_demo.py)。
4.6 推理速度对比(官方 README 数据)
| 模型 | 推理速度(token/s) |
|---|---|
| CodeGeeX-13B | 32 |
| CodeGeeX2-6B | 94 |
测试条件:
batch_size=1, max_length=2048,使用加速框架,硬件为GeForce RTX-3090。速度提升得益于 Multi-Query Attention 与 Flash Attention 架构。
5. 能力评测:HumanEval / HumanEval-X / DS1000
CodeGeeX2 的 Pass@k 指标定义与 CodeGeeX 论文 一致。
5.1 HumanEval(Pass@1, 10, 100)
| 模型 | Pass@1 | Pass@10 | Pass@100 |
|---|---|---|---|
| CodeGen-16B-multi | 19.2 | 34.6 | 55.2 |
| CodeGeeX-13B | 22.9 | 39.6 | 60.9 |
| Codex-12B | 28.8 | 46.8 | 72.3 |
| CodeT5Plus-16B-mono | 30.9 | 51.6 | 76.7 |
| Code-Cushman-001 | 33.5 | 54.3 | 77.4 |
| LLaMA-65B | 23.7 | - | 79.3 |
| LLaMA2-70B | 29.9 | - | - |
| CodeGen2.5-7B-mono | 33.4 | 58.4 | 82.7 |
| StarCoder-15B | 33.2 | 61.0 | 84.7 |
| CodeGeeX2-6B | 35.9 | 62.6 | 88.3 |
Pass@1 采样配置
n=20, t=0.2, top_p=0.95;Pass@10 / Pass@100 采样配置n=200, t=0.8, top_p=0.95。
5.2 HumanEval-X(Pass@1,六语言)
| 模型 | Python | C++ | Java | JavaScript | Go | Rust | Overall |
|---|---|---|---|---|---|---|---|
| CodeGen-16B-multi | 19.2 | 18.1 | 15.0 | 18.4 | 13.0 | 1.8 | 14.2 |
| CodeGeeX-13B | 22.9 | 17.1 | 20.0 | 17.6 | 14.4 | 4.3 | 16.0 |
| Replit-code-v1-3B | 22.0 | 20.1 | 20.1 | 20.1 | 12.2 | 8.6 | 17.2 |
| CodeGen2.5-7B-multi | 30.6 | 24.3 | 29.0 | 27.5 | 18.9 | 20.1 | 25.1 |
| StarCoder-15B | 35.5 | 28.2 | 31.5 | 33.2 | 21.3 | 17.8 | 27.9 |
| CodeGeeX2-6B | 35.9 | 29.3 | 30.8 | 32.2 | 22.5 | 18.1 | 28.1 |
Pass@1 采样配置
n=20, t=0.2, top_p=0.95。
5.3 DS1000(Pass@1,Python 库生态)
| 模型 | Matplotlib | Numpy | Pandas | Pytorch | SciPy | Scikit-learn | TensorFlow | Overall |
|---|---|---|---|---|---|---|---|---|
| # Samples | 155 | 220 | 291 | 68 | 106 | 115 | 45 | 1000 |
| CodeGen-16B-Mono | 31.7 | 10.9 | 3.4 | 7.0 | 9.0 | 10.8 | 15.2 | 11.7 |
| code-cushman-001 | 40.7 | 21.8 | 7.9 | 12.4 | 11.3 | 18.0 | 12.2 | 18.1 |
| Codex-001 | 41.8 | 26.6 | 9.4 | 9.7 | 15.0 | 18.5 | 17.2 | 20.2 |
| CodeGeeX2-6B | 40.5 | 25.5 | 14.5 | 17.3 | 19.3 | 24.0 | 23.0 | 23.1 |
| StarCoder-15B | 51.7 | 29.7 | 11.4 | 21.4 | 20.2 | 29.5 | 24.5 | 26.0 |
| Codex-002 | 57.0 | 43.1 | 26.5 | 41.8 | 31.8 | 44.8 | 39.3 | 39.2 |
Pass@1 采样配置
n=40, t=0.2, top_p=0.5。
5.4 在本地复现 HumanEval-X 评测
仓库提供了完整的端到端评测复现脚本 scripts/run_humanevalx.sh,它会遍历 python / java / js / cpp / go / rust 六种语言,依次执行生成(generation.py)、评测(evaluation.py)与结果检查(inspect_jsonl.py)三个环节。默认配置为 pass@1 贪心解码:
MODE=both bash ./scripts/run_humanevalx.sh # MODE 可选 gen / eval / both
脚本内置了三套可切换的采样配置(scripts/run_humanevalx.sh):
- pass@1 greedy:
NUM_SAMPLES=1, TEMP=1.0, TOPK=1, TOPP=1.0; - pass@1 estimated:
NUM_SAMPLES=20, TEMP=0.2, TOPK=0, TOPP=0.95; - pass@10 & pass@100:
NUM_SAMPLES=200, MICRO_BSZ=4, TEMP=0.8, TOPK=0, TOPP=0.95。
数据集使用仓库内置的 benchmark/humanevalx 目录下的 .jsonl.gz 文件(如 humanevalx_python.jsonl.gz);评测时对每种语言还有专门的超时设置(Rust 的 TIMEOUT 会提升到 300 秒)。底层评测管线由三个模块构成(可从源码看到调用关系):
- evaluation/generation.py:基于 ZeroMQ 的多机分布式代码生成,支持
--greedy、--temperature、--top-p、--top-k、--samples-per-problem、--micro-batch-size等参数; - evaluation/evaluation.py:读取生成结果、按语言拼接 import helper 与测试用例(evaluation/utils.py 的
IMPORT_HELPER)、执行测试并计算 Pass@k; - evaluation/inspect_jsonl.py:汇总检查结果。
estimate_pass_at_k(evaluation/utils.py)实现了与论文一致的 Pass@k 估计公式 1 - C(n-c, k)/C(n, k),这也是 README 各表数值的统计口径。
DS1000 结果可通过官方 DS-1000 评测代码(HKUNLP/DS-1000)复现,仓库侧对应的数据读取逻辑位于 evaluation/utils.py 的 read_dataset 中。
6. AI 编程助手:IDE 插件中的 CodeGeeX2
官方为 VS Code、IntelliJ IDEA、PyCharm、GoLand、WebStorm、Android Studio 等 IDE 提供了 CodeGeeX 插件。插件后端升级后支持 100+ 编程语言,可直接体验 CodeGeeX2 的代码生成与补全、添加注释、代码翻译及技术问答能力,并可通过 Ask CodeGeeX 交互式对话完成代码总结、解释、翻译、注释等任务。
上图(resources/codegeex_demo.png)展示了插件左侧对话面板与右侧代码编辑区联动的典型场景:用户选中 chat.py 中的 print_time 函数并提问"解释一下这个函数",CodeGeeX 随即给出包含函数定义、变量作用、循环逻辑与线程模块调用的详细说明。这正是 Ask CodeGeeX 在代码理解场景下的落地形态。请在 IDE 插件市场中搜索 CodeGeeX 下载安装。
7. 许可证与引用
本仓库代码遵循 Apache-2.0 协议开源,模型权重遵循 Model License 约束:CodeGeeX2-6B 权重对学术研究完全开放;商业使用需填写登记表申请。
如本工作对你有帮助,欢迎引用(BibTeX 亦收录于 README):
@inproceedings{zheng2023codegeex,
title={CodeGeeX: A Pre-Trained Model for Code Generation with Multilingual Benchmarking on HumanEval-X},
author={Qinkai Zheng and Xiao Xia and Xu Zou and Yuxiao Dong and Shan Wang and Yufei Xue and Zihan Wang and Lei Shen and Andi Wang and Yang Li and Teng Su and Zhilin Yang and Jie Tang},
booktitle={Proceedings of the 29th ACM SIGKDD Conference on Knowledge Discovery and Data Mining},
pages={5673--5684},
year={2023}
}
8. 参考资源(仓库内)
- README.md:模型特性、快速开始、完整评测表格与协议说明
- README_EN.md / README_JA.md / README_FR.md:多语言版本
- docs/zh/inference_zh.md:推理教程(多精度/量化、多 GPU、Mac、fastllm、ChatGLM.cpp)
- demo/run_demo.py:Gradio Demo 与全部启动参数
- demo/fastapicpu.py:FastAPI 服务(支持 CPU 推理与 chatglm-cpp 加速)
- demo/gpus.py:多 GPU 加载与 device map 自动配置
- evaluation/utils.py:语言标签表、Pass@k 估计与评测工具函数
- scripts/run_humanevalx.sh:HumanEval-X 端到端评测复现脚本
- benchmark/humanevalx:HumanEval-X 六语言评测数据集(.jsonl.gz)
