PaddleNLP 中的 DeBERTa 模型集合：架构解析、配置与实战使用指南

导读

本文围绕 PaddleNLP 文档 docs/en/model_zoo/transformers/Deberta/contents.rst 中收录的 DeBERTa 模型集合展开，系统梳理 PaddleNLP 对 DeBERTa 系列预训练模型的支持情况。你将掌握：DeBERTa 模型在 PaddleNLP 中的整体架构与解耦注意力（Disentangled Attention）原理、全部配置参数的语义与默认值、基于预训练权重加载模型与分词器的完整实战用法，以及可供下游任务微调的各任务头模型清单。

DeBERTa 模型集合总览

PaddleNLP 在 paddlenlp/transformers/deberta/ 目录下完整实现了 DeBERTa（Decoding-enhanced BERT with disentangled attention）模型，并在 docs/en/model_zoo/transformers/Deberta/contents.rst 中以表格形式汇总了当前支持的预训练权重。下表完整复现该文档内容：

预训练权重	语言	模型详情
microsoft/deberta-base	English	12 层 Transformer、隐藏层维度 768、12 个注意力头，约 100M 参数。在 80GB 训练数据上预训练，在大多数 NLU（自然语言理解）任务上优于 BERT 与 RoBERTa。

上述表格为 PaddleNLP 当前文档中正式收录的 DeBERTa v1 系列预训练权重。从源码的 DEBERTA_PRETRAINED_RESOURCE_FILES_MAP（见 paddlenlp/transformers/deberta/configuration.py）可以看到，microsoft/deberta-base 的模型权重文件 model_state.pdparams 由 PaddleNLP 官方 BOS 存储托管，可直接通过 from_pretrained 自动下载加载，无需手动转换权重格式。

另外需要说明的是：PaddleNLP 还支持 DeBERTa v2/v3 系列，对应的模型集合文档位于 docs/en/model_zoo/transformers/DebertaV2/contents.rst，包含 deepset/deberta-v3-large-squad2、microsoft/deberta-v3-base（12 层 / 768 维 / 12 头 / 86M 参数）、microsoft/deberta-v3-large（24 层 / 1536 维 / 24 头 / 900M 参数）等权重。v1 与 v2/v3 在 PaddleNLP 中被建模为两个独立的模型族（deberta 与 debertav2），本文聚焦 v1 系列。

模型架构：解耦注意力机制

DeBERTa 的核心创新在于"解耦注意力"（Disentangled Attention）机制。与 BERT 将位置信息直接加到词嵌入不同，DeBERTa 用两套独立的向量分别表示内容（content）与相对位置（relative position），并分别计算三组注意力分数：

• 内容到内容（content-to-content, c2c）：基于 token 内容本身的注意力；
• 内容到位置（content-to-position, c2p）：每个 query 关注与其存在相对位置关系的 key；
• 位置到内容（position-to-content, p2c）：每个 query 根据自身位置关注内容。

在 PaddleNLP 的实现中，这一机制位于 paddlenlp/transformers/deberta/modeling.py 的 DisentangledSelfAttention 类。从源码结构看，其关键设计包括：

• 通过单一的 in_proj 线性层一次性投影出 Q/K/V（bias_attr=False），并额外维护独立的 q_bias、v_bias 参数；
• pos_att_type 配置项控制启用哪些相对位置注意力分量，取值是 ["p2c", "c2p", "p2p"] 的子集，可传 "c2p|p2c" 形式的字符串，内部会按 | 拆分为列表；
• 当启用 c2p 时引入 pos_proj 投影层，启用 p2c 时引入 pos_q_proj 投影层；
• max_relative_positions 小于 1 时回退为 max_position_embeddings（默认 512）；
• 注意力概率 dropout 使用自定义的 StableDropout（见 modeling.py），其通过掩码操作而非乘法来节省计算与显存，配合 XDropout（paddle.autograd.PyLayer 实现，见 modeling.py）在反向传播中复用同一掩码，从而稳定训练并降低内存占用。

此外，DeBERTa 在输出层采用类似 ELECTRA 的生成式 MLM（masked language model）预训练目标，将解码器输出的概率分布软标签用于训练；position_biased_input=False 表示位置偏置不会直接叠加到输入嵌入上，而是仅通过上述相对位置注意力路径注入位置信息。

配置参数全解析

DebertaConfig（见 paddlenlp/transformers/deberta/configuration.py）继承自 PretrainedConfig，model_type = "deberta"。默认配置与 microsoft/deberta-base 保持一致，完整参数说明如下表：

