企业官网建设流程全解析

PaddleNLP 数据准备与处理全指南：从 load_dataset 到 DataLoader 的完整工作流

【免费下载链接】PaddleNLPEasy-to-use and powerful LLM and SLM library with awesome model zoo.项目地址: https://gitcode.com/gh_mirrors/pa/PaddleNLP

数据集加载与数据预处理是 NLP 任务中最关键的环节之一。PaddleNLP 为这一阶段提供了从内置数据集加载、自定义数据集构造、基于预训练模型/非预训练模型的特征转换，到 batchify 与 DataLoader 构建的一整套开箱即用的 API，并以低耦合、高内聚的模块化设计降低了学习成本。本文以 docs/en/data_prepare/overview.rst 为主线，结合 load_dataset 加载文档、数据预处理文档、自定义数据集文档 以及paddlenlp/datasets/dataset.py等源码，系统讲解 PaddleNLP 数据准备阶段的完整技术方案。读完本文，你将掌握：如何一键加载 20+ 内置数据集并自由切换MapDataset/IterDataset；如何基于本地文件、paddle.io.Dataset或第三方数据集自定义数据；如何编写trans_func完成 tokenization 与特征转换，并最终组装出可训练的DataLoader。

一、数据准备的整体设计：四大核心能力

在进入具体 API 之前，先看 PaddleNLP 对"数据与数据处理"这一阶段的设计理念。官方文档将其概括为三个特性：

• Powerful APIs（强大的 API）：为大多数常见 NLP 任务的数据处理流程提供统一、开箱即用的接口，避免重复造轮子；
• Flexible Encapsulation（灵活的封装）：模块之间保持低耦合、高内聚，用户可以基于继承与自定义机制，按需扩展出满足特定业务场景的数据处理方案；
• Built-in Datasets（内置数据集）：内置数据集覆盖大部分 NLP 任务，并提供简洁易用的加载协议与贡献指南，对新手与社区贡献者都非常友好。

这三个特性分别对应着三条主线：load_dataset等加载 API、DatasetBuilder继承机制、以及数量庞大的内置数据集。其中，数据集加载与处理的核心 API有三个：

这三个 API 的具体实现与调用方式，将在后续章节逐一展开。

二、理解 PaddleNLP 的数据处理工作流

PaddleNLP 的通用数据处理流程遵循一条清晰的流水线，任何 NLP 任务的数据准备都可以套用这个框架：

1. 加载数据集（内置或自定义数据集，返回原始数据 raw data）；
2. 定义trans_func（包括 tokenization、token 转 ID 等），并通过数据集的map方法将其应用于每条样本，把原始数据转换为特征 features；
3. 基于处理后的数据定义batchify 方法与BatchSampler；
4. 使用BatchSampler与batchify_fn定义DataLoader。

下图是 BERT 文本分类任务的数据处理流程图（原始数据 →Dataset.map(trans_func)→ 特征数据 → Batchify → 批次数据）：

从图中可以直观看到整条链路：原始样本（text+label）首先由trans_func通过 Bert Tokenizer 编码为input_ids、token_type_ids，同时将标签包装为列表形式；随后batchify_fn使用data.Pad将序列统一补齐到一致长度、使用data.Stack堆叠标签，最终产出模型可直接消费的批次数据。这条流程在 data_preprocess.rst 中有完整的分步示例，下面我们逐一深入每个环节。

三、加载内置数据集：load_dataset 详解

3.1 一行代码加载数据集

PaddleNLP 提供了 20+ 个内置 NLP 数据集，覆盖阅读理解、文本分类、序列标注、机器翻译等任务。以msra_ner（中文命名实体识别）数据集为例：

from paddlenlp.datasets import load_dataset train_ds, test_ds = load_dataset("msra_ner", splits=("train", "test"))

load_dataset会在paddlenlp.datasets包（默认路径为 paddlenlp/datasets/msra_ner.py）中定位msra_ner对应的数据读取脚本，并调用脚本中DatasetBuilder类的相关方法生成数据集。从源码看，load_dataset 的核心逻辑正是：根据传入的数据集名找到注册的DatasetBuilder类，将name、splits、data_files、lazy等参数透传给 builder 的_get_data/_read流程，最终返回数据集对象。

