vLLM 源码完全拆解（三十四）：推理内容解析器——同一个模型输出，为什么要拆成内容、思考与工具调用三段

注册表：名字如何变成类

ReasoningParserManager 维护两张表：reasoning_parsers 存已导入的类，lazy_parsers 存 (module_path, class_name)。--reasoning-parser qwen3 只传一个名字，服务启动时通过 get_reasoning_parser() 查表；如果是懒注册项，第一次访问才 importlib.import_module()，并把类缓存回 reasoning_parsers。vllm/reasoning/__init__.py 里的 _REASONING_PARSERS_TO_REGISTER 列出了全部名字，包括 deepseek_r1、deepseek_v3、deepseek_v4、deepseek_v41、qwen3、glm45、glm47、kimi_k2、gptoss、granite 等。懒加载的意义不只是启动速度：不同模型的 parser 可能依赖不同的模板工具，只有真正用到时才导入，可以避免一个模型的依赖拖垮整个服务。

BaseThinkingReasoningParser：一个反向扫描的判定器

绝大多数 ... 模型共享同一套逻辑。BaseThinkingReasoningParser 在构造时做了一件很关键的事：从 tokenizer 词表里查 start_token 与 end_token 的 id，查不到就直接抛 RuntimeError。这是一个启动期失败设计：如果用户把 --reasoning-parser qwen3 配到了一个词表里没有 ... 的模型上，服务应该在启动时拒绝，而不是在线上把整段输出都当成 reasoning。

1
start_token_id = self.vocab.get(self.start_token)
2
end_token_id = self.vocab.get(self.end_token)
3
if start_token_id is None or end_token_id is None:
4
    raise RuntimeError(...)

判定函数从序列末尾往前扫：

1
def is_reasoning_end(self, input_ids):
2
    for i in range(len(input_ids) - 1, -1, -1):
3
        if input_ids[i] == self.start_token_id:
4
            return False
5
        if input_ids[i] == self.end_token_id:
6
            return True
7
    return False

这个”从后往前、先遇到谁算谁”的写法同时处理了三种情况。正常输出是 ...：末尾先遇到 end，返回真；模型没有输出起始标记、直接从思考开始时，序列里只有 end，仍返回真；多轮对话的 prompt 里可能同时出现上一轮的 ... 和这一轮的 ...，从后往前找保证只看最近一段。若一个标记都没有，返回假，表示”当前仍处于思考中”。

extract_content_ids() 的细节更微妙：

1
if self.end_token_id not in islice(input_ids, 0, max(0, len(input_ids) - 1)):
2
    return []
3
else:
4
    return input_ids[input_ids.index(self.end_token_id) + 1 :]

它刻意排除了序列的最后一个 token。原因在于调用时机：当 is_reasoning_end_streaming() 判定本帧出现了 end token 时，parse_delta() 会把 delta_token_ids 传进来取”end 之后的 content ids”。如果 end 恰好是本帧最后一个 token，那么 end 后面没有内容，返回空列表；排除最后一个位置可以避免把 end 自己当成内容。index() 取第一次出现的位置，则对应”重复输出 </think>”的容错：后面的重复标记会被当作普通文本的一部分，而不是再次切换状态。

非流式解析用 partition() 完成：

1
parts = model_output.partition(self.start_token)
2
model_output = parts[2] if parts[1] else parts[0]
3
if self.end_token not in model_output:
4
    return model_output, None
5
reasoning, _, content = model_output.partition(self.end_token)
6
return reasoning, content or None

如果输出里有起始标记，就丢掉起始标记及其之前的内容；如果没有起始标记，则假设整段输出从思考开始。没有 end 标记时，整段都算 reasoning，content 为 None——这正是 max_tokens 截断在思考中途时的正确语义：用户不应该看到一个被截断的”回答”。

流式解析把”起始标记在上一帧还是本帧”与”结束标记在上一帧还是本帧”组合成六种情况。核心代码如下：

1
if self.start_token_id in previous_token_ids:
2
    if self.end_token_id in delta_token_ids:
3
        end_index = delta_text.find(self.end_token)
4
        reasoning = delta_text[:end_index]
