CodeGeeX 13B 多语言代码生成模型全解析:架构原理、MindSpore 训练实践、GPU 推理部署与 HumanEval-X 评测实战

原创2026-10-13 19:30:181,997 阅读
文章标签:代码模型大模型基础模型预训练微调模型评测

CodeGeeX 13B 多语言代码生成模型全解析:架构原理、MindSpore 训练实践、GPU 推理部署与 HumanEval-X 评测实战

CodeGeeX 是一个拥有 130 亿参数的多编程语言代码生成预训练模型,由清华大学知识工程实验室、智谱 AI 与鹏城实验室联合研发,论文发表于 KDD 2023。本文以仓库根目录 README_zh.md 为主线,结合 codegeex/torch/codegeex_model.py、configs/codegeex_13b.sh、scripts/test_inference.sh 等源码与配置,系统讲解模型架构、训练语料、国产昇腾平台训练实践、单卡/量化/并行推理的完整操作流程,并深入介绍多语言评测基准 HumanEval-X 的构造、复现与结果解读,帮助读者从模型原理到工程部署建立完整认知。

一、CodeGeeX 是什么:130 亿参数的多语言代码生成模型

CodeGeeX 是一个具有 130 亿(13B)参数的多编程语言代码生成预训练模型,采用华为 MindSpore 框架实现,在鹏城实验室"鹏城云脑 II"中的 192 个节点(共 1536 个国产昇腾 910 AI 处理器,32GB 显存)上训练而成。截至 2022 年 6 月 22 日,CodeGeeX 历时约两个月,在 20 多种编程语言的代码语料库(超过 8500 亿 Token)上完成预训练。

根据官方文档,CodeGeeX 具备以下四大特点:

特点 说明
高精度代码生成 支持生成 Python、C++、Java、JavaScript、Go 等多种主流编程语言的代码,在 HumanEval-X 代码生成任务上取得 47%~60% 的求解率,较其他开源基线模型有更佳的平均性能
跨语言代码翻译 支持代码片段在不同编程语言间自动翻译转换,翻译结果正确率高,在 HumanEval-X 代码翻译任务上超越其他基线模型
自动编程插件 提供完全免费的 VS Code 与 Jetbrains 系列 IDE 插件,利用模型的少样本生成能力辅助代码编写
模型跨平台开源 所有代码与模型权重开源开放(研究用途),同时支持昇腾与英伟达平台,可在单张昇腾 910 或英伟达 V100/A100 上实现推理

此外,CodeGeeX 配套发布了全新多编程语言评测基准 HumanEval-X——第一个支持功能正确性评测的多语言、多任务基准,包含 820 个人工编写的高质量代码生成题目、测试用例与参考答案,覆盖 Python、C++、Java、JavaScript、Go 五种语言,支持代码生成与代码翻译两种能力评测,其详细说明见 codegeex/benchmark/README_zh.md。

二、模型架构:自回归解码器的源码级拆解

2.1 核心结构参数

CodeGeeX 是一个基于 Transformer 的大规模预训练编程语言模型:从左到右生成的自回归解码器,将代码或自然语言标识符(token)作为输入,预测下一个标识符的概率分布。核心结构参数如下:

参数 数值
Transformer 层数 40 层(39 个标准 Transformer 层 + 1 个 TopQuery 层)
自注意力块隐藏层维度 5120
前馈层维度 20480
注意力头数 40
最大序列长度 2048
总参数量 130 亿

关于层数需要说明:README 中描述模型"含有 40 个 transformer 层",而从 configs/codegeex_13b.sh 的配置看 --num-layers 39,结合 codegeex/torch/codegeex_model.py 中 Transformer 类的实现可以推断:模型主体由 39 个 TransformerLayer 加上 1 个 TopQueryLayer(top-query 自注意力层)组成,合计 40 层注意力模块,与文档描述一致。