3.2 MapDataset 与 IterDataset：lazy 参数切换

生成的数据集既可以是MapDataset，也可以是IterDataset，二者分别是paddle.io.Dataset与paddle.io.IterableDataset的扩展。通过load_dataset的lazy参数即可切换：lazy=False返回MapDataset，lazy=True返回IterDataset。默认值为None，此时返回DatasetBuilder预定义的数据集类型（大多数内置数据集为MapDataset）。

from paddlenlp.datasets import load_dataset train_ds = load_dataset("msra_ner", splits="train") print(type(train_ds)) # <class 'paddlenlp.datasets.dataset.MapDataset'> # 默认 train_ds = load_dataset("msra_ner", splits="train", lazy=True) print(type(train_ds)) # <class 'paddlenlp.datasets.dataset.IterDataset'>

两种数据集类型的差异在源码中体现得很清楚：MapDataset 继承自paddle.io.Dataset，支持__getitem__随机索引访问，适合数据量适中、可整体载入内存的场景；IterDataset 继承自paddle.io.IterableDataset，只能顺序迭代，适合超大规模、无法一次性载入内存的数据。它们都提供了map、filter等扩展方法（见 dataset.py 与 dataset.py），语义与paddle.io的数据集方法保持一致但增加了 NLP 场景的灵活性。

3.3 选择子数据集：name 参数

部分数据集是多个子数据集的集合，每个子集是一个独立的数据集。例如GLUE数据集就包含 COLA、SST2、MRPC、QQP 等 10 个子集。load_dataset通过name参数指定子集。例如从 XTREME 基准中加载 SQuAD 数据集：

from paddlenlp.datasets import load_dataset squad_train = load_dataset('xtreme', name='squad', splits='train')

数据加载脚本会把name参数自动拼接到数据集文件路径中，例如 SQuAD 子集的文件通常存放在xtreme/squad目录下。splits参数则用于指定要取的数据集划分，例如同时取训练集与验证集：

train_ds, dev_ds = load_dataset("glue", name="cola", splits=("train", "dev"))

3.4 按内置数据集格式读取本地数据：data_files 参数

有时我们希望使用与内置数据集同格式的本地数据来替换部分内置数据（例如在 SQuAD 竞赛训练中做数据增强）。load_dataset的data_files参数即可实现这一功能。以SQuAD为例：

from paddlenlp.datasets import load_dataset train_ds, dev_ds = load_dataset("squad", data_files=("my_train_file.json", "my_dev_file.json")) test_ds = load_dataset("squad", data_files="my_test_file.json")

需要注意两点：

• 对某些数据集，不同划分可能需要不同的读取方式。此时必须在splits参数中提供相应的划分信息，且splits需要与data_files一一对应；
• 此场景下splits不再表示选择内置数据集划分，而是指定本地数据的读取格式。

以COLA数据集为例：

train_ds, test_ds = load_dataset( "glue", "cola", splits=["train", "test"], data_files=["my_train_file.csv", "my_test_file.csv"], )

重要提示：该数据集没有默认的加载选项，必须至少指定splits与data_files中的一项。

四、自定义数据集：三种构造方式

除了使用内置数据集，PaddleNLP 还支持通过load_dataset、MapDataset、IterDataset轻松定义自己的数据集。

4.1 从本地文件创建数据集

从本地文件创建数据集时，官方推荐基于本地数据格式编写一个 reader 函数，并把它传给load_dataset：

from paddlenlp.datasets import load_dataset def read(data_path): with open(data_path, 'r', encoding='utf-8') as f: # 跳过表头 next(f) for line in f: words, labels = line.strip('\n').split('\t') words = words.split('\002') labels = labels.split('\002') yield {'tokens': words, 'labels': labels} # data_path 是 read() 的参数 map_ds = load_dataset(read, data_path='train.txt', lazy=False) iter_ds = load_dataset(read, data_path='train.txt', lazy=True)

这里有几个最佳实践：