5
        content = delta_text[end_index + len(self.end_token):]
6
        return DeltaMessage(reasoning=reasoning, content=content or None)
7
    elif self.end_token_id in previous_token_ids:
8
        return DeltaMessage(content=delta_text)
9
    else:
10
        return DeltaMessage(reasoning=delta_text)
11
elif self.start_token_id in delta_token_ids:
12
    ...
13
else:
14
    return DeltaMessage(content=delta_text)

这张分支表解决的是”一帧里同时发生状态切换”的问题。最常见的切换帧是 ... 后面紧跟 ...：这一帧的 delta_text 既包含思考的尾巴，也包含回答的开头。代码用 find() 在文本里定位 end 标记，切出 reasoning 与 content 两段，放在同一个 DeltaMessage 里。另一个分支 end_token_id in previous_token_ids 表示思考早已结束，本帧全部是 content。单个特殊 token 的帧会被直接跳过，避免把纯标记作为空内容发给客户端。

extract_reasoning_streaming() 还处理了”模型不输出起始标记”的兼容路径。elif self.start_token_id in delta_token_ids 分支只在起始标记出现在本帧时生效；如果整个输出都没有起始标记，会落到最后的 else，把全部文本当作 content。这对某些蒸馏模型是错的：它们直接从思考内容开始，没有 ...。所以 DeepSeekR1ReasoningParser 覆盖了流式方法，补上了”没有起始标记但存在结束标记”的分支：

1
if (
2
    ret is not None
3
    and self.start_token_id not in previous_token_ids
4
    and self.start_token_id not in delta_token_ids
5
):
6
    if self.end_token_id in delta_token_ids:
7
        end_index = delta_text.find(self.end_token)
8
        return DeltaMessage(
9
            reasoning=delta_text[:end_index],
10
            content=delta_text[end_index + len(self.end_token):] or None,
11
        )
12
    elif self.end_token_id in previous_token_ids:
13
        return DeltaMessage(content=delta_text)
14
    else:
15
        return DeltaMessage(reasoning=delta_text)

这段覆盖是 vLLM reasoning parser 里最值得注意的工程细节之一：同一个模型家族的不同微调版本，模板可能不同。R1 蒸馏版经常省略开头的 ...，如果沿用基类逻辑，整段思考会被当成正式回答。parser 不能假设模板永远完整，只能把”缺失起始标记”当作一种合法状态来处理。

count_reasoning_tokens() 用深度计数而不是简单的区间判断：

1
depth = 0
2
for token_id in token_ids:
3
    if token_id == self.start_token_id:
4
        depth += 1
5
    elif token_id == self.end_token_id:
6
        if depth > 0:
7
            depth -= 1
8
    elif depth > 0:
9
        count += 1

这样嵌套的 ... 不会被重复计数，孤立的 end token 也不会把计数减成负数。它只统计两个标记之间的普通 token，不把标记本身算进思考 token 数。

模型差异：DeepSeek V3 的按请求委托

DeepSeekV3ReasoningParser 展示了另一种常见结构：模型同时支持思考与非思考模式，parser 需要按请求决定用哪套逻辑。它在构造时读取 chat_template_kwargs：

1
thinking = bool(chat_kwargs.get("thinking", False))
2
enable_thinking = bool(chat_kwargs.get("enable_thinking", False))
3
thinking = thinking or enable_thinking
4
self._parser = (
5
    DeepSeekR1ReasoningParser(...) if thinking else IdentityReasoningParser(...)
6
)

随后把所有抽象方法原样委托给内部 parser。IdentityReasoningParser 不做任何切分，整段输出都是 content。这意味着 --reasoning-parser deepseek_v3 并不是”永远开启思考解析”，它把”是否思考”的决定权交给每个请求的 chat_template_kwargs。这也是为什么 parser 的构造参数里要带 model_config 与 chat_template_kwargs：parser 的行为不只由模型名决定，还由这一次请求的模板参数决定。

DeepSeekV3ReasoningWithThinkingParser 只是在没有显式指定时把 thinking 与 enable_thinking 都默认成真，供那些”默认思考”的模型别名使用。

