CodeGeeX 多语言代码生成模型实战指南:架构解析、推理部署与 HumanEval-X 评测
CodeGeeX 多语言代码生成模型实战指南:架构解析、推理部署与 HumanEval-X 评测
CodeGeeX 是一个面向 20 多种编程语言、拥有 130 亿参数的代码生成预训练模型,本文以其官方中文文档为骨架,结合仓库源码与配置文件,系统讲解其模型架构、训练数据、MindSpore/昇腾国产平台实现、GPU 推理部署步骤(含量化与模型并行),以及配套的多语言代码生成基准 HumanEval-X 的数据格式、评测环境与评测流程。读完本文,你将能够独立完成 CodeGeeX-13B 的安装、权重获取、单卡/量化/多卡推理,并复现 HumanEval-X 上的代码生成与代码翻译评测。
CodeGeeX 概览与核心能力
CodeGeeX 是一个具有 130 亿参数的多编程语言代码生成预训练模型,采用华为 MindSpore 框架实现,在鹏城实验室"鹏城云脑II"中的 192 个节点(共 1536 个国产昇腾 910 AI 处理器)上训练而成。截至 2022 年 6 月 22 日,CodeGeeX 历时两个月,在 20 多种编程语言的代码语料库(>8500 亿 Token)上完成预训练。官方文档归纳了以下四大特点:
- 高精度代码生成:支持生成 Python、C++、Java、JavaScript 和 Go 等多种主流编程语言的代码,在 HumanEval-X 代码生成任务上取得 47%~60% 求解率,较其他开源基线模型具有更佳的平均性能。
- 跨语言代码翻译:支持代码片段在不同编程语言间自动翻译转换,翻译结果正确率高,在 HumanEval-X 代码翻译任务上超越了其它基线模型。
- 自动编程插件:基于 CodeGeeX 开发的插件已上架 VS Code 插件市场(完全免费),利用其强大的少样本生成能力,可自定义代码生成风格,辅助代码编写。
- 模型跨平台开源:所有代码和模型权重开源开放,用作研究用途;CodeGeeX 同时支持昇腾和英伟达平台,可在单张昇腾 910 或英伟达 V100/A100 上实现推理。
同时,该项目还发布了全新的多编程语言评测基准 HumanEval-X——第一个支持功能正确性评测的多语言、多任务基准,包含 820 个人工编写的高质量代码生成题目、测试用例与参考答案,覆盖 Python、C++、Java、JavaScript、Go 五种语言,可同时评测代码生成与代码翻译能力(详见 codegeex/benchmark/README_zh.md)。
快速开始:安装与模型权重
环境要求与安装
官方文档要求的环境版本为:Python 3.7+ / CUDA 11+ / PyTorch 1.10+ / DeepSpeed 0.6+。仓库根目录的 requirements.txt 中还列出了其余依赖(如 fire、pyzmq、regex、transformers、cpm_kernels、deepspeed>0.6.1 等)。
git clone https://gitcode.com/zai-org/CodeGeeX
cd CodeGeeX
pip install -e .
获取模型权重
模型权重需要通过官方申请渠道获取(约 26GB)。申请成功后,会收到一封包含临时下载链接文件 urls.txt 的邮件。推荐使用 aria2 并行加速下载:
aria2c -x 16 -s 16 -j 4 --continue=true -i urls.txt
下载完成后合并分片并解压得到完整权重:
cat codegeex_13b.tar.gz.* > codegeex_13b.tar.gz
tar xvf codegeex_13b.tar.gz
用 GPU 进行推理
推理分为三步:先写配置文件,再准备提示文件,最后运行脚本。完整链路可对照 scripts/test_inference.sh 与 tests/test_inference.py 源码理解。
第一步:配置权重路径。 编辑 configs/codegeex_13b.sh,将 CHECKPOINT_PATH 修改为实际存放 codegeex_13b.pt 权重的路径。该文件同时定义了模型全部关键超参,具体如下:
| 参数 | 值 | 说明 |
|---|---|---|
--num-layers |
39 | Transformer 层数(官方架构文档描述为 40 层,发布配置中为 39,以仓库配置为准) |
--hidden-size |
5120 | 隐藏层维度 |
--num-attention-heads |
40 | 注意力头数 |
--max-position-embeddings |
2048 | 最大序列长度 |
--attention-softmax-in-fp32 |
- | 注意力 Softmax 以 FP32 计算,保证精度与稳定 |
--layernorm-epsilon |
1e-5 | LayerNorm 的 epsilon |
--fp16 |
- | 使用 FP16 推理 |
--ws-encoding-start-id / --ws-encoding-length |
10 / 10 | 空格(whitespace)特殊编码的起始 id 与长度 |
--make-vocab-size-divisible-by |
52224 | 词表大小对齐到 52224,便于模型并行切分 |
--seq-length |
2048 | 模型输入序列长度 |
--load |
权重路径 | 加载检查点 |
第二步:准备提示。 将任意描述或代码片段写入 tests/test_prompt.txt。仓库自带的示例是一个"代码翻译"任务:先给出 Java 版本的 hasCloseElements 函数实现,再以 Python: 结尾引导模型续写出 Python 版本,这与 HumanEval-X 翻译任务的 prompt 构造方式(见下文)一脉相承。
第三步:运行推理脚本。 需指定 GPU 序号:
# 单卡推理(需显存大于 27GB)
bash ./scripts/test_inference.sh <GPU_ID> ./tests/test_prompt.txt
# 量化推理(需显存大于 15GB)
bash ./scripts/test_inference_quantized.sh <GPU_ID> ./tests/test_prompt.txt
# 多卡推理(每卡显存需大于 6GB,且需先将权重切分为 MP 分片)
bash ./scripts/convert_ckpt_parallel.sh <LOAD_CKPT_PATH> <SAVE_CKPT_PATH> <MP_SIZE>
bash ./scripts/test_inference_parallel.sh <MP_SIZE> ./tests/test_prompt.txt
test_inference.sh 通过 source 导入模型配置,然后调用 tests/test_inference.py 完成推理。其采样参数在脚本中设定为:--micro-batch-size 1、--out-seq-length 1024、--temperature 0.8、--top-p 0.95、--top-k 0、--greedy(脚本注释提示"remove --greedy if using sampling",即去掉该参数即可切换为随机采样)。test_inference.py 中的 add_code_generation_args 给出了这些参数的默认值与语义:temperature 为采样温度(默认 1.0)、top-p/top-k 为截断式采样参数、out-seq-length 为输出长度、--interative 可开启交互式多轮输入(默认关闭时也会进入循环输入模式,输入 stop 退出)。推理时模型通过 codegeex/megatron/inference.py 的 model_provider 构建,并在 codegeex.generate 中指定 backend="megatron"。
量化推理(scripts/test_inference_quantized.sh)在命令中追加 --quantize 标志并改用更低的采样温度 0.2。量化底层实现在 codegeex/quantization/quantize.py 中,核心是 W8A16Linear 与 QuantizedLinear:权重以 8-bit(或 4-bit)量化存储并配合逐通道缩放因子 weight_scale,推理时通过 extract_weight_to_half 还原为半精度参与矩阵乘,从而把显存占用从 27GB 降到 15GB。
多卡模型并行:先运行 scripts/convert_ckpt_parallel.sh 调用 codegeex/megatron/convert_ckpt_parallel.py 将完整权重切分为 MP_SIZE 份(注意该脚本把 CUDA_VISIBLE_DEVICES 固定为 0,1,切分时需两块 GPU);切分后的检查点按 mp_rank_0{i}_model_states.pt(i 为 rank,从 0 开始)的格式命名。随后 scripts/test_inference_parallel.sh 会依据 MP_SIZE 自动选择 configs/codegeex_13b_parallel.sh(MP_SIZE>1 时)或单卡配置(MP_SIZE=1 时),并通过 torchrun --nproc_per_node $MP_SIZE 拉起分布式推理,使用 tests/test_inference_megatron.py 作为入口。
插件使用指南
基于 CodeGeeX 的免费插件支持 VS Code 与 JetBrains IDEs:
- VS Code 版本:在应用市场搜索"codegeex"安装(要求 VS Code 版本不低于 1.68.0)。详细使用指南见 vscode-extension/README_zh.md,插件源码也在仓库内。该插件提供四种模式:
- 隐匿模式:停止输入时从光标处自动续写,灰色候选按
Tab插入,Alt/Option+[或]切换候选,Alt/Option+N获取新候选; - 交互模式:按
Ctrl+Enter生成多个候选并显示在右侧窗口,候选数量可在设置的Candidate Num中修改; - 翻译模式:选中代码后按
Ctrl+Alt+T,将代码翻译为当前编辑器语言的代码,可配置插入时注释或覆盖原文; - 提示模式(实验功能):按
Alt/Option+t触发,基于少样本能力自定义模板实现代码解释、概括、特定风格生成等功能,模板由[示例代码]、<INPUT>(选中代码的插入位置)、<INPUT:0,1>(保证针对同一函数)等占位符构成,可在设置Prompt Templates中添加自定义模板文件。
- 隐匿模式:停止输入时从光标处自动续写,灰色候选按
- JetBrains 版本:在 Plugins 市场搜索"codegeex"安装,要求 IDE 版本在 2021.1 或更高,目前支持 IntelliJ IDEA、PyCharm、GoLand、CLion、Android Studio、AppCode、Aqua、DataSpell、DataGrip、Rider、RubyMine、WebStorm。
模型架构与训练细节
架构:CodeGeeX 是一个基于 transformers 的大规模预训练编程语言模型,本质是从左到右生成的自回归解码器——将代码或自然语言标识符(token)作为输入,预测下一个标识符的概率分布。按官方文档,模型含有 40 个 transformer 层,每层自注意力块的隐藏层维数为 5120、前馈层维数为 20480,总参数量为 130 亿,支持的最大序列长度为 2048。这些超参(除层数外)与 configs/codegeex_13b.sh 及 tests/test_inference.py 中的默认值一致,也从侧面印证了配置文件的含义。
语料:训练语料由两部分组成。第一部分是开源代码数据集 The Pile 与 CodeParrot:The Pile 包含 GitHub 上拥有超过 100 颗星的部分开源仓库,从中选取 23 种编程语言的代码。第二部分是补充数据,直接从 GitHub 开源仓库爬取 Python、Java、C++ 代码,选取准则为:1) 至少拥有 1 颗星;2) 总大小 <10MB;3) 不在此前的开源代码数据集中。同时剔除符合下列任一条件的文件:1) 平均每行长度大于 100 字符;2) 由自动生成得到;3) 含有的字母不足字母表内的 40%;4) 大于 100KB 或小于 1KB。
为了让模型区分不同语言,每个样本开头都加上了 <a href="https://link.gitcode.com/i/07ddd288aee18f8f430c4b51be173c4a" target="_blank">注释符] language: [语言] 形式的前缀,例如 # language: Python。这一机制在推理链路中仍然保留:[codegeex/data/data_utils.py 中的 LANGUAGE_TAG 定义了 60 余种语言的注释前缀映射,process_extra_prompt 会在生成与翻译时自动把 # language: Python、// language: Java 等前缀拼接到 prompt 之前;tests/test_prompt.txt 中 Python:、Java: 的写法正是这种格式的延续。
模型使用与 GPT-2 相同的分词器,并将空格处理为特殊标识符,词表大小为 50400;配置文件中 --make-vocab-size-divisible-by 52224 与 --ws-encoding-start-id 10 --ws-encoding-length 10 则是为模型并行切分与空格编码预留的对齐参数。整个代码语料含有 23 种编程语言、总计 1587 亿个标识符(不含填充符)。
国产平台实现与训练
CodeGeeX 在 MindSpore 1.7 框架上实现,并在鹏城实验室的全国产计算平台(1536 个昇腾 910 AI 处理器,32GB 显存)上进行了约两个月的训练(2022 年 4 月 18 日至 6 月 22 日)。训练细节:
- 精度策略:除 LayerNorm 与 Softmax 使用 FP32 以获得更高精度与稳定性外,模型参数整体使用 FP16,整个模型约占用 27GB 显存。
- 并行策略:8 路模型并行 + 192 路数据并行,微批大小为 16、全局批大小为 3072,并采用 ZeRO-2 优化器降低显存占用。
在开发与训练过程中,团队与华为 MindSpore 团队合作对框架进行了针对性优化以提升训练效率:发现矩阵乘法计算时间占比仅 22.9%(大量时间耗费在其它算子),因此实现了一系列算子融合,包括单元素算子融合、层归一化算子融合、FastGelu 与矩阵乘法融合、批量矩阵乘法与加法融合等;同时还对矩阵乘法算子维度实现自动搜索调优。这些优化带来的收益是:在同等 GPU 卡数规模下(128 卡),昇腾 910 对 CodeGeeX 的训练效率从约为 NVIDIA A100 的 16.7% 提升至 43%;在千卡规模下,昇腾 910 训练效率相比自身优化前提升近 300%。使用优化后的软硬件训练时,CodeGeeX 单日训练量可达到 54.3B 个标识符(含填充符)。
HumanEval-X:多语言代码生成基准
为更好地评测代码生成模型的多语言生成能力,项目构建了新基准 HumanEval-X。此前的多语言代码生成评测基于语义相似度(如 CodeBLEU),具有一定误导性;HumanEval-X 则直接衡量生成代码的功能正确性。它包含 820 个高质量手写样本,覆盖 Python、C++、Java、JavaScript、Go,可用于多种任务。完整使用说明见 codegeex/benchmark/README_zh.md。
数据结构与任务定义
样本以 JSON 列表格式存储在 codegeex/benchmark/humaneval-x/[LANG]/data/humaneval_[LANG].jsonl.gz,每条样本包含 6 个字段:
task_id:题目的目标语言与 ID,语言为 ["Python", "Java", "JavaScript", "CPP", "Go"] 之一;prompt:函数声明与描述(docstring),用于代码生成;declaration:仅有函数声明,用于代码翻译;canonical_solution:手写的示例解答;test:隐藏测例,用于评测;example_test:提示中出现的公开测例,用于评测。
HumanEval-X 中每个语言的样本包含声明、描述和解答三部分,其组合可支持生成、翻译、概括等不同下游任务。项目目前聚焦两个任务:
- 代码生成:模型将函数声明与文档字符串作为输入,输出函数实现;
- 代码翻译:模型将两种语言的函数声明与源语言的实现作为输入,输出目标语言的实现。翻译任务中不输入文档字符串,以避免模型直接通过描述生成答案。
两个任务均采用 Codex 提出的无偏 pass@k 指标衡量生成代码的功能正确性:pass@k := E<a href="https://link.gitcode.com/i/505f4fe255bfbb0eec66a09f96b616de" target="_blank">1 - C(n-c, k)/C(n, k)],其中 n=200、k∈{1,10,100}。该指标的无偏估计实现在 [codegeex/benchmark/metric.py 的 estimate_pass_at_k 中:当 n-c < k 时返回 1.0,否则按 1 - ∏(1 - k/(n-c+1..n)) 计算,避免了对多次采样后取平均产生的有偏估计。
评测环境
评测生成代码需要在多种语言环境中编译运行,官方使用的依赖版本如下:
| 依赖 | 版本 |
|---|---|
| Python | 3.8.12 |
| JDK | 18.0.2.1 |
| Node.js | 16.14.0 |
| js-md5 | 0.7.3 |
| C++ | 11 |
| g++ | 7.5.0 |
| Boost | 1.71.0 |
| OpenSSL | 3.0.0 |
| go | 1.18.4 |
为省去配置多语言环境的麻烦,官方构建了 Docker 镜像。可直接拉取:
docker pull rishubi/codegeex:latest
也可以从 codegeex/docker/Dockerfile 自行构建(该 Dockerfile 基于 pytorch/pytorch:1.11.0-cuda11.3-cudnn8-runtime,内置 Go 1.18.4、Node.js 16.14.0 + js-md5 0.7.3、Boost 1.71.0、OpenSSL 3.0.0、JDK 18,并预装了 CodeGeeX 与评测依赖):
cd codegeex/docker
docker build [OPTIONS] .
创建容器时建议挂载本地数据目录:
docker run -it --gpus all --mount type=bind,source=<LOCAL PATH>,target=<PATH IN CONTAINER> [OPTIONS] <IMAGE NAME:TAG>
评测流程
先在 codegeex/benchmark/humaneval-x/ 下运行生成脚本得到各语言的结果。单机单卡直接传语言与输出路径即可;HOSTLIST 参数可指定 hostfile 以分布式生成(脚本会基于 ZeroMQ 建立调度通道,端口在 5000~9000 区间随机选取)。生成脚本内部采样参数为 temperature 0.8、top-p 0.95、out-seq-length 1024、samples-per-problem 1、seed 42,并调用 codegeex/benchmark/humaneval-x/generate_humaneval_x.py:
bash scripts/generate_humaneval_x.sh <LANG> <OUTPUT_PATH> [HOSTLIST]
生成结果会被 scripts/gather_output.sh 汇总为 JSON 列表格式文件:
{"task_id": "../..", "generation": "..."}
{"task_id": "../..", "generation": "..."}
...
随后在仓库根目录执行评测脚本(请谨慎执行:生成代码可能有极低概率产生意外行为。默认评测代码被注释,可查看 codegeex/benchmark/execution.py 中的警告并取消执行代码的注释,风险自负):
bash scripts/evaluate_humaneval_x.sh <RESULT_FILE> <LANG> <N_WORKERS>
scripts/evaluate_humaneval_x.sh 中 LANGUAGE 支持 python/java/cpp/js/go 之一,N_WORKERS 默认 64、超时默认 5 秒,脚本最终调用 codegeex/benchmark/humaneval-x/evaluate_humaneval_x.py 的 evaluate_functional_correctness:它会按语言把生成的代码与测试用例拼装成可执行程序(不同语言的拼装规则见该文件的 process_humaneval_test,例如 Python 自动注入 IMPORT_HELPER 中的常用 import,Go 则基于 test_setup 与 IMPORT_HELPER 动态补充包引用),并用多线程池并行执行、逐题判断通过与否,最终按 codegeex/benchmark/metric.py 的 estimate_pass_at_k 汇总出 pass@1/10/100。仓库的 generations/ 目录还提供了 Python 与 Rust 的生成结果样例可供参考。
代码生成与代码翻译结果
多语言代码生成:官方将 CodeGeeX 与两个开源模型对比——Meta 的 InCoder-6.7B、Salesforce 的 CodeGen-Multi-6B 与 CodeGen-Multi-16B。结果显示 CodeGeeX 获得最佳的平均性能:相较参数量更小的模型(6B 级)有 7.5%~16.3% 的提升,与参数量更大的 CodeGen-Multi-16B 表现相当(平均性能 54.76% vs 54.39%),同时显著提升了 InCoder-6.7B 与 CodeGen-Multi-6B(README 中亦给出 HumanEval-X 上五语言各自 pass@1/10/100 的具体对比)。
跨语言代码翻译:官方评测了未微调的 CodeGeeX-13B 与微调后的 CodeGeeX-13B-FT(后者使用 XLCoST 中代码翻译任务的训练集与一部分 Go 语言数据微调)。结果观察到模型对特定语言存在偏好,例如 CodeGeeX 擅长将其他语言翻译为 Python 与 C++,而 CodeGen-Multi-16B 擅长翻译为 JavaScript 和 Go,这可能是训练集中语料占比差异所致;在全部 20 个翻译对中,两种语言互相翻译的表现常常呈负相关,说明现有模型还不足以学好所有语言。翻译任务的 prompt 构造逻辑见 codegeex/benchmark/utils.py 的 read_translation_dataset:以 code translation\n 开头,依次拼接源语言声明、源语言解答、目标语言声明,与 tests/test_prompt.txt 的示例格式完全一致。翻译生成脚本为 scripts/translate_humaneval_x.sh(对应 codegeex/benchmark/humaneval-x/translate_humaneval_x.py),用法为 bash scripts/translate_humaneval_x.sh <LANG_SRC> <LANG_TGT> <OUTPUT_PATH> [HOSTLIST]。
许可证与引用
- 代码使用 Apache-2.0 许可证;
- 模型使用 模型许可证。
如使用本工作,欢迎引用 KDD 2023 论文:
@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}
}
如果遇到问题或有任何建议,可通过项目文档中提供的邮箱与团队联系。