精彩片段

API中转站如何治理结构化输出？JSON Schema、字段校验与自动修复教程 🧩 当 Claude API 只用于普通聊天时，模型输出一段自然语言通常已经足够。但在代码审查、工单分类、数据提取、内容审核、自动报表和企业工作流中，下游系统往往需要稳定、可解析的 JSON，而不是自由格式文本。真实项目中经常出现这些问题： • 模型在 JSON 前后添加解释

API中转站如何治理结构化输出？ON Sche、字段校验与自动修复教程

🧩 当 Claude API 只用于普通聊天时，模型输出一段自然语言通常已经足够。但在代码**、工单分类、数据提取、内容审核、自动报表和企业工作流中，下游系统往往需要稳定、可解析的 **ON，而不是自由格式文本。

真实项目中经常出现这些问题：

• 模型在 **ON 前后添加解释文字；

• 字段名称与约定不一致；

• 数字被输出成字符串；

• 必填字段缺失；

• 枚举值超出允许范围；

• **ON 外层被 Markdown 代码块包裹；

• 同一个字段有时返回对象，有时返回数组；

• 模型因为上下文不足而编造字段值；

• 自动重试多次，仍然得到无法解析的结果。

如果下游程序直接信任模型输出，一次格式变化就可能导致任务中断、数据库写入失败，甚至触发错误的业务操作。

因此，API中转站进入自动化场景后，不仅需要负责鉴权、路由和限流，还应配合业务系统建立结构化输出约束、Sche** 校验、错误修复和人工兜底机制。⚙️

🧠 一、为什么“请返回 **ON”还不够

很多开发者会在 Prompt 中写：

请使用 **ON 格式返回结果。

模型可能返回：

下面是分析结果：

{
  "risk": "high",
  "sum**ry": "发现高风险问题"
}

对于人类来说，这段内容很清楚；对于严格调用 json.loads() 的程序来说，它并不是合法的纯 **ON。

还有一种常见情况：

{
  "riskLevel": "HIGH",
  "details": "..."
}

而下游系统实际要求：

{
  "risk_level": "high",
  "sum**ry": "..."
}

两份结果表达的含义相似，但字段、大小写和数据结构不同，仍然无法直接使用。

因此，结构化输出必须同时约束：

{
  "output_constraints": [
    "顶层数据类型",
    "字段名称",
    "字段类型",
    "必填字段",
    "枚举范围",
    "数组元素结构",
    "是否允许额外字段",
    "空值处理规则"
  ]
}

🧱 二、先设计稳定的数据结构

以代码**结果为例，可以定义：

{
  "sum**ry": "本次变更存在两个需要处理的问题",
  "risk_level": "medium",
  "issues": [
    {
      "file": "src/auth.py",
      "line": 82,
      "severity": "high",
      "category": "security",
      "pro*lem": "刷新令牌缺少并发保护",
      "suggestion": "增加分布式锁"
    }
  ],
  "merge_recommen**tion": "**nual_review"
}

设计结构时应避免：

• 同一个字段承担多个含义；

• 字段名称使用模糊缩写；

• 数组和对象随机切换；

• 把数字、布尔值全部写成字符串；

• 在一个长文本字段中混合多个业务信息。

更适合程序处理的字段通常具备明确边界：

{
  "field_design": {
    "risk_level": "有限枚举",
    "issues": "同构对象数组",
    "line": "整数或null",
    "merge_recommen**tion": "有限枚举",
    "sum**ry": "简短自然语言"
  }
}

📐 三、使用 ON Sche 描述规则

**ON Sche** 可以把口头约定转化为机器可执行规则。