DeepSeek-R1 的 chat template 把 assistant 的输出组织成”思考块 + 回答块”。parser 之所以能在流式过程中稳定切分，是因为模板保证两个标记只会以固定字符串出现；而 tokenizer 又保证这两个字符串各自对应稳定的 token id。图片来源：DeepSeek-R1 论文 与官方仓库模板。

adjust_request：工具选择如何变成语法约束

ToolParser.adjust_request() 在请求进入引擎之前被调用。它做两件事：当 tool_choice="required" 或命名函数调用时，把 structured_outputs 设成由工具列表生成的 JSON Schema；并在需要结构标签时跳过已经由统一 parser 设置的标记。

1
json_schema_from_tool = get_json_schema_from_tools(
2
    tool_choice=request.tool_choice,
3
    tools=request.tools,
4
    parallel_tool_calls=request.parallel_tool_calls,
5
)
6
if json_schema_from_tool is not None:
7
    request.structured_outputs = StructuredOutputsParams(json=json_schema_from_tool)
8
    request.response_format = None

这一步与解析器本身看似无关，却是”工具调用为什么能稳定解析”的前提。required 和命名调用走的是约束解码：模型被强制输出符合工具 Schema 的 JSON，解析器只需要把 JSON 解析出来，不需要应付各种自由格式的标记。代价是首次请求要编译语法自动机，官方文档提到命名函数调用的首次延迟会多出数秒，之后由缓存承担。

auto 模式则不同。auto 下模型可以不调用工具，可以直接输出文本，因此不能强制 JSON。vLLM 的做法是提供结构标签（structural tag）：把工具调用的外层信封（标记与函数名）以及可选的参数 Schema 交给 xgrammar，让模型在”自由文本”与”工具调用格式”之间按语法选择。structural_tag_model 指明这个 parser 对应哪一种内置格式，ToolStrictLevel 控制约束强度：

• AUTO：由 tool_choice 与每个工具的 strict 字段共同决定；
• FUNCTION：只要请求带工具，就约束工具调用的信封（标记与函数名），参数内容仍可自由；
• PARAMETER：进一步按每个工具的 Schema 锁定参数，等价于把所有工具都当成 strict: true。

vllm/tool_parsers/tool_strict_level.py 把这三档定义成 IntEnum，服务端可以用 --tool-strict-level 抬高下限。文档特别强调”下限不会放松请求已有的约束”：客户端标了 strict: true 的工具在任何档位都保留 Schema。

这里有一个容易混淆的地方：结构标签约束的是”模型生成什么样”，解析器约束的是”生成结果如何被理解”。两者必须使用同一套格式知识。如果 parser 认为工具调用是 <tool_call><function=...>，而结构标签用的是 Hermes 的 JSON 信封，模型会在语法上被引导到一个 parser 不认识的格式。所以 structural_tag_model 与 parser 的实现是绑定的，不能只改其中一个。

tool_choice 的三种命运

DelegatingParser._extract_tool_calls() 是 tool_choice 语义的集中体现。它按优先级分成四条路径：

1. tool_choice="none"：不解析任何工具调用。对 legacy parser，直接返回 ([], content)，把模型输出原样当内容；对 engine-based parser，仍然走一遍工具解析，但最后清空 tool_calls，以保持内容字段与流式路径一致。
2. 命名调用且 parser 支持 required/named：模型输出被当作被选中函数的参数 JSON，直接构造一个 FunctionCall(name=..., arguments=content)，content 置 None。
3. required 且 parser 支持 required/named：输出应当是 FunctionDefinition 数组，用 pydantic 的 TypeAdapter 校验后逐个转成 FunctionCall。
4. auto，或 required/named 但 parser 不支持：走 parser 自己的 extract_tool_calls()，从模型的原生标记里抽取调用。

这四条路径解释了 supports_required_and_named 的含义。Hermes 这类模型在 required 下会被语法约束成标准 JSON 数组，所以可以直接用第 3 条；GLM 这类模型即使被约束，输出仍是 XML 风格的 <tool_call> 标记，标准 JSON 解析必然失败，因此必须设成 False，让 required 也回退到 parser 的原生解析。

