【Bug已解决】[Bug]:[Anthropic API] ValidationError in message_stream_converter masks underlying 500 error when serving GLM-5.2 解决方案

一、现象长什么样

用 vLLM 的 Anthropic API 兼容层（把 GLM-5.2 当 Claude 来服务）时，如果后端模型推理失败返回了 HTTP 500，客户端看到的却是：

422 ValidationError: field 'delta' is required in message_stream

或：

500 ... but body is "ValidationError: value is not a valid..." (本该是模型的 500 错误体)

几个典型表征：

1. 真正错误是上游 500（模型推理崩），但客户端收到 ValidationError：Anthropic 兼容层在把"流式消息"转成 Anthropic 格式时，先按"成功流"去解析/校验响应结构；但 500 的响应体根本不是合法的流式消息格式，于是校验层抛出 ValidationError，把原始 500 错误盖掉了。
2. 只在后端真的出错（500）时出现，正常推理不出现：说明问题在"错误路径"——正常响应能正确转换，但错误响应被转换层当成了"格式不对"而校验失败。
3. 用户排障被误导：看到 ValidationError 会去查"我的请求字段格式"，而真实原因是"模型推理 500"，方向完全错。

这不是 GLM-5.2 推理问题，而是Anthropic 兼容层的 message_stream_converter 没有先判断上游 HTTP 状态码，就直接按成功流去校验转换，导致上游 500 被校验错误掩盖。下面给出定位与修复（先判状态、再转换、错误透传）。

二、背景

Anthropic API 兼容层的工作流：

客户端 → vLLM Anthropic 端点 → 转发到 OpenAI/内部推理 → 拿到响应流
  → message_stream_converter 把内部流转换成 Anthropic 的 SSE 格式
  → 返回客户端

问题在于转换层的假设："响应流一定是成功的流式消息"。但后端可能在已经开始流式返回后才出错（或一开始就 500），响应体是错误 JSON（如 {"error": {"message": "...", "code": 500}}），根本不是 Anthropic 的 message_delta 事件格式。

转换层在 parse(event) 时按成功格式 pydantic 校验，遇到错误体就 ValidationError，然后这个 ValidationError 被当成响应内容发出去（甚至把状态码也从 500 改成 422），原始 500 信息丢失。

根因是转换层"先转换后判错"，且没有把上游错误状态码透传。修复就是"先判 HTTP 状态/错误体，再转换；错误就原样透传（含状态码）"。

下面用可运行代码复现并修复。

三、根因

拆成两条根因：

1. 转换层先校验成功格式，错误体触发 ValidationError message_stream_converter 拿到事件就 Model.validate(event)，错误体（500 的 JSON）不符合成功 schema → ValidationError，且不识别"这是上游错误"。根因是没有先区分"成功流"与"错误体"。

2. 上游错误状态码被覆盖/丢失 ValidationError 被当成响应内容，状态码可能从 500 变成 422，原始错误信息丢失。根因是错误没有按原状态码透传。

修复方向：转换前先"探测错误体"（有 error 字段 / 非预期结构）→ 直接透传原始错误与状态码；只有确认是成功流才做格式转换。

四、最小可运行复现

下面复现"错误体被当成功流校验 → ValidationError 掩盖 500"：

from typing import Optional
from dataclasses import dataclass

@dataclass
class StreamEvent:
    type: str
    delta: Optional[str] = None

def naive_convert(raw_event: dict):
    """现状：直接按成功流校验转换，不识别错误体。"""
    # 假设成功事件必有 type/delta
    if "delta" not in raw_event:
        raise ValueError("ValidationError: field 'delta' is required")
    return StreamEvent(**raw_event)

# 上游 500 的错误体（不是流式消息格式）
upstream_500 = {"error": {"message": "model crashed: OOM", "code": 500}}
try:
    naive_convert(upstream_500)
except ValueError as e:
    print("复现（错误被掩盖）:", e)   # ValidationError 而非 500 信息

复现（错误被掩盖）: ... ValidationError 即复现：真实的 500 信息（model crashed: OOM）被 ValidationError 盖掉。下面改成先判错误体。

五、解决方案（第一层：最小直接修复）

最小修复：转换前先"探测错误体"，是错误就原样透传（含状态码），只有成功流才校验转换。

from dataclasses import dataclass
from typing import Tuple, Optional

@dataclass
class ConvertResult:
    is_error: bool
    status: int
    payload: dict
    event: Optional[StreamEvent] = None

def detect_error(raw: dict, upstream_status: int) -> Optional[dict]:
    """若上游是非 2xx 或体含 error 字段，识别为错误体。"""
    if upstream_status >= 400:
        return {"message": raw.get("error", {}).get("message", "unknown"),
                "code": upstream_status}
    if "error" in raw:
        code = raw["error"].get("code", upstream_status)
        return {"message": raw["error"].get("message", "unknown"), "code": code}
    return None

def safe_convert(raw_event: dict, upstream_status: int) -> ConvertResult:
    err = detect_error(raw_event, upstream_status)
    if err is not None:
        # 错误体：原样透传（保留真实状态码与信息），不转成功流
        return ConvertResult(is_error=True, status=err["code"], payload=err)
    # 成功流：才做格式校验与转换
    if "delta" not in raw_event:
        raise ValueError("成功流缺少 delta 字段")
    return ConvertResult(is_error=False, status=200,
                         payload=raw_event,
                         event=StreamEvent(**raw_event))

