跳到主要内容

第 1.9.5 节：组装 Pydantic 数据契约的作品集交付件

这一节把前面完成的材料收束成可展示、可复盘的交付件。完成本节后，你应该能够把 Pydantic 数据契约收束成作品集页面、验收证据和面试回答。

本节交付物与面试讲法​

和作品集项目关系​

本章可以直接变成作品集项目里的“工程可信度”部分。

它尤其适合连接这几个作品集：

放进作品集时，不要只写“使用 Pydantic（数据校验库）校验数据”。更好的表达是：

我为客服 Agent 设计了统一数据契约，把模型结构化输出、工具输入、API（应用程序接口）响应、前端状态、日志字段和验收用例对齐到同一套字段语义。校验失败时，系统会根据风险进入有限重试、追问、降级、转人工或拒绝工具执行，而不是让模型输出直接驱动业务动作。

这段话比“我会 Pydantic（数据校验库）”更像真实项目经验。

练习题​

基础练习​

解释“数据契约”和“普通类型提示”的区别。要求回答：

  • 数据契约为什么不只是字段类型？
  • 它如何影响模型输出、工具调用、前端展示和日志？
  • 为什么校验失败也要设计成业务分支？

项目练习​

不用写代码。为客服工作台的“意图识别结果”设计字段契约，至少包含：

  • schema_version（契约版本）
  • intent（意图）
  • risk_level（风险等级）
  • next_action（下一步动作）
  • missing_fields（缺失字段）
  • validation_status（校验状态）
  • validation_error（校验错误）
  • retry_allowed（是否允许重试）
  • fallback_action（兜底动作）
  • trace_id（追踪编号）

要求：每个字段都写清含义、来源、推荐取值和校验失败后的处理方式。

项目练习​

为“查订单状态工具”设计工具输入契约。要求覆盖：

  • tool_name（工具名称）应该如何限制。
  • tool_args（工具参数）里哪些字段来自用户，哪些字段必须来自登录态或系统。
  • 缺少订单编号时如何追问。
  • 订单不属于当前用户时如何拒绝。
  • 工具超时时如何回复用户，如何记录日志。

挑战任务​

设计一个“校验失败处理策略表”。要求至少覆盖：

  • 模型输出无法解析。
  • 字段缺失。
  • 枚举值漂移。
  • 工具名称不在白名单。
  • 工具参数越权。
  • 高风险动作缺少人工确认。
  • 工具系统超时。
  • 前端状态不识别。

每个场景都要写出：是否允许重试、兜底动作、用户看到什么、日志记录什么。

面试题和推荐回答​

1. Pydantic（数据校验库）在 AI Agent（人工智能体）项目里解决什么问题？​

推荐回答：它解决的是边界数据可信问题，不只是写类型。比如模型结构化输出、工具输入、API 响应、前端状态和日志字段都需要统一契约。Pydantic（数据校验库）可以帮助系统检查字段是否完整、枚举是否有效、工具参数是否合格。校验失败后，系统再决定重试、降级、转人工或拒绝执行。

2. 为什么不能到处传 dict（字典）？​

推荐回答：自由字典短期方便，长期会让字段含义漂移。模型输出、后端、前端、工具和日志可能各自理解同一个字段，出了问题很难定位。数据契约能把字段名、含义、取值范围、失败处理和版本统一起来。

3. 结构化输出已经有字段了，为什么还要校验？​

推荐回答：模型生成的结构化输出仍然可能缺字段、枚举值漂移、工具参数不完整，甚至生成不存在的工具名。结构化只是形式，校验才是进入业务流程前的安全闸门。

4. 模型输出校验失败怎么办？​

推荐回答：先看失败类型。格式轻微错误可以有限重试；用户信息缺失应该追问；越权或高风险动作不能重试绕过，应该拒绝执行或转人工。所有失败都要记录 trace_id（追踪编号）和 validation_error（校验错误）。

5. 为什么工具调用前还要校验 tool_args（工具参数）？​

推荐回答：因为工具连接真实业务系统。模型可能把用户话术直接当参数，也可能缺少订单编号或传入他人订单。工具执行前必须校验字段完整性、用户身份、业务对象归属和风险等级。

6. schema_version（契约版本）有什么用？​

推荐回答：AI（人工智能）项目的字段会演进，比如新增风险等级、改变下一步动作枚举或增加工具字段。记录契约版本可以知道一次请求使用的是哪套规则，方便兼容、回滚、测试和排查线上问题。

7. risk_level（风险等级）应该由模型决定吗？​

推荐回答：模型可以给出初步风险判断，但系统要有规则二次校验。比如投诉、资金、隐私、威胁曝光等场景，不能完全依赖模型判断。高风险动作必须经过权限、审批或人工确认。

8. 数据契约如何影响前后端协作？​

推荐回答：前端需要稳定状态来展示回答、追问、转人工、错误和工具结果。如果后端只返回一段文字，前端只能猜。契约把 next_action（下一步动作）、validation_status（校验状态）和 fallback_action（兜底动作）统一后，前端可以按状态渲染，而不是按文案判断。