第 4 条还有一个”流末一致性”细节：如果 engine-based parser 没有找到完整调用，它会返回 tool_call_info.content，把不完整的工具标记丢掉；legacy parser 则保留原始 content。这是两种 parser 在 max_tokens 截断时的不同取舍：engine-based 认为”半个工具调用不该出现在回答里”，legacy 认为”用户至少应该看到原始输出”。

_get_function_name() 与 _make_tool_call_id() 负责构造命名调用的协议字段。后者只对 tool_call_id_type == "kimi_k2" 的模型生成确定性 id，其他模型返回 None，由上层按随机或模板规则生成。

ToolACE 在 2024 年提出用”自演化 API 合成 + 双重校验”构造函数调用训练数据，核心目标之一是让模型学会稳定的调用标记与参数格式。解析器的复杂度，本质上是模型训练格式多样性的镜像：训练数据里有哪些信封、参数写法与容错路径，parser 就要在推理侧对应地认出来。图片来源：ToolACE 论文。

传统 parser 的天花板

手写 parser 的典型结构是”在新增文本里找开始标记，再找函数名，再找参数，再用正则或 JSON 解析”。这套结构在单模型、单格式下工作良好，但一旦要支持几十个模型，就会出现三类重复劳动：

• 每个模型都要重新处理”标记被拆到两帧""参数 JSON 不完整""函数名与参数在同一帧”这些相同的边界；
• 每个模型都要自己维护”当前调用下标、函数名是否已发、参数已流出多少”这三份状态；
• 每个模型都要自己实现 extract_content_ids()、is_reasoning_end() 这些与具体标记无关的通用逻辑。

vllm/parser/ 的 ParserEngine 就是为消除这三类重复而出现的：把”格式”写成数据，把”边界处理”写进引擎。

一条 Qwen3 迁移表

以 vllm/parser/qwen3.py 为例。Qwen3 的格式是：

1
...思考...
2
<tool_call>
3
<function=name>
4
<parameter=key>value</parameter>
5
</function>
6
</tool_call>

它的配置从 initial_state = REASONING if thinking else CONTENT 开始，声明了九个终结点，其中 THINK_START、THINK_END、TOOL_START、TOOL_END 同时按 token id 匹配。迁移表里最有信息量的是这几条：

1
(ParserState.REASONING, "THINK_END"): Transition(
2
    ParserState.CONTENT, (EventType.REASONING_END,)
3
),
4
(ParserState.REASONING, "TOOL_START"): Transition(
5
    ParserState.TOOL_PREAMBLE,
6
    (EventType.REASONING_END, EventType.TOOL_CALL_START),
7
),
8
(ParserState.CONTENT, "TOOL_START"): Transition(
9
    ParserState.TOOL_PREAMBLE,
10
    (EventType.REASONING_END, EventType.TOOL_CALL_START),
11
),
12
(ParserState.CONTENT, "FUNC_PREFIX"): Transition(
13
    ParserState.TOOL_NAME, (EventType.TOOL_CALL_START,)
14
),
15
(ParserState.TOOL_PREAMBLE, "FUNC_PREFIX"): Transition(
16
    ParserState.TOOL_NAME, ()
17
),
18
(ParserState.TOOL_NAME, "CLOSE_ANGLE"): Transition(
19
    ParserState.TOOL_ARGS, ()
20
),
21
(ParserState.TOOL_ARGS, "FUNC_END"): Transition(
22
    ParserState.TOOL_BETWEEN, (EventType.TOOL_CALL_END,)
23
),

第一条是正常结束思考。第二条是 Qwen3 最关键的设计：工具调用可以直接结束思考，不需要先输出 </think>。模型有时会在思考态里直接吐 <tool_call>，引擎把这次迁移当成”隐式思考结束”，同时发出 REASONING_END 与 TOOL_CALL_START。第三条覆盖”思考本来就未开启”的情况：CONTENT 状态下直接出现工具调用，也要发 REASONING_END，因为对 API 来说，从”可能还在思考”到”进入工具阶段”本身就是一次推理阶段切换。