2.2 关键模块的源码实现

  • TopQuery 层:Transformer 类在 39 个 TransformerLayer 之后额外堆叠了 TopQueryLayer(见 codegeex/torch/codegeex_model.py),它使用 QueryEmbedding 提供的 top-query 位置嵌入作为 query,对主干网络的输出做一次额外的自注意力计算,这是 CodeGeeX 区别于常规 GPT 类模型的显著结构特点。
  • 激活函数:MLP 使用 fast_gelu(MindSpore 的 FastGelu 实现),定义为 x / (1 + exp(-1.702 * |x|)) * exp(0.851 * (x - |x|)),见 codegeex/torch/codegeex_model.py,与训练阶段算子融合的 FastGelu 保持一致的数值行为。
  • 精度策略:--attention-softmax-in-fp32 保证注意力 softmax 在 FP32 下计算以提高稳定性,--fp16 表示模型主体以半精度推理。
  • 词表对齐:配置中的 --make-vocab-size-divisible-by 52224 将词表 padding 到 52224(padded_vocab_size),便于张量并行切分,tests/test_inference.py 中的 --padded-vocab-size 52224 与此对应。

2.3 分词与空白编码

CodeGeeX 使用与 GPT-2 相同的 BPE 分词器(词表大小 50400),并将连续空格编码为特殊标识符以提升代码缩进的处理效果。在 codegeex/tokenizer/tokenizer.py 中,encode_whitespaces 将长度为 2~10 的连续空格替换为 <|extratoken_10|> 至 <|extratoken_18|> 形式的特殊 token,decode_whitespaces 在解码时将其还原。配置中的 --ws-encoding-start-id 10 --ws-encoding-length 10 即对应 start_extra_id=10, max_len=10 这两个空白编码参数。

2.4 自回归生成流程

codegeex/torch/inference.py 中的 sample_sequence_batch 实现了典型的 KV-Cache 增量解码:首步对完整上下文做一次前向,之后每步只输入最后一个 token 并复用 layer_past(key/value 缓存)逐步生成,直至生成 EOS 或达到 out_seq_length。采样阶段支持 greedy、top-k、top-p 与温度控制,top_k_logits 的实现见 codegeex/torch/inference.py。顶层封装 codegeex.generate 位于 codegeex/init.py,接受 prompt、out_seq_length、top_k、top_p、temperature、micro_batch_size 等参数,返回解码后的生成代码列表。

三、训练语料:23 种语言、1587 亿 Token

CodeGeeX 的训练语料由两部分组成:

  1. 开源代码数据集:The Pile 与 CodeParrot。其中 The Pile 包含 GitHub 上拥有超过 100 颗星的部分开源仓库,CodeGeeX 从中选取了 23 种编程语言的代码。
  2. 补充数据:直接从 GitHub 开源仓库爬取 Python、Java、C++ 代码。为保证高质量,仓库选取遵循以下准则:① 至少拥有 1 颗星;② 总大小小于 10MB;③ 不在此前的开源代码数据集中。

同时,符合下列任一条件的文件会被剔除:

  • 平均每行长度大于 100 字符;
  • 由自动生成得到;
  • 含有的字母不足字母表内的 40%;
  • 大于 100KB 或小于 1KB。

为了让模型区分不同语言,每个样本开头会加上形如 <a href="https://link.gitcode.com/i/058bf7240dd176ae7cd757892d56a93b" target="_blank">注释符] language: [语言] 的前缀,例如 # language: Python。整个代码语料共含 23 种编程语言,总计 1587 亿个标识符(不含填充符)。在评测代码生成时,[codegeex/benchmark/utils.py 的 process_extra_prompt 会为提示自动补充语言标签前缀。

四、国产平台训练实践:1536 个昇腾 910 上的两月征程

CodeGeeX 在 MindSpore 1.7 框架上实现,并使用鹏城实验室的全国产计算平台训练。具体来说:

  • 硬件规模:一个计算集群中的 1536 个昇腾 910 AI 处理器(32GB),训练周期约两个月(2022 年 4 月 18 日至 6 月 22 日)。
  • 混合精度:除 LayerNorm 与 Softmax 使用 FP32 以获得更高精度与稳定性外,模型参数整体使用 FP16,整个模型约占 27GB 显存。
  • 并行策略:8 路模型并行 + 192 路数据并行,微批大小(micro-batch)为 16,全局批大小(global batch)为 3072,并采用 ZeRO-2 优化器降低显存占用。

