vLLM 源码完全拆解（三十五）：Renderer 与分词输入侧——文本如何变成 token、又怎样被预算截断

注册表：tokenizer_mode 不是「快慢」二选一

早期 vLLM 的 tokenizer_mode 只有 auto、slow、mistral 三个选择：auto 使用 fast tokenizer，slow 强制慢实现，mistral 走 Mistral 的专用分词器。当前实现把它扩展成一张注册表：每个 mode 映射到一个模块和一个类，auto 只是「先探测、再回退」的入口。

1
_VLLM_TOKENIZERS = {
2
    "hf": ("hf", "CachedHfTokenizer"),
3
    "mistral": ("mistral", "MistralTokenizer"),
4
    "deepseek_v32": ("deepseek_v32", "DeepseekV32Tokenizer"),
5
    "deepseek_v4": ("deepseek_v4", "DeepseekV4Tokenizer"),
6
    "deepseek_v41": ("deepseek_v41", "DeepseekV41Tokenizer"),
7
    "kimi_audio": ("kimi_audio", "KimiAudioTokenizer"),
8
    "alpamayo2_super": ("alpamayo2_super", "Alpamayo2SuperTokenizer"),
9
    # ... 其余专用 tokenizer
10
}
11

12
TokenizerRegistry = _TokenizerRegistry(
13
    {
14
        mode: (f"vllm.tokenizers.{mod}", cls)
15
        for mode, (mod, cls) in _VLLM_TOKENIZERS.items()
16
    }
17
)

这张表背后是一个很重要的设计判断：分词不是纯文本问题，它和模型家族绑死。DeepSeek V3.2/V4 的 tokenizer 要处理特殊的 BOS、EOS 与编码规则；Mistral 的 Tekken tokenizer 有自己的词表格式；Kimi Audio 要把音频 token 与文本 token 放进同一个序列。把这些差异塞进一个 AutoTokenizer 分支会让代码变成无数个 if model_type == ...，注册表把差异收敛到「mode → 类」的一条映射上。

resolve_tokenizer_args 负责把用户传入的 auto 解析成具体 mode，顺序是：

1. 如果设置了 VLLM_USE_MODELSCOPE，先从 ModelScope 下载 tokenizer 文件，并忽略权重文件；
2. 按 runner 类型设置默认截断方向：generate/draft 用 left，pooling 用 right；
3. 如果仓库里有 tekken.json 或 tokenizer.model.v*，并且是 Mistral 模型仓库，自动切到 mistral；
4. 仍然为 auto 就回退到 hf；
5. hf 模式下强制 mistral_format=False，并从快照目录中排除权重，避免为了一个 tokenizer 拉下几十 GB 权重。

第 2 步的截断方向值得单独解释。生成请求默认从左边截断，保留尾部；池化请求默认从右边截断，保留头部。原因不是随意的：生成模型通常把系统提示放在开头，但上下文窗口不够时，用户更关心最近的对话，所以保留尾部；嵌入/重排模型要对整段文本做 pooling，截掉尾部比截掉开头更符合「保留开头主旨」的直觉。这个默认值会被后面的 TokenizeParams.truncation_side 覆盖，但它解释了为什么同一个 tokenizer_mode 在两个 runner 下行为不同。

get_tokenizer：一次加载，长期缓存

get_tokenizer 的职责比名字看起来重。它要做五件事：

1
def get_tokenizer(tokenizer_name, *args, tokenizer_cls=TokenizerLike, ...):
2
    if envs.VLLM_USE_FASTOKENS:
3
        from .fastokens import apply_fastokens_patch
4
        apply_fastokens_patch()
5

6
    requested_name = str(tokenizer_name)
7
    tokenizer_mode, tokenizer_name, args, kwargs = cached_resolve_tokenizer_args(...)
8

9
    if tokenizer_cls == TokenizerLike:
10
        tokenizer_cls_ = TokenizerRegistry.load_tokenizer_cls(tokenizer_mode)
11
    else:
12
        tokenizer_cls_ = tokenizer_cls
13

14
    config = get_config(tokenizer_name, config_format=..., ...)
15
    # 某些模型的 hub tokenizer_class 是错的，直接绕过 AutoTokenizer
16
    if model_type in _MODEL_TYPES_WITH_INCORRECT_TOKENIZER_CLASS:
17
        tokenizer_cls_ = TokenizersBackend
18

19
    tokenizer = tokenizer_cls_.from_pretrained(tokenizer_name, *args, **kwargs)
20
    if not tokenizer.is_fast:
21
        logger.warning("Using a slow tokenizer. This might cause a significant slowdown.")
22
    return tokenizer

三个细节值得展开。

第一，cached_resolve_tokenizer_args 是 lru_cache 包住的。 解析 mode 需要访问 Hugging Face Hub（判断是不是 Mistral 仓库、有没有 Tekken 文件），如果每个请求都做一次，网络抖动会直接变成请求延迟。缓存键包含 tokenizer 名称、revision、runner 类型、tokenizer_mode 等参数，因此同一个模型的不同 revision 不会串味。

第二，_MODEL_TYPES_WITH_INCORRECT_TOKENIZER_CLASS 是一张「Hub 元数据不可信」名单。 名单里的模型（例如 internlm2、step3_vl、unlimited-ocr）在 Hub 上声明的 tokenizer_class 与权重实际使用的分词器不一致，AutoTokenizer 会选错类。vLLM 的处理是绕过 AutoTokenizer，直接用通用的 TokenizersBackend 加载。这不是优雅的长期方案，源码注释也写明：更好的修法是让 Transformers 维护同样的名单，或者让模型作者修正 Hub 元数据。工程代码经常要在「等上游修」和「先让用户跑起来」之间做这种局部妥协。

第三，config 被显式传给 AutoTokenizer。 正常情况下 AutoTokenizer.from_pretrained 会自己重新读 config.json；vLLM 已经把 config 读进来了，再读一次不仅浪费，还存在竞态：两次读取之间 Hub 缓存被刷新，第二次可能读到不完整的文件。源码用 kwargs.setdefault("config", config) 复用第一次的结果，并在需要时把 _name_or_path 改回用户请求的 Hub ID，避免日志里出现本地快照路径。

CachedHfTokenizer：把重复属性计算缓存起来

Transformers 的 tokenizer 有很多「每次访问都重新算」的属性：all_special_ids、all_special_tokens、get_vocab()、__len__。对一个每秒处理上千请求的服务，这些属性会被反复访问，累积起来不可忽略。get_cached_tokenizer 用一个动态生成的子类把这些值固定在实例上：

1
class CachedTokenizer(tokenizer.__class__):
2
    @property
3
    def all_special_ids(self):
4
        return tokenizer_all_special_ids
5

6
    @property
7
    def max_token_id(self):
8
        return max_token_id
9

10
    @property
11
    def max_chars_per_token(self):
12
        return max_chars_per_token
13

14
    def get_vocab(self):
15
        return tokenizer_vocab
16

17
    def __len__(self):
18
        return tokenizer_len

max_chars_per_token 是这里最关键的派生量：它等于词表中最长 token 字符串的字符数。它给了 vLLM 一个不需要分词就能算出的字符上界——如果一段文本有 $C$ 个字符，那么它的 token 数至少是 $\lceil C / L_{\max} \rceil$，其中 $L_{\max}$ 就是 max_chars_per_token。反过来，如果 $C > T_{\max} \cdot L_{\max}$，这段文本一定超过 $T_{\max}$ 个 token。下一节的字符级预检查就建立在这个不等式上。

max_token_id 的推导还处理了一个边界：某些 tokenizer（例如 Qwen 系列）的 vocab_size 包含实现里额外添加的特殊 token，但这些 token 不在 get_vocab() 里。源码取两者最大值，保证后续按 token ID 上界做分配或校验时不会因为少算特殊 token 而越界。

为什么把模板渲染塞进 tokenizer 是不行的

早期 vLLM 的聊天请求处理方式是：拿到 messages 列表，调用 tokenizer.apply_chat_template(..., tokenize=True) 一步得到 token ID。这个写法简单，但把三件事耦合在了一次调用里：

1. 模板渲染：根据 Jinja 模板把消息列表转成一段文本，这一步需要知道 tools、reasoning_effort、内容格式（string 还是 openai 分块）等模板参数；
2. 分词：把文本转成 token ID；
3. 多模态对齐：图像/音频在模板里是一个占位符，分词之后要把它换成一串 token，并记录这串 token 在序列中的位置。