第四条是”没有 <tool_call> 包裹的 <function=”降级路径：模型漏了外层信封，引擎仍把它当作工具调用开始。第六、七条是 Qwen3 的参数格式：<function=name> 后的 > 让状态从 TOOL_NAME 进入 TOOL_ARGS，</function> 结束调用。<parameter=...> 与 </parameter> 则留在 TOOL_ARGS 内部，作为参数值的边界。

迁移表里还有一组”畸形恢复”路径，来自真实回归问题（代码注释里标了 issue 58227）：

• TOOL_NAME 状态下遇到 </function>：函数名没有闭合 >，直接结束调用，进入 TOOL_BETWEEN；
• TOOL_NAME 状态下遇到 <tool_call>：上一个调用没闭合，又出现新的调用，先 TOOL_CALL_END 再 TOOL_CALL_START；
• TOOL_NAME 状态下遇到 <function=：函数名没闭合又来了新函数，同上；
• TOOL_BETWEEN 状态下遇到 <tool_call> 或 <function=：连续调用没有外层闭合，直接开始下一个。

这些路径不是”可选的容错”，而是模型真实生成行为的产物。max_tokens 截断、训练数据里的边界样本、采样温度过高，都会让模型输出不完整信封。引擎把这些恢复动作写进迁移表，而不是散落在手写代码的 if 里，带来了一个直接好处：每一种格式的每一个边界都能用同一张表来审查和测试。

参数不是整块 JSON，而是被转换器增量重建

Qwen3 的参数原文是 <parameter=key>value</parameter>，但协议要求 function.arguments 是 JSON 字符串。_qwen3_arg_converter() 负责把原文转成 JSON：

1
def _qwen3_arg_converter(raw_args, partial, closed=None):
2
    params, open_param = _qwen3_parse_params(raw_args, partial, closed)
3
    if open_param is not None and open_param.group(1):
4
        params[open_param.group(1)] = _trim_wrapping_newlines(open_param.group(2))
5
    return json.dumps(params, ensure_ascii=False)

partial=True 表示流式中的原文可能还没闭合。正则 _PARAM_RE 匹配已闭合参数，_PARTIAL_PARAM_RE 匹配最后一个正在打开的参数；转换器把两者都放进字典，再用 json.dumps 重新序列化。这样每来一段参数文本，都能得到一个”截至目前的完整 JSON”。

但流式协议要的不是”完整 JSON 重发”，而是参数增量。arg_value_extender 承担这件事：它接收一段原文增量，返回该增量在 JSON 字符串里的转义形式；当遇到 </parameter> 或下一个 <parameter= 时返回 None，表示这个值的增量流结束。_param_value_extender() 的实现里有两个值得注意的细节：

1
window = _param_value_end_window(value)
2
if _PARAM_VALUE_END_RE.search(text):
3
    return None
4
...
5
return json.dumps(text, ensure_ascii=False)[1:-1]

第一，window 保留末尾可能正在形成 </parameter> 或 <parameter= 的一小段文本；如果直接把这段流给客户端，后面补齐标记时就会产生重复字符。第二，返回值用 json.dumps(text)[1:-1] 去掉外层引号，得到的是 JSON 字符串内部的转义文本——这正是 arguments 片段应该长的样子（例如原文里的换行要变成 \n，双引号要变成 \"）。

_ClosedParams 是转换器的增量缓存。它记录”上一次解析到的最后一个闭合参数的位置、参数字典与参数外文本”，下一次转换时如果新原文以旧原文为前缀，就从 closed.end 继续扫描，而不是从头再跑一遍正则。流式参数往往每帧只多几个字符，如果每帧都全量解析，一个长参数会把 CPU 时间成倍放大。

三段流水线：token、词法、状态

引擎的流式路径是 StreamingParserEngine，注释里写得很清楚：

1
delta_text + delta_token_ids
2
    → TokenIDScanner  (special token pre-lexing)
3
    → IncrementalLexer (text → terminal tokens with prefix buffering)
4
    → State Machine    (terminal → semantic events)
5
    → list[SemanticEvent]

1
if self.buffer in prefix_set and not final:
2
    if best_match is not None:
3
        longer_match = any(
4
            len(lit) > best_match[2] and lit.startswith(self.buffer)
5
            ...
6
        )
7
        if not longer_match:
8
            emit best_match