在开发与训练过程中,团队与华为 MindSpore 团队合作对框架进行了多项针对性优化,大幅提升训练效率:

  • 算子时间剖析:发现矩阵乘法计算时间占比仅为 22.9%,大量时间消耗在各类其他算子上;
  • 算子融合:实现单元素算子融合、层归一化算子融合、FastGelu 与矩阵乘法融合、批量矩阵乘法与加法融合等;
  • 矩阵乘法维度自动调优:自动搜索效率最高的计算维度组合。

这些优化带来显著收益:在同等 GPU 卡数规模下(128 卡),昇腾 910 对 CodeGeeX 的训练效率从约为 NVIDIA A100 的 16.7% 提升至 43%;在千卡规模下,昇腾 910 训练效率相比自身优化前提升近 300%。使用优化后的软硬件训练时,CodeGeeX 单日训练量可达 54.3B 个标识符(含填充符),验证了国产深度学习平台与工具的快速迭代能力与竞争力。

五、使用指南一:环境安装

CodeGeeX 最初使用 MindSpore 框架实现并在昇腾 910 AI 芯片上训练;为适配更多平台,官方将其转换到 Megatron-LM 框架,支持 PyTorch + GPU 环境。

环境要求:Python 3.7+ / CUDA 11+ / PyTorch 1.10+ / DeepSpeed 0.6+。

git clone https://gitcode.com/gh_mirrors/co/CodeGeeX.git
cd CodeGeeX
pip install -e .

六、使用指南二:模型权重下载与合并

通过官方模型申请页面提交申请后,会收到一封包含临时下载链接文件 urls.txt 的邮件。推荐使用 aria2 快速下载(请保证硬盘有足够的空间存放权重,约 26GB):

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 推理实战

7.1 配置文件解析

推理前,需要先在配置文件 configs/codegeex_13b.sh 中写明权重存放路径 CHECKPOINT_PATH。该文件中的核心模型参数如下:

参数 值 含义
--num-layers 39 Transformer 层数(另有 1 个 TopQuery 层)
--hidden-size 5120 隐藏层维度
--num-attention-heads 40 注意力头数
--max-position-embeddings 2048 最大位置编码长度
--attention-softmax-in-fp32 - 注意力 softmax 以 FP32 计算
--layernorm-epsilon 1e-5 LayerNorm 的 epsilon
--fp16 - 半精度推理
--ws-encoding-start-id 10 空白编码起始 token id
--ws-encoding-length 10 空白编码长度
--make-vocab-size-divisible-by 52224 词表 padding 对齐大小
--seq-length 2048 输入序列长度上限

多卡并行版本见 configs/codegeex_13b_parallel.sh,其并行检查点文件按 mp_rank_0{i}_model_states.pt 格式命名(i 为 rank,从 0 开始)。

7.2 编写提示文件

将提示(可以是任意描述或代码片段)写入 tests/test_prompt.txt。仓库自带示例是一个"代码翻译"任务:给出 Java 的 hasCloseElements 函数实现,要求模型续写 Python 版本:

code translation
Java:
public class Solution {
    public static boolean hasCloseElements(int[] nums, int threshold) {
        for (int i = 0; i < nums.length - 1; i++) {
            for (int j = i + 1; j < nums.length; j++) {
                if (Math.abs(nums[i] - nums[j]) < threshold) {
                    return true;
                }
            }
        }
        return false;
    }
}
Python:

7.3 三种推理方式

# 方式一:单 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

# 方式三:多 GPU 模型并行(每卡超过 6GB 显存)
# 先转换 checkpoint 为 MP_SIZE 份并行分片
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

7.4 推理脚本的源码剖析

scripts/test_inference.sh 是单卡推理入口:它通过 source 引入 configs/codegeex_13b.sh 的模型配置,用 CUDA_VISIBLE_DEVICES 指定 GPU,并调用 tests/test_inference.py 执行推理。默认采样参数为 --temperature 0.8 --top-p 0.95 --top-k 0 --greedy(greedy 模式下忽略温度与 top-p),输出序列长度为 1024,微批大小为 1。

tests/test_inference.py 的完整加载流程为:加载 CodeGeeXTokenizer(mode 为 codegeex-13b)→ 用 torch.load 载入 state dict(取 state_dict["module"])→ 构建 CodeGeeXModel → model.half() 转为 FP16 → 可选 quantize(model, weight_bit_width=8, backend="torch") → 读入提示文件 → 循环调用 codegeex.generate 生成。脚本还支持交互式输入:启动后逐行输入查询(Ctrl-D 结束多行输入,"stop" 退出)。