{
  "$sche**": "https://json-sche**.org/draft/2020-12/sche**",
  "type": "o*ject",
  "required": [
    "sum**ry",
    "risk_level",
    "issues",
    "merge_recommen**tion"
  ],
  "properties": {
    "sum**ry": {
      "type": "string",
      "minLength": 1,
      "**xLength": 500
    },
    "risk_level": {
      "type": "string",
      "enum": [
        "low",
        "medium",
        "high"
      ]
    },
    "issues": {
      "type": "array",
      "items": {
        "type": "o*ject",
        "required": [
          "file",
          "severity",
          "category",
          "pro*lem",
          "suggestion"
        ],
        "properties": {
          "file": {
            "type": "string"
          },
          "line": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 1
          },
          "severity": {
            "type": "string",
            "enum": [
              "low",
              "medium",
              "high"
            ]
          },
          "category": {
            "type": "string"
          },
          "pro*lem": {
            "type": "string"
          },
          "suggestion": {
            "type": "string"
          }
        },
        "additionalProperties": false
      }
    },
    "merge_recommen**tion": {
      "type": "string",
      "enum": [
        "approve",
        "**nual_review",
        "*lock"
      ]
    }
  },
  "additionalProperties": false
}

additionalProperties: false 可以阻止模型随意增加未定义字段。

但如果业务正在快速迭代，也可以暂时允许额外字段，再在正式版本中逐步收紧。

📝 四、Prompt 中如何嵌入结构化规则

不要只把完整 Sche** 原样塞进 Prompt，还应增加清晰的行为要求：

你是一名代码**助手。

请分析输入的代码差异，并仅返回一个合法 **ON 对象。

要求：
1. 不要输出 Markdown 代码块。
2. 不要在 **ON 前后添加解释。
3. 字段必须严格符合给定 Sche**。
4. 无法确定代码行时，line 返回 null。
5. 没有问题时，issues 返回空数组。
6. 不得编造文件名、代码行或测试结果。

然后附上精简的字段说明：

{
  "sum**ry": "字符串",
  "risk_level": "low | medium | high",
  "issues": [
    {
      "file": "字符串",
      "line": "整数或null",
      "severity": "low | medium | high",
      "category": "字符串",
      "pro*lem": "字符串",
      "suggestion": "字符串"
    }
  ],
  "merge_recommen**tion": "approve | **nual_review | *lock"
}

完整 Sche** 更适合程序校验；精简结构更适合帮助模型理解输出目标。

🌐 五、为结构化任务使用独立中转项目

结构化任务通常会被自动化程序大量调用，不应与普通聊天共用同一个 Key 和预算。

使用 灵能API 时，可以单独创建结构化输出项目，限制模型、并发和每日额度。

官网：

https://www.lnsns.com/

建议配置：

{
  "project": {
    "name": "structured-output-service",
    "allowed_models": [
      "coding-model"
    ],
    "**ily_*udget": 30,
    "**x_concurrency": 5,
    "environment": "production"
  }
}

独立项目便于统计：

• **ON 解析成功率；

• Sche** 校验成功率；

• 自动修复次数；

• 单任务 Token；

• 不同模型的格式稳定性。

🧪 六、Python 中如何校验模型输出

安装依赖：

pip install jsonsche**

校验代码：

import json
from jsonsche** import Draft202012Vali**tor


def vali**te_output(
    raw_text: str,
    sche**: dict,
) -> tuple[dict | None, list[str]]:
    try:
        **ta = json.loads(raw_text)
    except json.**ONDecodeError as exc:
        return None, [
            f"**ON解析失败：{exc.msg}"
        ]

    vali**tor = Draft202012Vali**tor(sche**)
    errors = sorted(
        vali**tor.iter_errors(**ta),
        key=lam*** error: list(error.path),
    )

    messages = []

    for error in errors:
        path = ".".join(
            str(item)
            for item in error.path
        )

        messages.append(
            f"{path or 'root'}: {error.message}"
        )

    return **ta, messages

调用结果：

**ta, errors = vali**te_output(
    model_response,
    review_sche**,
)

if errors:
    print("结构校验失败：")
    for error in errors:
        print("-", error)
else:
    print("结构校验成功")

这样可以区分：

• **ON 语法错误；

• 必填字段缺失；

• 类型错误；

• 枚举错误；

