综合小项目:用 Python 构建可追踪的 AI 决策记录整理器
前面的系列已经覆盖了模型调用、结构化输出、错误处理、安全边界、状态保存和评估。本篇把这些知识组合成一个小项目:读取一份会议或需求记录,让模型提取“已经决定的事项、待确认的问题和后续行动”,再由 Python 检查证据引用是否真实存在,最后保存一份可以继续追踪的 JSON 记录。模型只负责整理候选信息,不负责替人做决定,也不直接执行行动。
先定义可追踪的结果
输入文本先按非空行编号,例如 N1、N2。模型返回的每个决策必须引用至少一个真实的行号;程序发现 N99 这类不存在的引用时,直接拒绝报告。这样做不能保证模型理解完全正确,却能让人快速回到原文核对。
输出包含四部分:summary 是整体概括,decisions 是已有结论,open_questions 是材料中仍无法确定的问题,next_actions 是待办草稿。每个决策还有 confidence,它只是模型的自评,不是准确率证明。程序会额外生成一个由输入文本计算出的短 record_id,方便把同一份材料、报告和后续复核记录关联起来。
准备环境和数据结构
当前 openai Python SDK 可以使用 Responses API 的结构化解析方式,把 Pydantic 模型传给 text_format。先创建独立环境,并只从环境变量读取配置:
1 | python -m venv .venv |
创建 decision_log.py,先声明模型输出结构:
1 | import hashlib |
extra="forbid" 会拒绝未声明字段,字段长度和数值范围由 Pydantic 检查。不过,Pydantic 不知道 N1 是否真的存在,所以证据编号仍要在业务层校验。
编写最小整理器
把下面的函数接在同一个文件中:
1 | def number_notes(text: str) -> tuple[str, set[str]]: |
这里有三道边界:编号由本地代码生成,模型不能自行创造证据;结构由 DecisionReport 限定,未知字段会失败;最终文件保存了 record_id、来源路径和报告,后续可以按输入指纹查找。NOTES 被明确标记为数据,即使原文中出现“忽略前面规则”之类的句子,也不应被当成新的系统指令。
准备一份 notes.txt 后,先做不联网的自测:
1 | 本次发布范围只包括移动端页面。 |
1 | python decision_log.py --self-test |
--self-test 只验证编号、结构和证据检查,不需要密钥,也不会产生模型结果。第二条命令才会调用模型;生成内容会随模型和输入变化,不应把某一次输出写成固定示例。可以打开生成的 .decision.json,检查每个 evidence 是否都能在原文中找到。
常见问题
为什么结构化解析后还要手写校验?
结构化解析主要保证字段和类型正确,不保证证据编号存在,也不保证结论理解无误。格式校验和业务校验解决的是两类不同问题。
模型返回不存在的编号怎么办?
拒绝整份报告并记录错误,不要静默删除引用或自动把编号改成“最接近”的值。修正提示词、缩短输入或把材料分块后重试,必须保留清晰的失败原因。
output_parsed 为空怎么办?
先确认所选模型和服务端支持该结构化解析方式,再检查 SDK 版本、模型名和兼容接口的能力。不要在解析失败时直接把普通文本当成可信报告。
这个工具能自动执行行动吗?
不能。next_actions 只是从文字中整理出的草稿;创建任务、发送通知或修改系统数据前,还应增加人工确认、权限检查和幂等设计。
小结
这个项目把模型放在“提取候选信息”的位置,把编号、结构校验、证据检查和文件保存交给 Python。可追踪不等于正确,但稳定的证据编号和 record_id 能让每条结果回到输入、复核和比较。以后接入多轮对话、数据库或审批流程时,也应继续保持这个边界:模型提出候选,程序验证约束,人决定是否采纳。