参数	默认值	说明
vocab_size	50265	词表大小，定义 input_ids 可表示的 token 数量
hidden_size	768	编码器层与池化层的隐藏层维度
embedding_size	768（未显式指定时取 hidden_size）	嵌入层维度，允许与 hidden_size 解耦（对应 DeBERTa 的嵌入层与编码器层分离设计）
num_hidden_layers	12	Transformer 编码器层数
num_attention_heads	12	每层注意力头数
intermediate_size	3072	前馈网络中间层维度
hidden_act	"gelu"	激活函数，支持 gelu、relu、silu、gelu_new 等
hidden_dropout_prob	0.1	嵌入、编码器、池化层全连接层的 dropout 概率
attention_probs_dropout_prob	0.1	注意力概率的 dropout 比率
max_position_embeddings	512	模型支持的最大序列长度
type_vocab_size	0	token_type_ids 的词表大小（DeBERTa 不使用 segment 嵌入）
initializer_range	0.02	权重矩阵截断正态初始化的标准差
layer_norm_eps	1e-7	LayerNorm 的 epsilon
pad_token_id	0	用于填充 input_ids 的 token id
position_biased_input	False	是否将位置偏置加到输入嵌入上
pos_att_type	["p2c", "c2p"]	相对位置注意力类型，["p2c", "c2p", "p2p"] 的子集
output_attentions	False	是否返回注意力权重
output_hidden_states	True	是否返回所有层的隐藏状态
relative_attention	True	是否启用相对位置编码

上述默认值在 configuration.py 的 DEBERTA_PRETRAINED_INIT_CONFIGURATION 中集中定义，因此 DebertaConfig() 与从 microsoft/deberta-base 加载得到的配置完全等价。

配置对象与模型的联动使用方式如下：

from paddlenlp.transformers import DebertaConfig, DebertaModel

# 以 DeBERTa-base 风格配置初始化模型
configuration = DebertaConfig()
model = DebertaModel(configuration)

# 从预训练权重加载配置
configuration = DebertaConfig.from_pretrained("microsoft/deberta-base")

# 访问模型配置
configuration = model.config

PaddleNLP 的自动模型（AutoModel）机制也已注册 DeBERTa 模型族：在 paddlenlp/transformers/auto/configuration.py 中 "deberta" 映射到 DebertaConfig，在 paddlenlp/transformers/auto/modeling.py 中 "deberta" 映射到 Deberta 模型族。这意味着除了直接使用 DebertaModel，还可以使用 AutoModel / AutoConfig 统一入口加载，便于多模型族切换实验。

分词器：基于字节级 BPE 的 DebertaTokenizer

DebertaTokenizer（见 paddlenlp/transformers/deberta/tokenizer.py）基于字节级 Byte-Pair-Encoding（BBPE）构建，与 GPT-2/RoBERTa 的 BPE 实现同源。其资源文件为 vocab.json（词表）与 merges.txt（合并规则），pretrained_resource_files_map 同样指向 microsoft/deberta-base 的 BOS 存储。

关键实现细节：