• 多余字段；

• 数值范围错误。

🧹 七、先做低风险格式清理

部分输出只存在简单包装问题，例如：

{
  "risk_level": "low"
}

可以先移除外层代码块：

def strip_code_fence(text: str) -> str:
    value = text.strip()

    if value.startswith("```"):
        lines = value.splitlines()

        if lines:
            lines = lines[1:]

        if lines and lines[-1].strip() == "```":
            lines = lines[:-1]

        return "\n".join(lines).strip()

    return value

但清理逻辑不应擅自修改业务值。

例如不能自动把：

{
  "risk_level": "严重"
}

静默转换为：

{
  "risk_level": "high"
}

除非业务明确维护了这种映射。

🔄 八、结构错误如何自动修复

当输出能够解析，但不符合 Sche** 时，可以把错误列表交给修复模型。

修复 Prompt：

你需要修复一个 **ON 对象，使其符合给定 Sche**。

要求：
1. 仅修复结构和格式。
2. 不要增加原结果中不存在的事实。
3. 无法确定的字段使用 null、空数组或允许的默认值。
4. 仅返回修复后的 **ON。

输入：

{
  "original_output": {
    "risk": "HIGH",
    "items": []
  },
  "vali**tion_errors": [
    "root: 'sum**ry' is a required property",
    "root: 'risk_level' is a required property",
    "root: Additional properties are not allowed"
  ]
}

修复后仍必须重新执行 Sche** 校验。

自动修复不能绕过验证流程。

🚦 九、哪些错误可以自动修复

适合自动修复：

{
  "repaira*le_errors": [
    "Markdown代码块包装",
    "字段名称轻微偏差",
    "数字字符串转换",
    "缺少可安全推导的默认字段",
    "枚举大小写错误",
    "多余解释文本"
  ]
}

不适合自动修复：

{
  "unsafe_repairs": [
    "缺少关键业务结论",
    "虚构文件和代码行",
    "安全等级判断错误",
    "金额和日期来源不明",
    "引用来源不存在",
    "模型未完成核心分析"
  ]
}

当内容本身不可信时，应该重新执行原任务或进入人工复核，而不是只修正格式。

📊 十、建立结构化输出质量指标

可以记录：

{
  "structured_metri**": {
    "json_parse_rate": 0.992,
    "sche**_valid_rate": 0.968,
    "auto_repair_rate": 0.041,
    "repair_success_rate": 0.887,
    "**nual_review_rate": 0.012,
    "**erage_retry_count": 0.08
  }
}

还应按以下维度拆分：

• 模型；

• Prompt 版本；

• Sche** 版本；

• 项目；

• 任务类型；

• 输入长度；

• 输出长度。

如果某个 Prompt 更新后校验成功率下降，应立即暂停发布。

🧱 十一、Sche** 也需要版本管理

业务字段会持续变化。

例如 v1：

{
  "risk_level": "medium",
  "issues": []
}

v2 增加：

{
  "risk_level": "medium",
  "issues": [],
  "merge_recommen**tion": "**nual_review"
}

请求记录应包含：

{
  "sche**": {
    "name": "code_review",
    "version": "v2"
  },
  "prompt_version": "v8",
  "model": "coding-model"
}

下游消费者必须明确支持哪个版本。

不要在同一个接口中无提示改变字段结构。

🔁 十二、如何兼容旧版消费者

可以建立转换层：

def convert_v2_to_v1(**ta: dict) -> dict:
    return {
        "risk_level": **ta["risk_level"],
        "issues": **ta["issues"],
    }

或者通过请求参数指定：

{
  "output_sche**": "code_review_v1"
}

推荐设置弃用周期：

{
  "deprecation": {
    "sche**": "code_review_v1",
    "status": "deprecated",
    "sunset_**te": "2026-10-01",
    "replacement": "code_review_v2"
  }
}

🔐 十三、防止结构化输出触发危险操作

即使 **ON 完全符合 Sche**，也不代表内容可以直接执行。