第三步在多模态模型里尤其麻烦：模板渲染时并不知道图像占多少 token，要等视觉处理器算出 patch 数量；而分词又只能处理文本。如果这三步都在 apply_chat_template 里，任何一处的策略变化都要改动同一个函数。

当前实现的拆法是：BaseRenderer 定义了 render_prompt（把原始输入变成 DictPrompt）和 tokenize_prompts（把 DictPrompt 变 token）两个可独立重写的阶段；render_cmpl / render_chat 是两个顶层入口，各自按顺序调这两个阶段，最后调用 process_for_engine 组装多模态特征与引擎输入。

1
def render_chat(self, conversations, chat_params, tok_params=None, ...):
2
    arrival_time = time.time()
3
    if tok_params is None:
4
        tok_params = self.default_chat_tok_params
5

6
    rendered = [self.render_messages(c, chat_params) for c in conversations]
7
    ...
8
    tok_prompts = self.tokenize_prompts(dict_prompts, tok_params)
9
    ...
10
    eng_prompts = [
11
        self.process_for_engine(p, arrival_time, skip_mm_cache=skip_mm_cache,
12
                                tok_params=tok_params)
13
        for p in tok_prompts
14
    ]
15
    return out_conversations, eng_prompts

注意 render_chat 返回的是二元组：out_conversations 是「模板层面理解后的会话」，eng_prompts 是引擎输入。前者用于输出侧的增量解码与工具调用解析——这些解析器需要知道 user 与 assistant 的分界在模板里的确切形式，而不是从 token 流里猜。

默认 TokenizeParams 的两个差异：add_special_tokens

default_cmpl_tok_params 与 default_chat_tok_params 只差一个字段，但理由不同：

1
# Completion
2
TokenizeParams(max_total_tokens=model_config.max_model_len,
3
               do_lower_case=encoder_config.get("do_lower_case", False),
4
               add_special_tokens=True)
5

6
# Chat
7
TokenizeParams(max_total_tokens=model_config.max_model_len,
8
               do_lower_case=encoder_config.get("do_lower_case", False),
9
               add_special_tokens=False)

补全请求的输入是原始文本，用户期望模型看到的正是他写的文本，因此 tokenizer 的默认行为——自动补 BOS——是合理的。聊天请求的输入是「模板已经渲染好的文本」，好的 chat template 已经把 BOS 或 <|im_start|> 等特殊 token 写进了文本；如果再让 tokenizer 补一次，就会出现两个 BOS。这不是理论问题：Qwen 系列的模板以 <|im_start|>system 开头，Llama 3 的模板同样显式放入 <|begin_of_text|>，重复补 BOS 会让模型行为明显走样。

多模态模型的情况又不同：如果渲染器挂着 mm_processor，两个默认值都取自 mm_processor.info.default_tok_params。原因在于视觉占位符的 token 化参数要与多模态处理器自己算出的 token 数保持一致——处理器按 default_tok_params 预算图像 patch 的 token 数，如果分词侧用了别的参数（例如多加了 BOS），两边就会错一位，后面所有 offset 与 length 全部错位。

把渲染与分词合并会放大截断的错误

把模板渲染与分词拆成两个阶段，除了职责清晰，还消除了一个合并实现时的典型错误：apply_chat_template(tokenize=True) 内部的截断语义与用户的 truncate_prompt_tokens 不一致。HF 的 apply_chat_template 在 tokenize=True 时会先渲染文本，再调用 tokenizer；它支持 max_length 与 truncation 参数，但截断侧取自 tokenizer 的默认值，而不是用户为这次请求指定的方向。更麻烦的是，它会在渲染后立刻做截断，此时多模态占位符还是一个 token，展开之后又会超预算，而 apply_chat_template 本身无法在此之后重新校验。

拆开之后，每一段职责都持有自己的参数：渲染阶段只关心文本如何拼接、特殊 token 是否由模板提供；分词阶段只关心文本如何变成 token、截断预算与并行偏移；多模态展开阶段只关心占位符如何替换与对齐。任何一段出问题，错误信息都指向具体那一段，而不是笼统的「tokenizer 报错」。

safe_apply_chat_template 做的三件防御性工作

