前面的系列已经分别介绍了提示词、结构化输出、错误处理和人工复核。现在把这些知识组合成一个小项目:用户提交一段退货申请,模型负责提取申请类型、订单号和缺失材料,程序再用确定性规则决定是补充信息、人工审核,还是进入下一步。这个例子不直接执行退款,也不把模型判断当成最终业务决定,重点是学习如何划清模型与程序的责任边界。

先划定项目边界

退货申请通常是自然语言,例如:“上周买的耳机左耳没有声音,订单号 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 应用具备校验、复核和安全降级的基础。