量化原理:量化推理通过 codegeex/quantization/quantize.py 的 quantize 函数将各层的 query/key/value/dense 及 MLP 线性层替换为 W8A16 量化线性层(权重 8-bit、激活 16-bit),配合 codegeex/kernels 中的反量化内核在运行时恢复权重,从而将显存占用从约 27GB 降至约 15GB。

并行推理:多卡场景先由 scripts/convert_ckpt_parallel.sh 调用 codegeex/megatron/convert_ckpt_parallel.py 将完整权重按张量并行大小切分,再由 scripts/test_inference_parallel.sh 通过 torchrun --nproc_per_node <MP_SIZE> 启动 tests/test_inference_megatron.py 分布式推理。仓库中还有 OneFlow、Paddle、MindSpore 等平台的对应推理实现与脚本,如 scripts/test_inference_oneflow.sh、scripts/test_inference_paddle.sh,可参考 codegeex/oneflow/inference.py、codegeex/paddle/inference.py。

八、插件生态:VS Code 与 JetBrains

基于 CodeGeeX 开发的免费插件支持 VS Code 与 Jetbrains IDEs,未来会支持更多平台。

  • VS Code 版本:在应用市场搜索"codegeex"即可安装,详细使用指南见 vscode-extension/README_zh.md,插件源码位于仓库的 vscode-extension/codegeex-vscode-extension 目录。
  • Jetbrains 版本:在 Plugins 市场搜索"codegeex"安装,需确保 IDE 版本在 2021.1 或更高。目前支持 IntelliJ IDEA、PyCharm、GoLand、CLion、Android Studio、AppCode、Aqua、DataSpell、DataGrip、Rider、RubyMine、WebStorm 等。

九、HumanEval-X:多语言代码生成与翻译基准

9.1 设计动机

此前,多语言代码生成能力通常基于语义相似度(如 CodeBLEU)衡量,具有一定误导性;HumanEval-X 则用于衡量生成代码的功能正确性。HumanEval-X 包含 820 个高质量手写样本,覆盖 Python、C++、Java、JavaScript、Go 五种语言,可支持多种下游任务。

9.2 任务定义与指标

HumanEval-X 中每个语言的样本包含声明(函数声明)、描述(文档字符串)与解答(参考答案)三部分,组合后可支持生成、翻译、概括等任务,目前官方关注两个任务:

  • 代码生成:模型将函数声明与文档字符串作为输入,输出函数实现;
  • 代码翻译:模型将两种语言的函数声明与源语言的实现作为输入,输出目标语言上的实现。翻译任务中不输入文档字符串,以避免模型直接通过描述生成答案。

两种任务均采用 Codex 论文所使用的无偏 pass@k 指标判断生成代码的功能正确性:

pass@k:=E[1−(n−ck)(nk)],n=200, k∈(1,10,100)\text{pass}@k := \mathbb{E}\left[1-\frac{\binom{n-c}{k}}{\binom{n}{k}}\right],\quad n=200,\ k\in(1,10,100)

其中 n 为每个问题采样的候选解数量(200),c 为通过测试的候选解数量。该无偏估计的实现见 codegeex/benchmark/metric.py 的 estimate_pass_at_k,其通过 1 - prod(1 - k / arange(n - c + 1, n + 1)) 完成计算,避免了对有偏朴素估计的直接套用。

9.3 数据格式