• 尽量把数据读取代码写成生成器（generator），这样能同时良好地构造MapDataset与IterDataset；
• 建议将每条样本格式化为字典，便于数据流监控与后续的map处理；
• 大多数场景下MapDataset即可满足需求，只有数据集过大、无法一次性载入内存时才考虑IterDataset；
• 自定义 reader 函数的参数可以直接以关键字参数的形式传给load_dataset；对自定义数据集，lazy参数是必填的；
• 只有 PaddleNLP 内置数据集才支持自动的 label 转 id（详见 如何编写 DatasetBuilder）。像上面这种自定义数据集，需要在自定义特征转换函数中手动实现 label 转 id 的逻辑。

4.2 从 paddle.io.Dataset / IterableDataset 包装

如果你习惯用paddle.io.Dataset/paddle.io.IterableDataset创建数据集，可以直接用MapDataset/IterDataset包装，转换为 PaddleNLP 数据集对象，从而获得map、filter等数据处理能力。下面是一个简单示例（IterDataset的用法类似）：

from paddle.io import Dataset from paddlenlp.datasets import MapDataset class MyDataset(Dataset): def __init__(self, path): def load_data_from_source(path): ... return data self.data = load_data_from_source(path) def __getitem__(self, idx): return self.data[idx] def __len__(self): return len(self.data) ds = MyDataset(data_path) # paddle.io.Dataset new_ds = MapDataset(ds) # paddlenlp.datasets.MapDataset

4.3 从其他 Python 对象创建

理论上，任何包含__getitem__和__len__方法的 Python 对象都可以用来创建MapDataset，包括List、Tuple、DataFrame等：

from paddlenlp.datasets import MapDataset data_source_1 = [1, 2, 3, 4, 5] data_source_2 = ('a', 'b', 'c', 'd') list_ds = MapDataset(data_source_1) tuple_ds = MapDataset(data_source_2) print(list_ds[0]) # 1 print(tuple_ds[0]) # a

同理，包含__iter__方法的 Python 对象（如List、Generator）可以创建IterDataset：

from paddlenlp.datasets import IterDataset data_source_1 = ['a', 'b', 'c', 'd'] data_source_2 = (i for i in range(5)) list_ds = IterDataset(data_source_1) gen_ds = IterDataset(data_source_2) print([data for data in list_ds]) # ['a', 'b', 'c', 'd'] print([data for data in gen_ds]) # [0, 1, 2, 3, 4]

注意：向IterDataset传入生成器对象时，第二次迭代会自动重置生成器；若想复用生成的数据，需要先将其转换为 list。此外，IterDataset生成的数据集只能被迭代一次。

这种通用性意味着我们也可以用同样的方法从第三方数据集创建 PaddleNLP 数据集，例如 HuggingFacedatasets：

from paddlenlp.datasets import MapDataset from datasets import load_dataset hf_train_ds = load_dataset('msra_ner', split='train') train_ds = MapDataset(hf_train_ds) print(type(train_ds)) # <class 'paddlenlp.datasets.dataset.MapDataset'> print(train_ds[2]) # {'id': '2', 'ner_tags': [0, 0, 0, 5, 0, 0, 5, 0, ...], 'tokens': ['因', '有', '关', '日', '寇', ...]}

五、数据预处理：从原始数据到特征

数据集里通常是原始数据，需要经过特定处理与采样形成批次，再通过paddle.io.DataLoader喂给模型训练或推理。PaddleNLP 对流水线中的每一步都提供了对应支持。根据是否使用预训练模型，数据预处理分为两条路径。

5.1 基于预训练模型的预处理：Tokenizer + map

使用预训练模型做 NLP 任务时，加载对应的 Tokenizer 是必不可少的。PaddleNLP 的PreTrainedTokenizer通过内置的__call__方法实现了基础的数据处理能力，所有预训练模型的 Tokenizer 都继承自PreTrainedTokenizer。以BertTokenizer为例：

from paddlenlp.transformers import BertTokenizer tokenizer = BertTokenizer.from_pretrained('bert-base-chinese') # 单句转换（单条数据） print(tokenizer(text='天气不错')) # {'input_ids': [101, 1921, 3698, 679, 7231, 102], 'token_type_ids': [0, 0, 0, 0, 0, 0]} # 句对转换（单条数据） print(tokenizer(text='天气', text_pair='不错')) # {'input_ids': [101, 1921, 3698, 102, 679, 7231, 102], 'token_type_ids': [0, 0, 0, 0, 1, 1, 1]} # 单句转换（多条数据） print(tokenizer(text=['天气', '不错'])) # [{'input_ids': [101, 1921, 3698, 102], 'token_type_ids': [0, 0, 0, 0]}, # {'input_ids': [101, 679, 7231, 102], 'token_type_ids': [0, 0, 0, 0]}]