例如模型返回：

{
  "action": "delete_user",
  "user_id": "1024"
}

下游系统不能因为格式正确就直接删除用户。

应增加业务规则：

{
  "execution_policy": {
    "allowed_actions": [
      "create_draft",
      "send_for_review"
    ],
    "**nual_approval_actions": [
      "delete_user",
      "pu*lish_production",
      "tran**er_funds"
    ]
  }
}

Sche** 负责检查“格式是否正确”，业务策略负责判断“操作是否允许”。

🛠️ 十四、完整处理流水线

推荐流程：

接收模型输出
    ↓
清理外层格式
    ↓
**ON语法解析
    ↓
**ON Sche**校验
    ↓
业务规则校验
    ↓
可修复？
   ↙     ↘
自动修复   重新生成或人工复核
    ↓
再次校验
    ↓
保存结果
    ↓
交给下游系统

配置示例：

{
  "structured_pipeline": {
    "strip_**rkdown": true,
    "json_parse": true,
    "sche**_vali**te": true,
    "*usiness_vali**te": true,
    "auto_repair": true,
    "**x_repair_attempts": 1,
    "**nual_review_on_failure": true
  }
}

📈 十五、使用平台记录分析格式稳定性

在 灵能API 中可以将结构化任务的 request_id、模型和 Token 用量与内部校验结果关联。

访问入口：

https://www.lnsns.com/

日志示例：

{
  "request_id": "req_xxxxx",
  "project": "structured-output",
  "model": "coding-model",
  "prompt_version": "v8",
  "sche**_version": "v2",
  "json_parsed": true,
  "sche**_valid": false,
  "repair_attempted": true,
  "repair_succeeded": true,
  "input_tokens": 4200,
  "output_tokens": 780
}

当某个模型格式稳定但内容质量一般时，不能只看 Sche** 成功率；仍需结合业务准确率判断。

🧪 十六、固定测试集如何设计

测试用例应覆盖：

{
  "test_cases": [
    "正常单问题输出",
    "无问题时返回空数组",
    "缺少代码行时返回null",
    "多个问题数组",
    "超长问题描述",
    "特殊字符与换行",
    "模型输出Markdown代码块",
    "字段类型错误",
    "枚举值错误",
    "额外字段",
    "空响应",
    "截断**ON"
  ]
}

验收标准：

{
  "acceptance": {
    "json_parse_rate": 0.99,
    "sche**_valid_rate": 0.97,
    "unsafe_auto_repair": 0,
    "**nual_review_tracea*le": true
  }
}

🚨 十七、常见问题排查

**ON 经常被截断

检查：

• `**x_tokens` 是否过低；

• 输出结构是否过于复杂；

• issues 数量是否无限制；

• 网络或流式连接是否中断。

可以增加：

{
  "limits": {
    "**x_issues": 20,
    "**x_sum**ry_characters": 500
  }
}

模型频繁增加额外字段

在 Prompt 中强调字段白名单，并启用：

{
  "additionalProperties": false
}

自动修复后内容发生变化

说明修复 Prompt 权限过大。

应明确：

> 只修复结构，不重新分析业务内容。

Sche** 成功率高但业务结果错误

这说明格式治理正常，内容评测不足。

需要增加：

• 规则校验；

• 事实验证；

• 固定测试集；

• 人工抽样；

• 质量评分。

🚀 十八、推荐生产配置

正式上线前，可以在灵能API 中创建独立 Key，通过官网 https://www.lnsns.com/ 核对结构化项目与普通聊天项目是否分开统计。

{
  "structured_output": {
    "sche**_required": true,
    "sche**_version_required": true,
    "**rkdown_for**dden": true,
    "json_parse_required": true,
    "*usiness_vali**tion_required": true,
    "auto_repair_ena*led": true,
    "**x_repair_attempts": 1,
    "unsafe_action_*locked": true,
    "**nual_review_fall*ack": true,
    "metri**_ena*led": true
  }
}