模板渲染本身也有工程细节。safe_apply_chat_template 在调用 Jinja 之前会：

1. 解析模板来源：从 tokenizer 自带的 chat_template、用户请求里传入的 chat_template、或模型配置的默认模板中确定最终模板；如果三者都没有，直接抛出 ChatTemplateResolutionError，说明 Transformers v4.44 之后不再允许隐式使用默认模板。
2. 处理 developer 角色：OpenAI 协议新增了 developer 角色，但很多模型的模板只认识 system。如果模板里没有 developer 分支，函数会把这类消息转换成 system 并合并相邻的 system 消息。这一步必须在渲染之前做，否则 Jinja 会走到 else 分支把消息当作用户消息处理。
3. 统一 return_dict：Transformers v5 把 apply_chat_template(tokenize=True) 的默认返回类型改成了 BatchEncoding，而 vLLM 下游期望一个扁平的 token 列表。函数在 kwargs 没有显式指定 return_dict 时强制设为 False，保证 v4 与 v5 下行为一致。

第三点是典型的「上游默认值变更」问题。推理框架的依赖范围很宽：部署环境里 Transformers 可能是 v4 也可能是 v5，如果代码依赖的是默认值，升级就会静默地改变返回类型，最终表现为「渲染结果是一个 dict，prompt_token_ids 取出来是 None」这类难以定位的错误。显式设置参数，抵消上游默认值变更，是框架层常用的兼容手段。

模板错误如何变成 400

模板本身可以在渲染时抛出异常，例如用户给 reasoning_effort 传了一个模板不支持的值，模板里可能写 {{ error("unsupported reasoning_effort") }} 或直接比较失败。源码的处理是把这类异常转换为 VLLMValidationError，并提取模板里的原因：

1
except Exception as e:
2
    # 模板通过抛异常来拒绝不合法的用户输入；
3
    # 把它暴露成 400，并带上模板自己的原因（通常列出支持的值）
4
    logger.warning("Chat template rejected the request: %s", e)
5
    raise VLLMValidationError(_template_error_reason(e)) from e

如果不做转换，模板异常会一路冒泡成 500，用户看到的是服务器内部错误，而实际原因是自己的参数不合法。区分 400 与 500 对客户端重试策略影响很大：400 不应该重试，500 往往值得重试。

模板渲染与生成配置的交互

InputProcessor.process_inputs 在拿到引擎输入之后做两件与采样参数有关的事：

1
sampling_params.update_from_generation_config(
2
    self.generation_config_fields,
3
    self.renderer.get_eos_token_id(),
4
)
5
if self.tokenizer is not None:
6
    sampling_params.update_from_tokenizer(self.tokenizer)

generation_config_fields 来自模型的 generation_config.json，它包含模型作者给出的默认温度、top_p、EOS 等。如果客户端没有显式传这些参数，vLLM 会用生成配置补全。update_from_tokenizer 则从 tokenizer 的 eos_token_id 等信息补全停止 token。这两步都必须发生在渲染之后，因为 EOS 列表要同时包含 generation_config 与 tokenizer 各自声明的值——不同模型的 EOS 可能不止一个（例如 <|endoftext|> 与 <|im_end|> 都可能是合法停止点）。

如果渲染阶段把某些特殊 token 当作普通文本处理，或者分词阶段把 EOS 当成了普通 token 的一部分，停止条件就会失效，请求会一直生成到 max_tokens 才停。输入侧与采样侧的这种「隐式契约」是调试中最隐蔽的问题之一：输出看起来正常，只是特别长。

needs_detokenization：给调用方的「可读文本」选项

TokenizeParams 里还有一个不太显眼的字段 needs_detokenization。它的注释特意说明不要与 SamplingParams.detokenize 混淆：后者管理的是模型输出是否要解码成文本，而前者管理的是输入在 token 化之后是否需要重新解码出原始文本。当 needs_detokenization=True 且输入是 token ID 而不是文本时，_tokenize_singleton_prompt 会执行：

1
if params.needs_detokenization and "prompt" not in prompt:
2
    prompt = self._detokenize_prompt(prompt)

