CamemBERT 实践指南基于 fairseq 加载与使用法语 RoBERTa 预训练模型【免费下载链接】fairseqFacebook AI Research Sequence-to-Sequence Toolkit written in Python.项目地址: https://gitcode.com/gh_mirrors/fa/fairseq导读CamemBERT 是 Facebook AI Research 基于 RoBERTa 架构训练的法语预训练语言模型于 2020 年发表是法语 NLP 领域的重要基础模型。本文以 examples/camembert/README.md 为骨架结合 fairseq 仓库中的源码实现完整讲解 CamemBERT 的预训练模型家族、两种加载方式torch.hub 与from_pretrained、掩码填充fill mask与特征提取extract features等核心用法并深入剖析其背后的 Hub 接口、SentencePiece 分词与模型架构细节。读完本文你将能够在自己的项目中直接加载 CamemBERT 完成法语文本的遮蔽词预测、句向量提取与下游任务微调。CamemBERT 是什么CamemBERT论文题为CamemBERT: a Tasty French Language Model是一个在138GB 法语文本上预训练的语言模型架构上完全沿用RoBERTaA Robustly Optimized BERT Pretraining Approach。与 RoBERTa 一样它采用掩码语言建模Masked Language ModelingMLM目标使用mask符号遮蔽部分词元并预测被遮蔽的内容同时去掉了 BERT 原有的下一句预测NSP任务并采用了更大的 batch size、更长的训练步数等 RoBERTa 的优化训练策略。在 fairseq 中CamemBERT 的实现位于 fairseq/models/roberta/model_camembert.py通过register_model(camembert)注册为 fairseq 的可加载模型类型类名CamembertModel直接继承自 fairseq/models/roberta/model.py 中的RobertaModel因此它与 RoBERTa 共享同一套模型结构、Hub 接口与分类头机制仅词表与预训练权重不同。与 RoBERTa 的关系对比维度RoBERTaCamemBERT预训练语言英语以及其他多语言变体法语模型类RobertaModel注册名robertaCamembertModel注册名camembert基础架构Transformer EncoderBERT 结构与 RoBERTa 完全相同默认分词器GPT-2 BPEbpegpt2SentencePiecebpesentencepiece从源码可以看出两者在加载路径上的关键差异是分词器RobertaModel.from_pretrained的默认参数是bpegpt2见 model.py而CamembertModel.from_pretrained的默认参数是bpesentencepiece见 model_camembert.py。这也是 CamemBERT 在法语上表现优异的重要原因——SentencePiece 直接在原始文本上做无监督子词切分能够更自然地处理法语的连读、省音如l、d等形态变化。预训练模型总览CamemBERT 官方发布了 6 个预训练检查点覆盖不同的参数量级与训练语料规模。下表完整列出各模型的关键信息下载归档托管于 fairseq 官方模型下载服务路径格式为https://dl.fbaipublicfiles.com/fairseq/models/归档名Model#paramsDownloadArch.Training datacamembert/camembert-base110Mcamembert-base.tar.gzBaseOSCAR (138 GB of text)camembert-large335Mcamembert-large.tar.gzLargeCCNet (135 GB of text)camembert-base-ccnet110Mcamembert-base-ccnet.tar.gzBaseCCNet (135 GB of text)camembert-base-wikipedia-4gb110Mcamembert-base-wikipedia-4gb.tar.gzBaseWikipedia (4 GB of text)camembert-base-oscar-4gb110Mcamembert-base-oscar-4gb.tar.gzBaseSubsample of OSCAR (4 GB of text)camembert-base-ccnet-4gb110Mcamembert-base-ccnet-4gb.tar.gzBaseSubsample of CCNet (4 GB of text)这些模型名在源码中有明确映射。model_camembert.py 中的hub_models()类方法定义了 8 个别名其中camembert与camembert.v0均指向 base 版归档供 torch.hub 与from_pretrained自动解析下载地址{ camembert: http://dl.fbaipublicfiles.com/fairseq/models/camembert-base.tar.gz, camembert.v0: http://dl.fbaipublicfiles.com/fairseq/models/camembert-base.tar.gz, camembert-base: http://dl.fbaipublicfiles.com/fairseq/models/camembert-base.tar.gz, camembert-large: http://dl.fbaipublicfiles.com/fairseq/models/camembert-large.tar.gz, camembert-base-ccnet: http://dl.fbaipublicfiles.com/fairseq/models/camembert-base-ccnet.tar.gz, camembert-base-ccnet-4gb: http://dl.fbaipublicfiles.com/fairseq/models/camembert-base-ccnet-4gb.tar.gz, camembert-base-wikipedia-4gb: http://dl.fbaipublicfiles.com/fairseq/models/camembert-base-wikipedia-4gb.tar.gz, camembert-base-oscar-4gb: http://dl.fbaipublicfiles.com/fairseq/models/camembert-base-oscar-4gb.tar.gz, }架构参数Base 与 LargeCamemBERT 的 Base/Large 架构直接复用 RoBERTa 的命名架构定义于 fairseq/models/roberta/model.py架构参数Baseroberta_baseLargeroberta_largeencoder_layersTransformer 层数1224encoder_embed_dim隐藏维度7681024encoder_ffn_embed_dimFFN 维度30724096encoder_attention_heads注意力头数1216max_positions最大序列长度512512activation_fn激活函数gelugeludropout/attention_dropout0.1 / 0.10.1 / 0.1与经典 Transformer 相比RoBERTa/CamemBERT 在结构上有一处显著差异使用学习型位置编码encoder_learned_posTrue、对 embedding 做 LayerNormlayernorm_embeddingTrue且不缩放 embeddingno_scale_embeddingTrue并且采用 BERT 风格的参数初始化init_bert_params。这些配置同样适用于 CamemBERT。环境准备在使用 CamemBERT 之前需要先安装 fairseq 及其依赖# 安装 fairseq从当前仓库根目录安装 pip install -e . # CamemBERT 使用 SentencePiece 分词需额外安装 pip install sentencepiece # torch.hub 方式要求 PyTorch 1.1 # 推荐使用 PyTorch 1.8 的稳定版本fairseq 的 torch.hub 入口依赖dataclasses、hydra、numpy、omegaconf、regex、requests、torch等包缺失时会直接抛出RuntimeError见 hubconf.py。若以 torch.hub 方式加载模型时缺少 Cython 编译组件fairseq 还会自动尝试就地构建token_block_utils_fast扩展见 hubconf.py。加载方式一通过 torch.hubPyTorch 1.1torch.hub 是最便捷的加载方式只需模型别名即可自动下载归档、构建模型与分词器import torch camembert torch.hub.load(pytorch/fairseq, camembert) camembert.eval() # disable dropout (or leave in train mode to finetune)也可以显式指定具体的模型变体camembert torch.hub.load(pytorch/fairseq, camembert-base) camembert torch.hub.load(pytorch/fairseq, camembert-large) camembert torch.hub.load(pytorch/fairseq, camembert-base-ccnet-4gb)加载机制说明torch.hub 会执行仓库根目录的 hubconf.py其中遍历 fairseq 的MODEL_REGISTRY为每个模型类的hub_models()中定义的名称自动暴露from_pretrained入口见 hubconf.py。也就是说torch.hub.load(..., camembert)底层等价于调用CamembertModel.from_pretrained(camembert)。加载机制说明补充from_pretrained通过 fairseq/hub_utils.py 中的from_pretrained函数完成「别名 → 下载 URL → 归档解压 → 加载词典/分词文件 → 恢复模型与任务」的完整流程首先用archive_map即hub_models()把别名解析为下载地址随后从归档中探测sentencepiece.bpe.model、vocab.json、merges.txt等分词资源并自动注入配置。加载方式二通过 from_pretrainedPyTorch 1.0 或自定义模型对于 PyTorch 1.0 环境或需要从本地自定义检查点加载的场景可以直接下载归档后使用CamembertModel.from_pretrained# 下载并解压 camembert 模型归档 wget https://dl.fbaipublicfiles.com/fairseq/models/camembert-base.tar.gz tar -xzvf camembert-base.tar.gz# 在 fairseq 中加载模型 from fairseq.models.roberta import CamembertModel camembert CamembertModel.from_pretrained(/path/to/camembert) camembert.eval() # disable dropout (or leave in train mode to finetune)CamembertModel.from_pretrained的方法签名见 model_camembert.py如下参数默认值说明model_name_or_path—模型别名如camembert-base或本地归档/目录路径checkpoint_filemodel.pt检查点文件名可传入多个用os.pathsep分隔做模型集成data_name_or_path.词典与分词资源路径以.开头时自动从归档内解析bpesentencepiece分词器类型CamemBERT 默认 SentencePiece**kwargs—其他参数覆盖例如load_checkpoint_headsTrue加载后返回的是一个 RobertaHubInterface 实例它内部持有cfg、task与model并自动构建好 BPE 编码器self.bpe encoders.build_bpe(cfg.bpe)。所有后续的encode、fill_mask、extract_features、predict等操作都由该接口提供。掩码填充fill_maskCamemBERT 的核心能力之一是预测被mask遮蔽的词。原文档给出的示例masked_line Le camembert est mask :) camembert.fill_mask(masked_line, topk3) # [(Le camembert est délicieux :), 0.4909118115901947, délicieux), # (Le camembert est excellent :), 0.10556942224502563, excellent), # (Le camembert est succulent :), 0.03453322499990463, succulent)]fill_mask的返回结果是一个三元组列表每项为(补全后的完整句子, 概率, 补全的词元)。它要求输入中恰好包含一个mask标记否则会触发断言错误见 hub_interface.py。fill_mask 的底层实现从 hub_interface.py 的源码可以拆解出它的完整执行流程BPE 编码用 SentencePiece 对mask两侧的文本分别编码再拼接成s ... mask ... /s形式的输入序列定位掩码位置masked_index (tokens self.task.mask_idx).nonzero(...)其中mask_idx是 masked LM 任务在词典中注册的特殊符号self.mask_idx self.dictionary.add_symbol(mask)见 fairseq/tasks/masked_lm.py前向推理在utils.model_eval上下文中以features_onlyFalse运行模型得到包含词表投影的 logitsTop-k 采样对 logits 做 softmax 后取概率最高的 k 个词元再经词典解码与 SentencePiece 反解得到候选词。一个值得注意的细节SentencePiece 以▁U2581表示词首空格因此代码中会检查预测的 BPE 子词是否以\u2581开头若是则在前方补一个空格以保证还原后的句子格式正确见 hub_interface.py。特征提取extract_features除了掩码填充CamemBERT 还可以输出 Transformer 各层的上下文表示用于下游任务或分析# 提取最后一层特征 line Jaime le camembert ! tokens camembert.encode(line) last_layer_features camembert.extract_features(tokens) assert last_layer_features.size() torch.Size([1, 10, 768]) # 提取所有层的特征layer 0 为 embedding 层 all_layers camembert.extract_features(tokens, return_all_hiddensTrue) assert len(all_layers) 13 assert torch.all(all_layers[-1] last_layer_features)输出形状解释extract_features(tokens)返回(batch, seq_len, embed_dim)即[1, 10, 768]——1 个句子、10 个 BPE 子词含s与/s、768 维隐藏向量Base 模型return_all_hiddensTrue时返回13 个张量的列表第 0 个是 embedding 层的输出后 12 个对应 12 层 Transformer 的隐状态最后一个元素与单独调用extract_features的结果完全一致源码中通过assert torch.all(all_layers[-1] last_layer_features)验证。extract_features 的底层实现在 hub_interface.py 中该接口做了三件事一维 token 序列自动扩展 batch 维度tokens.unsqueeze(0)检查序列长度是否超过模型最大位置数self.model.max_positions()Base/Large 均为 512超限则抛出ValueError以features_onlyTrue调用模型跳过 LM 头仅返回编码器输出。从 fairseq/models/roberta/model.py 可以看到内部实现Transformer Encoder 的输出为T x B x C时间维在前接口会转置为B x T x C再返回return_all_hiddens时通过extra[inner_states]收集所有中间层状态并逐个转置。编码与解码的细节encode()见 hub_interface.py的序列格式约定为单句s a b c /s句对s d e f /s /s 1 2 3 /s用额外的/s作为句对分隔符可通过no_separatorTrue关闭decode()见 hub_interface.py则负责把 token 序列还原为文本处理s前缀与连续/s分隔出的多个句子。面向下游任务的扩展分类头与预测CamemBERT 的RobertaHubInterface还提供了句级分类能力可快速在法语下游任务情感分类、意图识别、句子对分类等上进行微调# 为模型注册一个分类头num_classes 为类别数 camembert.register_classification_head(sentence_classification_head, num_classes2) # 推理返回 log softmax 概率 probs camembert.predict(sentence_classification_head, tokens, return_logitsFalse) # 若要得到原始 logits设置 return_logitsTrue logits camembert.predict(sentence_classification_head, tokens, return_logitsTrue)其实现位于 hub_interface.pypredict先提取最后一层特征再喂给model.classification_heads[head]。分类头定义在 model.py 的RobertaClassificationHead结构为「取s位置的表示 → dropout → 全连接 → tanh 激活 → dropout → 输出投影」即经典的 BERT[CLS]池化方案等价实现为features[:, 0, :]。若检查点中包含分类头权重加载时传入load_checkpoint_headsTrue即可自动恢复model.py 的upgrade_state_dict_named会负责新旧检查点的键名迁移如decoder→encoder、emb_layer_norm→layernorm_embedding。加载过程中的关键机制小结整个 CamemBERT 加载链路可归纳为别名解析model_camembert.py 的hub_models()提供别名 → 下载地址映射归档装载fairseq/hub_utils.py 下载/解压归档自动探测并注入sentencepiece.bpe.model、vocab.json、merges.txt等资源模型与任务恢复checkpoint_utils.load_model_ensemble_and_task载入模型权重、词典与 masked LM 任务分词器构建fairseq/data/encoders/sentencepiece_bpe.py 中的SentencepieceBPE注册名sentencepiece负责文本 ↔ 子词的互转接口封装返回 RobertaHubInterface对外暴露encode、decode、fill_mask、extract_features、predict、register_classification_head等统一 API。此外tests/test_dictionary.py 中的测试还揭示了一个实现细节CamemBERT 会覆盖词典中的unk、s、/s等特殊符号定义因此在自定义词典或微调脚本时需要留意特殊符号的兼容性。引用如果在研究或产品中使用了 CamemBERT请引用原始论文inproceedings{martin2020camembert, title{CamemBERT: a Tasty French Language Model}, author{Martin, Louis and Muller, Benjamin and Su{\a}rez, Pedro Javier Ortiz and Dupont, Yoann and Romary, Laurent and de la Clergerie, {\E}ric Villemonte and Seddah, Djam{\e} and Sagot, Beno{\^\i}t}, booktitle{Proceedings of the 58th Annual Meeting of the Association for Computational Linguistics}, year{2020} }相关资源原始使用说明examples/camembert/README.md模型实现fairseq/models/roberta/model_camembert.py、fairseq/models/roberta/model.pyHub 接口fairseq/models/roberta/hub_interface.py加载工具fairseq/hub_utils.py、hubconf.py分词实现fairseq/data/encoders/sentencepiece_bpe.py【免费下载链接】fairseqFacebook AI Research Sequence-to-Sequence Toolkit written in Python.项目地址: https://gitcode.com/gh_mirrors/fa/fairseq创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