接下来通过MapDataset.map方法将转换函数统一作用于数据集。以LCQMC（中文语义匹配数据集，句子对二分类任务）为例，展示完整的数据处理管线：

from paddlenlp.transformers import BertTokenizer from paddlenlp.datasets import load_dataset tokenizer = BertTokenizer.from_pretrained('bert-base-chinese') train_ds = load_dataset('lcqmc', splits='train') print(train_ds[0]) # {'query': '喜欢打篮球的男生喜欢什么样的女生', 'title': '爱打篮球的男生喜欢什么样的女生', 'label': 1}

LCQMC 是句子对匹配任务，即判断两个句子是否语义相似，需要处理键为query和title的文本数据。我们基于PreTrainedTokenizer实现一个数据处理函数，并传给数据集的map方法：

def convert_example(example, tokenizer): tokenized_example = tokenizer( text=example['query'], text_pair=example['title']) # 为训练添加 label tokenized_example['label'] = [example['label']] return tokenized_example from functools import partial trans_func = partial( convert_example, tokenizer=tokenizer) train_ds.map(trans_func) print(train_ds[0]) # {'input_ids': [101, 1599, 3614, 2802, ..., 102], # 'token_type_ids': [0, 0, ..., 1, 1, 1], # 'label': [1]}

可以看到，数据集中的文本数据已被处理成模型可接受的特征。

map方法有一个重要参数batched（默认False）。当设为True时，trans_func接收一批样本进行批量处理：

def convert_examples(examples, tokenizer): queries = [example['query'] for example in examples] titles = [example['title'] for example in examples] tokenized_examples = tokenizer(text=queries, text_pair=titles, return_dict=False) # 为训练添加 label for idx in range(len(tokenized_examples)): tokenized_examples[idx]['label'] = [examples[idx]['label']] return tokenized_examples from functools import partial trans_func = partial(convert_examples, tokenizer=tokenizer) train_ds.map(trans_func, batched=True) print(train_ds[0]) # 与上例结果一致

两种实现的结果相同，但在机器阅读理解、对话等任务中，单条原始数据可能生成多条特征，通常就需要将batched参数设为True（参考run_squad.py示例）。

map方法还有一个num_workers参数：当它大于 0 时开启多进程数据处理，可提升处理速度。但需注意，如果数据处理函数使用了与数据索引相关的信息，多进程可能导致结果出错。

5.2 基于非预训练模型的预处理：JiebaTokenizer + Vocab

使用非预训练模型时，可以借助 PaddleNLP 内置的JiebaTokenizer与Vocab完成数据处理，整体流程与预训练模型路径类似。以中文情感分析数据集ChnSentiCorp为例：

from paddlenlp.data import JiebaTokenizer, Vocab from paddlenlp.datasets import load_dataset train_ds = load_dataset('chnsenticorp', splits='train') print(train_ds[0]) # {'text': '选择珠江花园的原因就是方便，有电动扶梯直接到达海边，...', 'label': 1} # 从本地词表文件构建 Vocab vocab = Vocab.load_vocabulary('./senta_word_dict.txt', unk_token='[UNK]', pad_token='[PAD]') # 用 Vocab 初始化 JiebaTokenizer tokenizer = JiebaTokenizer(vocab)

补充说明：

• 除了从本地词表文件初始化，Vocab还提供多种初始化方式，包括从dict和数据集创建；
• 除了内置的JiebaTokenizer，用户也可以实现自定义分词方式或使用第三方分词库，再通过Vocab.to_indices将 token 转为索引。

convert_example方法将 token 转为 id，随后沿用与预训练模型路径相似的处理流程：

def convert_example(example, tokenizer): input_ids = tokenizer.encode(example["text"]) valid_length = [len(input_ids)] label = [example["label"]] return input_ids, valid_length, label from functools import partial trans_fn = partial(convert_example, tokenizer=tokenizer) train_ds.map(trans_fn) print(train_ds[0]) # ([417329, 128448, 140437, 173188, 118001, 213058, ..., 1250380], # [67], # [1])