# 复现修复：500 错误体被识别并透传，不再变成 ValidationError
r = safe_convert(upstream_500, upstream_status=500)
print("透传错误:", r.status, r.payload)   # 500 {'message': 'model crashed: OOM', ...}

这一层改动让上游 500 在转换层被识别为错误并原样透传（保留 500 状态码与真实信息），客户端看到的不再是掩盖性的 ValidationError。

六、解决方案（第二层：结构化改进）

把"Anthropic 流转换"做成结构化组件：集中管理"错误体识别 → 透传"与"成功流转换"，并支持 SSE 包装（错误也按 Anthropic 的错误事件格式返回，但状态码正确）。

from enum import Enum
from typing import Dict, Callable

class StreamPhase(Enum):
    SUCCESS = "success"
    ERROR = "error"

class MessageStreamConverter:
    def __init__(self):
        self._handlers: Dict[StreamPhase, Callable] = {}

    def register(self, phase: StreamPhase, fn: Callable):
        self._handlers[phase] = fn

    def convert(self, raw: dict, upstream_status: int):
        err = detect_error(raw, upstream_status)
        if err is not None:
            # 错误：用 Anthropic 错误事件格式包装，但保留真实 status
            err_event = {"type": "error", "error": err}
            return ConvertResult(is_error=True, status=err["code"], payload=err_event)
        # 成功：转成 Anthropic message_delta 事件
        return ConvertResult(is_error=False, status=200,
                             payload={"type": "content_block_delta",
                                      "delta": {"type": "text_delta",
                                                "text": raw.get("delta", "")}})

# 用法
conv = MessageStreamConverter()
r = conv.convert(upstream_500, 500)
print("客户端应收到状态码", r.status, "体:", r.payload)

MessageStreamConverter 把"错误识别/透传"与"成功转换"分离，错误仍按 Anthropic 风格包装（客户端好解析），但状态码与真实信息不被掩盖。

七、解决方案（第三层：断言 / CI 守护）

错误掩盖最怕"线上 500 被当成 422"。用断言守两条不变量：

def check_converter_invariants(raw, upstream_status):
    r = MessageStreamConverter().convert(raw, upstream_status)
    err = detect_error(raw, upstream_status)
    if err is not None:
        # 不变量 1：错误必须透传真实状态码，不被改成 422
        assert r.status == err["code"], f"状态码被改: {r.status} != {err['code']}"
        # 不变量 2：透传体必须含真实错误信息（不得是 ValidationError 文案）
        assert "model crashed" in str(r.payload) or r.is_error
    return True

def test_anthropic_error_passthrough():
    # 上游 500：必须透传 500，不得变 ValidationError
    check_converter_invariants(upstream_500, 500)
    # 上游 200 成功流：正常转换
    check_converter_invariants({"delta": "hi"}, 200)
    print("OK: Anthropic 流转换错误透传不变量通过")

if __name__ == "__main__":
    test_anthropic_error_passthrough()

把 test_anthropic_error_passthrough 接进 CI，任何"又把 500 改成 422/ValidationError"的改动都会立即红。

八、排查清单

Anthropic 兼容层把 500 掩盖成 ValidationError，按序查：

1. 先看原始上游状态码：客户端收到 ValidationError 时，去查 vLLM 后端的真实响应——若后端是 500，根因就是转换层掩盖。
2. 转换前先判错误体：detect_error 检查上游 status ≥ 400 或体含 error 字段，是错误就原样透传，不进成功流校验。
3. 保留真实状态码：错误透传时状态码必须是上游真实码（500），绝不能变成 422/ValidationError 的码。
4. 错误也按 Anthropic 风格包装：返回 {"type":"error","error":{...}} 让客户端能解析，但 HTTP 状态码与 message 是真实的。
5. 成功流才校验格式：只有确认是成功响应才按 Anthropic schema 校验 delta 等字段，避免错误体触发 ValidationError。
6. 日志记原始错误：透传前把上游原始 500 错误体打到服务端日志，方便排障（客户端只看到透传后的，服务端看完整）。
7. CI 接 test_anthropic_error_passthrough：锁死"500 不被改成 422 / 真实信息不丢"，防止错误掩盖回归。

九、小结

Anthropic API 兼容层把 GLM-5.2 上游 500 掩盖成 ValidationError 的根因是**message_stream_converter 先按成功流校验转换、遇到错误体就 ValidationError，且没把上游错误状态码透传**。三层修复：

• 第一层：detect_error 先识别错误体（status≥400 或含 error 字段），safe_convert 错误原样透传（保留真实状态码与信息），只有成功流才校验；
• 第二层：MessageStreamConverter 分离"错误透传"与"成功转换"，错误仍按 Anthropic 风格包装但状态码/信息不掩盖；
• 第三层：CI 断言守住"500 不被改成 422 / 真实信息不丢"，任何掩盖立即红。

落实后，vLLM 的 Anthropic 兼容层在后端模型推理 500 时，客户端收到的是带真实 500 状态码和真实错误信息的错误事件，而不是误导性的 ValidationError。