样本以 JSON 列表格式存储在 codegeex/benchmark/humaneval-x/<a href="https://link.gitcode.com/i/d47368872f9e156e1d52376d8a664249" target="_blank">LANG]/data/humaneval_[LANG].jsonl.gz(如 [codegeex/benchmark/humaneval-x/python/data/humaneval_python.jsonl.gz),每条样本包含 6 个部分:

字段 说明
task_id 题目的目标语言与 ID,语言为 Python / Java / JavaScript / CPP / Go 之一
prompt 函数声明与描述,用于代码生成
declaration 仅有函数声明,用于代码翻译
canonical_solution 手写的示例解答
test 隐藏测例,用于评测
example_test 提示中出现的公开测例,用于评测

9.4 评测环境

评测生成的代码需要使用多种语言编译、运行,官方使用的各编程语言依赖及版本如下:

依赖 版本
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

熟悉 Dockerfile 的读者也可以从 codegeex/docker/Dockerfile 自行构建或定制:

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>

9.5 生成与评测流程

第一步:生成代码。运行 scripts/generate_humaneval_x.sh 对指定语言逐题采样(默认温度 0.8、top-p 0.95、每问题采样数、seed 42),内部由 codegeex/benchmark/humaneval-x/generate_humaneval_x.py 通过 ZeroMQ 通道在分布式 worker 之间分发任务:

bash scripts/generate_humaneval_x.sh <LANG> <OUTPUT_PATH> [HOSTLIST]

第二步:整理结果。将生成的代码按如下 JSON 列表格式存储(每行一条):

{"task_id": "../..", "generation": "..."}
{"task_id": "../..", "generation": "..."}

第三步:执行评测。在仓库根目录运行:

bash scripts/evaluate_humaneval_x.sh <RESULT_FILE> <LANG> <N_WORKERS>

⚠️ 安全警告:请谨慎执行评测。生成的代码可能以极低概率产生意外行为。请在 codegeex/benchmark/humaneval-x/execution.py 中查看警告并取消执行代码的注释,风险自负。

评测内部流程如下(见 codegeex/benchmark/humaneval-x/evaluate_humaneval_x.py):

  1. 读取题目集与生成结果;
  2. 按语言组装测试代码:Python 会注入 IMPORT_HELPER 中的常用 import(math、re、itertools、numpy 等,见 codegeex/benchmark/utils.py);Go/C++/JS/Java 分别写入独立临时目录并调用对应编译/运行工具链;
  3. 用 ThreadPoolExecutor(n_workers) 并行执行每个样本的测试用例(codegeex/benchmark/humaneval-x/execution.py 的 check_correctness),Python 环境还启用了 reliability_guard 禁用危险系统调用并设置超时;
  4. 汇总通过数,调用 estimate_pass_at_k 计算 pass@1 / pass@10 / pass@100。

脚本默认参数为 N_WORKERS=64、LANGUAGE=python、TIMEOUT=5 秒,可通过 scripts/evaluate_humaneval_x.sh 的第 4 个位置参数调整超时时间。

十、实验结果:多语言代码生成

HumanEval-X 在五种语言上的具体 pass@k(k=1, 10, 100)性能及所有语言上的平均性能表明:CodeGeeX 的平均表现优于 InCoder-6.7B 与 CodeGen-Multi-6B/16B。

官方将 CodeGeeX 与另外两个开源代码生成模型进行了比较:Meta 的 InCoder 与 Salesforce 的 CodeGen,选取对比对象为 InCoder-6.7B、CodeGen-Multi-6B 与 CodeGen-Multi-16B。结果显示:

  • CodeGeeX 能获得最佳的平均性能,显著超越参数量更小的模型(提升 7.5%~16.3%);
  • 与参数量更大的 CodeGen-Multi-16B 表现相当(平均性能 54.76% vs. 54.39%)。

十一、实验结果:跨语言代码翻译

官方同时评测了模型在多语言间代码翻译上的性能。对于 CodeGeeX,评测对象包括未经微调的 CodeGeeX-13B 与经过微调的 CodeGeeX-13B-FT(使用 XLCoST 中代码翻译任务的训练集与一部分 Go 语言数据微调)。

结果呈现两个值得注意的现象:

  1. 语言偏好:模型对特定语言存在偏好。例如 CodeGeeX 擅长将其他语言翻译为 Python 与 C++,而 CodeGen-Multi-16B 擅长翻译为 JavaScript 和 Go,这可能源于训练集中各语言语料占比的差异;
  2. 翻译对负相关:在 20 个翻译对中,两种语言互相翻译的表现常常呈负相关,这可能说明现有模型还不足以学好所有的语言。

如需在本地复现翻译任务的生成,可参考 scripts/translate_humaneval_x.sh 与 codegeex/benchmark/humaneval-x/translate_humaneval_x.py。

十二、许可证与引用

如果本工作对你有帮助,欢迎引用以下论文:

@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}
}
登录后查看全文
CodeGeeX