结构化 JSON 输出经常解析失败，怎么减少模型多说一句话

仅靠“请只返回 JSON”并不稳。常见问题包括多一个 Markdown 代码块、字段缺失、类型错误、流式中断导致 JSON 没闭合。更可靠的方法是优先使用结构化输出能力，并在本地做 schema 校验。

一、为什么会出现这个问题

• SDK 版本、接口版本、模型名称和示例代码并不匹配。
• Python 的 base_url 与 Node.js 的 baseURL 等配置写法不同。
• 旧教程仍使用旧接口，而当前服务只实现其中一部分。
• 异常被 SDK 包装后，只看最后一行会丢掉响应状态码和原始响应体。

二、推荐的排查顺序

1. 锁定版本和接口

记录 Node/Python、SDK 版本、base URL、模型名和 endpoint。不要把 2023 年旧博客的参数直接复制到当前 SDK。

2. 先跑最小请求

只保留 model + 简单 input。最小请求成功后，再逐个加 stream、tools、JSON schema 等复杂能力。

3. 保留原始响应

遇到异常时记录 status code、content-type、body 前几百字符和 request id，避免 SDK 把关键信息包装掉。

三、可以直接复制的排查示例

from pydantic import BaseModel, ValidationError

class Article(BaseModel):
    title: str
    summary: str
    tags: list[str]

raw = {'title':'Codex 技巧','summary':'常见问题排查','tags':['Codex','AI Coding']}
try:
    obj = Article.model_validate(raw)
    print(obj)
except ValidationError as e:
    print(e)

四、使用建议

只要模型输出要直接进入数据库、自动化或 API，就应该把结构校验当成必需项。