它把给定的 token 序列解码回文本，放进 prompt["prompt"]。为什么需要这个？一些下游路径（例如结构化输出解析、内容解析、日志展示）需要原始 prompt 文本，而客户端可能只提供了 token ID（例如已经按 token 计费的前端）。_detokenize_prompt 的注释说明了执行时机：「在截断之后解码，使文本与发送给引擎的 token 匹配」——如果先解码再截断，prompt 文本就是完整未截断的版本，与引擎实际收到的 token 不一致，日志与调试信息会误导人。这个先后顺序看起来是小细节，实际上决定了「日志里看到的 prompt」与「模型看到的 prompt」是否一致。

三个派生量：max_input_tokens、max_truncation_tokens、max_input_chars

1
@property
2
def max_input_tokens(self) -> int | None:
3
    # max_output_tokens 不在这里扣除：这个值代表模型上下文长度本身
4
    return self.max_total_tokens
5

6
@property
7
def max_truncation_tokens(self) -> int | None:
8
    max_input_tokens = self.max_input_tokens
9
    if max_input_tokens is None:
10
        return None
11
    if self.max_output_tokens == 0:
12
        return max_input_tokens
13
    return max(0, max_input_tokens - 1)

max_input_tokens 刻意不扣除输出预算。这一点容易误解成 bug：模型总上下文是 $N$，用户要求生成 $M$ 个 token，那么 prompt 最多只能是 $N-M$，为什么这里返回 $N$？

答案在于「拒绝」和「截断」是两套口径。max_input_tokens 是「不截断时允许的 prompt 上限」，即整个上下文全给输入时能放多少——如果 prompt 本身就有 $N$ 个 token，那它是合法的输入，只是输出预算为 0。真正要扣输出预算的是截断上限：max_truncation_tokens 在生成请求下返回 $N-1$。源码注释写得很直白：如果截断到完整的 $N$，下游 get_max_tokens() 会把采样预算钳到 0，一个超长 prompt 会变成「静默地生成零个 token」，用户既没报错也没输出。

池化请求（embedding、rerank）没有生成阶段，max_output_tokens = 0，因此截断上限就是 $N$，把整个上下文用于输入。这个 0 是有意义的标记而不是「未设置」，判断逻辑必须用它来区分生成与池化，不能写成 if not max_output_tokens 后混入 None。

第三个派生量来自 tokenizer：

其中 $T_{\max} = \texttt{max\_input\_tokens}$，$L_{\max} = \texttt{tokenizer.max\_chars\_per\_token}$。它给出一个不必分词就能算出的字符上限：任何 token 至多对应 $L_{\max}$ 个字符，所以 $T_{\max}$ 个 token 的文本不可能超过 $C_{\max}$ 个字符。反过来讲，如果文本长度超过 $C_{\max}$，那么它一定超过 $T_{\max}$ 个 token，不需要真的分词就能拒绝它。

这个不等式在长文本上的意义值得算一下。对一个典型的约 128k token 上下文的模型，假设 $L_{\max} = 12$，则 $C_{\max} \approx 1.5\text{M}$ 字符。如果用户不截断地送进 5M 字符的文档，直接分词要处理几十 MB 的 Python 字符串并在 Rust/Rayon 分词器里构建大块中间结构，可能消耗数秒 CPU 与上百 MB 内存；而字符检查在 $O(1)$ 的 len(text) 之后就能返回 400。先做字符级上界检查，是给最坏情况设一道廉价的闸门。

字符级预截断与 token 级截断

_text_len_check 按三条分支处理：

1
max_input_chars = max_input_tokens * tokenizer.max_chars_per_token
2

3
if self.truncate_prompt_tokens is None:
4
    if len(text) > max_input_chars:
5
        raise VLLMValidationError("... your prompt contains ...")
6
elif self.truncation_side is not None and len(text) > max_input_chars:
7
    if self.truncation_side == "left":
8
        text = text[-max_input_chars:]
9
    else:
10
        text = text[:max_input_chars]
11
return text

三条分支对应三种意图：