9
        break
10
    else:
11
        break

1
if not self.buffer and self._has_only_literals and self._literal_first_chars:
2
    for ch in text:
3
        if ch in self._literal_first_chars:
4
            break
5
    else:
6
        return [LexToken(self.content_terminal, text, sum(char_token_counts))]

1
if ch in ("}", "]"):
2
    if self._args_brace_depth > 0:
3
        self._args_brace_depth -= 1
4
    if self._args_brace_depth == 0:
5
        return []
6
    self._args_safe_end = len(self._args_buffer)
7
    return self._flush_safe_args()

适配器：把引擎塞回旧接口

引擎的接口是 feed()/finish() 返回 SemanticEvent，但服务层用的是 ReasoningParser 与 ToolParser 的方法。vllm/parser/engine/adapters.py 用两个适配器把两者接起来：

1
class ParserEngineReasoningAdapter(ReasoningParser):
2
    engine_based_streaming: bool = True
3

4
    def extract_reasoning_streaming(...):
5
        with self._skip_tool_parsing():
6
            return self._parser_engine.extract_reasoning_streaming(...)
7

8
    def finish_streaming(self):
9
        with self._skip_tool_parsing():
10
            return self._parser_engine.finish_streaming()

_skip_tool_parsing() 是一个上下文管理器，临时把引擎的 skip_tool_parsing 置真，让推理适配器只关心思考段。engine_based_streaming=True 告诉上层 Parser：“这个 parser 的内部状态由引擎管理，不需要你替它维护 previous/current 文本。” has_engine_confirmed_reasoning_end() 返回引擎的 reasoning_ended，而不是重新扫描 token——因为引擎在处理标记时已经知道迁移是否发生，重复扫描反而会与 detokenizer 的延迟不一致。

工具适配器同理，只是它用 skip_reasoning_parsing 屏蔽推理标记。两个适配器的存在，让引擎可以逐步替换手写 parser：同一个 Parser 组合里可以一个用引擎、一个用 legacy，Parser 会按 engine_based 选择自己的状态推进方式。

parse_delta 的八个阶段

DelegatingParser.parse_delta() 是整条链路的核心。它的输入是一帧的 delta_text、delta_token_ids、请求对象、可选的 prompt_token_ids，以及 finished 标志。按执行顺序可以拆成八个阶段。

第一阶段：初始化流状态。 首次调用时，如果拿到了 prompt_token_ids，会做一次”prompt 是否已经在思考段”的检查：

1
if not state.prompt_reasoning_checked and prompt_token_ids is not None:
2
    state.prompt_reasoning_checked = True
3
    self.set_prompt_token_ids(prompt_token_ids)
4
    if self._reasoning_parser is None or self.is_reasoning_end(prompt_token_ids):
5
        state.reasoning_ended = True
6
    else:
7
        self._reasoning_parser.adjust_initial_state_from_prompt(prompt_token_ids)

如果 prompt 里已经包含 ...（例如 continue_final_message 把用户消息续写进思考段），reasoning_ended 初始为假，第一个生成 token 会进入思考通道；如果 prompt 已闭合思考，reasoning_ended 初始为真，第一个 token 就是内容或工具调用。没有拿到 prompt ids 时，默认从”未结束”开始，由流中的标记来切换。

第二阶段：推进当前文本。 state.advance() 按 engine/legacy 返回不同的 current/previous 视图。

第三阶段：推理通道。 如果 _in_reasoning_phase(state) 为真（有 reasoning parser 且 reasoning_ended 仍为假），调用 extract_reasoning_streaming()：

1
delta_message = self.extract_reasoning_streaming(
2
    previous_text=state.previous_text,
3
    current_text=current_text,
4
    delta_text=delta_text,
5
    previous_token_ids=state.previous_token_ids,
6
    current_token_ids=current_token_ids,
7
    delta_token_ids=delta_token_ids,
8
)

这段调用返回的 DeltaMessage 只可能带 reasoning、content 或两者都有，带工具调用是不合法的。

