精彩片段

API中轉(zhuǎn)站如何治理結(jié)構(gòu)化輸出？JSON Schema、字段校驗(yàn)與自動(dòng)修復(fù)教程 ?? 當(dāng) Claude API 只用于普通聊天時(shí)，模型輸出一段自然語言通常已經(jīng)足夠。但在代碼審查、工單分類、數(shù)據(jù)提取、內(nèi)容審核、自動(dòng)報(bào)表和企業(yè)工作流中，下游系統(tǒng)往往需要穩(wěn)定、可解析的 JSON，而不是自由格式文本。真實(shí)項(xiàng)目中經(jīng)常出現(xiàn)這些問題： ? 模型在 JSON 前后添加解釋

API中轉(zhuǎn)站如何治理結(jié)構(gòu)化輸出？ON Sche、字段校驗(yàn)與自動(dòng)修復(fù)教程

?? 當(dāng) Claude API 只用于普通聊天時(shí)，模型輸出一段自然語言通常已經(jīng)足夠。但在代碼**、工單分類、數(shù)據(jù)提取、內(nèi)容審核、自動(dòng)報(bào)表和企業(yè)工作流中，下游系統(tǒng)往往需要穩(wěn)定、可解析的 **ON，而不是自由格式文本。

真實(shí)項(xiàng)目中經(jīng)常出現(xiàn)這些問題：

? 模型在 **ON 前后添加解釋文字；

? 字段名稱與約定不一致；

? 數(shù)字被輸出成字符串；

? 必填字段缺失；

? 枚舉值超出允許范圍；

? **ON 外層被 Markdown 代碼塊包裹；

? 同一個(gè)字段有時(shí)返回對(duì)象，有時(shí)返回?cái)?shù)組；

? 模型因?yàn)樯舷挛牟蛔愣幵熳侄沃担?/p>

? 自動(dòng)重試多次，仍然得到無法解析的結(jié)果。

如果下游程序直接信任模型輸出，一次格式變化就可能導(dǎo)致任務(wù)中斷、數(shù)據(jù)庫寫入失敗，甚至觸發(fā)錯(cuò)誤的業(yè)務(wù)操作。

因此，API中轉(zhuǎn)站進(jìn)入自動(dòng)化場景后，不僅需要負(fù)責(zé)鑒權(quán)、路由和限流，還應(yīng)配合業(yè)務(wù)系統(tǒng)建立結(jié)構(gòu)化輸出約束、Sche** 校驗(yàn)、錯(cuò)誤修復(fù)和人工兜底機(jī)制。??

?? 一、為什么“請(qǐng)返回 **ON”還不夠

很多開發(fā)者會(huì)在 Prompt 中寫：

請(qǐng)使用 **ON 格式返回結(jié)果。

模型可能返回：

下面是分析結(jié)果：

{
  "risk": "high",
  "sum**ry": "發(fā)現(xiàn)高風(fēng)險(xiǎn)問題"
}

對(duì)于人類來說，這段內(nèi)容很清楚；對(duì)于嚴(yán)格調(diào)用 json.loads() 的程序來說，它并不是合法的純 **ON。

還有一種常見情況：

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

而下游系統(tǒng)實(shí)際要求：

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

兩份結(jié)果表達(dá)的含義相似，但字段、大小寫和數(shù)據(jù)結(jié)構(gòu)不同，仍然無法直接使用。

因此，結(jié)構(gòu)化輸出必須同時(shí)約束：

{
  "output_constraints": [
    "頂層數(shù)據(jù)類型",
    "字段名稱",
    "字段類型",
    "必填字段",
    "枚舉范圍",
    "數(shù)組元素結(jié)構(gòu)",
    "是否允許額外字段",
    "空值處理規(guī)則"
  ]
}

?? 二、先設(shè)計(jì)穩(wěn)定的數(shù)據(jù)結(jié)構(gòu)

以代碼**結(jié)果為例，可以定義：

{
  "sum**ry": "本次變更存在兩個(gè)需要處理的問題",
  "risk_level": "medium",
  "issues": [
    {
      "file": "src/auth.py",
      "line": 82,
      "severity": "high",
      "category": "security",
      "pro*lem": "刷新令牌缺少并發(fā)保護(hù)",
      "suggestion": "增加分布式鎖"
    }
  ],
  "merge_recommen**tion": "**nual_review"
}

設(shè)計(jì)結(jié)構(gòu)時(shí)應(yīng)避免：

? 同一個(gè)字段承擔(dān)多個(gè)含義；

? 字段名稱使用模糊縮寫；

? 數(shù)組和對(duì)象隨機(jī)切換；

? 把數(shù)字、布爾值全部寫成字符串；

? 在一個(gè)長文本字段中混合多個(gè)業(yè)務(wù)信息。

更適合程序處理的字段通常具備明確邊界：

{
  "field_design": {
    "risk_level": "有限枚舉",
    "issues": "同構(gòu)對(duì)象數(shù)組",
    "line": "整數(shù)或null",
    "merge_recommen**tion": "有限枚舉",
    "sum**ry": "簡短自然語言"
  }
}

