前面的系列已经分别介绍了提示词、结构化输出、错误处理和人工复核。现在把这些知识组合成一个小项目:用户提交一段退货申请,模型负责提取申请类型、订单号和缺失材料,程序再用确定性规则决定是补充信息、人工审核,还是进入下一步。这个例子不直接执行退款,也不把模型判断当成最终业务决定,重点是学习如何划清模型与程序的责任边界。
先划定项目边界
退货申请通常是自然语言,例如:“上周买的耳机左耳没有声音,订单号 20261118001,已经拍了开箱视频。”我们希望得到一份稳定的数据,而不是一段难以解析的回复:
order_id:订单号,找不到时为 null;
issue_type:质量问题、商品不符、无理由退货或其他;
summary:只根据原文写出的简短摘要;
required_evidence:该类型通常需要的材料;
missing_evidence:原文中尚未提供的材料;
risk_level:低、中或高。
模型适合从文字中提取和归纳,程序适合执行固定规则。例如,只要缺少订单号,就不能把申请标记为“材料齐全”;只要风险等级为高,就必须转人工。即使模型返回了“可以退款”,程序也不应该因此直接调用退款接口。
用 Pydantic 定义结果结构
当前 OpenAI Python SDK 支持用 client.responses.parse() 配合 Pydantic 模型请求结构化结果。模型名称仍从环境变量读取,便于切换部署;密钥只从环境变量读取,不写入代码。
先安装依赖:
1
| python -m pip install openai pydantic
|
然后定义返回结构。枚举可以限制模型只能选择预先声明的值,extra="forbid" 则拒绝未定义字段:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27
| from enum import Enum
from pydantic import BaseModel, ConfigDict
class IssueType(str, Enum): QUALITY = "quality_issue" NOT_AS_DESCRIBED = "not_as_described" NO_REASON = "no_reason" OTHER = "other"
class RiskLevel(str, Enum): LOW = "low" MEDIUM = "medium" HIGH = "high"
class ReturnAssessment(BaseModel): model_config = ConfigDict(extra="forbid")
order_id: str | None issue_type: IssueType summary: str required_evidence: list[str] missing_evidence: list[str] risk_level: RiskLevel
|
order_id 可以为空,但字段本身仍然存在。这样程序不需要猜测“字段不存在”和“用户没有提供订单号”是不是同一件事。结构化输出解决的是格式约束,不代表字段内容已经被业务系统证实。
写出最小可运行程序
下面的 check_return_request 是完整的模型调用流程。提示词明确了任务、分类范围、事实边界和缺失信息的处理方式;用户原文放在单独的标记中,避免和规则混在一起。
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94
| import json import os
from openai import APIError, APITimeoutError, OpenAI from pydantic import BaseModel, ConfigDict from enum import Enum
class IssueType(str, Enum): QUALITY = "quality_issue" NOT_AS_DESCRIBED = "not_as_described" NO_REASON = "no_reason" OTHER = "other"
class RiskLevel(str, Enum): LOW = "low" MEDIUM = "medium" HIGH = "high"
class ReturnAssessment(BaseModel): model_config = ConfigDict(extra="forbid")
order_id: str | None issue_type: IssueType summary: str required_evidence: list[str] missing_evidence: list[str] risk_level: RiskLevel
def build_client() -> OpenAI: kwargs: dict[str, object] = { "api_key": os.environ["OPENAI_API_KEY"], "timeout": 30.0, "max_retries": 2, } base_url = os.getenv("OPENAI_BASE_URL") if base_url: kwargs["base_url"] = base_url return OpenAI(**kwargs)
def check_return_request(text: str) -> dict[str, object]: if not text.strip(): raise ValueError("退货申请不能是空白文本") if len(text) > 2_000: raise ValueError("退货申请超过 2,000 个字符")
response = build_client().responses.parse( model=os.environ["AI_MODEL"], input=[ { "role": "system", "content": ( "你是退货材料整理助手。只根据用户原文提取信息,不要猜测订单号或事实。" "issue_type 只能是 quality_issue、not_as_described、no_reason、other。" "required_evidence 和 missing_evidence 都必须是材料名称列表。" ), }, { "role": "user", "content": f"<return_request>\n{text}\n</return_request>", }, ], text_format=ReturnAssessment, )
assessment = response.output_parsed if assessment is None: raise RuntimeError("模型没有返回可解析的结构化结果")
if assessment.risk_level is RiskLevel.HIGH: route = "manual_review" elif assessment.order_id is None or assessment.missing_evidence: route = "request_more_information" else: route = "ready_for_manual_review"
result = assessment.model_dump(mode="json") result["route"] = route return result
if __name__ == "__main__": request = input("请输入退货申请:") try: print(json.dumps(check_return_request(request), ensure_ascii=False, indent=2)) except (ValueError, APITimeoutError) as exc: print(f"请求未处理:{exc}") except APIError: print("模型服务调用失败,请稍后重试。")
|
运行前设置 OPENAI_API_KEY 和 AI_MODEL,再执行 python return_checker.py。程序不会打印密钥,也不会把模型的自然语言回复直接当作 JSON 解析,而是让 SDK 先按声明的 Pydantic 结构解析,再由本地规则计算 route。模型输出的具体内容取决于输入和模型,不能预先假定某一段固定结果。
为什么还要保留本地规则
结构化输出只能保证字段形状和枚举范围,不能证明订单真实存在,也不能证明用户上传的照片确实展示了故障。route 放在 Python 中有三个好处:规则可读、规则可测试、规则不会随着模型温度或版本变化而改变。
生产代码还应把“转人工”和“请求补充材料”记录为状态,而不是覆盖原始申请。日志只记录请求编号、状态、耗时和错误类型,原文与订单信息应按业务需要脱敏保存。若以后增加退款执行功能,执行前还要再次检查订单状态、金额和权限,不能把这段脚本直接连接到资金操作。
常见问题
Pydantic 校验通过,结果就一定正确吗
不一定。校验通过只说明结果符合预先声明的类型和枚举。订单号可能是用户写错的,摘要也可能遗漏关键信息。高风险字段需要查询真实系统或人工确认。
为什么不让模型直接返回 route
可以让模型提供建议,但最终路由依赖明确的业务规则。把“缺少订单号就补充信息”写在代码里,比把它藏在提示词中更容易审查和回归测试。
API 调用失败时能否返回空对象
不应该。空对象会被下游误认为“没有问题”。示例把输入错误、超时和服务错误分开处理;实际项目可以将失败状态写入队列,或交给人工重试,但不要伪造成功结果。
小结
这个小项目把一次自然语言申请拆成四层:提示词说明提取任务,结构化输出约束数据形状,Pydantic 结果承接模型响应,本地规则决定业务路由。模型负责处理语言的不确定性,程序负责执行可验证的边界;只要坚持这个分工,就能在不牺牲灵活性的前提下,让 AI 应用具备校验、复核和安全降级的基础。