PaddleNLP PP-UIE 数据标注指南:使用 doccano 构建命名实体识别、关系抽取与事件抽取训练数据
PaddleNLP PP-UIE 数据标注指南:使用 doccano 构建命名实体识别、关系抽取与事件抽取训练数据
本文以 PaddleNLP 通用信息抽取大模型 PP-UIE 的轻定制训练流程为背景,完整讲解基于开源标注平台 doccano 的"安装 → 项目创建 → 数据上传 → 标签构建 → 任务标注 → 数据导出 → 数据转换"全链路操作,并结合仓库中的 doccano.py 与 utils.py 源码,深入说明标注数据如何被转换为可训练模型所需的指令格式。读完本文,你将能够独立完成从零标注一批命名实体识别(NER)、关系抽取(RE)或事件抽取(EE)数据,并一键生成 PP-UIE 模型微调所需的 train/dev/test 数据集。
1. 数据标注在 PP-UIE 定制训练中的位置
PP-UIE 是 PaddleNLP 团队基于开源模型与高质量数据集构建的通用信息抽取大模型,支持统一训练命名实体识别(NER)、关系抽取(RE)与事件抽取(EE)三类任务,模型包含 0.5B、1.5B、7B、14B 四个版本(详见 information_extraction README)。
对于简单的抽取目标,可以直接通过 paddlenlp.Taskflow 实现零样本(zero-shot)抽取;但对于细分垂类场景,PaddleNLP 推荐使用轻定制功能——标注少量数据(例如几十条)进行模型微调,以进一步提升效果。README 中以"报销工单信息抽取"为例,展示了如何通过少量训练数据完成 PP-UIE 微调。
该应用目录的代码结构如下:
llm/application/information_extraction/
├── README.md # PP-UIE 应用总览(开箱即用 + 训练定制)
├── doccano.md # 数据标注指南(本文主题)
├── doccano.py # doccano 导出数据 → 训练数据 的转换脚本
└── utils.py # 数据转换与负例构造的核心工具
其中"从标注到训练"的关键通道就是:doccano 平台标注 → 导出 JSONL → doccano.py 转换 → run_finetune.py 微调。本文聚焦于该通道中的标注环节与数据转换环节。
2. doccano 安装与环境配置
doccano 是一个开源的文本标注平台,参考其官方文档完成安装与初始配置即可。
本文标注示例使用的环境版本为:
- doccano 1.6.2
说明:后续导出的 JSONL(relation) 文件格式以该版本为基准。从 utils.py 的解析代码可以看到,转换脚本读取的是
{"text": ..., "relations": [...], "entities": [...]}结构,即 doccano 1.7.0 及以上版本的 JSONL 导出格式与 1.6.2 的 JSONL(relation) 格式均可被正确解析。
3. 项目创建:为抽取式任务建项目
PP-UIE 面向抽取类型的任务,需要根据实际业务创建一个新的标注项目。
创建项目时的关键配置:
- 任务类型选择 序列标注(Sequence Labeling)
- 勾选 Allow overlapping entity(允许实体重叠)
- 勾选 Use relation Labeling(启用关系标注)
这三项配置可以适配命名实体识别、关系抽取、事件抽取等全部 PP-UIE 支持的抽取任务:
- 命名实体识别只需要 Span(实体片段)标注;
- 关系抽取在 Span 基础上还需要在实体之间建立 Relation;
- 事件抽取需要标注触发词(Span)、事件论元(Span)以及"触发词 → 论元"的 Relation。
勾选"允许重叠实体"非常必要:中文文本中经常出现嵌套实体(例如"北京大学"既是机构名也包含地名"北京"),开启后可以对重叠片段分别标注。
4. 数据上传:TextLine 格式统一约定
上传的原始数据文件为 txt 格式,每一行是一条待标注文本,示例:
2月8日上午北京冬奥会自由式滑雪女子大跳台决赛中中国选手谷爱凌以188.25分获得金牌
第十四届全运会在西安举办
上传数据时,数据类型选择 TextLine。
NOTE:doccano 支持 TextFile、TextLine、JSONL 和 CoNLL 四种数据上传格式,PP-UIE 定制训练中统一使用 TextLine 这一文件格式。即上传的文件必须为 txt 格式,且数据标注时,该文件的每一行待标注文本会显示为一页内容,便于逐条标注。
5. 标签构建:Span 与 Relation 两种标签类型
抽取式任务包含 Span 与 Relation 两种标签类型:
| 标签类型 | 含义 | 典型用途 |
|---|---|---|
| Span | 原文本中的目标信息片段 | 实体识别中某类型的实体;事件抽取中的触发词和论元 |
| Relation | 原文本中 Span 之间的关系 | 关系抽取中两个实体(Subject & Object)之间的关系;事件抽取中论元和触发词之间的关系 |
- Span 类型标签构建示例:定义如"时间""选手""赛事名称""得分"等实体类型标签,标注时在文本中框选对应片段并赋予类型。
- Relation 类型标签构建示例:定义如"歌手""发行时间""所属专辑"等关系类型标签,标注时从 Subject 实体指向 Object 实体建立关系。
6. 任务标注:三类抽取任务的标注方法与 schema 设计
6.1 命名实体识别(NER)
命名实体识别是指识别文本中具有特定意义的实体。在开放域信息抽取中,抽取的类别没有限制,用户可以自己定义。
标注示例中定义了 时间、选手、赛事名称 和 得分 四种 Span 类型标签,对应的 schema 为:
schema = [
'时间',
'选手',
'赛事名称',
'得分'
]
标注时只需为每条文本中的实体片段指定对应 Span 标签,不需要建立任何 Relation。该 schema 可直接用于 PP-UIE 的 Taskflow('information_extraction') 零样本抽取(参考 README 实体抽取示例)。
6.2 关系抽取(RE)
关系抽取是指从文本中识别实体并抽取实体之间的语义关系,即抽取三元组(实体一,关系类型,实体二)。
标注示例中定义了 作品名、人物名 和 时间 三种 Span 类型标签,以及 歌手、发行时间 和 所属专辑 三种 Relation 标签。Relation 标签由 Subject 对应实体指向 Object 对应实体(例如从"作品名"实体指向"人物名""时间"等实体)。
该标注示例对应的 schema 为:
schema = {
'作品名': [
'歌手',
'发行时间',
'所属专辑'
]
}
schema 的键是作为抽取主体的 Span 类型,值是挂在该主体下的关系类型列表。转换后,模型将被要求针对每个"主体 + 关系"的提示给出对应的客体实体。
6.3 事件抽取(EE)
事件抽取是指从自然语言文本中抽取事件并识别事件类型和事件论元的技术。UIE 所包含的事件抽取任务,是指根据已知事件类型,抽取该事件所包含的事件论元。
标注示例中定义了 地震触发词(触发词)、等级(事件论元)和 时间(事件论元)三种 Span 标签,以及 时间 和 震级 两种 Relation 标签。
事件抽取标注有两项硬性约定:
- 触发词标签统一格式为
XX 触发词,XX表示具体事件类型。上例中的事件类型是地震,则对应触发词为地震触发词; - Relation 标签由触发词指向对应的事件论元。
该标注示例对应的 schema 为:
schema = {
'地震触发词': [
'时间',
'震级'
]
}
可以看到,事件抽取在标注层面与关系抽取同构:触发词充当"主体",事件论元充当"客体"。
7. 数据导出:导出 JSONL(relation) 格式
标注完成后,在 doccano 平台上选择导出的文件类型为 JSONL(relation)。
导出的数据示例(每条样例占一行,存储为 json 格式):
{
"id": 38,
"text": "百科名片你知道我要什么,是歌手高明骏演唱的一首歌曲,1989年发行,收录于个人专辑《丛林男孩》中",
"relations": [
{
"id": 20,
"from_id": 51,
"to_id": 53,
"type": "歌手"
},
{
"id": 21,
"from_id": 51,
"to_id": 55,
"type": "发行时间"
},
{
"id": 22,
"from_id": 51,
"to_id": 54,
"type": "所属专辑"
}
],
"entities": [
{
"id": 51,
"start_offset": 4,
"end_offset": 11,
"label": "作品名"
},
{
"id": 53,
"start_offset": 15,
"end_offset": 18,
"label": "人物名"
},
{
"id": 54,
"start_offset": 42,
"end_offset": 46,
"label": "作品名"
},
{
"id": 55,
"start_offset": 26,
"end_offset": 31,
"label": "时间"
}
]
}
标注数据保存在同一个文本文件中,每条样例占一行,包含以下字段:
| 字段 | 说明 |
|---|---|
id |
样本在数据集中的唯一标识 ID |
text |
原始文本数据 |
entities |
数据中包含的 Span 标签,每个 Span 标签包含四个字段 |
relations |
数据中包含的 Relation 标签,每个 Relation 标签包含四个字段 |
Span 标签(entities 数组元素)的四个字段:
id:Span 在数据集中的唯一标识 ID;start_offset:Span 的起始 token 在文本中的下标;end_offset:Span 的结束 token 在文本中下标的下一个位置(即左闭右开区间,text<a href="https://link.gitcode.com/i/64eac3f74002a2c57b4da016f312a1a6" target="_blank">start_offset:end_offset]即为实体原文,这一点与 [utils.py 中text[entity["start_offset"] : entity["end_offset"]]的切片取实体名的逻辑一致);label:Span 类型。
Relation 标签(relations 数组元素)的四个字段:
id:(Span1, Relation, Span2) 三元组在数据集中的唯一标识 ID,不同样本中的相同三元组对应同一个 ID;from_id:Span1 对应的标识 ID(Subject);to_id:Span2 对应的标识 ID(Object);type:Relation 类型。
8. 数据转换:doccano.py 一键生成训练集
该章节详细说明如何通过 doccano.py 脚本对 doccano 平台导出的标注数据进行转换,一键生成训练/验证/测试集。
8.1 转换步骤
- 标注完成后,在 doccano 平台上导出
JSONL(relation)形式的文件,并将其重命名为doccano_ext.json,放入./data目录下; - 通过 doccano.py 脚本进行数据形式转换,然后便可以开始进行相应模型训练。
转换命令:
python doccano.py \
--doccano_file ./data/doccano_ext.json \
--save_dir ./data \
--negative_ratio 1
8.2 可配置参数说明
基于 doccano.py 中 argparse 的实际定义,各参数如下:
| 参数 | 说明 | 默认值 |
|---|---|---|
doccano_file |
从 doccano 导出的数据标注文件 | ./data/doccano_ext.json |
save_dir |
训练数据的保存目录 | ./data |
negative_ratio |
最大负例比例,该参数只对抽取类型任务有效,适当构造负例可提升模型效果。负例数量和实际的标签数量有关,最大负例数量 = negative_ratio × 正例数量 | 5 |
splits |
划分数据集时训练集、验证集、测试集所占的比例,默认为 [0.8, 0.1, 0.1],即按 8:1:1 划分 |
[0.8, 0.1, 0.1] |
task_type |
选择任务类型,目前只有信息抽取(ie)这一种任务 |
ie |
is_shuffle |
是否对数据集进行随机打散 | False |
seed |
随机种子 | 1000 |
schema_lang |
选择 schema 的语言,可选 ch 和 en,英文数据集请选择 en |
ch |
参数说明与源码细节:
negative_ratio:构造负例的核心参数。从 utils.py 中add_entity_negative_example可以看到,负例生成逻辑是:对每条文本,取"全局标签集合与当前文本实际出现标签集合的差集"作为冗余标签,再按negative_ratio × 正例数量抽样构造负例(负例的目标输出固定为无相应实体)。关系负例则在 utils.py 中按negative_ratio // 3分为三类构造:反向关系(把 Subject/Object 对调)、实体替换(用其他实体名替换主体)、标签替换(用其他标签类型替换关系),最后用收集到的备选样本补足到目标负例数量。splits:当splits非空时其长度必须为 3,且三项之和必须等于 1(源码用Decimal精确求和校验,见 doccano.py)。转换时会同时生成train.json、dev.json、test.json以及记录划分索引的sample_index.json。is_shuffle:注意原标注指南中写"默认为 True",但当前仓库源码 doccano.py 中该参数的默认值为"False"(通过strtobool解析,即实际默认 False),README 同样标注为默认 False,实际使用以仓库当前实现为准。schema_lang:直接影响转换后指令的构造方式。从 utils.py 可以看到:中文(ch)关系提示格式为主体 + "的" + 关系(如"作品名的歌手"),英文(en)格式为关系 + " of " + 主体(如singer of 作品名)。因此英文数据集必须选择en,否则生成的提示语与语言习惯不匹配。seed:通过set_seed(utils.py)同步设置 Paddle、Pythonrandom与 NumPy 的随机种子,保证负例抽样与数据打散结果可复现。
8.3 转换产物与底层指令格式
转换后的每条训练样本是一条 {"src": ..., "tgt": ...} 格式的 JSON 行,其中 src 由 utils.py 中定义的阅读理解模板拼接而成:
你是一个阅读理解专家,请提取所给句子与问题,提取实体。请注意,如果存在实体,则一定在原句中逐字出现,请输出对应实体的原文,不要进行额外修改;如果无法提取,请输出"无相应实体"。
**句子开始**
{sentence}
**句子结束**
**问题开始**
{prompt}
**问题结束**
**回答开始**
tgt 为标注的实体/客体原文(多个以逗号拼接)后接 **回答结束** 标记;构造的负例 tgt 固定为 无相应实体。
实体样本与关系样本会分别经 convert_llm_examples 转换后拼接输出,因此一份导出的标注数据会被拆解为"实体抽取"与"关系抽取"两类指令样本,供两阶段式抽取训练使用。
8.4 转换备注
- 默认情况下 doccano.py 脚本会按照比例将数据划分为 train/dev/test 数据集;
- 每次执行 doccano.py 脚本,将会覆盖已有的同名数据文件;
- 在模型训练阶段推荐构造一些负例以提升模型效果,数据转换阶段已内置该功能,可通过
negative_ratio控制自动构造的负样本比例(负样本数量 = negative_ratio × 正样本数量); - 对于从 doccano 导出的文件,默认文件中的每条数据都是经过人工正确标注的。
9. 转换之后:微调与定制预测
数据转换完成后,即可衔接 PP-UIE 的定制训练流程(详见 README 训练定制章节):
模型微调:推荐使用大模型精调工具(finetune 文档),在 PaddleNLP llm 目录下通过 run_finetune.py 启动。dataset_name_or_path 指向 doccano.py 生成的 ./application/information_extraction/data 目录,参考配置可查看 llm/config/qwen/sft_argument.json:
# 返回 PaddleNLP/llm 目录
python -u -m paddle.distributed.launch --gpus "0,1" run_finetune.py ./config/qwen/sft_argument.json
定制模型一键预测:微调完成后,可使用 predict/predictor.py 进行高性能推理,例如:
# PaddleNLP/llm 目录下
python predict/predictor.py \
--model_name_or_path ./checkpoints/ie_ckpts \
--dtype float16 \
--data_file ./application/information_extraction/data/test.json \
--output_file ./output.json \
--src_length 512 \
--max_length 1024 \
--batch_size 4 \
--inference_model 1 \
--quant_type weight_only_int8
其中 data_file 即 doccano.py 生成的 test.json,整条"标注 → 转换 → 微调 → 预测"链路就此打通。更多推理参数说明可参考 大模型推理教程。
10. 小结
围绕 PP-UIE 定制训练,doccano 标注环节的完整要点可以归纳为一条链路:创建"序列标注 + 重叠实体 + 关系标注"项目 → 上传 TextLine 格式 txt → 定义 Span/Relation 标签 → 按 NER/RE/EE 三种范式标注 → 导出 JSONL(relation) → 重命名 doccano_ext.json 放入 data 目录 → 运行 doccano.py 一键生成 train/dev/test。
整个链路中值得特别注意的实践要点:
- 三类任务共享同一标注框架,事件抽取的触发词必须命名为"XX 触发词"格式;
- 导出必须选
JSONL(relation),Span 的 offset 为左闭右开区间; negative_ratio是提升模型效果的开关,负例自动构造已内置在转换脚本中;- 英文数据集务必设置
schema_lang=en,否则生成的指令提示语不匹配。
相关仓库文件:doccano.md、doccano.py、utils.py、information_extraction README。