第四阶段：判断是否切换。 对 engine-based reasoning parser，切换条件由引擎确认：has_engine_confirmed_reasoning_end()。对 legacy parser，调用 _is_reasoning_end_streaming(current_token_ids, delta_token_ids)。这一步与第三阶段的顺序不能颠倒：必须先让 reasoning parser 处理完这一帧，再判断是否切换；如果先切换，这一帧里”思考尾巴 + 回答开头”的文本就会被整个送到工具阶段，思考尾巴会丢失。

切换发生时，DelegatingParser 做四件事：

1
state.reasoning_ended = True
2
reasoning_transitioned = True
3
current_token_ids = self._extract_content_ids(delta_token_ids)
4
flush_delta = (
5
    reasoning_parser.finish_streaming()
6
    if reasoning_parser is not None
7
    and reasoning_parser.engine_based_streaming
8
    else None
9
)
10
current_text = (
11
    (delta_message.content if delta_message else None) or ""
12
) + ((flush_delta.content if flush_delta else None) or "")

第一，翻状态位；第二，用 reasoning parser 的 extract_content_ids(delta_token_ids) 取”end 标记之后的 token id”，这个结果会作为工具阶段的 token 上下文；第三，对 engine-based parser 调用 finish_streaming()，把引擎在思考态里扣住的文本（例如 ... 结束标记后已经出现的 <）冲出来；第四，把这些内容拼成 current_text，作为下一阶段的输入。

这里有一个容易写错的点：current_text 只取 delta_message.content 与 flush_delta.content，不取 delta_message.reasoning。原因在于工具阶段只关心”内容与工具标记”，思考尾巴已经在上一阶段作为 reasoning 发出，不能再拼进工具输入，否则工具参数会混入思考文本。

第五阶段：准备工具阶段。 如果是 engine-based 组合且有工具 parser，切换帧的 content 被清空，交给工具阶段重新分类：

1
if self._engine_based:
2
    if self._tool_parser is not None:
3
        if delta_message:
4
            delta_message.content = None
5
    elif current_text:
6
        ...

如果只有 reasoning parser 没有工具 parser（例如纯推理模型），flush 出来的 content 没有下一段来消费，于是直接作为 content 发出去，避免文本丢失。对 legacy 组合，delta_text = current_text，让工具 parser 从”本帧已有的内容”开始重新扫描。

第六阶段：工具通道。 如果 _in_tool_call_phase(state) 为真（有 tool parser 且 reasoning_ended 为真），首次进入时把 tool_call_text_started 置真并清空 previous：

1
if not state.tool_call_text_started:
2
    state.tool_call_text_started = True
3
    state.previous_text = ""
4
    state.previous_token_ids = []
5
    delta_text = current_text
6
    delta_token_ids = current_token_ids

这个清空非常关键。工具 parser 的 previous_text 如果还包含完整的思考内容，它的正则会在思考文本里找到”看起来像工具调用”的片段，产生误报；清空后，工具 parser 只看到切换到工具阶段之后的文本。

随后调用 _extract_tool_calls_streaming()，把返回的 DeltaMessage 里的 function_name_returned 存回状态，并把本帧的 reasoning 尾巴合并回去：

1
reasoning_from_this_batch = delta_message.reasoning if delta_message else None
2
...
3
if reasoning_from_this_batch:
4
    if delta_message is None:
5
        delta_message = DeltaMessage(reasoning=reasoning_from_this_batch)
6
    elif not delta_message.reasoning:
7
        delta_message.reasoning = reasoning_from_this_batch

为什么需要合并？因为在切换帧里，reasoning parser 返回的 DeltaMessage 同时带 reasoning 和 content；content 被交给工具阶段，工具阶段可能返回一个新的 DeltaMessage（只带工具字段）。如果把整个 delta_message 覆盖掉，reasoning 尾巴就丢了。合并逻辑保证一帧里”思考尾巴 + 工具开始”能同时到达客户端。

工具调用计数也在这里更新。history_tool_call_cnt 初始值由 _initialize_history_tool_call_cnt() 从请求消息历史里统计（仅 kimi_k2 需要），工具 ID 生成依赖这个计数；每帧新增的调用则按 tc.id is not None 计数，兼容一个 delta 同时完成多个调用的 required 路径。