• 不截断（truncate_prompt_tokens is None）：超长就报错，让用户自己处理。这里不能悄悄截断，因为生成的截断结果与用户预期相差很远，而且字符级截断的边界可能切在 token 中间。
• 显式指定截断方向：字符级先截一刀，把送入分词器的字符数压到 $C_{\max}$ 之下。这只是一道资源闸门，不能保证最终 token 数一定不超过 $T_{\max}$：$L_{\max}$ 是「单个 token 最多覆盖多少字符」，$C_{\max}$ 个字符在极端文本上（例如每个 token 只覆盖 1 个字符）仍可能切出超过 $T_{\max}$ 个 token。最终的精确 token 预算仍由后面的 _token_truncation 负责，字符级截断只是保证分词器不会处理一个无限长的字符串。
• 指定了截断数量但没有指定方向（truncation_side is None）：跳过字符级预截断，交给 tokenizer 自己的 truncation=True 处理。为什么这里不做预截断？因为 tokenizer 的默认截断侧可能与我们需要的方向不一致，而且如果不做字符级预截断，tokenizer 在 get_encode_kwargs() 里会用 max_length = max_input_tokens + 1 把输出限制在上限加一，从而既不会浪费资源，又能让 _token_len_check 准确报出「至少超了多少」。

第三分支里 +1 的细节值得单独说。get_encode_kwargs 中：

1
max_length = self.truncate_prompt_tokens
2
if max_length is not None and max_length < 0:
3
    max_length = self.max_truncation_tokens
4
elif max_length is None and self.max_input_tokens is not None:
5
    # 防止 tokenization 消耗超过必要的资源，
6
    # 同时仍然让 _token_len_check 按用户预期失败
7
    max_length = self.max_input_tokens + 1

如果直接用 max_input_tokens 作为 tokenizer 的截断上限，那么超长 prompt 会被截断到恰好 $T_{\max}$，后面的 _token_len_check 看到长度不超过上限就放行了——错误被「成功截断」掩盖。截到 $T_{\max}+1$ 则相反：超长 prompt 被截到上限加一，_token_len_check 看到 $\text{len} > T_{\max}$ 就会报错，并在错误信息里用 at least 限定词说明真实长度可能更大。这是「不截断时保证报错」的实现技巧：用一个精心选择的边界值，让校验函数在压缩后的数据上仍然能做出正确判断。

上图展示 Transformers 的 tokenizer 类继承层次：统一接口 PreTrainedTokenizerBase 位于上层，下面区分实际执行分词的后端和模型专用类。它不是 Normalizer → PreTokenizer → Model 的处理时序图，两者需要分开理解。一次 encode 的内部处理还包括规范化、预分词、模型分词和特殊 token 后处理；vLLM 的字符级截断发生在这些步骤之前，而 max_chars_per_token 反映的是词表里最长 token 的字符数，因此这一字符预算是安全但偏保守的上界。图源：Hugging Face 官方博客。

字符级预截断后的偏移重映射

如果字符级预截断从左侧砍掉了 $K$ 个字符，分词得到的偏移就是相对于截断后文本的。_get_text_truncation_offset 返回这个 $K$，随后 _apply_prompt_char_offset 把它加回每个偏移：

1
if char_offset == 0:
2
    return prompt
3
offsets = prompt.get("prompt_token_offsets")
4
if offsets is not None:
5
    prompt["prompt_token_offsets"] = [
6
        (start, end) if (start, end) == (0, 0)
7
        else (start + char_offset, end + char_offset)
8
        for start, end in offsets
9
    ]

(0, 0) 被特判跳过。Fast tokenizer 对特殊 token（BOS、EOS、模板插入的控制 token）返回 (0, 0)，它不是真实的字符区间；如果也加上 $K$，这些特殊 token 会被「定位」到原文本的第 $K$ 个字符附近，和它们实际的位置毫无关系。这个特判保证特殊 token 保留原来的「无位置」语义。

输入侧在真实工作负载中的位置

要理解这一层为什么值得单独优化，不妨看看它在真实工作负载中的位置。Agent 与多轮对话场景的特点是：每轮调用都携带一整个会话历史，新增加的内容相对很小。TokTier 的论文（Zhenyu Zhang 与 Zhichao Cao，Arizona State University，2026 年 7 月发表于 arXiv）统计了 153,951 次交互式调用，其图 2 给出了「上下文 token 数 $N$」与「每次新增 token 数 $\Delta$」的联合分布：会话续轮集中在比首次会话小一到三个数量级的新增 token 区间，也就是说绝大多数调用的内容是「大上下文 + 小增量」。

