Transformers 中的 BertJapanese：基于 MeCab/Sudachi 等分词的日语 BERT 分词器全解析-北京尧图网络

Transformers 中的 BertJapanese基于 MeCab/Sudachi 等分词的日语 BERT 分词器全解析【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers本文导读日语文本没有空格分词无法直接套用标准 BERT 的 WordPiece 流程。本篇技术指南以官方文档 docs/source/en/model_doc/bert-japanese.md 为主体系统讲解 Transformers 仓库中BertJapaneseTokenizer的分层分词架构、四种词级分词器与三种子词级分词器的选型与参数并给出可一键复现的推理代码、底层源码证据与测试用例验证。读完你既能用一行代码跑通cl-tohoku/bert-base-japanese系列模型也能按业务需求定制 MeCab/Sudachi/JumanPP 等日文形态素解析方案。一、BertJapanese 是什么在日语 BERT 场景中模型结构本身与标准 BERT完全一致唯一的关键差异在于分词方式。日语通常不空格分词因此必须借助形态素解析器Morphological Analyzer先将句子切分为“单词”再喂给子词切分器。文档与源码都反复强调这一点This implementation is the same as BERT, except for tokenization method模型 API 参考直接沿用 BERT见 BERT 文档。该功能由贡献者 cl-tohoku东北大学乾研究室发布的cl-tohoku/bert-japanese系列模型作者于 2020-11-16 引入本仓库。仓库内实现位于两个文件分词器实现src/transformers/models/bert_japanese/tokenization_bert_japanese.py单元测试tests/models/bert_japanese/test_tokenization_bert_japanese.py文档最初描述了两类分词模型但从当前源码以及测试文件的用例矩阵看可用的组合已扩展到远不止两种层级可选实现说明词级分词word_tokenizer_typebasic/mecab/sudachi/jumanpp把日文切分为“单词”子词级分词subword_tokenizer_typewordpiece/character/sentencepiece把单词进一步切分为可入词表的子词下文将逐一说明每种组合如何配置、背后的分词器类如何工作。二、安装与依赖文档明确说明使用 MeCab 词级分词需要额外安装形态素解析相关依赖# 从 PyPI 安装时 pip install transformers[ja] # 从源码安装clone 仓库后时 pip install -e .[ja]这里jaextra 的具体内容定义在 setup.py 的extras[ja]中第 208-210 行extras[ja] deps_list(fugashi, ipadic, unidic_lite, unidic, rhoknp) if PYTHON_MINOR_VERSION 14: extras[ja] deps_list(sudachipy, sudachidict_core)其中各包对应关系依赖版本声明见 src/transformers/dependency_versions_table.pyfugashi1.0MeCab 的 Python 封装MecabTokenizer的必需依赖ipadic1.0.0,2.0IPA 词典unidic_lite1.0.7与unidic1.0.2UNIDIC 词典轻量版 / 完整版完整版需额外执行python -m unidic download下载体积较大rhoknpJuman 的 Python 封装JumanppTokenizer的必需依赖sudachipy0.6.6与sudachidict_coreSudachiPy 分词器及其核心词典SudachiTokenizer的必需依赖注意当前 setup.py 将其限定在 Python 3.14 的环境下安装。如果只使用 Character 字符级或 Basic 词级切分无形态素解析则无需这些额外依赖。若遗漏安装源码会抛出明确的提示例如MecabTokenizer.__init__中捕获ModuleNotFoundError并提示 You need to install fugashi to use MecabTokenizer见 tokenization_bert_japanese.py。三、快速上手两种经典用法3.1 MeCab WordPiececl-tohoku/bert-base-japaneseMeCab 与 WordPiece 的组合是cl-tohoku/bert-base-japanese的默认配置。文档给出了如下可直接运行示例注意原文档中的变量笔误model.device已修正为bertjapanese.deviceimport torch from transformers import AutoModel, AutoTokenizer bertjapanese AutoModel.from_pretrained(cl-tohoku/bert-base-japanese, device_mapauto) tokenizer AutoTokenizer.from_pretrained(cl-tohoku/bert-base-japanese) ## 输入日语文本 line 吾輩は猫である。 inputs tokenizer(line, return_tensorspt).to(bertjapanese.device) print(tokenizer.decode(inputs[input_ids][0])) # [CLS] 吾輩は猫である。 [SEP] outputs bertjapanese(**inputs)可以看到句子先被 MeCab 按词法切分为吾輩 / は / 猫 / で / ある / 。六个“单词”词与词之间有明确的空格边界。由于吾輩、猫等词整体存在于 BERT 词表中因此此处 WordPiece 未发生二次切分。3.2 Character 字符级切分cl-tohoku/bert-base-japanese-char若使用字符级切分模型则完全不依赖形态素解析器输出效果是逐字展开bertjapanese AutoModel.from_pretrained(cl-tohoku/bert-base-japanese-char, device_mapauto) tokenizer AutoTokenizer.from_pretrained(cl-tohoku/bert-base-japanese-char) ## 输入日语文本 line 吾輩は猫である。 inputs tokenizer(line, return_tensorspt).to(bertjapanese.device) print(tokenizer.decode(inputs[input_ids][0])) # [CLS] 吾輩は猫である。 [SEP] outputs bertjapanese(**inputs)两种模型在仓库中的注册名均为BertJapaneseTokenizer。在 src/transformers/models/auto/tokenization_auto.py 中通过(bert-japanese, BertJapaneseTokenizer)映射因此AutoTokenizer.from_pretrained会根据 checkpoint 的tokenizer_class自动路由到正确实现——这一点由 test_tokenizer_bert_japanese 直接验证assertIsInstance(tokenizer, BertJapaneseTokenizer)。四、BertJapaneseTokenizer 构造参数全解BertJapaneseTokenizer继承自 [PreTrainedTokenizer]构造签名与参数在源码tokenization_bert_japanese.py中可查参数类型默认值说明vocab_filestr必填每行一个 WordPiece 词条的词表文件vocab.txtspm_filestrNoneSentencePiece 模型文件.spm/.model仅当subword_tokenizer_typesentencepiece时必填并校验存在性do_lower_caseboolFalse是否在 basic/mecab/sudachi 阶段转小写do_word_tokenizeboolTrue是否执行词级切分置False则整句作为单个输入do_subword_tokenizeboolTrue是否执行子词切分置False则词级结果直接作为 tokenword_tokenizer_typestrbasic词级分词器取值[basic, mecab, sudachi, jumanpp]subword_tokenizer_typestrwordpiece子词分词器取值[wordpiece, character, sentencepiece]mecab_kwargsdictNone透传给MecabTokenizer的关键字参数sudachi_kwargsdictNone透传给SudachiTokenizer的关键字参数jumanpp_kwargsdictNone透传给JumanppTokenizer的关键字参数never_split/unk_token/sep_token/pad_token/cls_token/mask_token-[UNK]/[SEP]/[PAD]/[CLS]/[MASK]沿袭标准 BERT 的特殊 token 约定词表相关常量在源码第 33 行定义VOCAB_FILES_NAMES {vocab_file: vocab.txt, spm_file: spiece.model}即 WordPiece/Character 模式依赖vocab.txtSentencePiece 模式依赖spiece.model二者通过subword_tokenizer_type切换使用。BertJapaneseTokenizer还设定了token_type_ids_patternbert_style、token_type_ids_include_special_tokensTrue、special_tokens_patterncls_sep因此它与 BERT 一样单句编码为[CLS] ... [SEP]句对编码为[CLS] A [SEP] B [SEP]每条 token 都附带 token_type_ids——这与 test_sequence_builders 的断言行为一致。五、核心流水线两段式_tokenize理解BertJapaneseTokenizer的关键是它的两段式切分流水线源码_tokenize见 tokenization_bert_japanese.pydef _tokenize(self, text): if self.do_word_tokenize: tokens self.word_tokenizer.tokenize(text, never_splitself.all_special_tokens) else: tokens [text] if self.do_subword_tokenize: split_tokens [sub_token for token in tokens for sub_token in self.subword_tokenizer.tokenize(token)] else: split_tokens tokens return split_tokens流水线可概括为词级切分由word_tokenizer把整句切成一串日语“单词”形态素子词切分对第 1 步输出的每一个词再调用subword_tokenizer做二次切分如 WordPiece 把词典外长词拆成##前缀子词特殊 token[CLS]/[SEP]等在all_special_tokens的保护下不被切开。在构造函数中word_tokenizer_type决定实例化BasicTokenizer/MecabTokenizer/SudachiTokenizer/JumanppTokenizer中的哪一个subword_tokenizer_type决定实例化WordpieceTokenizer/CharacterTokenizer/SentencepieceTokenizer中的哪一个非法取值会抛出ValueError。一个值得注意的工程细节当词级分词器为mecab/sudachi/jumanpp时底层持有不可序列化的解析器对象因此类实现了__getstate__pickle 时删除word_tokenizer与__setstate__反序列化时依据保存的 kwargs 重建解析器确保模型可被pickle与多进程分发见 tokenization_bert_japanese.py。六、词级分词器word tokenizer逐一分析6.1 BasicTokenizerbasic默认即标准 BERT 的BasicTokenizer。BertJapaneseTokenizer在构造它时强制传入tokenize_chinese_charsFalse见 tokenization_bert_japanese.py。这是因为对日语启用中文逐字切分会把汉字拆得过碎破坏后续形态素/子词处理仓库中的 BasicTokenizer 完整保留了对 CJK 区间含扩展区判定的_is_chinese_char逻辑第 737-759 行但在此处被显式关闭。它同时完成 Unicode NFKC/NFC 归一化、空白清理、标点拆分与小写化。6.2 MecabTokenizermecab通过fugashi封装 MeCab 完成形态素解析构造逻辑见 tokenization_bert_japanese.py其mecab_kwargs支持参数默认值说明do_lower_caseFalse是否对非never_splittoken 做小写化normalize_textTrue切分前是否对文本做 Unicode NFKC 归一化用于把全角/半角统一如→アップル、→8mecab_dicunidic_lite使用的词典ipadicIPA、unidic_lite轻量 UNIDIC、unidic完整 UNIDIC需python -m unidic download若使用系统词典则传None并改用mecab_optionmecab_optionNone直接传给 MeCab 构造器的原始选项字符串设置mecab_dic后源码会拼出-d {dic_dir} -r {mecabrc}再附加用户自定义的mecab_option实现词典路径与配置的自动定位。tokenize对 MeCab 输出的每个词取word.surface作为 token并按需做小写化。测试对三种词典均给出预期见 test_tokenization_bert_japanese.py同一输入ストアでiPhone が発売された。使用ipadic输出アップルストア一词而使用unidic_lite/unidic输出アップルストア两词——这正是不同词典粒度差异的直观体现实践选型时应保持“训练用词典推理用词典”。6.3 SudachiTokenizersudachi基于 SudachiPy 的三粒度形态素解析器构造见 tokenization_bert_japanese.py其sudachi_kwargs关键参数参数默认值说明normalize_textTrueNFKC 归一化开关trim_whitespaceFalse是否剔除并 trim 空白/tab/换行 tokensudachi_split_modeA切分粒度A最细、B中、C不切分sudachi_dict_typecore词典类型small/core/fullsudachi_config_path/sudachi_resource_dirNoneSudachiPy 配置与资源目录sudachi_projectionNone词投影模式如surface/normalized/reading/normalized_nouns等需要 sudachipy0.6.8projection是 Sudachi 的特色能力。测试 test_sudachi_tokenizer_projection 展示了投影前后的差异输入これはねこです。在sudachi_split_modeAsudachi_projectionnormalized_nouns下被切分为此れ / は / 猫 / です / 。其中これ→此れ、ねこ→猫即为词典投影把平假名口语还原为规范表记的结果。SplitMode 三档差异同样有测试佐证test_tokenization_bert_japanese.py对外国人参政権A/B/C 三种模式分别输出外国/人/参政/権、外国人/参政権、外国人参政権。将其接入完整分词器时如测试中的word_tokenizer_typesudachi, sudachi_kwargs{sudachi_split_mode: B}会进一步得到带##的 WordPiece 子词外国/##人/参政/##権。6.4 JumanppTokenizerjumanpp基于rhoknp调用 Juman构造见 tokenization_bert_japanese.py。jumanpp_kwargs支持do_lower_case、normalize_text默认True、trim_whitespace默认False。其tokenize通过self.juman.apply_to_sentence(text).morphemes逐个取词素文本。测试 test_jumanpp_full_tokenizer_with_jumanpp_kwargs_trim_whitespace 验证了它也能与 WordPiece 正常衔接。Juman 由京都大学 Kurohashi 实验室维护擅长长距离依存与未知语处理适合作为 MeCab/Sudachi 之外的高精度备选。七、子词级分词器subword tokenizer逐一分析7.1 WordpieceTokenizerwordpiece默认标准的 BERT WordPiece 实现源码见 tokenization_bert_japanese.py采用最长匹配优先的贪心算法对每个词从最长子串开始向词表查询非词首子词一律加##前缀子串超过max_input_chars_per_word100或无法切分时输出[UNK]。解码时通过 .join(tokens).replace( ##, )还原convert_tokens_to_string。测试 test_wordpiece_tokenizer 展示了核心行为こんばんは→こん/##ばんは。7.2 CharacterTokenizercharacter逐字切分源码见 tokenization_bert_japanese.py。先做 NFKC 归一化再对每个字符查词表こんにちは→こ/ん/に/ち/は词表外的字符如测试中的ほ映射为[UNK]见 test_character_tokenizer。由于该模式不需要词级分词器配合形态素解析是文档所述“第二种经典用法”的底层实现。7.3 SentencepieceTokenizersentencepiece当subword_tokenizer_typesentencepiece时构造器要求spm_file指向spiece.model词表与 id 映射改由 SentencePiece 的sp_model提供vocab_size、_convert_token_to_id/_convert_id_to_token都会切换到 SP 模型路径。其实现参考了 Albert 分词器见类注释及 tokenization_bert_japanese.py输出采用▁前缀标记词首。注意此时主切分器仍然先由word_tokenizer通常配 sudachi/jumanpp产出词序列再交给 SentencePiece。这类组合实际存在于社区模型中例如测试使用的nlp-waseda/roberta-base-japanese-with-auto-jumanppJumanpp 词级 SentencePiece 子词级其预期输出如▁国境 ▁の ▁長い ...见 test_sentencepiece_tokenizer。八、解码与词表读写行为解码WordPiece/Character 模式下convert_tokens_to_string以空格拼接 token 并去掉##粘连SentencePiece 模式下直接调用 SP 模型的decode见 tokenization_bert_japanese.py。词表加载load_vocab按行读取vocab.txt构造OrderedDicttoken → id并同步维护反向ids_to_tokens第 38-46、124-125 行。保存save_vocabulary按配置分别写出vocab.txt或 SP 模型的序列化 proto 到spiece.model第 263-293 行。词表扩展get_vocab在基础词表之上合并added_tokens_encoder中未冲突的新增 token。九、参数组合速查与选型建议综合上述实现可将完整组合归纳如下词级分词器子词分词器典型搭配场景basicwordpiece简单位切分无形态学信息仅适合预切好的空格文本mecabwordpiece/character经典cl-tohoku/bert-base-japanese/-char路线词典选ipadic或unidic_litesudachiwordpiece/sentencepiece需要 split_mode A/B/C 粒度控制或规范化投影jumanppwordpiece/sentencepiece追求更高精度的形态素切分选型要点推理必须与训练一致do_lower_case、normalize_text、MeCab 的mecab_dic、Sudachi 的sudachi_split_mode/sudachi_dict_type等任何一项不一致都会改变 token id导致下游模型结果漂移字符级 vs 词法级Character 模式实现简单、无需外部词典且对未知词友好但序列更长、信息粒度更细词法级模式序列更短、语义单元更完整但引入外部解析器依赖与词典normalize_text 影响显著NFKC 会把半角片假名与全角数字统一后再切分。若关闭normalize_textFalse测试显示、会保持原样见 test_mecab_tokenizer_no_normalize对依赖原始表记的任务可能更合适切分粒度对比测试可参考仓库测试同一句 \tストアでiPhone が \n 発売された。在 tests/models/bert_japanese/test_tokenization_bert_japanese.py 中被 ipadicアップルストア一体与 unidic_liteアップル/ストア拆分解析出不同结果直接展示了词典差异对下游词表覆盖的影响。十、延伸阅读模型结构 API与 BERT 完全一致BERT 模型文档分词器完整源码tokenization_bert_japanese.py行为验证用例test_tokenization_bert_japanese.py日语 extra 依赖声明setup.pyAutoTokenizer 路由注册tokenization_auto.py本文对应的英文原文文档docs/source/en/model_doc/bert-japanese.md另有日文、韩文译版如果你手头的任务恰好是处理无空格书写的日语文本那么基于BertJapaneseTokenizer的词法级MeCab/Sudachi/Juman 子词级WordPiece/Character/SentencePiece两段式流水线就是与预训练权重对齐度最高、也最值得在生产中复用的分词方案。【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Transformers 中的 BertJapanese：基于 MeCab/Sudachi 等分词的日语 BERT 分词器全解析

相关推荐

浏览器并发请求限制与HTTP/1.1性能优化实战

qwen-vl-utils 避坑实战：3 个函数搞定高分辨率图片与长视频的 Token 爆炸

模板代码调试指南：从通用思路到多场景实战解析

更多资讯

AI工程从零搭建：可审计可压测的生产级RAG系统

Hermes Agent：从工具调用到经验复用的AI范式突破

AI降噪技术解决告警风暴：DBSCAN与XGBoost实战

AI工程化操作系统：Python+TypeScript+Rust三层架构实践

OpenClaw异常消耗问题分析与解决方案

UI自动化测试批量执行优化与pytest实战

今日更新

淘宝商品详情API开发实战与性能优化指南

Unity Package Manager刷新错误排查与解决方案

Java record 规范构造器能否被反序列化或反射绕过

本周精选

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

基于DRV8818与STM32的双极步进电机驱动方案实战解析

DRV8818PWPR+PIC18F45K80双极步进电机控制方案实战

本月热门

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

基于DRV8818与STM32的双极步进电机驱动方案实战解析

DRV8818PWPR+PIC18F45K80双极步进电机控制方案实战

读完文章，想聊聊您的网站？