如果你正在用大模型做流式对话大概率会碰到一个现象接口返回的不是完整句子而是一小段一小段的 token 字符串把这些片段按顺序拼起来最终才是你看到的完整回答。这个把 token 重新变成文本的过程就是 tokenizer 里的 decode。很多初学者接触大模型时会把 tokenizer 简单理解成“切词工具”只关心 encode 阶段文本怎么切成 id 送给模型。但实际上decode 才是让模型输出“变成人话”的关键。模型在每一步生成的是一个整数 idid 本身没有意义只有通过词表映射回 token再经过解码规则还原成字符串用户才能真正读懂。这篇文章是“从零构建大模型”系列的第二篇焦点放在 decode从 BPE 编码结果回到可读文本。我们会从 BPE 的原理讲起用一份极简 Python 实现跑通 train / encode / decode 全流程再结合 Hugging Face Transformers 中的真实 tokenizer把 decode 最常见的坑——空格、特殊 token、Unicode 报错——一次性讲清楚。读完这篇文章你应该能做到看懂 tokenizer 的 vocab 和 merges 文件手动实现一个能还原文本的 decode 函数以及在 transformers 库中正确使用 decode 接口而不踩坑。1. 解码为什么是大模型最容易忽视的环节先抛一个反直觉的观点在训练和推理的大部分时间里模型根本不知道“文本”是什么。大模型吃进去的是 token id吐出来的也是 token id。所谓“分词”“编码”本质上是把人类语言转换成模型能处理的整数序列而 decode 就是把整数序列还原成人类语言。也就是说encode 是模型的输入端decode 是模型的输出端。很多同学只研究输入端却在输出端直接踩坑。举几个真实场景你在做文本生成模型返回了一串 id你直接打印出来看结果是[15496, 2159, 11, 995]这种数字完全不知道模型说了什么。你想把用户输入传给模型但不知道用什么编码方式结果中文变成了一串\xe5\x9c\xa8之类的字节或者直接报UnicodeDecodeError。你生成了一句话decode 之后发现词和词之间没有空格或者首尾多了奇怪的符号Ġ、▁。你批量推理把所有序列一起 decode结果每个句子后面都跟着一堆[PAD]。这些问题不是模型本身的问题而是 tokenizer 的 decode 环节没有处理对。理解了 decode你才算真正掌握了大模型输入输出闭环。另一个容易混淆的点decode 并不总是一个严格可逆的过程。由于 tokenizer 里可能包含 normalization归一化步骤比如小写转换、Unicode 规范化decode(encode(text))的结果不一定和原始文本完全一致。BERT-base-uncased会把Hello变成hello这就是模型设计时想要的。理解这一点能避免你在做 round-trip 测试时产生不必要的困惑。2. BPE 和 tokenizer 的核心概念2.1 什么是 BPEBPE 全称 Byte Pair Encoding中文常翻译为“字节对编码”。它最初是数据压缩领域的一种算法后来被引入自然语言处理领域成为 GPT、BERT、RoBERTa 等主流模型的子词切分算法。BPE 的核心思想很简单从字符级别开始反复合并语料中频率最高的相邻字符对形成新的子词单元。比如如果文本中e和r相邻出现非常多那么er就会成为一个新的 token。继续迭代er又可能和n合并成ern。最终得到的是一棵从字符到子词、再到完整词汇的合并规则树。这个设计的目的是在“词汇表大小”和“序列长度”之间找一个平衡如果只用单个字符词表很小但任何单词都要拆成很多 token序列变长训练推理开销大。如果直接用完整单词词表可能变成几十万甚至上百万而且遇到没见过的新词会直接 OOVOut of Vocabulary词表外单词报错。BPE 用中间层级的子词单元既能覆盖绝大多数单词又能通过组合表示未见过的单词例如low和est合并成lowest。2.2 encode、tokenize、decode 的关系在 Hugging Face 的 tokenizer 体系中有几个概念经常被混用概念作用返回内容tokenize把文本切分成 token 字符串列表[Hello, ,, World]encode把文本转换成模型输入的 id 列表[15496, 2159, 11, 995]decode把 id 列表还原成文本Hello, Worldconvert_ids_to_tokens把 id 映射成 token 字符串[hello, ,, world]容易犯的错误是直接用convert_ids_to_tokens的结果做字符串拼接希望还原文本。这在很多模型上会得到hello world但没有空格或者出现Ġ、▁这样的特殊符号。正确做法永远是调用tokenizer.decode因为它会处理空格、特殊标记和字节级还原。2.3 为什么 decode 不是简单查表最直观的想法是每个 id 对应词表中的一个字符串把这些字符串拼起来不就是文本吗问题在于BPE 的子词在拼接时需要额外的规则才能还原原始空格。以 GPT-2 的 Byte-level BPE 为例空格会被编码成一个特殊字符Ġ如果直接拼接然后打印你会看到一堆看着像乱码的符号。decode 过程要把这些特殊字符还原为真正的空格并且如果 token 本身是 UTF-8 字节片段还需要按字节重新解码成 Unicode 字符。所以decode 的本质是把整数 id 序列映射回 token 字符串再做字符串层级的还原和清理。3. BPE 的训练、编码与解码原理要真正理解 decode必须先理解 BPE 是如何训练的以及编码时 merge 规则是怎么应用的。3.1 BPE 训练流程BPE 的训练可以分成四步将语料按空格切分成单词序列并在每个单词末尾加一个词尾标记比如/w表示“这个词结束了”。把每个单词拆成单个字符统计所有相邻字符对的出现频率。找到频率最高的相邻字符对将它们合并成一个新的符号。重复第 2、3 步直到达到预设的 merge 次数或词表大小。举一个最小例子。假设语料只有low和lowest两个词初始切分为l o w /w和l o w e s t /w。统计相邻对l o出现 2 次o w出现 2 次w /w出现 1 次w e出现 1 次……如果l o频率最高就把它合并成lo。之后语料变成lo w /w和lo w e s t /w。继续迭代lo w出现 2 次合并成low。最终可能得到low/w、lowest/w等 token。训练完成之后会得到两个关键产物词表 vocab所有合法 token 的集合。合并规则 merges合并的先后顺序列表例如[(l, o), (lo, w), ...]。3.2 BPE 编码流程编码时输入是一段文本。BPE 编码的原则是严格按照训练时得到的 merge 顺序把文本逐步合并成词表中的 token。具体做法是把文本按空格切成单词每个单词末尾加/w。把每个单词拆成字符。遍历 merge 规则如果当前字符序列中出现了规则中的相邻对就执行合并每个规则可以重复应用直到无法再合并为止。最后把合并得到的 token 序列映射成 id。3.3 BPE 解码流程这是本文的核心。BPE 解码不是把 merge 规则一步步逆推而是更直接的字符串拼接过程。因为编码过程中我们并没有丢失原始字符信息——每个 token 都是原始字符序列合并后的子串最后编码得到的 token 序列只要按照顺序拼接起来再处理词尾标记/w和特殊空格符号就能还原原始文本。以 GPT-2 的 Byte-level BPE 为例解码流程是把每个 id 映射回词表中的 token 字符串。把 token 字符串逐个拼接。把Ġ替换成普通空格。如果 token 是字节级表示把整个字符串按 UTF-8 字节解码回文本。所以decode 在 BPE 体系里恰恰是最简单的部分。它看起来“反直觉”的原因在于很多初学者误以为需要把 merge 规则倒过来逐步拆开但实际上不需要。3.4 一个容易误解的点空格标记不同的 tokenizer 用不同的方式表示空格GPT-2 的 Byte-level BPE 用Ġ表示空格。SentencePiece 用▁表示空格且它通常放在词的开头而不是结尾。经典 BPE 教程用/w表示词尾decode 时替换为空格。如果你用convert_ids_to_tokens查看中间结果会看到它们但用decode时这些细节已经被自动处理了。这也是为什么我一直强调实际工程里直接用 tokenizer 提供的高层接口而不是自己拼接。4. 最小 BPE 实现与 decode 完整代码下面我们用纯 Python 实现一个最简单的 BPE tokenizer包含训练、编码、解码三个部分。代码不依赖任何第三方库目标是跑通全流程理解原理。为了简化这里用/w表示词尾decode 时把它替换成空格。这个实现会丢失原始文本里多个连续空格的信息但足以演示 BPE 的核心逻辑。4.1 训练 BPE 词表和 merge 规则# bpe_mini.py import re from collections import Counter def get_vocab(text): 将文本按空白切分并在每个词尾添加 /w 标记。 返回一个 Counterkey 是字符元组value 是词频。 words text.split() vocab Counter() for w in words: chars list(w) [/w] vocab[tuple(chars)] 1 return vocab def get_stats(vocab): 统计词表中所有相邻字符对的频率。 pairs Counter() for word, freq in vocab.items(): for i in range(len(word) - 1): pairs[(word[i], word[i 1])] freq return pairs def merge_vocab(pair, vocab): 将 vocab 中的所有相邻字符对 pair 合并成一个新符号。 v_out {} bigram .join(pair) merged .join(pair) for word in vocab: w .join(word) w2 w.replace(bigram, merged) v_out[tuple(w2.split())] vocab[word] return v_out def train_bpe(text, num_merges): 训练 BPE返回合并规则列表。 vocab get_vocab(text) merges [] for _ in range(num_merges): pairs get_stats(vocab) if not pairs: break best max(pairs, keypairs.get) merges.append(best) vocab merge_vocab(best, vocab) return merges这段代码的核心在于merge_vocab。它利用字符串替换的方式把形如(l, o)的相邻对替换成lo。这里的关键是顺序训练时生成的 merge 顺序决定了编码时的合并顺序不能打乱。4.2 实现 encode 和 decode# bpe_mini.py 续 def encode(text, merges): 按训练好的 merge 规则把文本编码成 token 序列。 这里返回的是字符串 token而不是整数 id。 words text.split() tokens [] for w in words: chars list(w) [/w] for pair in merges: i 0 while i len(chars) - 1: if chars[i] pair[0] and chars[i 1] pair[1]: chars chars[:i] [pair[0] pair[1]] chars[i 2:] else: i 1 tokens.extend(chars) return tokens def decode(tokens): 把 token 序列还原成文本。 /w 是词尾标记decode 时替换为空格。 text .join(tokens) text text.replace(/w, ) return text.strip()encode的实现思路是对每个词单独应用 merge 规则。因为训练时不会跨词合并所以编码时也不需要跨词合并。每应用一个 merge 规则如果当前序列匹配就合并并继续从头开始匹配同一个规则直到没有匹配项。decode就更简单了把所有 token 字符串拼起来再把/w还原成空格。这就是 BPE 解码的精髓。4.3 用最小语料跑通全流程# bpe_mini.py 续 if __name__ __main__: corpus ( low low low low low lower lowest newest newest newest newest newest newest widest widest widest width width width ) merges train_bpe(corpus, 30) print(学习到的 merge 规则) for m in merges: print(m) sample lowest newest wider tokens encode(sample, merges) print(\n编码后的 token 序列) print(tokens) restored decode(tokens) print(\n解码还原的文本) print(restored) print(\n是否还原成功, restored sample)运行这段代码你会看到类似下面的输出学习到的 merge 规则 (n, e) (e, w) (w, e) (l, o) (o, w) (ne, w) (low, e) (newe, s) ... 编码后的 token 序列 [low, e, st, /w, newe, s, t, /w, w, i, d, e, r, /w] 解码还原的文本 lowest newest wider 是否还原成功 True注意由于语料不同你运行得到的 merge 顺序可能和这里不完全一致。关键是最后restored sample为True说明 encode 和 decode 是自洽的。这个小实现虽然在工程上非常粗糙但它完整展示了 BPE 的 train / encode / decode 闭环。理解它再去看 Hugging Face 源码或 GPT-2 的 tokenizer会轻松很多。5. 真实大模型中的 decodeHugging Face 与 Byte-level BPE生产环境不太可能用上面这种纯手写实现更常见的是使用 Hugging Face Transformers 自带的 tokenizer。下面看一个最常用的例子。5.1 BERT 和 GPT-2 的 encode 与 decodefrom transformers import AutoTokenizer # BERT 使用 WordPiece不是 BPE但封装方式一样 bert_tokenizer AutoTokenizer.from_pretrained(bert-base-uncased) text Hello, World! ids bert_tokenizer(text)[input_ids] print(BERT ids:, ids) print(BERT decode:, bert_tokenizer.decode(ids))输出大概是BERT ids: [101, 7592, 1010, 2088, 999, 102] BERT decode: [CLS] hello, world! [SEP]这里有两个值得注意的点[CLS]和[SEP]是特殊 token。decode默认会把它们显示出来如果不想看到需要传skip_special_tokensTrue。Hello被还原成了hello因为bert-base-uncased在 tokenization 之前做了 lowercasing小写化。这就是前面说的 normalization 导致 decode 不能完全还原原始文本。再看 GPT-2 的 Byte-level BPEfrom transformers import GPT2Tokenizer tokenizer GPT2Tokenizer.from_pretrained(gpt2) text Hello, World! 你好 ids tokenizer.encode(text) print(GPT-2 ids:, ids) # 看一下每个 id 对应的 token 字符串 print(tokens:, tokenizer.convert_ids_to_tokens(ids)) print(decode:, tokenizer.decode(ids))输出大致是GPT-2 ids: [15496, 11, 995, 0, 34387, 198, 34387, 120] tokens: [Hello, ,, ĠWorld, !, Ġä, ½, Ġ, ä, ½] decode: Hello, World! 你好关键点来了convert_ids_to_tokens的结果里出现Ġ它是 GPT-2 对空格的编码。如果你直接把这些 token 拼接会得到Hello,ĠWorld!Ġä½Ġä½看起来像乱码。而tokenizer.decode会自动把Ġ还原成空格并把字节级 token 按 UTF-8 还原成中文。这就是“decode 必须在 tokenizer 层面完成而不是手动拼接”的最有力证据。5.2 SentencePiece 风格的空格标记如果你使用 T5、XLM-Roberta、Llama 等基于 SentencePiece 的模型会看到另一种空格标记▁。from transformers import AutoTokenizer tokenizer AutoTokenizer.from_pretrained(xlm-roberta-base) text I love NLP ids tokenizer(text)[input_ids] print(tokenizer.convert_ids_to_tokens(ids)) print(tokenizer.decode(ids))输出可能是[s, ▁I, ▁love, ▁N, L, P, /s] s I love NLP/s▁表示空格并且 SentencePiece 习惯把空格标记放在词的开始位置而不是结束位置。decode 时会把它还原成空格。如果你用convert_ids_to_tokens自行拼接很容易丢掉这些空格。5.3 使用 decode 时如何正确做批量解码批量生成时最容易出现的错误是把 padding token 一起解码出来。比如from transformers import AutoTokenizer tokenizer AutoTokenizer.from_pretrained(bert-base-uncased) batch tokenizer([hello world, hi], paddingTrue, truncationTrue) print(batch[input_ids]) print(tokenizer.decode(batch[input_ids][1]))输出可能是[[101, 7592, 2088, 102, 0, 0], [101, 7632, 102, 0, 0, 0]] [CLS] hi [SEP] [PAD] [PAD] [PAD]所以批量解码时要么把attention_mask中为 0 的位置过滤掉要么直接传skip_special_tokensTrue。注意skip_special_tokens默认是False它只会跳过pad、s这类特殊 token不会自动帮你把字符串里的[PAD]找出来。实际项目里更推荐这样处理def clean_decode(tokenizer, input_ids, attention_mask): valid_ids [ id_ for id_, mask in zip(input_ids, attention_mask) if mask 1 ] return tokenizer.decode(valid_ids, skip_special_tokensTrue)6. 运行结果与效果验证写 decode 逻辑时不能只看“能跑”要验证“还原正确”。这里给一个完整的验证思路。6.1 验证 round-trip所谓 round-trip就是text - encode - decode之后能否回到原始文本。from transformers import AutoTokenizer tokenizer AutoTokenizer.from_pretrained(bert-base-uncased) test_cases [ hello world, the quick brown fox jumps over the lazy dog, tokenization is not hard, ] for text in test_cases: ids tokenizer.encode(text) decoded tokenizer.decode(ids, skip_special_tokensTrue) print(f{text} - {decoded} - {text decoded})注意这里不能直接用原始字符串和 decode 结果比较因为bert-base-uncased会把大写转小写中文也不支持。更适合比较的是小写化后的文本或者使用gpt2这类大小写敏感的模型。6.2 验证中文是否完整还原中文场景下最容易踩的坑就是 Unicode 解码问题。下面的代码演示了错误使用 decode 时会出现什么情况from transformers import GPT2Tokenizer tokenizer GPT2Tokenizer.from_pretrained(gpt2) text 深度学习 ids tokenizer.encode(text) print(ids:, ids) print(token 字符串:, tokenizer.convert_ids_to_tokens(ids)) print(decode 结果:, tokenizer.decode(ids))你会看到 GPT-2 把中文拆成了多个字节 token但最终decode能够完整还原成“深度学习”。这就是 Byte-level BPE 对 Unicode 的处理方式。6.3 手动拼接 token 导致 UnicodeDecodeError如果你绕过decode手动把 token 拼接后按某种编码解码很容易遇到报错。比如下面这个例子# 模拟一个常见的错误操作把 UTF-8 字节序列用 ascii 解码 token_bytes b\xe5\x9c\xa8 # UTF-8 编码的“在” print(token_bytes.decode(ascii))运行时会抛出UnicodeDecodeError: ascii codec cant decode byte 0xe5 in position 0: ordinal not in range(128)在 BPE 场景里这种错误通常出现在你试图手写解码逻辑却没有正确处理 UTF-8 字节边界的时候。正确的做法是交给 tokenizer 的 decode 方法或者用bytes(ids).decode(utf-8)这种基于原始字节的方式。7. 常见问题与排查思路下面这些问题是 tokenizer decode 环节最常见的我按“现象 - 可能原因 - 排查方式 - 解决方案”整理成了表格方便收藏。问题现象可能原因排查方式解决方案decode 结果中空格消失直接拼接convert_ids_to_tokens的结果打印convert_ids_to_tokens观察Ġ或▁改用tokenizer.decode不要手动拼接解码时出现 UnicodeDecodeError把 UTF-8 字节 token 交给 ascii 或错误编码解码查看异常栈定位是哪个 decode 调用交给 tokenizer 内部处理或bytes(...).decode(utf-8)批量解码结果尾部出现[PAD]没有过滤 padding token检查input_ids尾部是否存在 pad id使用attention_mask过滤或skip_special_tokensTruedecode 结果首尾多出空格/w或▁被还原成空格对比期望输出按需strip()但流式输出时不能直接 strip中文被拆成很多片段Byte-level BPE 对中文按 UTF-8 字节切分打印convert_ids_to_tokens正常现象decode能还原不要手动合并特殊 token 出现在生成结果中模型输出了s、/s、[CLS]等打印generated_ids生成时设置skip_special_tokensTruedecode 结果不是原始输入tokenizer 包含 normalization例如小写化对比大小写和 Unicode 规范化结果根据模型设计判断是否合规必要时选择无 normalization 的模型8. 工程实践建议与后续学习方向掌握了原理和常见坑之后再聊几个工程层面的建议。这些建议适用于本地推理、线上服务、流式输出等真实场景。8.1 流式输出时不要直接拼接半个 token大模型生成是逐个 token 产生的。如果每次只对新 token 做 decode可能会出现“半个词”的显示问题因为一个汉字可能被拆成多个字节 token一次 decode 一个 token 时只能得到不完整的字节序列。常用的做法有两种每次把已经生成的全部 token id 追加到自己维护的列表中整体 decode 后更新界面。缺点是 token 多了以后每次全量解码开销稍大。做增量 decode。把之前的“稳定文本”缓存下来每次只解码新增部分并尝试去掉末尾不完整的字节片段。实现稍微复杂但效率更高。如果只是写 demo推荐第一种简单直接full_ids [] for new_id in stream_generate(): full_ids.append(new_id) text tokenizer.decode(full_ids, skip_special_tokensTrue) # 更新界面8.2 训练自己的 tokenizer 时合并规则要保留如果你用 SentencePiece 或 Hugging Face Tokenizers 训练自己的 BPE tokenizer训练完一定要保留两个文件vocab.json或tokenizer.json词表。merges.txt合并规则。部署时服务端和客户端必须使用完全相同的 tokenizer 文件。很多线上事故都是模型权重换了、tokenizer 没换或者两边词表不一致导致的。8.3 在 Python 中统一使用 UTF-8无论是读取语料、保存 tokenizer、还是处理中文文本一律在代码里显式指定 UTF-8 编码with open(corpus.txt, r, encodingutf-8) as f: text f.read()不要依赖操作系统默认编码。很多 UnicodeDecodeError 就是因为在 Windows 下读取了包含中文的文本却用了默认的 GBK 编码。8.4 为 tokenizer 写 round-trip 测试在你的代码仓库里加一个简单的测试防止后续改动把 decode 弄坏def test_round_trip(tokenizer, text): ids tokenizer.encode(text) decoded tokenizer.decode(ids, skip_special_tokensTrue) assert text decoded, fround-trip failed: {text} - {decoded}要注意这个测试只对没有 normalization 或 normalization 不影响文本的 tokenizer 才严格成立。对bert-base-uncased这种模型测试前需要先把 text 转成小写。8.5 后续学习方向如果这篇文章帮你建立了 BPE 和 decode 的直觉下一步可以继续深入这几个方向SentencePiece 的 Unigram 语言模型分词算法以及它和 BPE 的区别。Byte-level BPE 如何在字节层面处理多语言为什么它对中文和 emoji 更友好。在部署大模型时prefill 阶段和 decode 阶段对 tokenizer 的不同效率要求。如何训练一个面向中文垂直领域的高质量 tokenizer以及如何在领域语料上进行增量训练。如果只记住一件事那我建议收藏这句话decode 的本质不是把 merge 规则倒过来执行而是把 token 序列按词表展开并做字符串级别的还原。这个认知能帮你绕开 tokenizer 相关的大部分坑。