这个分布与分词层的两个设计直接相关。第一，如果每次请求都对完整文本重新分词，成本与 $N$ 成正比，而新信息只有 $\Delta$，这就是 vLLM 与大多数前端仍存在的结构性浪费；TokTier 提出的方向是利用会话状态只对增量做分词，并处理「追加可能改变旧 token 边界」的修复问题。第二，正是因为我们讨论的这层代码对每次请求都做完整截断预算，max_input_tokens 附近的请求才会成为热点——大多数续轮请求的 $N$ 都很大且接近上限。理解这两点，就能明白为什么 vLLM 把字符级上界检查放在分词之前：大量请求的 $N$ 接近上限，字符级检查是成本最低的第一道门。

需要说明的是，TokTier 目前发表在 arXiv、尚未被主流推理框架默认合并，它描述的是一种路线而非 vLLM 当前实现；把它的工作负载数据拿来参照的意义在于，它说明了输入侧优化的收益空间有多大。

lru_cache 包住的两个函数

get_tokenizer 与 resolve_tokenizer_args 都被 lru_cache 包过一遍。它们的结果对同一个 (模型, revision, mode, runner_type) 是稳定不变的，缓存命中意味着：

• 不会再次访问 Hub 判断 Mistral 仓库；
• 不会重复调用 AutoTokenizer.from_pretrained，避免重新读取几 MB 的 tokenizer.json；
• 不会重复构建 CachedTokenizer 子类。

在一个多进程部署里，每个 API server 进程都会加载一次 tokenizer，但每个进程内的请求共享同一实例。这是 vLLM 的常规部署模型：tokenizer 是进程级单例，不是请求级对象。

CachedHfTokenizer 的收益量化

max_chars_per_token 的缓存收益可以粗略算一下：Transformers 的 get_vocab() 每次返回一个新的 dict 拷贝，一个 15 万词的词表在 Python 里每次拷贝都要重新分配几 MB 到十几 MB 的字典，耗时在毫秒量级；all_special_ids 与 __len__ 也类似。若每个请求访问一次 max_chars_per_token，在没有缓存的情况下服务吞吐会受 CPU 侧显著拖累。缓存之后，这些值在 tokenizer 加载时算一次，代价只有一次 $O(V)$ 遍历。

max_chars_per_token 本身的计算也值得注意：它遍历整个词表求最长 token 的字符数。对一个混合了英文 BPE 与中文字符的 tokenizer，最长 token 往往是少数「粘贴了大量字符」的特殊 token，所以这个值有时会偏大。偏大的上界只会让字符级截断更保守（留下更长的文本交给分词），不会造成正确性问题。

分词与字符长度的关系：不是线性的

字符级上界不等式只用了词表里最长 token 作为系数，但真实的分词比例取决于文本内容。英文自然语言的约 4 个字符对应一个 token（常见 BPE 词表下），中文则在约 1 到 1.5 个汉字一个 token，代码由于符号多、长标识符少，往往更接近 3 个字符一个 token。这意味着 $L_{\max}$ 通常远大于平均比例（例如 $L_{\max} \approx 12$ 而英文平均约 4），$C_{\max}$ 对常规文本的估计偏保守约三倍。

保守的上界有个直接后果：字符级预截断不会截掉太多不该截的内容，但它也不会真正把文本压到接近 $T_{\max}$ 的真实长度。因此字符级截断之后仍然需要 token 级截断，两层截断的职责不同：字符级保证「不会因为分词本身吃光资源而崩」，token 级保证「语义上的预算不超」。如果只有字符级，截到 $C_{\max}$ 字符的英文文本按 4 字符/token 估算可能仍有约 $3T_{\max}$ 个 token，远超预算，最终仍要由 token 级截断砍掉大部分；反过来，对平均 token 很长的文本，$C_{\max}$ 个字符又可能不到 $T_{\max}$ 个 token，字符级截得不够狠。两层截断缺一不可。

截断方向对缓存命中的影响

truncation_side 的选择除了语义，还影响前缀缓存的命中率。生成请求默认左截断保留尾部：多轮对话里最新的几轮内容在尾部，保留它们让模型看到最近的上下文；前缀缓存按 token 序列前缀匹配，左截断意味着每轮截断后的序列开头都不同，前缀命中率很低。池化请求默认右截断保留头部，前缀是稳定的文档开头，命中率高。