?? 三、使用 ON Sche 描述規(guī)則

**ON Sche** 可以把口頭約定轉(zhuǎn)化為機(jī)器可執(zhí)行規(guī)則。

{
  "$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 可以阻止模型隨意增加未定義字段。

但如果業(yè)務(wù)正在快速迭代，也可以暫時(shí)允許額外字段，再在正式版本中逐步收緊。

?? 四、Prompt 中如何嵌入結(jié)構(gòu)化規(guī)則

不要只把完整 Sche** 原樣塞進(jìn) Prompt，還應(yīng)增加清晰的行為要求：

你是一名代碼**助手。

請(qǐng)分析輸入的代碼差異，并僅返回一個(gè)合法 **ON 對(duì)象。

要求：
1. 不要輸出 Markdown 代碼塊。
2. 不要在 **ON 前后添加解釋。
3. 字段必須嚴(yán)格符合給定 Sche**。
4. 無法確定代碼行時(shí)，line 返回 null。
5. 沒有問題時(shí)，issues 返回空數(shù)組。
6. 不得編造文件名、代碼行或測試結(jié)果。

然后附上精簡的字段說明：

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

完整 Sche** 更適合程序校驗(yàn)；精簡結(jié)構(gòu)更適合幫助模型理解輸出目標(biāo)。

?? 五、為結(jié)構(gòu)化任務(wù)使用獨(dú)立中轉(zhuǎn)項(xiàng)目

結(jié)構(gòu)化任務(wù)通常會(huì)被自動(dòng)化程序大量調(diào)用，不應(yīng)與普通聊天共用同一個(gè) Key 和預(yù)算。

使用 靈能API 時(shí)，可以單獨(dú)創(chuàng)建結(jié)構(gòu)化輸出項(xiàng)目，限制模型、并發(fā)和每日額度。

官網(wǎng)：

https://www.lnsns.com/

建議配置：

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

獨(dú)立項(xiàng)目便于統(tǒng)計(jì)：

? **ON 解析成功率；

? Sche** 校驗(yàn)成功率；

? 自動(dòng)修復(fù)次數(shù)；

? 單任務(wù) Token；

? 不同模型的格式穩(wěn)定性。

?? 六、Python 中如何校驗(yàn)?zāi)Ｐ洼敵?/h2>

安裝依賴：

pip install jsonsche**

校驗(yàn)代碼：

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

調(diào)用結(jié)果：

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

if errors:
    print("結(jié)構(gòu)校驗(yàn)失敗：")
    for error in errors:
        print("-", error)
else:
    print("結(jié)構(gòu)校驗(yàn)成功")

這樣可以區(qū)分：

? **ON 語法錯(cuò)誤；

? 必填字段缺失；

? 類型錯(cuò)誤；

? 枚舉錯(cuò)誤；

? 多余字段；

? 數(shù)值范圍錯(cuò)誤。

?? 七、先做低風(fēng)險(xiǎn)格式清理

部分輸出只存在簡單包裝問題，例如：

{
  "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

但清理邏輯不應(yīng)擅自修改業(yè)務(wù)值。

例如不能自動(dòng)把：

{
  "risk_level": "嚴(yán)重"
}

靜默轉(zhuǎn)換為：

{
  "risk_level": "high"
}

除非業(yè)務(wù)明確維護(hù)了這種映射。

?? 八、結(jié)構(gòu)錯(cuò)誤如何自動(dòng)修復(fù)

當(dāng)輸出能夠解析，但不符合 Sche** 時(shí)，可以把錯(cuò)誤列表交給修復(fù)模型。

修復(fù) Prompt：

你需要修復(fù)一個(gè) **ON 對(duì)象，使其符合給定 Sche**。

要求：
1. 僅修復(fù)結(jié)構(gòu)和格式。
2. 不要增加原結(jié)果中不存在的事實(shí)。
3. 無法確定的字段使用 null、空數(shù)組或允許的默認(rèn)值。
4. 僅返回修復(fù)后的 **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"
  ]
}

修復(fù)后仍必須重新執(zhí)行 Sche** 校驗(yàn)。

自動(dòng)修復(fù)不能繞過驗(yàn)證流程。

?? 九、哪些錯(cuò)誤可以自動(dòng)修復(fù)

適合自動(dòng)修復(fù)：

{
  "repaira*le_errors": [
    "Markdown代碼塊包裝",
    "字段名稱輕微偏差",
    "數(shù)字字符串轉(zhuǎn)換",
    "缺少可安全推導(dǎo)的默認(rèn)字段",
    "枚舉大小寫錯(cuò)誤",
    "多余解釋文本"
  ]
}

不適合自動(dòng)修復(fù)：

{
  "unsafe_repairs": [
    "缺少關(guān)鍵業(yè)務(wù)結(jié)論",
    "虛構(gòu)文件和代碼行",
    "安全等級(jí)判斷錯(cuò)誤",
    "金額和日期來源不明",
    "引用來源不存在",
    "模型未完成核心分析"
  ]
}

