English | 中文

预训练已成为自然语言处理任务中不可或缺的一部分。UER-py（通用编码器表示）是一个用于在通用领域语料库上进行预训练，并在下游任务上进行微调的工具包。UER-py 保持了模型的模块化设计，支持研究的可扩展性。它既便于用户使用现有的预训练模型，也提供了接口供用户进一步扩展。借助 UER-py，我们构建了一个包含多种不同特性的预训练模型库。完整的文档请参阅 UER-py 项目 Wiki。

🚀 我们已开源了 TencentPretrain，它是 UER-py 的重构新版本。TencentPretrain 支持多模态模型，并能够训练大规模模型。如果您对中等规模的文本模型（参数量少于十亿）感兴趣，我们建议您继续使用 UER-py 项目。

目录

• 功能特性
• 系统要求
• 快速入门
• 预训练数据
• 下游数据集
• 模型库
• 使用说明
• 竞赛解决方案
• 引用
• 联系方式

功能特性

UER-py 具有以下特点：

• 可复现性 UER-py 已在多个数据集上进行了测试，其性能应与原始预训练模型实现（如 BERT、GPT-2、ELMo 和 T5）相匹配。
• 模型模块化 UER-py 分为以下几个组件：嵌入层、编码器、目标嵌入层（可选）、解码器（可选）和目标。每个组件都实现了丰富的模块，清晰且健壮的接口使用户能够自由组合这些模块，以构建几乎不受限制的预训练模型。
• 模型训练 UER-py 支持 CPU 模式、单 GPU 模式以及分布式训练模式。
• 模型库 借助 UER-py，我们预训练并发布了多种不同特性的模型。合理选择预训练模型对于下游任务的性能至关重要。
• SOTA 结果 UER-py 支持全面的下游任务（例如分类和机器阅读理解），并提供了多项 NLP 竞赛的优胜方案。
• 丰富功能 UER-py 提供了与预训练相关的丰富功能，如特征提取器和文本生成等。

系统要求

• Python >= 3.6
• torch >= 1.1
• six >= 1.12.0
• argparse
• packaging
• regex
• 进行预训练模型转换（与 TensorFlow 相关）时，需要 TensorFlow
• 使用 sentencepiece 模型进行分词时，需要 SentencePiece
• 开发堆叠模型时，需要 LightGBM 和 BayesianOptimization
• 进行全词掩码的预训练时，需要像 jieba 这样的分词工具
• 在序列标注类下游任务中使用 CRF 时，需要 pytorch-crf

快速入门

本节通过几个常用示例展示如何使用 UER-py。更多详细内容请参阅“使用说明”部分。我们首先在书评情感分类数据集上使用 BERT（一种文本预训练模型）。先在书评语料库上对模型进行预训练，然后再在书评情感分类数据集上进行微调。输入文件共有三个：书评语料库、书评情感分类数据集和词汇表。所有文件均采用 UTF-8 编码，并包含在本项目中。

BERT 语料库的格式如下（每行为一句话，文档之间用空行分隔）：

doc1-sent1
doc1-sent2
doc1-sent3

doc2-sent1

doc3-sent1
doc3-sent2

书评语料库是从书评分类数据集中提取的。我们去除了标签，并从中间将每篇书评分成两部分，以构建一个包含两句话的文档（详见 corpora 文件夹中的 book_review_bert.txt）。

分类数据集的格式如下：

label    text_a
1        instance1
0        instance2
1        instance3

标签和实例之间用制表符 \t 分隔。第一行为列名列表。对于 n 分类问题，标签 ID 应为 0 到 n-1 之间的整数（包括 0 和 n-1）。

我们使用 Google 的中文词汇表文件 models/google_zh_vocab.txt，其中包含 21128 个汉字。

首先对书评语料库进行预处理。在预处理阶段，需要将语料库处理成指定预训练模型所需的格式（--data_processor）：

python3 preprocess.py --corpus_path corpora/book_review_bert.txt --vocab_path models/google_zh_vocab.txt \
                      --dataset_path dataset.pt --processes_num 8 --data_processor bert

请注意，需要安装 six>=1.12.0。

预处理过程较为耗时。使用多进程可以显著加快预处理速度（--processes_num）。默认使用 BERT 分词器（--tokenizer bert）。预处理完成后，原始文本会被转换为 dataset.pt，这是 pretrain.py 的输入。然后我们下载 Google 预训练的中文 BERT 模型 google_zh_model.bin（UER 格式，原始模型来自 这里），并将其放入 models 文件夹中。加载预训练的中文 BERT 模型后，我们继续在书评语料库上对其进行进一步预训练。预训练模型通常由嵌入层、编码器和目标层组成。为了构建预训练模型，我们需要提供相关信息。配置文件（--config_path）指定了预训练模型使用的模块和超参数。更多细节请参阅 models/bert/base_config.json。假设我们有一台配备 8 块 GPU 的机器：

python3 pretrain.py --dataset_path dataset.pt --vocab_path models/google_zh_vocab.txt \
                    --pretrained_model_path models/google_zh_model.bin \
                    --config_path models/bert/base_config.json \
                    --output_model_path models/book_review_model.bin \
                    --world_size 8 --gpu_ranks 0 1 2 3 4 5 6 7 \
                    --total_steps 5000 --save_checkpoint_steps 1000 --batch_size 32