这是一个真实存在的权衡：左截断更符合对话语义，但牺牲缓存；右截断更省算力，但可能丢掉最新的指令。对需要高吞吐的批处理场景，显式设置右截断并组织文档让头部包含关键上下文，能显著提高前缀复用；对交互式对话，左截断几乎总是更合适。vLLM 把这个选择交给用户与 runner_type 的默认值，而不是写死。

max_num_batched_tokens 与输入侧的关系

调度器的 max_num_batched_tokens 控制每步调度的 token 预算，它作用于已经进入引擎的请求。输入侧截断决定了单条请求最大能贡献多少 token：如果 max_model_len 是 128k 而 max_num_batched_tokens 是 8192，那么一条 128k 的请求在开启分块预填充时会以 8192 token 为一块，被拆成 16 个调度步。输入侧的长度校验与调度器的分块是两套不同的机制：前者决定请求是否合法，后者决定合法请求如何被拆开执行。理解这一点，才能明白为什么 truncate_prompt_tokens 不能设置为「反正调度器会分块」——分块解决的是显存与步骤粒度，不解决请求超长被拒绝的问题。

字符与 token 的双重坐标系

输入侧所有偏移、长度、截断都涉及两套坐标系：字符与 token。大多数 bug 出现在两套坐标系之间的转换上：

• 字符级截断改了文本，token 偏移必须同步平移；
• token 级截断改了序列，并行的偏移数组必须同步切片；
• 多模态展开改了序列长度，占位符的 offset 必须随之平移；
• _text_len_check 在小写化之前执行，而 do_lower_case 会改变字符数（某些 Unicode 字符小写后长度不同），所以同一段文本经过 _text_lowercase 后长度可能变化，偏移的假设要在这个前提下成立。

最后一点在源码里有一个隐式的顺序保证：_validate_text 依次执行 _text_len_check 与 _text_lowercase。如果小写化让文本变长（例如土耳其语中某些字符的规则），偏移仍以原始文本为准，这是因为小写化发生在分词之前，分词本身是在小写后的文本上执行，偏移自然对应小写后的文本——但是 _apply_prompt_char_offset 只补了 left 截断的偏移，没有补小写化造成的偏移，这一点在通用文本上没有问题，在特殊语言上值得留意。

多进程下的 tokenizer 一致性

vLLM 支持数据并行与张量并行，但 tokenizer 并不在每条 engine 进程里，而是位于前端（API server）进程；engine 只接收 token ID。多前端部署时，每个前端进程都会独立加载一份 tokenizer，因此必须保证它们完全相同：同样的 mode 解析结果、同样的特殊 token、同样的 max_chars_per_token。resolve_tokenizer_args 的 lru_cache 只在进程内生效，跨进程的一致性依赖的是 Hub 快照路径的规范化（get_non_weight_snapshot_path）与 HF 缓存本身——同一个 revision 会解析到同一份本地文件。如果不同前端用了不同的 tokenizer_mode（例如有人手改了某个进程的参数），同一段文本就会得到不同的 token 序列，前缀缓存的命中率骤降，因为前缀块无法重合。这也是为什么 tokenizer_mode 属于 ModelConfig 的一部分，而不是可以在运行时单独修改的变量。

部署建议

从这层代码可以直接推出几条部署实践：

• 不要手动指定 tokenizer_mode=slow。慢 tokenizer 在 Python 里逐字符处理，吞吐会下降一到两个数量级，源码会在日志里给出明确 warning。
• 生产环境显式设置模板渲染超时。默认 30 秒的意图是防止一个请求卡死服务，但如果有用户提交超长 system prompt 导致模板渲染接近这个时间，可以调大；反过来，如果模板本身有性能问题，调小能让故障更早暴露。
• 多模态服务不要用 renderer_num_workers > 1 搭配池化缓存。源码在 ModelConfig 校验里明确禁止：池化模型的 mm_processor_cache 不是线程安全的，多 worker 会并发操作同一个缓存，因此要求 renderer_num_workers = 1 或关闭缓存。
• 截断方向要显式指定。依赖 tokenizer 的默认截断侧会在更换 tokenizer 版本时悄悄改变行为，显式 truncation_side 可以让行为稳定。