9. 日志里为什么要记录 trace_id（追踪编号）？​

推荐回答：trace_id（追踪编号）可以把用户输入、模型输出、校验结果、工具调用、API 响应和前端展示串起来。没有它，线上问题只能靠猜，尤其是模型输出不稳定时很难复盘。

10. Pydantic（数据校验库）和 FastAPI（后端接口框架）是什么关系？​

推荐回答：FastAPI（后端接口框架）常用 Pydantic（数据校验库）表达请求响应模型。但在 AI Agent 项目里，Pydantic（数据校验库）的价值不止 API 层，还包括模型输出校验、工具输入校验、日志字段和验收样例。

11. 校验失败时为什么不能直接让模型自由修正？​

推荐回答：低风险格式问题可以让模型有限重试，但越权、缺用户信息、高风险动作缺确认这类问题不是模型重新生成就能解决的。让模型自由修正可能绕过权限和业务规则，所以必须按失败类型决定重试、追问、转人工或拒绝。

12. 你会如何把本章内容讲成项目亮点？​

推荐回答：我会说我在客服 Agent 项目里设计了统一数据契约，把模型结构化输出、工具输入、API 响应、前端状态、日志字段和验收用例对齐。所有模型结果先经过契约校验，工具调用前再校验参数、权限和风险。失败时系统会有限重试、追问、降级、转人工或拒绝执行，并用 trace_id（追踪编号）追踪全链路。

13. 面试官问“这不就是写几个模型类吗”，怎么回答？​

推荐回答：模型类只是实现方式。真正的工程价值是统一字段语义和失败路径。比如同一个 risk_level（风险等级）要影响模型输出、工具执行、前端提醒、日志审计和测试验收。如果只写类但没有这些治理，它仍然只是语法层面的封装。

14. 数据契约怎么帮助测试？​

推荐回答：测试可以直接围绕字段契约写样例，比如退款缺订单号时 missing_fields（缺失字段）必须包含订单编号，next_action（下一步动作）不能是直接调用退款工具；投诉威胁曝光时 risk_level（风险等级）必须是 high，兜底应转人工。这样测试验证的是业务边界，而不是只看接口成功。

本章交付物​

读完本章后，你应该能产出 4 类材料。

交付物 1：系统流程图​

使用本章的流程图，说明用户问题如何进入模型，模型输出如何被契约校验，工具调用如何再次校验，失败如何进入重试、降级、转人工或拒绝执行，最后如何记录 trace_id（追踪编号）。

交付物 2：字段契约表​

至少完成一张客服工作台核心字段契约表，覆盖：

  • schema_version（契约版本）
  • intent（意图）
  • risk_level（风险等级）
  • next_action（下一步动作）
  • missing_fields（缺失字段）
  • tool_name（工具名称）
  • tool_args（工具参数）
  • validation_status（校验状态）
  • validation_error（校验错误）
  • retry_allowed（是否允许重试）
  • fallback_action（兜底动作）
  • trace_id（追踪编号）

交付物 3：失败与兜底表​

至少覆盖：

  • 模型输出无法解析。
  • 字段缺失。
  • 枚举漂移。
  • 工具参数缺失。
  • 工具越权。
  • 高风险动作缺确认。
  • 工具超时。
  • 前端状态不识别。

每个失败场景都要写清是否允许重试、兜底动作、用户提示和日志字段。

交付物 4：面试讲法​

准备 1 分钟讲法：

我在客服 Agent 项目里没有把 Pydantic（数据校验库）当成单纯语法工具，而是把它作为数据契约治理层。模型结构化输出、工具输入、API 响应、前端状态、日志字段和验收用例都围绕同一套字段语义设计，包括意图、风险等级、下一步动作、缺失字段、工具参数、校验状态、兜底动作和追踪编号。模型输出不能直接驱动业务动作，必须先通过契约校验；工具执行前还要校验权限、参数和业务对象归属。校验失败时，系统会按风险进入有限重试、追问、降级、转人工或拒绝执行，并通过 trace_id（追踪编号）支持复盘。

小结​

Pydantic（数据校验库）在本书里的重点不是语法，而是把 AI Agent 系统里的边界数据变成可校验、可追踪、可验收的契约。

本章最重要的结论有 5 个：

  • 数据契约要统一模型输出、工具输入、API 响应、前端状态、日志字段和验收用例。
  • 字段设计要讲清含义、来源、取值、消费者和失败处理。
  • 模型结构化输出不是直接可信数据，必须经过校验。
  • 工具执行前必须再次校验参数、权限、风险和业务对象归属。
  • 校验失败不是简单报错，而是进入重试、追问、降级、转人工或拒绝执行。

下一步学习 FastAPI（后端接口框架）、测试、日志、RAG、MCP 和 LangGraph（智能体状态图框架）时，你会反复看到同一个原则：Agent 越接近真实业务，越需要稳定的数据契约。

继续学习​