mv models/book_review_model.bin-5000 models/book_review_model.bin

请注意，pretrain.py 训练得到的模型会附加一个记录训练步数的后缀（--total_steps）。我们可以去掉后缀以便于使用。

接下来，我们在下游分类数据集上对预训练模型进行微调。我们使用 pretrain.py 输出的 book_review_model.bin 中的嵌入层和编码器：

python3 finetune/run_classifier.py --pretrained_model_path models/book_review_model.bin \
                                   --vocab_path models/google_zh_vocab.txt \
                                   --config_path models/bert/base_config.json \
                                   --train_path datasets/book_review/train.tsv \
                                   --dev_path datasets/book_review/dev.tsv \
                                   --test_path datasets/book_review/test.tsv \
                                   --epochs_num 3 --batch_size 32

微调后的分类模型默认保存路径为 models/finetuned_model.bin。需要注意的是，预训练任务的实际批量大小是 --batch_size 乘以 --world_size；而下游任务（如分类）的实际批量大小则为 --batch_size。

随后，我们使用微调后的模型进行推理。

python3 inference/run_classifier_infer.py --load_model_path models/finetuned_model.bin \
                                          --vocab_path models/google_zh_vocab.txt \
                                          --config_path models/bert/base_config.json \
                                          --test_path datasets/book_review/test_nolabel.tsv \
                                          --prediction_path datasets/book_review/prediction.tsv \
                                          --labels_num 2

--test_path 指定待预测文件的路径，该文件应包含 text_a 列。--prediction_path 指定包含预测结果的文件路径。我们需要通过 --labels_num 显式指定标签数量。上述数据集为二分类数据集。

以上内容提供了使用 UER-py 进行预处理、预训练、微调和推理的基本方法。更多用法案例请参阅完整的 :arrow_right: 快速入门 :arrow_left: 。完整版快速入门包含了丰富的用例，覆盖了大多数与预训练相关的应用场景。建议用户阅读完整版快速入门，以便合理使用该项目。

预训练数据

本节提供了一系列 :arrow_right: 预训练数据 :arrow_left: 的链接。UER 可以直接加载这些预训练数据。

下游数据集

本节提供了一系列 :arrow_right: 下游数据集 :arrow_left: 的链接。UER 可以直接加载这些数据集。

模型库

借助 UER，我们预训练了多种不同特性的模型（例如基于不同语料库、编码器和目标的模型）。关于这些预训练模型的详细介绍及其下载链接，请参阅 :arrow_right: 模型库 :arrow_left: 。所有预训练模型均可被 UER 直接加载。

使用说明

UER-py 的目录结构如下：

UER-py/
    |--uer/
    |    |--embeddings/ # 包含嵌入组件的模块
    |    |--encoders/ # 包含编码器组件的模块，如 RNN、CNN、Transformer
    |    |--decoders/ # 包含解码器组件的模块
    |    |--targets/ # 包含目标组件的模块，如语言模型、掩码语言模型
    |    |--layers/ # 包含常用的神经网络层
    |    |--models/ # 包含 model.py，用于组合不同组件的模块
    |    |--utils/ # 包含常用的工具函数
    |    |--model_builder.py
    |    |--model_loader.py
    |    |--model_saver.py
    |    |--opts.py
    |    |--trainer.py
    |
    |--corpora/ # 包含预训练数据
    |--datasets/ # 包含下游任务数据集
    |--models/ # 包含预训练模型、词汇表和配置文件
    |--scripts/ # 包含用于预训练模型的实用脚本
    |--finetune/ # 包含下游任务微调脚本
    |--inference/ # 包含下游任务推理脚本
    |
    |--preprocess.py
    |--pretrain.py
    |--README.md
    |--README_ZH.md
    |--requirements.txt
    |--LICENSE

代码按照组件划分（例如嵌入、编码器等），用户可以轻松使用并进行扩展。

关于 UER 的全面使用示例，请参阅 :arrow_right: 使用说明 :arrow_left: ，这些示例可以帮助用户快速实现 BERT、GPT-2、ELMo、T5 等预训练模型，并在多种下游任务上对预训练模型进行微调。

竞赛解决方案

UER-py 已被用于多项 NLP 竞赛的获奖方案中。在本节中，我们提供了一些使用 UER-py 在 CLUE 等 NLP 竞赛中取得 SOTA 结果的案例。更多详细信息请参阅 :arrow_right: 竞赛解决方案 :arrow_left: 。

引用

如果您在学术研究中使用了 UER-py 中的工作（例如预训练模型），请引用发表于 EMNLP 2019 的 系统论文：

@article{zhao2019uer,
  title={UER: An Open-Source Toolkit for Pre-training Models},
  author={Zhao, Zhe and Chen, Hui and Zhang, Jinbin and Zhao, Xin and Liu, Tao and Lu, Wei and Chen, Xi and Deng, Haotang and Ju, Qi and Du, Xiaoyong},
  journal={EMNLP-IJCNLP 2019},
  pages={241},
  year={2019}
}

