Python + JSON Schema 实现工单结构化输出与本地复核

客服系统最危险的自动化，不是模型答错一句话，而是把"退款 9999 元"当成真指令一路执行。结构化输出（Structured Outputs）能要求模型按 JSON Schema 返回字段；但它不是业务真相。你还需要第二道本地门：金额、枚举值和缺失字段必须由程序复核。本篇用一个可复制的 Python 骨架完成这件事。

官方 Responses API 参考说明，json_schema 可用于受约束的 JSON 输出，且较旧的 json_object 不推荐优先使用。模型、权限与配额以你的账号为准。示例为了可离线验证，先用模拟响应；接入时只替换 call_model，密钥仅从环境变量读取。

flowchart LR I[用户文本] --> M[模型按 JSON Schema 提取] M --> J[JSON 对象] J --> V[本地字段/金额校验] V -->|通过| Q[进入人工队列] V -->|拒绝| E[记录原因并回问]

环境准备

需要 Python 3.10+。演示没有第三方依赖；真实请求可安装 pip install openai，并设置 export OPENAI_API_KEY='...'。不要把密钥写进源码。下面代码的超时参数放在真实调用处，避免网络问题无限等待。

python 复制代码

import json, os
from decimal import Decimal

ALLOWED = {"refund", "shipping", "other"}
MAX_REFUND = Decimal("500.00")

SCHEMA = {"type": "object", "properties": {
    "category": {"type": "string"}, "amount": {"type": "string"},
    "summary": {"type": "string"}}, "required": ["category", "summary"]}

def call_model(text: str) -> dict:
    # 真实接入：确认 os.getenv("OPENAI_API_KEY") 非空，
    # 使用客户端 timeout=20，并传 text.format={type: "json_schema", ...}。
    if not os.getenv("OPENAI_API_KEY"):
        return {"category": "refund", "amount": "128.50", "summary": text}
    raise RuntimeError("示例未在本次任务中实际调用线上 API")

def validate(ticket: dict) -> tuple[bool, str]:
    if not isinstance(ticket.get("summary"), str) or not ticket["summary"].strip():
        return False, "缺少摘要"
    if ticket.get("category") not in ALLOWED:
        return False, "未知分类"
    if ticket.get("category") == "refund":
        try:
            amount = Decimal(ticket.get("amount", "-1"))
        except Exception:
            return False, "金额不是十进制数"
        if not (Decimal("0") < amount <= MAX_REFUND):
            return False, "金额超出自动队列范围"
    return True, "QUEUED_FOR_REVIEW"

if __name__ == "__main__":
    ticket = call_model("订单 A12 重复扣款，请退 128.50 元")
    ok, reason = validate(ticket)
    print(json.dumps({"ticket": ticket, "ok": ok, "reason": reason}, ensure_ascii=False))

运行 python ticket.py，在未设置密钥时预期看到 ok: true 和 QUEUED_FOR_REVIEW；它只进入人工队列，不会退款。关键点是 Schema 解决形状，本地 validate 解决业务边界。常见失败有三类：模型漏字段，要求 Schema 的 required 字段并回问；金额带"元"或逗号，拒绝后让模型只输出数字字符串；网络慢或 429，真实调用设 20 秒超时并指数退避，不要在超时后盲目重试有副作用的动作。

适合把自由文本变成工单、表单和审核草稿；不适合拿模型结果直接放款、删库或处理医疗结论。工程化时，为每条记录保存原文、模型版本、Schema 版本和校验结果；再用脱敏历史样本统计拒绝率。5 分钟实践：新增 priority 枚举，只让 high 工单走人工复核，写一个断言验证未知优先级会被拒绝。

你的工单系统里，哪一个字段绝不能只相信模型输出？

关注「蜗牛聊AI」，一起看懂技术变化背后的真正机会。

本文首发于 java4u.cn，转载请注明出处。