當(dāng)內(nèi)容本身不可信時(shí)，應(yīng)該重新執(zhí)行原任務(wù)或進(jìn)入人工復(fù)核，而不是只修正格式。

?? 十、建立結(jié)構(gòu)化輸出質(zhì)量指標(biāo)

可以記錄：

{
  "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
  }
}

還應(yīng)按以下維度拆分：

? 模型；

? Prompt 版本；

? Sche** 版本；

? 項(xiàng)目；

? 任務(wù)類型；

? 輸入長度；

? 輸出長度。

如果某個(gè) Prompt 更新后校驗(yàn)成功率下降，應(yīng)立即暫停發(fā)布。

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

業(yè)務(wù)字段會(huì)持續(xù)變化。

例如 v1：

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

v2 增加：

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

請(qǐng)求記錄應(yīng)包含：

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

下游消費(fèi)者必須明確支持哪個(gè)版本。

不要在同一個(gè)接口中無提示改變字段結(jié)構(gòu)。

?? 十二、如何兼容舊版消費(fèi)者

可以建立轉(zhuǎn)換層：

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

或者通過請(qǐng)求參數(shù)指定：

{
  "output_sche**": "code_review_v1"
}

推薦設(shè)置棄用周期：

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

?? 十三、防止結(jié)構(gòu)化輸出觸發(fā)危險(xiǎn)操作

即使 **ON 完全符合 Sche**，也不代表內(nèi)容可以直接執(zhí)行。

例如模型返回：

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

下游系統(tǒng)不能因?yàn)楦袷秸_就直接刪除用戶。

應(yīng)增加業(yè)務(wù)規(guī)則：

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

Sche** 負(fù)責(zé)檢查“格式是否正確”，業(yè)務(wù)策略負(fù)責(zé)判斷“操作是否允許”。

??? 十四、完整處理流水線

推薦流程：

接收模型輸出
    ↓
清理外層格式
    ↓
**ON語法解析
    ↓
**ON Sche**校驗(yàn)
    ↓
業(yè)務(wù)規(guī)則校驗(yàn)
    ↓
可修復(fù)？
   ↙     ↘
自動(dòng)修復(fù)   重新生成或人工復(fù)核
    ↓
再次校驗(yàn)
    ↓
保存結(jié)果
    ↓
交給下游系統(tǒng)

配置示例：

{
  "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
  }
}

?? 十五、使用平臺(tái)記錄分析格式穩(wěn)定性

在 靈能API 中可以將結(jié)構(gòu)化任務(wù)的 request_id、模型和 Token 用量與內(nèi)部校驗(yàn)結(jié)果關(guān)聯(lián)。

訪問入口：

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
}

當(dāng)某個(gè)模型格式穩(wěn)定但內(nèi)容質(zhì)量一般時(shí)，不能只看 Sche** 成功率；仍需結(jié)合業(yè)務(wù)準(zhǔn)確率判斷。

?? 十六、固定測試集如何設(shè)計(jì)

測試用例應(yīng)覆蓋：

{
  "test_cases": [
    "正常單問題輸出",
    "無問題時(shí)返回空數(shù)組",
    "缺少代碼行時(shí)返回null",
    "多個(gè)問題數(shù)組",
    "超長問題描述",
    "特殊字符與換行",
    "模型輸出Markdown代碼塊",
    "字段類型錯(cuò)誤",
    "枚舉值錯(cuò)誤",
    "額外字段",
    "空響應(yīng)",
    "截?cái)?*ON"
  ]
}

驗(yàn)收標(biāo)準(zhǔn)：

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

?? 十七、常見問題排查

**ON 經(jīng)常被截?cái)?/h3>

檢查：

? `**x_tokens` 是否過低；

? 輸出結(jié)構(gòu)是否過于復(fù)雜；

? issues 數(shù)量是否無限制；

? 網(wǎng)絡(luò)或流式連接是否中斷。

可以增加：

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

模型頻繁增加額外字段

在 Prompt 中強(qiáng)調(diào)字段白名單，并啟用：

{
  "additionalProperties": false
}

自動(dòng)修復(fù)后內(nèi)容發(fā)生變化

說明修復(fù) Prompt 權(quán)限過大。

應(yīng)明確：

> 只修復(fù)結(jié)構(gòu)，不重新分析業(yè)務(wù)內(nèi)容。

Sche** 成功率高但業(yè)務(wù)結(jié)果錯(cuò)誤

這說明格式治理正常，內(nèi)容評(píng)測不足。

需要增加：

? 規(guī)則校驗(yàn)；

? 事實(shí)驗(yàn)證；

? 固定測試集；

? 人工抽樣；

? 質(zhì)量評(píng)分。

?? 十八、推薦生產(chǎn)配置

正式上線前，可以在靈能API 中創(chuàng)建獨(dú)立 Key，通過官網(wǎng) https://www.lnsns.com/ 核對(duì)結(jié)構(gòu)化項(xiàng)目與普通聊天項(xiàng)目是否分開統(tǒng)計(jì)。

{
  "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
  }
}