联系方式

有关本项目的沟通，请联系赵哲 (helloworld@alu.ruc.edu.cn; nlpzhezhao@tencent.com) 或李宇东 (liyudong123@hotmail.com) 或侯成 (chenghoubupt@bupt.edu.cn) 或史文航 (wenhangshi@ruc.edu.cn)。

本工作由企业导师 鞠琪、杨雪峰、邓浩堂 和学校导师 刘涛、杜晓勇 指导完成。

同时，我们也得到了刘伟杰、张鲁胜、崔建伟、李夏宇、毛伟权、赵欣、陈辉、张金彬、王志若、周鹏、刘海啸以及吴伟健等人的大力支持。

UER-py 快速上手指南

UER-py (Universal Encoder Representations) 是一个用于通用领域语料预训练及下游任务微调的 NLP 工具包。它支持模块化模型构建，兼容 BERT、GPT-2、ELMo、T5 等主流架构，并提供丰富的预训练模型库。

环境准备

系统要求

• Python: >= 3.6
• PyTorch: >= 1.1
• 操作系统: Linux / macOS / Windows

前置依赖

安装基础依赖包：

pip install torch>=1.1 six>=1.12.0 argparse packaging regex

可选依赖（按需安装）：

• TensorFlow: 用于转换 TensorFlow 格式的预训练模型。
• SentencePiece: 用于使用 SentencePiece 模型进行分词。

  # 建议从源码编译或使用 pip 安装
  pip install sentencepiece
  

• jieba: 用于全词掩码（Whole Word Masking）预训练时的中文分词。

  pip install jieba
  

• pytorch-crf: 用于序列标注任务中的 CRF 层。

  pip install pytorch-crf
  

• LightGBM & BayesianOptimization: 用于开发堆叠模型。

安装步骤

1. 克隆项目代码

   git clone https://github.com/dbiir/UER-py.git
   cd UER-py
   

2. 验证环境 确保 python3 可正常运行，且上述依赖已正确安装。项目无需额外的 setup.py 安装步骤，直接在根目录运行脚本即可。

基本使用

以下示例演示如何使用 UER-py 完成 数据预处理 -> 模型预训练 -> 下游任务微调 -> 推理 的全流程。本例基于书评情感分类任务，使用 BERT 架构。

1. 数据预处理

将原始文本语料转换为模型所需的 .pt 格式。 假设已有语料文件 corpora/book_review_bert.txt 和词表 models/google_zh_vocab.txt。

python3 preprocess.py --corpus_path corpora/book_review_bert.txt --vocab_path models/google_zh_vocab.txt \
                      --dataset_path dataset.pt --processes_num 8 --data_processor bert

提示: --processes_num 指定并行进程数，可显著加速处理过程。

2. 模型预训练 (或继续预训练)

加载现有的中文 BERT 模型并在书评语料上继续预训练。 需先下载 Google 中文 BERT 模型 (google_zh_model.bin) 并放入 models/ 目录。

python3 pretrain.py --dataset_path dataset.pt --vocab_path models/google_zh_vocab.txt \
                    --pretrained_model_path models/google_zh_model.bin \
                    --config_path models/bert/base_config.json \
                    --output_model_path models/book_review_model.bin \
                    --world_size 8 --gpu_ranks 0 1 2 3 4 5 6 7 \
                    --total_steps 5000 --save_checkpoint_steps 1000 --batch_size 32

注意:

• --world_size 为 GPU 数量，实际预训练 batch size = batch_size × world_size。
• 生成的模型文件名会附带步数后缀（如 book_review_model.bin-5000），使用时可重命名去除后缀。

mv models/book_review_model.bin-5000 models/book_review_model.bin

3. 下游任务微调

使用预训练好的模型在标注数据集上进行情感分类微调。 数据格式要求：第一行为表头，列之间用 \t 分隔（label, text_a）。

python3 finetune/run_classifier.py --pretrained_model_path models/book_review_model.bin \
                                   --vocab_path models/google_zh_vocab.txt \
                                   --config_path models/bert/base_config.json \
                                   --train_path datasets/book_review/train.tsv \
                                   --dev_path datasets/book_review/dev.tsv \
                                   --test_path datasets/book_review/test.tsv \
                                   --epochs_num 3 --batch_size 32

微调后的模型默认保存为 models/finetuned_model.bin。

4. 模型推理

使用微调后的模型对无标签数据进行预测。

python3 inference/run_classifier_infer.py --load_model_path models/finetuned_model.bin \
                                          --vocab_path models/google_zh_vocab.txt \
                                          --config_path models/bert/base_config.json \
                                          --test_path datasets/book_review/test_nolabel.tsv \
                                          --prediction_path datasets/book_review/prediction.tsv \
                                          --labels_num 2

参数说明:

• --test_path: 待预测文件路径（需包含 text_a 列）。
• --prediction_path: 预测结果输出路径。
• --labels_num: 明确指定分类类别数量（本例为 2 类）。

---

更多高级用法、模型配置详解及完整案例，请参考项目官方 Wiki。