分词系统

相关源文件

• docs/source/en/gguf.md
• src/transformers/configuration_utils.py
• src/transformers/convert_slow_tokenizer.py
• src/transformers/feature_extraction_utils.py
• src/transformers/file_utils.py
• src/transformers/integrations/ggml.py
• src/transformers/modeling_flax_utils.py
• src/transformers/modeling_gguf_pytorch_utils.py
• src/transformers/modeling_tf_utils.py
• src/transformers/models/llama/tokenization_llama.py
• src/transformers/models/llama/tokenization_llama_fast.py
• src/transformers/models/seamless_m4t/tokenization_seamless_m4t.py
• src/transformers/models/siglip/tokenization_siglip.py
• src/transformers/models/t5/tokenization_t5.py
• src/transformers/models/t5/tokenization_t5_fast.py
• src/transformers/models/udop/convert_udop_to_hf.py
• src/transformers/models/udop/tokenization_udop.py
• src/transformers/models/udop/tokenization_udop_fast.py
• src/transformers/tokenization_utils.py
• src/transformers/tokenization_utils_base.py
• src/transformers/tokenization_utils_fast.py
• src/transformers/utils/hub.py
• tests/models/fnet/test_tokenization_fnet.py
• tests/models/layoutlmv2/test_tokenization_layoutlmv2.py
• tests/models/layoutlmv3/test_tokenization_layoutlmv3.py
• tests/models/layoutxlm/test_tokenization_layoutxlm.py
• tests/models/llama/test_tokenization_llama.py
• tests/models/markuplm/test_tokenization_markuplm.py
• tests/models/t5/test_tokenization_t5.py
• tests/models/tapas/test_tokenization_tapas.py
• tests/models/udop/test_tokenization_udop.py
• tests/quantization/ggml/test_ggml.py
• tests/test_configuration_common.py
• tests/test_feature_extraction_common.py
• tests/test_modeling_flax_common.py
• tests/test_modeling_tf_common.py
• tests/test_tokenization_common.py
• tests/tokenization/test_tokenization_fast.py
• tests/tokenization/test_tokenization_utils.py

目的与范围

分词系统提供了一个统一的接口，用于将文本转换为可由 transformer 模型处理的 token。它支持快速（基于 Rust）和慢速（基于 Python）分词器，处理特殊 token，管理词汇表，并支持不同分词格式之间的转换，包括 GGUF 文件。

有关模型加载和配置的信息，请参阅 基础类和模型加载。有关自动选择分词器的 Auto Classes 的详细信息，请参阅 Auto Classes 系统。

架构概述

分词系统围绕分层类结构构建，基础类提供通用功能，特定实现则针对不同分词器类型。

类层次结构

来源： src/transformers/tokenization_utils_base.py15-891 src/transformers/tokenization_utils_fast.py82-93 src/transformers/tokenization_utils.py1-700

分词流程

来源： src/transformers/tokenization_utils_base.py2500-2700 src/transformers/tokenization_utils_fast.py200-400

基类

PreTrainedTokenizerBase

PreTrainedTokenizerBase 类是所有分词器的基础，提供了编码、解码和批量处理的核心功能。

关键方法

• __call__() - 主要分词接口
• encode() - 将文本转换为 token ID
• decode() - 将 token ID 转换回文本
• batch_encode_plus() - 批量分词，支持填充/截断

来源： src/transformers/tokenization_utils_base.py2500-2800 src/transformers/tokenization_utils_base.py3000-3200

SpecialTokensMixin

SpecialTokensMixin 处理特殊 token，例如 [CLS]、[SEP]、<pad>、<unk> 等。

特殊 token 属性

• bos_token - 序列开始
• eos_token - 序列结束
• unk_token - 未知 token
• sep_token - 分隔符 token
• pad_token - 填充 token
• cls_token - 分类 token
• mask_token - 掩码 token
• additional_special_tokens - 自定义特殊 token

来源： src/transformers/tokenization_utils_base.py847-900 src/transformers/tokenization_utils_base.py858-878

BatchEncoding

BatchEncoding 类封装了分词器的输出，并提供了处理分词序列的实用方法。

主要功能

• 访问分词结果的类似字典的接口
• 张量转换方法
• 用于快速分词器的 token-to-word/character 映射
• PyTorch 张量的设备传输方法

来源： src/transformers/tokenization_utils_base.py192-790

快速分词器 vs 慢速分词器

快速分词器 (PreTrainedTokenizerFast)

快速分词器基于 HuggingFace 的 tokenizers 库（用 Rust 编写），可显著提高性能。

优点

• 速度：比慢速分词器快 5-20 倍
• 对齐跟踪：Character/word 到 token 的映射
• 批量处理优化
• 高级预处理和后处理

来源： src/transformers/tokenization_utils_fast.py98-127 src/transformers/convert_slow_tokenizer.py127-133

慢速分词器 (PreTrainedTokenizer)

慢速分词器是纯 Python 实现，提供兼容性和自定义选项。

用例

• 调试和检查
• 自定义分词逻辑
• 没有快速分词器支持的模型
• 研究和实验

来源： src/transformers/tokenization_utils.py200-500

GGUF 集成

该分词系统支持从 GGUF (GPT-Generated Unified Format) 文件加载分词器，从而实现与量化模型的集成。

GGUF 分词器加载

来源： src/transformers/tokenization_utils_fast.py121-127 src/transformers/integrations/ggml.py36-110 src/transformers/modeling_gguf_pytorch_utils.py37-53

GGUF 分词器转换

该系统包含用于 GGUF 文件中不同分词器类型的转换器。

来源： src/transformers/integrations/ggml.py400-600 src/transformers/convert_slow_tokenizer.py400-1000

特定模型的 Pipe

Llama 分词器

Llama 分词器使用 SentencePiece，支持慢速和快速实现。

关键文件

• LlamaTokenizer - 基于 SentencePiece 的慢速分词器
• LlamaTokenizerFast - 具有 ByteFallback 的快速分词器

特性

• SentencePiece 词汇表
• 对 <s>、</s>、<unk> 的特殊处理
• 聊天模板支持
• 旧版行为选项

来源： src/transformers/models/llama/tokenization_llama.py56-130 src/transformers/models/llama/tokenization_llama_fast.py46-100

T5 分词器

T5 分词器处理序列到序列任务，并对前缀进行特殊处理。

特性

• 带有额外 ID 的 SentencePiece
• 任务前缀处理
• 特殊 token 规范化

来源： src/transformers/models/t5/tokenization_t5.py45-80 src/transformers/models/t5/tokenization_t5_fast.py40-80

关键工作流程

分词器创建工作流程

来源： src/transformers/tokenization_utils_base.py1800-2000 src/transformers/tokenization_utils_fast.py130-200

文本处理管道

来源： src/transformers/tokenization_utils_base.py2500-2700 src/transformers/tokenization_utils_fast.py200-400

文件组织

组件	主要文件
基类	tokenization_utils_base.py
快速分词器	tokenization_utils_fast.py
慢速分词器	tokenization_utils.py
转换工具	convert_slow_tokenizer.py
GGUF 集成	integrations/ggml.py, modeling_gguf_pytorch_utils.py
模型分词器	models/{model}/tokenization_{model}.py
测试	tests/test_tokenization_common.py

来源： src/transformers/tokenization_utils_base.py1-50 src/transformers/tokenization_utils_fast.py1-50 src/transformers/integrations/ggml.py1-50