执行摘要

• 一句话：修复 Cohere v2 停止序列终止原因映射
• 推荐动作：建议快速阅读本 PR。它提供了一个非常干净且典型的『外部协议枚举映射』修复案例，值得借鉴的是如何利用 vLLM 现有字段的语义（如 stop_reason 的类型信息）来消除歧义，并通过类型启发式而非引入新字段来最小化改动。同时该 PR 的测试设计（单测 + 非流式集成 + 流式集成）可以作为前端修复的参考规范。

功能与动机

PR body 明确指出：vLLM 将 EOS、stop-token 和 stop-string 终止都归类为 finish_reason="stop"，匹配到的 stop 字符串单独存放在 stop_reason 中，但 Cohere v2 转换只检查 finish_reason，导致 STOP_SEQUENCE 映射在响应和流式两条路径上均不可达。该问题直接影响 Cohere v2 客户端无法区分配置的 stop sequence 与普通完成。

实现拆解

1. 扩展 _map_finish_reason：在 vllm/entrypoints/cohere/serving.py 中，将 _map_finish_reason 增加可选参数 stop_reason: int | str | None = None。当 reason == "stop" 且 stop_reason 为字符串时返回 STOP_SEQUENCE，否则回退到原有静态映射表。这一修改利用了 stop_reason 的类型语义：字符串代表匹配的 stop 序列，整数代表 stop token ID。
2. 接入非流式响应路径：在 _chat_completion_to_v2 中，将 choice.stop_reason 一并传给 _map_finish_reason（choice.finish_reason 和 choice.stop_reason），保证 CohereChatV2Response.finish_reason 正确。
3. 接入流式状态机：在 _StreamState.__init__ 中新增 self.stop_reason: int | str | None = None；在 _chat_completion_stream_to_v2 消费 chunk 时，当 choice.finish_reason 非空时同步更新 state.stop_reason = choice.stop_reason；随后在 _build_message_end_event 中新增 stop_reason 参数并传入 _map_finish_reason，最终 SSE message-end 事件的 delta.finish_reason 能正确反映 stop sequence。
4. 回归测试：在 tests/entrypoints/cohere/test_serving_conversion.py 新增 test_only_string_stop_reasons_are_stop_sequences（参数化验证字符串 stop_reason 映射为 STOP_SEQUENCE，整数与 None 保持 COMPLETE）和 test_stop_sequence_finish_reason（非流式端到端）；在 tests/entrypoints/cohere/test_serving_streaming.py 新增同名流式测试，覆盖 SSE message-end 事件。测试辅助函数 _build_chat_completion_response 与 _make_chunk 均补充了 stop_reason 参数以支持构造对应输入。

关键文件：

• vllm/entrypoints/cohere/serving.py（模块 前端服务；类别 source；类型 core-logic；符号 _map_finish_reason, _chat_completion_to_v2, _chat_completion_stream_to_v2, _build_message_end_event）: 核心修复文件：修改了 _map_finish_reason 以利用 stop_reason 类型区分 stop sequence，并在非流式与流式两条路径中透传该字段，是本次变更的主逻辑。
• tests/entrypoints/cohere/test_serving_conversion.py（模块 转换测试；类别 test；类型 test-coverage；符号 test_only_string_stop_reasons_are_stop_sequences, test_stop_sequence_finish_reason）: 非流式转换测试：新增 test_only_string_stop_reasons_are_stop_sequences 验证类型启发式，并新增 test_stop_sequence_finish_reason 覆盖端到端响应构造。
• tests/entrypoints/cohere/test_serving_streaming.py（模块 流式测试；类别 test；类型 test-coverage；符号 test_stop_sequence_finish_reason）: 流式测试：新增 test_stop_sequence_finish_reason，验证 SSE message-end 事件中的 finish_reason 正确报告为 STOP_SEQUENCE。

关键符号：_map_finish_reason, _chat_completion_to_v2, _chat_completion_stream_to_v2, _build_message_end_event, _StreamState

关键源码片段

vllm/entrypoints/cohere/serving.py

核心修复文件：修改了 _map_finish_reason 以利用 stop_reason 类型区分 stop sequence，并在非流式与流式两条路径中透传该字段，是本次变更的主逻辑。

# vllm/entrypoints/cohere/serving.py
​
# vLLM 将 EOS、stop token 和 stop string 终止都报告为 finish_reason="stop"。
# 其中匹配到的 stop string 会以字符串形式放在 stop_reason 字段，而 stop
# token 则以整数 ID 表示，因此可以用 isinstance 区分这两种情况。
def _map_finish_reason(
    reason: str | None, stop_reason: int | str | None = None
) -> CohereFinishReason:
    # 只有 reason=="stop" 且 stop_reason 为字符串时才视为命中 stop sequence。
    if reason == "stop" and isinstance(stop_reason, str):
        return "STOP_SEQUENCE"
    # 其余情况回退到静态映射表，未知值默认 COMPLETE。
    return _FINISH_REASON_MAP.get(reason, "COMPLETE")

评论区精华

本 PR 的 GitHub review 中未出现针对实现的技术讨论或争议。两位维护者 andrewbcohere 和 DarkLight1337 均直接批准（APPROVED）。唯一的流程性沟通是 PR 作者 taking-lying-flat 请求维护者在合并 main 后重新触发 CI，DarkLight1337 执行了 /ci run。PR body 中还特别说明该修复与 PR #45807（Anthropic Messages API 的同类转换）不重复，因为后者针对的是 Anthropic 端点而非 Cohere v2。

• 暂无高价值评论线程

风险与影响

• 风险：整体风险较低，但存在以下具体风险点：
  • 对 stop_reason 类型语义的依赖：_map_finish_reason 使用 isinstance(stop_reason, str) 区分 stop sequence 与 stop token。如果未来 vLLM 在其他场景（如新增的 stop 类型）把字符串填充到 stop_reason 而含义不同，可能产生误判。当前语义与 vLLM 的 finish_reason/stop_reason 约定一致，属于合理假设。
  • 流式状态机字段同步：_StreamState 新增 stop_reason 字段后，需要保证所有更新 finish_reason 的路径都同步更新 stop_reason。当前改动仅在 choice.finish_reason is not None 分支中同步，异常分支仍走 ERROR，逻辑一致。
  • 向后兼容性：_map_finish_reason 的新参数带默认值，旧调用点不受影响；_build_message_end_event 新增参数同样带默认值，无破坏性变更。
  • 测试覆盖：新增测试覆盖了正常路径（字符串 stop_reason），但对整数 stop token、None 的覆盖仅存在于 test_only_string_stop_reasons_are_stop_sequences，流式端到端测试未覆盖整数 stop token 场景，但风险可控。
  • 影响：影响范围集中在 Cohere v2 API 端点（vllm/entrypoints/cohere/serving.py）的行为：所有通过该端点发起的非流式与流式请求，在命中配置的 stop sequence 时，响应中的 finish_reason 由原来的 COMPLETE 变为 STOP_SEQUENCE。这对依赖 Cohere 协议语义的客户端（如需要判断停止原因的应用）是重要的可观测性改进；不影响模型执行、token 生成或性能。对团队而言，修改集中且小，维护成本低。
  • 风险标记：依赖 stop_reason 类型语义, 流式状态机新增字段需保持同步

关联脉络

• 暂无明显关联 PR