注意：这里单条数据是元组而非字典，因此后续的batchify_fn需要相应调整（见下一节）。

六、Batchify 与 DataLoader：组装训练批次

PaddleNLP 提供了多种内置的 collate 函数，与paddle.io.BatchSampler配合即可简化批次的构建。

6.1 基于字典数据：Dict + Pad + Stack

继续沿用 LCQMC 的例子。上一节处理后的每条样本是一个包含input_ids、token_type_ids、label三个键的字典。其中input_ids和token_type_ids在送入模型前需要pad（补齐），而label需要stack（堆叠）后传给损失函数。因此使用 PaddleNLP 内置的Dict、Stack、Pad函数来组织批次数据：

from paddlenlp.data import Dict, Stack, Pad # 用 Dict 将 Pad/Stack 函数与字典键对应起来 train_batchify_fn = lambda samples, fn=Dict({ 'input_ids': Pad(axis=0, pad_val=tokenizer.pad_token_id), 'token_type_ids': Pad(axis=0, pad_val=tokenizer.pad_token_type_id), 'label': Stack(dtype="int64") }): fn(samples)

接着用paddle.io.BatchSampler和batchify_fn构建paddle.io.DataLoader：

from paddle.io import DataLoader, BatchSampler train_batch_sampler = BatchSampler(train_ds, batch_size=2, shuffle=True) train_data_loader = DataLoader( dataset=train_ds, batch_sampler=train_batch_sampler, collate_fn=train_batchify_fn, )

至此，完整的数据准备管线就构建完成了。更丰富的 batchify 方法可参考 paddlenlp.data.collate 文档。

注意事项：

• 进行单机多卡训练时，请用DistributedBatchSampler替换BatchSampler；
• 对于更复杂的 batching 需求（如 batch 内排序、按 token 数切分 batch），可使用 PaddleNLP 内置的SamplerHelper（参考机器翻译 transformer 的reader.py示例）。

6.2 基于元组数据：Tuple + Pad + Stack

在非预训练模型路径（ChnSentiCorp 示例）中，单条数据不是字典而是元组（input_ids、valid_length、label），因此batchify_fn需要改用Tuple函数按索引对齐：

from paddlenlp.data import Tuple, Stack, Pad # 用 Tuple 函数将 Pad、Stack 等函数与数据中的元素按位置对应 train_batchify_fn = lambda samples, fn=Tuple(( Pad(axis=0, pad_val=vocab.token_to_idx.get('[PAD]', 0)), # input_ids Stack(dtype="int64"), # seq len Stack(dtype="int64") # label )): fn(samples)

对比可见：Dict函数按键将单条数据中的键值对映射到对应的Pad/Stack等函数，适用于每条数据是字典的情形；Tuple则通过索引对齐单条数据中的不同成分。因此，需要特别注意convert_example与batchify_fn之间的对应关系。此后的流程与预训练模型路径保持一致。

七、向社区贡献数据集：DatasetBuilder 核心协议

PaddleNLP 鼓励社区贡献数据集，而贡献方式正是定义一个DatasetBuilder子类。一个合格的DatasetBuilder需要遵循特定的协议与规范。以LCQMC为例，其核心成员变量如下：

from paddle.dataset.common import md5file from paddle.utils.download import get_path_from_url from paddlenlp.utils.env import DATA_HOME class LCQMC(DatasetBuilder): """LCQMC: A Large-scale Chinese Question Matching Corpus""" lazy = False URL = "https://bj.bcebos.com/paddlehub-dataset/lcqmc.tar.gz" MD5 = "62a7ba36f786a82ae59bbde0b0a9af0c" META_INFO = collections.namedtuple('META_INFO', ('file', 'md5')) SPLITS = { 'train': META_INFO(os.path.join('lcqmc', 'train.tsv'), '2193c022439b038ac12c0ae918b211a1'), 'dev': META_INFO(os.path.join('lcqmc', 'dev.tsv'), 'c5dcba253cb4105d914964fd8b3c0e94'), 'test': META_INFO(os.path.join('lcqmc', 'test.tsv'), '8f4b71e15e67696cc9e112a459ec42bd'), }