• bytes_to_unicode()（见 tokenizer.py)建立 UTF-8 字节到 Unicode 字符串的双向映射，避免 BPE 在空白/控制字符上失效；
• 特殊 token 与 BERT 一致：[CLS]、[SEP]、[UNK]、[PAD]、[MASK]，do_lower_case=True；
• 单句输入格式化为 <a href="https://link.gitcode.com/i/61c0c3b73772250a55d2e22adb6b3176" target="_blank">CLS] X [SEP]，句对格式化为 [CLS] A [SEP] B [SEP]（见 build_inputs_with_special_tokens，[tokenizer.py）；
• 由于不使用 segment 嵌入（type_vocab_size=0），句对的 token_type_ids 仍按 BERT 惯例生成 0/1 序列以保持接口兼容（见 create_token_type_ids_from_sequences，tokenizer.py）。

from paddlenlp.transformers import DebertaTokenizer

tokenizer = DebertaTokenizer.from_pretrained("microsoft/deberta-base")
outputs = tokenizer("Welcome to use PaddlePaddle and PaddleNLP")
print(outputs)
# {'input_ids': [1, 25194, 7, 304, 221, 33151, 510, 33151, 8, 221, 33151, 487, 21992, 2],
#  'token_type_ids': [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]}

# 将 token id 序列还原为文本
text = tokenizer.convert_ids_to_string([14618, 284, 779, 350, 37382, 47, 37382, 290, 350, 37382, 45, 19930])
# 'Welcome to use PaddlePaddle and PaddleNLP'

预训练模型加载与下游任务实战

DebertaPreTrainedModel 提供 from_pretrained 能力，配合 DEBERTA_PRETRAINED_RESOURCE_FILES_MAP 自动下载权重。paddlenlp/transformers/deberta/modeling.py 中 __all__ 声明的模型族包括（modeling.py）：

• DebertaModel：基础编码器，输出序列隐藏状态（默认同时输出各层 hidden states，因为 output_hidden_states=True）；
• DebertaForSequenceClassification：文本分类 / 句对分类任务头；
• DebertaForQuestionAnswering：抽取式问答任务头（输出 span 起止 logits）；
• DebertaForTokenClassification：序列标注任务头（NER 等）；
• DebertaForMultipleChoice：多项选择任务头。

from paddlenlp.transformers import (
    DebertaModel,
    DebertaForSequenceClassification,
    DebertaForQuestionAnswering,
    DebertaForTokenClassification,
    DebertaForMultipleChoice,
    DebertaTokenizer,
)

# 1. 基础模型：获取序列表示
model = DebertaModel.from_pretrained("microsoft/deberta-base")

# 2. 文本分类（需根据任务配置 num_labels）
cls_model = DebertaForSequenceClassification.from_pretrained(
    "microsoft/deberta-base", num_labels=2
)

# 3. 抽取式问答
qa_model = DebertaForQuestionAnswering.from_pretrained("microsoft/deberta-base")

# 4. 序列标注
token_model = DebertaForTokenClassification.from_pretrained(
    "microsoft/deberta-base", num_labels=7
)

# 5. 多项选择
mc_model = DebertaForMultipleChoice.from_pretrained("microsoft/deberta-base", num_classes=4)

以文本分类为例的完整推理流程（可与 AutoModel 入口互换）：

import paddle
from paddlenlp.transformers import DebertaForSequenceClassification, DebertaTokenizer

model = DebertaForSequenceClassification.from_pretrained(
    "microsoft/deberta-base", num_labels=2
)
tokenizer = DebertaTokenizer.from_pretrained("microsoft/deberta-base")

inputs = tokenizer(
    ["PaddleNLP makes NLP easy.", "DeBERTa is powerful."],
    max_length=128,
    padding=True,
    truncation=True,
    return_tensors="pd",
)
model.eval()
with paddle.no_grad():
    logits = model(**inputs)
    probs = paddle.nn.functional.softmax(logits, axis=-1)
    print(probs)

使用要点与注意事项

1. 序列长度上限：max_position_embeddings=512，输入超过 512 的序列需设置 truncation=True 或采用长文本策略；分词器在 PRETRAINED_POSITIONAL_EMBEDDINGS_SIZES（tokenizer.py）中登记的 deberta-base 上限同样为 512。

2. 输出规模：output_hidden_states 默认开启，DebertaModel 的前向结果默认携带各层 hidden states（BaseModelOutput），若仅需顶层输出可传入 output_hidden_states=False 以降低内存占用；output_attentions 默认关闭，需要分析注意力权重时再显式开启。

3. 权重来源与一致性：文档表格中收录的 microsoft/deberta-base 与源码 DEBERTA_PRETRAINED_RESOURCE_FILES_MAP 中的键一一对应，确保 from_pretrained 开箱即用；若需使用文档未收录的其他 DeBERTa 权重（如基于 HF 生态转换的权重），可借助 PaddleNLP 的工具链（如 llm/tools/convert_ckpt_from_hf.py）转换后以本地目录方式加载。

4. 版本区分：v1（本文 deberta 模型族）与 v2/v3（debertav2 模型族）在 PaddleNLP 中是两个独立实现，加载权重时需按模型族选择对应类，不要混用。

总结

PaddleNLP 的 DeBERTa 模型集合以 microsoft/deberta-base 为当前文档收录的 v1 预训练权重，提供了从配置类（DebertaConfig）、字节级 BPE 分词器（DebertaTokenizer）到解耦注意力编码器（DebertaModel）及其五个下游任务头模型的完整实现链，并已接入 AutoModel 自动模型体系。读者可直接基于上述示例完成权重加载、文本编码与分类 / 问答 / 标注 / 多选等任务的微调与推理；如需探索更大规模的 v3 系列（如 900M 参数的 microsoft/deberta-v3-large），可进一步阅读 DebertaV2 模型集合文档 并对照 paddlenlp/transformers/deberta_v2/ 源码使用。