先说结论：这个问题的根子不在 vLLM，也不在 MiniMax M2 的采样逻辑，而在一层看起来人畜无害的自定义 parser 上。为了查清楚它，我前后折腾了两天，走了不少弯路。我尽量把完整的排查链路写出来，给正在用 vLLM 部署 MiniMax M2 这类模型、并且对流式输出做后处理的同学一个参考。
事情是这样的：我们组把 MiniMax M2 接进 vLLM，用 OpenAI 兼容接口对外提供对话服务。联调阶段，前端同事反馈了一个非常诡异的现象——流式对话里，助手回答经常在最后一句完整的话之后就再没有任何增量输出，前端一直显示"正在输入"，个别请求甚至直接超时。最初我怀疑是服务端的 stop token 配置有问题，或者模型在长对话里压根没有生成结束标签。但翻 vLLM 的日志和 HTTP 响应，finish_reason明明是stop，采样结果也正常。真正定位后才发现，是整个链路里一层"清洗模型输出特殊标签"的 parser，把流式输出中唯一一次出现的结束标签给删掉了。这类问题不算罕见，但定位过程非常绕，值得完整复盘一遍。
1. 现象速写：一段永远等不到"句号"的流
1.1 线上现象与初步判断
我先说清楚最直观的表现。用 OpenAI SDK 写个小脚本直连 vLLM 的/v1/chat/completions接口，stream=True拉流，一切正常。最后一个 chunk 会带finish_reason: "stop"，而且在这之前模型已经把结束标签（以 MiniMax 系列常见的<|im_end|>为例，具体名称看模型配置文件里的 special tokens）作为普通delta.content输出了。
但业务侧不是这么消费的。我们实际的前端链路是：vLLM → 自研代理层 → 前端页面。代理层做三件事：聚合增量内容、做格式清洗、透传状态给前端。清洗这一步，就是那个 parser 在干活。前端收到最终 content 后，发现末尾没有结束标签，按产品规范就必须继续等待"对话结束"的语义信号，于是气泡一直停留在"输入中"状态。
更麻烦的是，部分请求还出现了finish_reason: "length"的情况。原因是模型在缺少结束信号的情况下会继续生成内容，一直撞到max_tokens上限。这给了第二个误导信号：我一度以为是max_tokens设置太小，或者采样温度太高导致模型不会收尾。
1.2 复现窗口：为什么本地不触发、线上必现
排查初期最让人恼火的，是这个问题没法稳定复现。本地联调用的是 vLLM 直连，脚本里根本没过代理层，自然一切正常。回归脚本又是关掉流式的，一次性拿到完整 content，清洗逻辑虽然也会删除标签，但因为整个对话语义已经闭环，没有人检查"末尾必须有结束标签"，所以也不报错。
只有完全复刻生产链路——vLLM → 代理层 → parser → 前端——才能必现。这导致我第一天基本浪费在怀疑网络抖动、怀疑 vLLM 版本 bug、怀疑负载均衡策略上面。后来我把代理层日志调成 debug 级别，逐条对比 parser 的输入输出，才把问题框定到清洗逻辑。
这算是一条经验：流式输出类问题，如果本地不复现，优先检查"链路中间件"，而不是反复试框架参数。中间任何一层对文本做了聚合、清洗、截断，都可能改变流式输出的语义完整性。
2. 结束标签在 vLLM 输出链路上的两个"关卡"
2.1 采样阶段的 structured output parser
排查之前，得先把结束标签在 vLLM 里会经过哪些环节搞清楚。第一个容易出问题的点，是response_format带来的结构化输出逻辑。如果你在请求里带了 JSON Schema 或者 grammar，vLLM 会在解码采样阶段做约束，每次只挑选符合 grammar 规则的 token。这意味着如果结束标签不在允许集合里，采样器会直接拒绝生成它，流会以finish_reason: "length"结束，而不是正常结束。
MiniMax M2 这类模型走的是对话模板，正常情况下结束标签是模型自己采样出来的，不受 grammar 约束。但如果你在测试阶段不小心给请求加了response_format={"type": "json_object"}，又没在 schema 里允许特殊 token，那就会出现"内容完整、但模型就是不愿意停"的现象。这个坑很多人踩过，我刚开始也怀疑过这个方向。验证方式很简单：关掉response_format，或者临时改用不带 structured output 的模型配置跑同一段对话，看结束标签是否恢复。
2.2 文本阶段的业务 parser 与"延迟确认"陷阱
第二个环节是 detokenizer 输出增量文本之后，你业务代码里的 parser。vLLM 的流式输出会把 token ids 逐步转成文本，以delta.content形式交给上层。对于特殊 token，比如<|im_end|>、<|endoftext|>，vLLM 默认是有保护逻辑的，不会把一个多字节 token 拆碎成两个 chunk 推给你。我的实测里，结束标签要么完整出现在某个 chunk 的 content 里，要么以delta.content == ""+finish_reason的方式收尾。
问题恰恰出在业务 parser 处理这个delta.content的时候。很多团队会在代理层做"清除模型输出中的 ChatML 标签"这类操作，比如把<s>、</s>删掉，避免展示层出现杂字符。这种清洗正则如果写得太宽，很容易把结束标签也匹配进去。因为结束标签本身就是尖括号包裹的形式，正则是不会区分"这是语料里的临时标记"还是"这是模型输出的终止信号"的。
还有一个值得说的细节：detokenizer 对分片文本有"延迟确认"机制。当一个多字节字符（比如中文字符）被拆分到两个 token 时，vLLM 会等下一个 chunk 来了再确认字符完整性，避免输出乱码。特殊 token 同理。如果代理层的 parser 在判断"chunk 末尾是不是一个孤立标签"时没考虑这个机制，看到一行以<|开头、还没收尾的字符串，就提前把它当垃圾丢弃，结束标签也会丢。这不是 vLLM 的问题，而是消费方对流式边界理解不够。
3. 排查实景：三条线索如何汇到 parser 身上
3.1 线索一：模型真的生成了结束标签吗
排查从最底层开始。我先绕过代理层和 parser，直接用 vLLM 暴露的原始 OpenAI 兼容接口跑同样的对话，关闭流式模式，完整打印message.content。结果明确：MiniMax M2 在正常对话里一定会输出结束标签，位置就在内容末尾。换句话说，模型侧没有异常。
这一步非常关键。很多人在流式输出问题上一上来就怀疑"模型是不是没学会结束"，但模型是黑盒，应该先用非流式接口确认"模型在离线、完整输出场景下是否包含你要找的信号"。如果非流式输出有结束标签，那问题一定出在"传输或消费"环节。
3.2 线索二：vLLM 默认 detokenizer 有没有吞标签
第二步，我把流式打开，仍然直连 vLLM，不过代理层。写了个十行左右的 Python 脚本，把每个 chunk 的delta.content和finish_reason原样打印出来。日志显示，倒数第二个或倒数第三个 chunk 里出现了完整的结束标签字符串，然后finish_reason才变成stop。
到这里基本可以排除 vLLM 内部的采样和 detokenize 环节。我还在SamplingParams里检查过stop_token_ids、stop这些参数，确认业务层没有额外传 stop 配置。结论是：vLLM 默认链路没有吞掉结束标签，问题不在框架，而在框架之上那层自定义逻辑。
3.3 线索三：业务 parser 的正则清掉了什么
第三步，把代理层 debug 日志打开。代理层把 vLLM 返回的所有 chunk 聚合成一个完整字符串，再交给 parser 做格式清洗。我对比了 parser 入参和出参，发现一个非常刺眼的差异：入参末尾有<|im_end|>，出参没有。
当时 parser 干的事情，是把模型输出里的 ChatML 语法标签剥掉，方便做页面展示。核心逻辑是这么写的：
import re def clean_model_output(text: str) -> str: # 移除 ChatML 语法标签，例如 <s>、</s>、<|im_start|>、<|im_end|> text = re.sub(r"<\|[^|]*\|>|</?s>", "", text) # 再压缩多余的空白行 text = re.sub(r"\n{3,}", "\n\n", text).strip() return text看到这个正则的第一眼我就明白了。<\|[^|]*\|>用来匹配|包围的保留标签，<|im_end|>完全命中，于是被当成普通标记删掉。而finish_reason在代理层透传时又没有作为"结束语义"透给前端，前端就只能靠 content 里是否有结束标签来判断对话是否真的说完了。两条信息断掉一条，前端就会死等。
4. 修复落地：给 parser 加一层"标签保护"
4.1 修复设计：白名单保留特殊标签
修复不复杂，但设计上要克制。最省事的做法是把结束标签从清洗正则里排除掉，比如改成：
TAG_PATTERN = r"<\|im_start\||<\|im_end\||</?s>"但这样写太脆。MiniMax 的 tokenizer 里有不少保留标签，如果换模型、换版本，特殊 token 集合可能变化，正则漏掉任何一个，又会出现类似事故。更稳妥的做法是维护一个"不可动标签白名单"，在清洗前先把白名单里的标签替换成占位符，清洗完成后再还原回来：
import re # 从 tokenizer 配置里读出来的保留标签，这里用 MiniMax 常见集合举例 PROTECTED_TAGS = { "<|im_end|>", "<|endoftext|>", "<|user|>", "<|assistant|>", "<|system|>", "<s>", "</s>", } def clean_model_output_with_protection(text: str) -> str: # 第一步：保护 placeholder_map = {} for i, tag in enumerate(PROTECTED_TAGS): placeholder = f"__PROTECTED_TAG_{i}__" placeholder_map[placeholder] = tag text = text.replace(tag, placeholder) # 第二步：原有清洗逻辑，只处理非保护内容 text = re.sub(r"<\|[^|]*\|>", "", text) # 删除其他保留标签 text = re.sub(r"\n{3,}", "\n\n", text).strip() # 第三步：还原 for placeholder, tag in placeholder_map.items(): text = text.replace(placeholder, tag) return text这样做的核心好处是：parser 永远保留模型语义层面的终止信号，清洗只处理展示层不需要的杂字符。占位符替换顺序也很重要，必须用迭代式的replace，避免占位符本身被后面的正则误伤。
另外补充一点：如果业务上"完全不希望结束标签进 content"，比如要求前端的最终文本干净、不含任何 ChatML 标记，那正确的做法不是在 parser 里删掉标签，而是在代理层把"是否检测到结束标签"这个布尔值单独提出来，连同finish_reason一起放到给前端的 meta 字段里。前端根据 meta 判断对话结束，content 保持干净。把"信号"和"展示文本"混在同一个字符串里处理，是这次事故的深层设计问题。
4.2 回归验证与压测数据
修复之后，我做了三个维度的验证。
第一，单轮回归。拿之前必现的对话样本，跑 100 次流式请求，结束标签保留率从 0% 恢复到 100%。前端不再出现死等，所有stop的请求都在收到标签后正常关闭气泡。
第二，并发回归。模拟 30 路并发、每路连续 50 轮对话，观察代理层日志。除了结束标签全部保留之外，我还确认了占位符替换不会影响正常文本内容——比如用户输入里恰好包含__PROTECTED_TAG_0__这样的字符串，清洗后依然原样输出，不会被错误还原成标签。
第三，结构化输出回归。确认带了response_format的请求不受影响，因为白名单只是保护标签不被删除，不影响采样阶段约束。
完整改动只有 parser 一个文件，三十行不到。代理层逻辑、vLLM 配置、前端判断全部没动，这也从侧面说明问题定位准确。
5. 同类事故的通用排查清单与经验复盘
5.1 可以照抄的症状-排查方向对照表
我把这类"流式输出内容不完整/标签丢失"的问题整理成一张对照表，每次排查直接按表格走：
| 症状 | 优先排查方向 | 验证手段 |
|---|---|---|
| 流式输出完整，但末尾无结束标签 | 自定义 parser / 文本清洗逻辑 | 对比 parser 入参与出参 |
| 流式输出提前截断，finish_reason 为 length | structured output grammar 约束 | 关闭 response_format 重放 |
| 流式输出乱码或字符被拆散 | detokenizer 分片保护逻辑 | 打印原始 chunk，观察多字节字符 |
| finish_reason 与内容不同步 | 代理层透传逻辑 | 检查 chunk 顺序和 meta 透传 |
| 非流式正常、流式必现 | 链路中间件 | 逐层剥离，从 vLLM 原始接口重放 |
这张表的逻辑是：先确认"模型侧有没有产出目标信号"，再看"框架传输是否完整"，最后盯"业务消费是否有损"。绝大多数问题出在第三步，但大家总爱在第一步反复纠结。
5.2 顺带踩过的另外两个流式输出坑
这次复盘还让我想起两个相邻的坑，顺便一起说了。
第一个是 chunk 边界上的多字节字符截断问题。业务 parser 如果按"每批 chunk 到达就立刻处理"的方式聚合文本，很容易在中文字符被拆成两个 token 时输出乱码。解决方案是在 parser 里维护一个累积 buffer，只有确认一个完整字符（或者一个完整特殊 token）后才交给下游。vLLM 内部有延迟确认机制，但业务层很多代码并不知道这一点，会把中间态的乱码直接透出去。
第二个是finish_reason和最后一个增量 chunk 的到达顺序。实际观测中，某些版本、某些扩展配置下，finish_reason: "stop"可能会比最后一段 content 更早暴露给代理层。如果代理层以finish_reason为准直接截断并关闭流，那么最后一段含结束标签的增量可能根本不会被推送到前端。处理办法是：代理层在收到finish_reason后不要立即截断，留一个短暂等待窗口，把 buffer 里剩余的增量消费完再关闭连接。
5.3 三条值得长期遵守的排查纪律
最后说三条纪律，是我这次踩坑换来的，比任何临时补丁都值钱。
纪律一：流式输出缺东西，从最原始接口开始重放。不要带着中间层日志猜，先证明"最底层是好的"，再逐层往上加。非流式接口是最便宜的验证工具，先用它确认模型输出内容完整。
纪律二：所有对模型输出做后处理的代码，必须维护一个"不可动标签清单"。这个清单直接来自 tokenizer 的special_tokens配置，每次换模型、升级 vLLM 后都要 diff 一遍。任何"删除所有尖括号内容"类型的正则，都应该过一遍这个清单，确认不会误杀语义信号。
纪律三：把"结束标签必须保留"写成自动化回归用例。不要靠人肉看日志确认。因为这类 bug 在压测并发下才会暴露，人工很难每次都盯住最后一个 chunk。我当时就是在回归脚本里加了一条断言：流式聚合后的 content 末尾必须匹配预期结束标签，不匹配直接标红。这条断言后来在换 vLLM 版本时又帮我们抓了一次类似问题。
说实话，大模型流式输出链路里，"框架 bug"这个锅很少真的有框架来背，多数时候是我们自己的后处理逻辑在和特殊 token 的语义打架。结束标签不是可有可无的格式符号，它是模型输出里一个明确的终止信号。任何一层消费逻辑在动它之前，都该先想清楚：这个标签是给机器看的，还是给用户看的，还是两者都要。想清楚了，很多问题一开始就不会发生。
