Transformers 填充Padding与截断Truncation完整指南参数语义、组合策略与源码实现【免费下载链接】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本文围绕 Transformers 官方文档《Relleno y truncamiento》docs/source/es/pad_truncation.md展开系统讲解 Tokenizer 编码时padding、truncation、max_length三个核心参数的取值语义与推荐组合方式并结合 tokenization_utils_base.py 的源码实现深入说明这些策略在底层是如何被解析与执行的。读完本文你将能够针对变长批次输入这一 NLP 高频场景为文本分类、问答、序列标注等任务正确配置填充与截断并理解 Tensor Cores 优化、padding token 校验等细节。为什么需要填充与截断批量batched输入的样本通常长度各不相同无法直接转换为固定大小的张量tensor。填充Padding与截断Truncation正是解决这一问题的两种策略用于从变长批次中构造出矩形rectangular张量填充Padding向较短的序列追加特殊的padding token使其长度等于批次中最长序列的长度或等于模型可接受的最大输入长度截断Truncation反向操作把过长的序列截短。在绝大多数场景下把批次填充到最长序列的长度 截断到模型可接受的最大长度的组合已经足够高效。但 API 还支持更多策略只需掌握三个参数padding、truncation和max_length。padding 参数控制填充策略padding参数接受布尔值或字符串控制是否填充以及填充到什么长度取值行为True或longest填充到批次中最长序列的长度如果只传入单条序列则不进行任何填充max_length填充到max_length参数指定的长度若未提供max_length即max_lengthNone则填充到模型可接受的最大输入长度。即使只传入单条序列也会执行填充False或do_not_pad默认不进行填充允许批次内序列长度不一致从源码看这些取值最终被映射为PaddingStrategy枚举定义于 tokenization_utils_base.pyTrue默认解析为PaddingStrategy.LONGEST填充到批次最长序列max_length对应PaddingStrategy.MAX_LENGTHFalse对应PaddingStrategy.DO_NOT_PAD。truncation 参数控制截断策略truncation参数同样接受布尔值或字符串控制是否截断以及采用哪种截断方式取值行为True或longest_first截断到max_length指定的长度未提供时截断到模型最大可接受长度max_lengthNone。该策略会逐 token 截断当输入是序列对或序列对批次时每次从当前较长的那条序列中移除一个 token交替进行直到达到目标长度only_second截断到max_length或模型最大可接受长度当输入为序列对或序列对批次时只截断第二句only_first截断到max_length或模型最大可接受长度当输入为序列对或序列对批次时只截断第一句False或do_not_truncate默认不进行截断即使序列长度超过模型最大可接受输入尺寸也原样输出这些取值在源码中对应TruncationStrategy枚举见 tokenization_utils_base.pyclass TruncationStrategy(ExplicitEnum): ONLY_FIRST only_first ONLY_SECOND only_second LONGEST_FIRST longest_first DO_NOT_TRUNCATE do_not_truncate其中longest_first是唯一一种会动态平衡序列对两侧长度的策略它逐 token 截断每次优先从当前更长的序列中移除 token直到整体长度达标适合希望尽量均衡保留句子对内容的场景如问答中的 question/context 对。max_length控制填充与截断的目标长度max_length参数控制填充和截断的目标长度可以是整数或None当取值为None时会自动使用模型可接受的最大输入长度model_max_length若模型没有特定的最大输入长度如 XLNet则截断到 max_length和填充到 max_length会被自动停用相关策略降级为不执行。源码中对应逻辑在_get_padding_truncation_strategiestokenization_utils_base.py当max_length is None时若当前策略需要MAX_LENGTH则读取self.model_max_length若model_max_length大于内部阈值LARGE_INTEGER表示模型没有明确的最大长度限制则把策略回退为DO_NOT_PAD或DO_NOT_TRUNCATE。这里有一个值得注意的向后兼容行为见 tokenization_utils_base.py如果只设置了max_length而没有显式设置padding与truncation框架会自动激活truncation longest_first——即只传max_length等价于按模型最大长度截断。组合配置速查表推荐用法全集下表总结了填充与截断的推荐配置方式覆盖了无截断 / 截断到模型最大长度 / 截断到指定长度三大类场景。如果你的输入是序列对或序列对批次可以把下表中的truncationTrue替换为从[only_first, only_second, longest_first]中选择的某一策略例如truncationonly_second或truncationlongest_first以精确控制句子对中两条序列的截断方式。截断方式填充方式推荐调用不截断不填充tokenizer(batch_sentences)填充到批次最长长度tokenizer(batch_sentences, paddingTrue)或tokenizer(batch_sentences, paddinglongest)填充到模型最大输入长度tokenizer(batch_sentences, paddingmax_length)填充到指定长度tokenizer(batch_sentences, paddingmax_length, max_length42)填充到某值的整数倍tokenizer(batch_sentences, paddingTrue, pad_to_multiple_of8)截断到模型最大输入长度不填充tokenizer(batch_sentences, truncationTrue)或tokenizer(batch_sentences, truncationESTRATEGIA)填充到批次最长长度tokenizer(batch_sentences, paddingTrue, truncationTrue)或tokenizer(batch_sentences, paddingTrue, truncationESTRATEGIA)填充到模型最大输入长度tokenizer(batch_sentences, paddingmax_length, truncationTrue)或tokenizer(batch_sentences, paddingmax_length, truncationESTRATEGIA)填充到指定长度不可行截断到指定长度不填充tokenizer(batch_sentences, truncationTrue, max_length42)或tokenizer(batch_sentences, truncationESTRATEGIA, max_length42)填充到批次最长长度tokenizer(batch_sentences, paddingTrue, truncationTrue, max_length42)或tokenizer(batch_sentences, paddingTrue, truncationESTRATEGIA, max_length42)填充到模型最大输入长度不可行填充到指定长度tokenizer(batch_sentences, paddingmax_length, truncationTrue, max_length42)或tokenizer(batch_sentences, paddingmax_length, truncationESTRATEGIA, max_length42)表中两个不可行组合需要特别说明截断到模型最大输入长度 填充到指定长度不可行因为截断目标是模型最大长度时若再指定一个不同的填充目标长度两者会互相冲突截断到指定长度 填充到模型最大输入长度不可行同理当max_length已作为截断目标时无法同时让它作为填充到模型最大长度的长度来源。直观的速记法则是max_length同时服务于截断与max_length模式的填充因此指定具体长度与模型最大长度这两类目标在同一调用中只能二选一。实战示例从批次文本到张量以batch_sentences为例三种最常用的配置如下from transformers import AutoTokenizer tokenizer AutoTokenizer.from_pretrained(bert-base-uncased) batch_sentences [ But what about second breakfast?, Dont think he knows about second breakfast, Pip., What about elevensies?, ]最常用组合填充到批次最长 截断到模型最大长度BERT 最大输入长度 512return_tensorspt返回 PyTorch 张量便于直接送入模型encoded tokenizer( batch_sentences, paddingTrue, # 填充到批次最长序列 truncationTrue, # 截断到模型最大可接受长度 return_tensorspt, )填充到指定长度配合paddingmax_lengthencoded tokenizer(batch_sentences, paddingmax_length, max_length42)截断到指定长度短文本不受影响长文本被截短encoded tokenizer(batch_sentences, truncationTrue, max_length42)填充到 8 的整数倍配合 Tensor Cores 优化见下文encoded tokenizer(batch_sentences, paddingTrue, pad_to_multiple_of8)相关扩展参数pad_to_multiple_of、padding_side 与溢出 token除了文档重点介绍的三个参数编码 API 还提供若干与填充/截断配套的实用参数完整定义见 tokenization_utils_base.py 中的ENCODE_KWARGS_DOCSTRINGpad_to_multiple_ofint可选将序列填充到该值的整数倍前提是已激活padding。其核心价值在于对齐 NVIDIA Tensor Cores计算能力 7.5Volta 及以后的硬件上张量维度对齐到 8 的倍数可显著提升矩阵运算效率。源码在 tokenization_utils_base.py 中还会额外校验若同时启用了截断且max_length不是pad_to_multiple_of的整数倍会抛出错误提示避免出现填充目标与截断目标不一致的歧义。padding_sidestr可选选择填充发生在右侧right还是左侧left。默认值取自 tokenizer 类属性。注意部分架构如基于 Transformer decoder 的自回归模型要求左填充left padding因为右侧位置用于生成 token。strideint默认 0与return_overflowing_tokensTrue配合使用让溢出overflowingtoken 片段与截断后的主片段保持一定数量的重叠 token适合需要滑动窗口切分长文档的场景如长文本分类、问答中的长 context。return_overflowing_tokensbool默认False是否返回因截断而溢出的 token 序列。注意当输入为序列对或序列对批次且truncation_strategy longest_first即True时源码会直接报错而不是返回溢出 token因为longest_first是两侧交替截断无法干净地切分出单一溢出片段。return_tensorspt返回 PyTorch 张量、np返回 NumPy 数组、tf返回 TensorFlow 张量是编码结果直接送入模型的关键参数。return_attention_mask/return_token_type_ids是否返回注意力掩码与 token 类型 ID。注意力掩码在填充场景下至关重要——模型需要靠它区分真实 token 与 padding token。源码级原理策略是如何被解析的所有 tokenizer无论快慢在调用时都会经过PreTrainedTokenizerBase.__call__其中策略解析集中在_get_padding_truncation_strategies方法tokenization_utils_base.py其处理顺序可以归纳为四步向后兼容仅传max_length而未显式指定截断策略时自动激活truncation longest_first归一化策略枚举paddingTrue→PaddingStrategy.LONGESTtruncationTrue→TruncationStrategy.LONGEST_FIRST字符串取值直接映射到对应枚举解析max_lengthmax_lengthNone时按需回退到model_max_length若模型无明确最大长度model_max_length超过内部LARGE_INTEGER阈值MAX_LENGTH类策略自动降级为不执行参数合法性校验激活填充但 tokenizer 没有 padding token 时抛出ValueError见 tokenization_utils_base.py提示信息同时给出两种解决方案——将eos_token设为pad_token或通过add_special_tokens({pad_token: [PAD]})新增 pad token。最后一步校验在实际使用中非常常见像 GPT、Llama 这类 decoder-only 模型默认没有pad_token直接调用tokenizer(batch, paddingTrue)就会触发该报错。此时可以按报错提示操作tokenizer.pad_token tokenizer.eos_token # 或 tokenizer.add_special_tokens({pad_token: [PAD]})与相关文档的衔接填充与截断是 Tokenizer 使用的通用概念与当前仓库的以下文档配套阅读效果更佳tokenizer_summary.md三种子词分词算法BPE、Unigram、WordPiece的原理理解 token 从哪里来fast_tokenizers.md快速 tokenizer 中填充/截断的额外行为差异data_collators.mdDataCollatorWithPadding等数据整理器在训练循环中自动执行填充padding_free.md连续批处理continuous batching等场景下去填充padding-free的替代方案。小结填充与截断是构造变长批次张量的基础能力掌握padding、truncation、max_length三个参数的取值语义就掌握了 Tokenizer 输出的形状控制权longest与max_length两种填充目标、longest_first/only_first/only_second三种截断策略以及pad_to_multiple_of、padding_side、stride等配套参数共同构成了从原始文本到模型可消费张量的完整控制面。配合 tokenization_utils_base.py 中_get_padding_truncation_strategies的解析逻辑你可以准确预判任何参数组合的行为——包括那些不可行的组合为什么被设计为不可行。【免费下载链接】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 填充（Padding）与截断（Truncation）完整指南：参数语义、组合策略与源码实现
Transformers 填充Padding与截断Truncation完整指南参数语义、组合策略与源码实现【免费下载链接】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本文围绕 Transformers 官方文档《Relleno y truncamiento》docs/source/es/pad_truncation.md展开系统讲解 Tokenizer 编码时padding、truncation、max_length三个核心参数的取值语义与推荐组合方式并结合 tokenization_utils_base.py 的源码实现深入说明这些策略在底层是如何被解析与执行的。读完本文你将能够针对变长批次输入这一 NLP 高频场景为文本分类、问答、序列标注等任务正确配置填充与截断并理解 Tensor Cores 优化、padding token 校验等细节。为什么需要填充与截断批量batched输入的样本通常长度各不相同无法直接转换为固定大小的张量tensor。填充Padding与截断Truncation正是解决这一问题的两种策略用于从变长批次中构造出矩形rectangular张量填充Padding向较短的序列追加特殊的padding token使其长度等于批次中最长序列的长度或等于模型可接受的最大输入长度截断Truncation反向操作把过长的序列截短。在绝大多数场景下把批次填充到最长序列的长度 截断到模型可接受的最大长度的组合已经足够高效。但 API 还支持更多策略只需掌握三个参数padding、truncation和max_length。padding 参数控制填充策略padding参数接受布尔值或字符串控制是否填充以及填充到什么长度取值行为True或longest填充到批次中最长序列的长度如果只传入单条序列则不进行任何填充max_length填充到max_length参数指定的长度若未提供max_length即max_lengthNone则填充到模型可接受的最大输入长度。即使只传入单条序列也会执行填充False或do_not_pad默认不进行填充允许批次内序列长度不一致从源码看这些取值最终被映射为PaddingStrategy枚举定义于 tokenization_utils_base.pyTrue默认解析为PaddingStrategy.LONGEST填充到批次最长序列max_length对应PaddingStrategy.MAX_LENGTHFalse对应PaddingStrategy.DO_NOT_PAD。truncation 参数控制截断策略truncation参数同样接受布尔值或字符串控制是否截断以及采用哪种截断方式取值行为True或longest_first截断到max_length指定的长度未提供时截断到模型最大可接受长度max_lengthNone。该策略会逐 token 截断当输入是序列对或序列对批次时每次从当前较长的那条序列中移除一个 token交替进行直到达到目标长度only_second截断到max_length或模型最大可接受长度当输入为序列对或序列对批次时只截断第二句only_first截断到max_length或模型最大可接受长度当输入为序列对或序列对批次时只截断第一句False或do_not_truncate默认不进行截断即使序列长度超过模型最大可接受输入尺寸也原样输出这些取值在源码中对应TruncationStrategy枚举见 tokenization_utils_base.pyclass TruncationStrategy(ExplicitEnum): ONLY_FIRST only_first ONLY_SECOND only_second LONGEST_FIRST longest_first DO_NOT_TRUNCATE do_not_truncate其中longest_first是唯一一种会动态平衡序列对两侧长度的策略它逐 token 截断每次优先从当前更长的序列中移除 token直到整体长度达标适合希望尽量均衡保留句子对内容的场景如问答中的 question/context 对。max_length控制填充与截断的目标长度max_length参数控制填充和截断的目标长度可以是整数或None当取值为None时会自动使用模型可接受的最大输入长度model_max_length若模型没有特定的最大输入长度如 XLNet则截断到 max_length和填充到 max_length会被自动停用相关策略降级为不执行。源码中对应逻辑在_get_padding_truncation_strategiestokenization_utils_base.py当max_length is None时若当前策略需要MAX_LENGTH则读取self.model_max_length若model_max_length大于内部阈值LARGE_INTEGER表示模型没有明确的最大长度限制则把策略回退为DO_NOT_PAD或DO_NOT_TRUNCATE。这里有一个值得注意的向后兼容行为见 tokenization_utils_base.py如果只设置了max_length而没有显式设置padding与truncation框架会自动激活truncation longest_first——即只传max_length等价于按模型最大长度截断。组合配置速查表推荐用法全集下表总结了填充与截断的推荐配置方式覆盖了无截断 / 截断到模型最大长度 / 截断到指定长度三大类场景。如果你的输入是序列对或序列对批次可以把下表中的truncationTrue替换为从[only_first, only_second, longest_first]中选择的某一策略例如truncationonly_second或truncationlongest_first以精确控制句子对中两条序列的截断方式。截断方式填充方式推荐调用不截断不填充tokenizer(batch_sentences)填充到批次最长长度tokenizer(batch_sentences, paddingTrue)或tokenizer(batch_sentences, paddinglongest)填充到模型最大输入长度tokenizer(batch_sentences, paddingmax_length)填充到指定长度tokenizer(batch_sentences, paddingmax_length, max_length42)填充到某值的整数倍tokenizer(batch_sentences, paddingTrue, pad_to_multiple_of8)截断到模型最大输入长度不填充tokenizer(batch_sentences, truncationTrue)或tokenizer(batch_sentences, truncationESTRATEGIA)填充到批次最长长度tokenizer(batch_sentences, paddingTrue, truncationTrue)或tokenizer(batch_sentences, paddingTrue, truncationESTRATEGIA)填充到模型最大输入长度tokenizer(batch_sentences, paddingmax_length, truncationTrue)或tokenizer(batch_sentences, paddingmax_length, truncationESTRATEGIA)填充到指定长度不可行截断到指定长度不填充tokenizer(batch_sentences, truncationTrue, max_length42)或tokenizer(batch_sentences, truncationESTRATEGIA, max_length42)填充到批次最长长度tokenizer(batch_sentences, paddingTrue, truncationTrue, max_length42)或tokenizer(batch_sentences, paddingTrue, truncationESTRATEGIA, max_length42)填充到模型最大输入长度不可行填充到指定长度tokenizer(batch_sentences, paddingmax_length, truncationTrue, max_length42)或tokenizer(batch_sentences, paddingmax_length, truncationESTRATEGIA, max_length42)表中两个不可行组合需要特别说明截断到模型最大输入长度 填充到指定长度不可行因为截断目标是模型最大长度时若再指定一个不同的填充目标长度两者会互相冲突截断到指定长度 填充到模型最大输入长度不可行同理当max_length已作为截断目标时无法同时让它作为填充到模型最大长度的长度来源。直观的速记法则是max_length同时服务于截断与max_length模式的填充因此指定具体长度与模型最大长度这两类目标在同一调用中只能二选一。实战示例从批次文本到张量以batch_sentences为例三种最常用的配置如下from transformers import AutoTokenizer tokenizer AutoTokenizer.from_pretrained(bert-base-uncased) batch_sentences [ But what about second breakfast?, Dont think he knows about second breakfast, Pip., What about elevensies?, ]最常用组合填充到批次最长 截断到模型最大长度BERT 最大输入长度 512return_tensorspt返回 PyTorch 张量便于直接送入模型encoded tokenizer( batch_sentences, paddingTrue, # 填充到批次最长序列 truncationTrue, # 截断到模型最大可接受长度 return_tensorspt, )填充到指定长度配合paddingmax_lengthencoded tokenizer(batch_sentences, paddingmax_length, max_length42)截断到指定长度短文本不受影响长文本被截短encoded tokenizer(batch_sentences, truncationTrue, max_length42)填充到 8 的整数倍配合 Tensor Cores 优化见下文encoded tokenizer(batch_sentences, paddingTrue, pad_to_multiple_of8)相关扩展参数pad_to_multiple_of、padding_side 与溢出 token除了文档重点介绍的三个参数编码 API 还提供若干与填充/截断配套的实用参数完整定义见 tokenization_utils_base.py 中的ENCODE_KWARGS_DOCSTRINGpad_to_multiple_ofint可选将序列填充到该值的整数倍前提是已激活padding。其核心价值在于对齐 NVIDIA Tensor Cores计算能力 7.5Volta 及以后的硬件上张量维度对齐到 8 的倍数可显著提升矩阵运算效率。源码在 tokenization_utils_base.py 中还会额外校验若同时启用了截断且max_length不是pad_to_multiple_of的整数倍会抛出错误提示避免出现填充目标与截断目标不一致的歧义。padding_sidestr可选选择填充发生在右侧right还是左侧left。默认值取自 tokenizer 类属性。注意部分架构如基于 Transformer decoder 的自回归模型要求左填充left padding因为右侧位置用于生成 token。strideint默认 0与return_overflowing_tokensTrue配合使用让溢出overflowingtoken 片段与截断后的主片段保持一定数量的重叠 token适合需要滑动窗口切分长文档的场景如长文本分类、问答中的长 context。return_overflowing_tokensbool默认False是否返回因截断而溢出的 token 序列。注意当输入为序列对或序列对批次且truncation_strategy longest_first即True时源码会直接报错而不是返回溢出 token因为longest_first是两侧交替截断无法干净地切分出单一溢出片段。return_tensorspt返回 PyTorch 张量、np返回 NumPy 数组、tf返回 TensorFlow 张量是编码结果直接送入模型的关键参数。return_attention_mask/return_token_type_ids是否返回注意力掩码与 token 类型 ID。注意力掩码在填充场景下至关重要——模型需要靠它区分真实 token 与 padding token。源码级原理策略是如何被解析的所有 tokenizer无论快慢在调用时都会经过PreTrainedTokenizerBase.__call__其中策略解析集中在_get_padding_truncation_strategies方法tokenization_utils_base.py其处理顺序可以归纳为四步向后兼容仅传max_length而未显式指定截断策略时自动激活truncation longest_first归一化策略枚举paddingTrue→PaddingStrategy.LONGESTtruncationTrue→TruncationStrategy.LONGEST_FIRST字符串取值直接映射到对应枚举解析max_lengthmax_lengthNone时按需回退到model_max_length若模型无明确最大长度model_max_length超过内部LARGE_INTEGER阈值MAX_LENGTH类策略自动降级为不执行参数合法性校验激活填充但 tokenizer 没有 padding token 时抛出ValueError见 tokenization_utils_base.py提示信息同时给出两种解决方案——将eos_token设为pad_token或通过add_special_tokens({pad_token: [PAD]})新增 pad token。最后一步校验在实际使用中非常常见像 GPT、Llama 这类 decoder-only 模型默认没有pad_token直接调用tokenizer(batch, paddingTrue)就会触发该报错。此时可以按报错提示操作tokenizer.pad_token tokenizer.eos_token # 或 tokenizer.add_special_tokens({pad_token: [PAD]})与相关文档的衔接填充与截断是 Tokenizer 使用的通用概念与当前仓库的以下文档配套阅读效果更佳tokenizer_summary.md三种子词分词算法BPE、Unigram、WordPiece的原理理解 token 从哪里来fast_tokenizers.md快速 tokenizer 中填充/截断的额外行为差异data_collators.mdDataCollatorWithPadding等数据整理器在训练循环中自动执行填充padding_free.md连续批处理continuous batching等场景下去填充padding-free的替代方案。小结填充与截断是构造变长批次张量的基础能力掌握padding、truncation、max_length三个参数的取值语义就掌握了 Tokenizer 输出的形状控制权longest与max_length两种填充目标、longest_first/only_first/only_second三种截断策略以及pad_to_multiple_of、padding_side、stride等配套参数共同构成了从原始文本到模型可消费张量的完整控制面。配合 tokenization_utils_base.py 中_get_padding_truncation_strategies的解析逻辑你可以准确预判任何参数组合的行为——包括那些不可行的组合为什么被设计为不可行。【免费下载链接】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），仅供参考