贡献的数据集需继承paddlenlp.datasets.DatasetBuilder类，类名采用驼峰命名，并在 docstring 中简要描述数据集来源等信息。需要定义的成员变量包括：

• lazy：默认数据集类型，False对应MapDataset，True对应IterDataset；
• URL：数据集压缩包的下载地址，必须是有效、稳定的链接；若数据集不是压缩包格式，可以省略；
• MD5：数据集压缩包的 MD5 校验值，用于文件校验；非压缩包格式可省略；
• META_INFO：数据集划分信息的格式定义；
• SPLITS：数据集的划分信息，包含解压后的文件位置、文件名、MD5 值等；对非压缩包数据集，通常在此提供下载地址，也可包含文件读取配置等参数。

此外，部分数据集还需要其他成员变量，如VOCAB_INFO（可参考iwslt15.py）。成员变量的格式可能各不相同，贡献者可根据实际需求调整。

协议要点：

• 如果贡献的数据集没有子集，DatasetBuilder必须包含SPLITS成员变量，且必须是以划分名称为键的字典；
• 如果数据集包含子集，则必须包含BUILDER_CONFIGS成员变量，以子集的name为键、值为包含splits划分信息的字典（格式可参考glue.py）。

随后需要实现两个必须的方法：

_get_data方法——定位并校验数据集文件：

def _get_data(self, mode, **kwargs): """Check and download Dataset""" default_root = os.path.join(DATA_HOME, self.__class__.__name__) filename, data_hash = self.SPLITS[mode] fullname = os.path.join(default_root, filename) if not os.path.exists(fullname) or (data_hash and not md5file(fullname) == data_hash): get_path_from_url(self.URL, default_root, self.MD5) return fullname

_get_data根据输入的mode和划分信息定位具体的数据集文件：先对本地文件做 MD5 校验，校验失败则调用paddle.utils.download.get_path_from_url下载并校验数据集文件，最后返回数据集文件的本地路径。

_read方法——从给定文件路径读取数据：

def _read(self, filename): """Reads data.""" with open(filename, 'r', encoding='utf-8') as f: head = None for line in f: data = line.strip().split("\t") if not head: head = data else: query, title, label = data yield {"query": query, "title": title, "label": label}

_read方法必须是生成器，这样DatasetBuilder才能同时构造MapDataset和IterDataset。当不同划分需要不同的读取方式时，该方法还需支持split参数并分别处理。

可选方法：

• get_labels：返回数据集全部标签的列表，用于将类别标签转换为 id，该列表会作为实例变量传给生成的数据集。若想让DatasetBuilder在数据集生成时自动完成 label 转 id，需要将样本中的标签键命名为"label"或"labels"，并正确实现get_labels；
• get_vocab：当数据集提供词表文件时，需配合VOCAB_INFO变量实现，返回包含数据集词表信息的Dictionary对象，用于训练时初始化paddlenlp.data.Vocab。

总结：_read与_get_data是必需的，get_labels与get_vocab视数据集内容可选；若不想做 md5 校验，也可省略相关成员变量与校验代码。完整规范详见 如何编写 DatasetBuilder。

八、结语：一条可复用的数据准备方法论

回顾全文，PaddleNLP 的数据准备体系可以归纳为一套可复用的方法论：用load_dataset/自定义 reader 拿到原始数据 → 用map+trans_func（Tokenizer 或 Vocab 路径）把原始数据转成特征 → 用Dict/Tuple组合Pad/Stack定义batchify_fn→ 用BatchSampler+batchify_fn构建DataLoader。无论任务是基于 BERT 的文本分类、LCQMC 语义匹配，还是基于词表的中文情感分析，这条链路都能直接套用；需要扩展时，MapDataset/IterDataset的map、filter方法以及DatasetBuilder的继承机制提供了充分的定制空间。各环节更完整的 API 说明可继续查阅 paddlenlp.datasets.dataset 文档、paddlenlp.data.collate 文档 及 数据预处理文档。

【免费下载链接】PaddleNLPEasy-to-use and powerful LLM and SLM library with awesome model zoo.项目地址: https://gitcode.com/gh_mirrors/pa/PaddleNLP