第七阶段：无阶段直通。 如果三个条件都满足——没有产生 delta_message、本帧没有发生推理切换、当前既不在推理阶段也不在工具阶段——则把整段 delta 作为 content 发出。这个分支处理的是”没有配 reasoning parser、也没有进入工具阶段”的普通文本流。

第八阶段：流末收尾与抑制。 如果 finished 为真，先 finalize_generation()：

1
fallback_fn = getattr(self._reasoning_parser, "get_streaming_fallback_content", None)
2
if fallback_fn is not None and not state.reasoning_ended:
3
    promoted = fallback_fn(state.previous_text, request)
4
    if promoted:
5
        delta_message.content = (delta_message.content or "") + promoted
6
self._append_unstreamed_tool_args(delta_message)

get_streaming_fallback_content() 是部分 reasoning parser 的可选能力：当流在思考中途结束时，parser 可以决定把某一段思考”提升”为 content。默认不实现，所以大多数模型在 max_tokens 截断时 content 为空。_append_unstreamed_tool_args() 则用 get_remaining_unstreamed_args() 把工具参数补齐。

最后是 include_reasoning 抑制：

1
if delta_message and not request.include_reasoning:
2
    delta_message.reasoning = None
3
    if not delta_message.content and not delta_message.tool_calls:
4
        delta_message = None

注意这里的顺序：先清 reasoning，再判断”如果只剩 reasoning，就整帧不发”。如果先判断再清，就会把一整帧空消息发给客户端。ChatStreamProcessor 在此基础上还会隐藏 logprobs 与 token_ids，两层共同保证思考内容不会从任何字段泄漏。

非流式 parse：先推理，再工具

非流式路径简单得多：

1
def parse(self, model_output, request, enable_auto_tools=False, model_output_token_ids=()):
2
    self._initialize_history_tool_call_cnt(request)
3
    reasoning, content = self.extract_reasoning(model_output, request)
4
    tool_calls, content = self._extract_tool_calls(
5
        content=content, request=request, enable_auto_tools=enable_auto_tools
6
    )
7
    return reasoning, content, tool_calls

顺序是先切思考、再解析工具，因为工具解析只在 content 上进行。没有 reasoning parser 时，extract_reasoning() 返回 (None, model_output)，工具 parser 拿到整段输出，这对应”纯工具模型”（如 Hermes）的情况。工具解析后，content 可能被置 None（整段都是工具调用），也可能保留工具调用之外的文本。

model_output_token_ids 参数在这一层没有被使用，但会被子类或上层用来做 token 级统计。ChatStreamProcessor 在非流式路径里另用 parser.count_reasoning_tokens(token_ids) 计算 usage。

阶段表

把上面的流程压缩成一张表，能更直观地看出每个字段在哪个阶段产生：

性能账：解析器在关键路径上的成本

解析器运行在 API 进程的 CPU 线程里，与 GPU 前向是异步的。它的成本主要来自四块：逐字符词法扫描、JSON 参数转换、状态机迁移和文本拼接。engine-based 路径用三个手段把成本压住：

• IncrementalLexer 的”无终结点首字符”快路径，让普通文本整段通过；
• TokenIDScanner 按 token id 直接命中特殊标记，避免正则扫描；
• 参数转换用 _ClosedParams 缓存已闭合参数，避免每帧从头解析。

legacy 路径的典型成本是每帧对 previous_text 做正则匹配；当思考文本很长时，正则的匹配范围会随帧数线性增长。engine-based parser 的状态机只处理当前 delta，不随历史增长。这也是 vLLM 逐步把新模型 parser 迁到引擎格式的直接原因：在线服务里，解析器的复杂度必须与”本帧”成正比，而不是与”整条输出”成正比。

但引擎路径也不是零成本。每个 delta 都要经过 scanner、lexer、状态机三层；如果 delta 很小（例如投机解码下每帧只有 1 个 token），三层调用本身的开销就会显现。StreamingParserEngine.feed() 为此写了快路径：如果 delta 没有任何特殊 token 的 id、lexer buffer 为空、且文本里没有终结点首字符，直接按当前状态发出内容事件，跳过 scanner 与 lexer。这个快路径在 decode 阶段命中率很高。