Pydantic AI 进阶实战:RunContext 依赖注入、输出校验自动重试与多模型切换

怎么把数据库连接安全传进智能体工具、模型编出假单号怎么让它自动重改?本文详解 Pydantic AI 的 RunContext 强类型依赖注入、output_validator 配合 ModelRetry 自愈闭环,以及 ModelFallback 容灾代码。

NNathaniel bigo··原创首发·AI 辅助撰写
8 分钟读完
资料核对于 2026-11-19 · 依据官方文档与公开资料整理 其他 账号

在读完 Pydantic AI 快速入门与基础 output_type 用法 之后,把智能体真正接进企业 FastAPI 后端立刻会碰到三个实战深水区问题:

  1. 工具函数里要查 PostgreSQL 连接池和当前登录用户的 tenant_id,难道要靠丑陋且线程不安全的全局变量往里塞吗?
  2. 模型虽然输出了合法的 JSON 字符串 {"order_id": "ORD-9999"},但去库里一查根本没这个单号,怎么把报错原因精准踢回给大模型让它自己重查,而不是直接抛 500 崩给前端?
  3. 主力云端模型突遇高峰期 429 限流时,怎么零改动业务代码平滑切到备用厂商?

把 RunContext[Deps]、ModelRetry 与 ModelFallback 三剑客组合起来,就能写出类型检查器百分百放心的生产级 Python 智能体。

AI 全栈开发订阅配套入口:在本地部署与联调开源 AI 框架时,搭配固定月费的终端编程智能体与旗舰推理订阅能大幅缩短排错时间。国内无境外信用卡可在本站通过支付宝、微信支付或 AlipayHK 免密自助开通 Claude Code 订阅、ChatGPT Plus / Pro 或查看 AI 会员充值总览。

Pydantic AI 依赖注入与校验自愈四步

一、看清两种恢复机制的职责边界:ModelRetry 与 ModelFallback

很多刚进阶的开发者容易把“校验不通过让模型重改”和“接口挂了换备用模型”混为一谈。在 Pydantic AI 架构里,这两件事由完全不同的组件分工负责:

Pydantic AI 两种错误恢复机制分工

二、完整生产级代码:依赖注入 + 数据库深校验自愈 + 备用模型容灾

装好核心包(pip install pydantic-ai),下面这段结构紧凑的代码展示了如何像写 FastAPI Depends 一样,把异步数据库连接与当前用户身份强类型注入给动态指令、工具函数与输出校验器:

python
import asyncio
from dataclasses import dataclass
from pydantic import BaseModel, Field
from pydantic_ai import Agent, ModelRetry, RunContext
from pydantic_ai.capabilities import ModelFallback

# 1. 定义运行时依赖容器:测试时可轻松替换为内存替身对象,无需连真实数据库
@dataclass
class SupportDeps:
    current_user_id: str
    valid_orders: dict[str, str]  # 生产中替换为异步数据库连接池如 AsyncSession

# 2. 定义强类型最终输出结构
class RefundDecision(BaseModel):
    order_id: str = Field(description="核实存在且归属当前用户的订单号")
    approved: bool
    reason_cn: str = Field(description="给用户的简明中文处理说明")

# 3. 初始化智能体:绑定依赖类型、重试预算及跨厂商热备模型
refund_agent = Agent(
    "anthropic:claude-sonnet-4-5",
    deps_type=SupportDeps,
    output_type=RefundDecision,
    retries=2,  # 允许工具或输出校验触发最多 2 次回炉修正
    capabilities=[ModelFallback("openai:gpt-4o")],
)

# 4. 动态系统指令:通过 ctx.deps 安全读取当前请求上下文
@refund_agent.instructions
def dynamic_user_context(ctx: RunContext[SupportDeps]) -> str:
    return f"当前发起售后的登录用户 ID 为 {ctx.deps.current_user_id},严禁处理他人名下订单。"

# 5. 工具函数:首参声明 RunContext[SupportDeps],IDE 自动补全所有依赖属性
@refund_agent.tool
async def list_my_orders(ctx: RunContext[SupportDeps]) -> dict[str, str]:
    """查询当前用户名下所有真实历史订单号及状态。"""
    return ctx.deps.valid_orders

# 6. 业务级深层输出校验器:拦截“格式合法但业务查无此单”的幻觉输出
@refund_agent.output_validator
async def verify_order_exists(
    ctx: RunContext[SupportDeps], decision: RefundDecision
) -> RefundDecision:
    if decision.order_id not in ctx.deps.valid_orders:
        raise ModelRetry(
            f"订单号 '{decision.order_id}' 在当前用户名下不存在。"
            "请先调用 list_my_orders 工具核实真实单号后再重新输出结构化结果。"
        )
    return decision

async def main():
    deps = SupportDeps(
        current_user_id="U-801",
        valid_orders={"ORD-202611": "已签收三天"},
    )
    # 故意输入一个用户记错的模糊单号,触发校验拦截 -> 自动调工具核实 -> 自愈通过
    res = await refund_agent.run("帮我给尾号 2611 的那个订单申请退货", deps=deps)
    print(res.output)

if __name__ == "__main__":
    asyncio.run(main())
研发团队订阅与高配额省心方案:调试复杂多步智能体循环、RAG 切片策略与 CI 评测流水线非常消耗单日 Token。个人主力开发推荐免上号兑换 Claude Pro iOS 自助卡密 或 5 倍额度的 Claude Max 5x,多人研发团队协同亦可联系客服定制 ChatGPT Business 团队版。

三、这套设计给工程团队带来的三个真金白银收益

相比在普通工作流框架(例如对比 LlamaIndex Workflows 或 LangGraph 状态图)里手写一堆 try/except JSONDecodeError 循环,上面这段代码把最脏的胶水逻辑全部收归框架底层:

  1. 静态类型检查直接抓低级拼写 Bug:你在 Agent(..., deps_type=SupportDeps) 里声明了依赖类型,如果在工具里不小心手滑把 ctx.deps.current_user_id 敲成了 ctx.deps.user_id,不用等上线跑代码,编辑器里的 Pyright 或 Mypy 当场就会标红报错。
  2. 单元测试一秒跑完零外部耦合:写 pytest 单元测试时,根本不需要拉起 Docker 数据库容器,只需构造一个塞了假字典的 SupportDeps 实例传进 agent.run(..., deps=fake_deps),连模型本身都可以用内置的 TestModel 替身秒级跑通全链路校验逻辑。
  3. ModelRetry 把报错文案变成最精准的二次提示词:注意看第 47 行抛出的 ModelRetry 异常文本——务必用清晰直白的语言写明“哪里错了 + 下一步该调哪个工具纠正”,并通过 ctx.retry 观察当前是第几次重试,通常 retries=2 就能救回九成以上的字段疏漏。

日常编写 Python 类型安全后端与多模型容灾架构时,搭配高配额的官方编程订阅与推理账号能大幅提升联调效率。需要开通海外正规开发订阅的工程师,可前往查看贝果研究社 Claude Code 订阅与配置方案或全站 AI 订阅自助导航。

常见问题

在工具函数内部(@agent.tool)如果发现大模型传进来的查询参数不合法,也能抛 ModelRetry 吗?

完全可以,而且非常推荐这样做。比如大模型传了一个格式错误的日期字符串 "昨天" 给要求 YYYY-MM-DD 的统计工具,千万不要直接抛普通的 ValueError 让整个请求崩溃退出,而是直接 raise ModelRetry("日期参数必须为 YYYY-MM-DD 格式,请修正后重调本工具"),大模型看到反馈后下一秒就会自己改好参数重调一次。

运行时想临时给 VIP 用户升级成更强的模型,需要重新实例化一个新的 Agent 吗?

不需要。Agent 实例在设计上是无状态、全局可安全复用的单例(就像 FastAPI 的 APIRouter)。遇到高价值请求需要临时切换模型时,只需在单次执行时传入覆盖参数 await refund_agent.run(prompt, deps=deps, model="anthropic:claude-opus-4-6"),仅对当次请求生效且绝不污染其他并发用户。

如果连续触发了 2 次 ModelRetry 模型依然改不对,后端该怎么捕获降级?

当重试次数耗尽(超过 retries=2 设定的预算)仍未通过输出校验时,Pydantic AI 会抛出明确的 UnexpectedModelBehavior 异常。生产接口中建议在 agent.run() 外层捕获该异常,记录下 capture_run_messages() 里的完整工具交互轨迹用于事后排查提示词漏洞,同时向前端返回一个温和的人工兜底状态(例如将工单转入待人工客服复核队列),保证核心业务链路永不白屏报错。

搭好开源框架后,国内没有外币信用卡怎么开通主力编程与大模型订阅?

可在 本站 AI 会员充值中心 使用支付宝、微信支付或 AlipayHK 自助选购卡密,支持免交密码兑换 Claude Code(Pro / Max)、ChatGPT Plus 与 ChatGPT Pro,并支持开具增值税发票;实时价格与售后边界(封号不在质保范围)以对应商品页说明为准。

小结

  1. 通过 @dataclass 搭配 deps_type 与 RunContext[Deps],实现零全局变量、完美支持静态类型检查与单测替身的依赖注入。
  2. 用 @agent.output_validator 配合 raise ModelRetry("具体纠错指引"),把数据库查无此单等业务幻觉拦截在闭环内部自动重修。
  3. 将 Agent 定义为无状态模块级单例,配合 ModelFallback 挂载跨厂商备用官方模型,轻松扛住单点接口限流抖动。

Nathaniel 的更多内容

  1. 01

    独立开发者用 ChatGPT + Codex 跑通产品全流程:市场验证、PRD、原型到代码上线复盘清单

    单人做独立产品最容易陷入「闭门写两个月代码上线零用户」或「AI 写到一半目录越改越崩」。本文整理「ChatGPT 负责市场验证、PRD 与复盘 + Codex 负责工程实现与测试」的五阶段双轨流程,附起手提示词与 7 项上线复盘清单。

    ChatGPTCodex0
  2. 02

    用 ChatGPT 批量生成规范文件命名规则、整理混乱目录树与合并零散发票抬头清单脚本

    面对满桌面的「新建文件夹」「最终版2」和上百张零散电子发票,手工改名抄台账耗时又容易漏重。本文分享先脱敏取样、再用 ChatGPT 生成带预演和回滚日志的本地 Python 脚本,离线安全完成目录整理与发票抬头合并去重的实战流程。

    ChatGPT0
  3. 03

    用 ChatGPT 做海外邮件营销(EDM)受众分层文案、A/B 主题行测试与防进垃圾箱自检

    做海外独立站或出海 SaaS 邮件营销(EDM),最怕千人一面群发被直接送进垃圾箱。本文结合 Gmail/Yahoo 批量发件人规范,梳理用 ChatGPT 设计受众分层文案、批量生成 A/B 主题行矩阵并开展发前垃圾词与合规自检的实战提示词。

    ChatGPT0
  4. 04

    用 ChatGPT 写 Notion Formula 2.0 公式、Obsidian Dataview 查询与 Airtable 自动化脚本

    给 Notion 数据库写多条件 Formula 2.0 公式、给 Obsidian 写 Dataview 动态看板,或在 Airtable 里写自动化脚本,经常因为一个小括号或类型不匹配报错半天。本文整理三大工具的通用上下文喂料规范与三套直接可复制的生成提示词。

    ChatGPT其他 AI 工具0
  5. 05

    用 ChatGPT 处理复杂 JSON / YAML / XML 字段映射、格式转换与校验规则编写实战

    对接第三方 API、迁移 Kubernetes 配置或解析政企 XML 报文时,手工对照几百行嵌套字段既慢又容易漏掉空值与类型边界。本文整理用 ChatGPT 完成字段映射表梳理、生成确定性转换脚本以及编写 JSON Schema / Pydantic / XSD 校验规则的实战流。

    ChatGPT其他 AI 工具0
  6. 06

    用 ChatGPT 准备本科/硕士毕业论文答辩:提炼答辩 PPT 结构、模拟导师犀利追问与 3 分钟自述稿

    毕业论文写完后,要在 3–5 分钟内讲清研究价值并顶住答辩评委的连环追问并不轻松。本文整理在严格遵守高校学术规范的前提下,用 ChatGPT 提炼答辩 PPT 结构、打磨 3 分钟口语自述稿并开展模拟导师犀利追问的排练流程与提示词。

    ChatGPT0

同产品的其他教程

  1. 01

    用 ChatGPT 速读英文产品手册、开源文档与 GitHub Issue 并沉淀团队中文内训手册

    团队引入海外 SaaS 工具或开源框架时,全英文文档晦涩冗长、真正的坑全藏在几十页 GitHub Issue 讨论里。本文分享速读拆解英文手册、归类 Issue 排障库以及重构团队中文内训 SOP 的完整实战流程。

    ChatGPT其他 AI 工具0
  2. 02

    用 ChatGPT 写油猴脚本(Tampermonkey)与浏览器书签小工具解决网页繁琐重复操作实战

    每天在后台系统里重复勾选几十个复选框、手工复制网页表格或清理遮挡阅读的侧边栏,既枯燥又浪费时间。本文分享不会写 JS 也能用 F12 配合 ChatGPT 写出油猴脚本与书签小工具的完整实战流程。

    ChatGPT其他 AI 工具0
  3. 03

    用 ChatGPT 写高质量 SQL 窗口函数(RANK / LAG / SUM OVER)做留存与漏斗分析实战

    做用户留存率、复购间隔与有序转化漏斗时,多层自连接既难读又拖垮数据库,窗口函数则是高效解法。本文整理数据库方言喂数规范、CTE 分层提示词以及用内置沙盒先验证再上线的完整实战流程。

    ChatGPT其他 AI 工具0
  4. 04

    ChatGPT 连接 Canva、Figma、Linear、Jira、Dropbox 等第三方应用搜不到数据或授权失效怎么办

    在 ChatGPT 接入 Canva、Figma、Linear、Jira 或 Dropbox 后,明明显示已连接却搜不到文件工单,或老提示授权失效怎么办?本文拆解账号错绑、OAuth 范围漏选、权限继承与管理员拦截 5 步排障法。

    ChatGPT其他 AI 工具0
  5. 05

    Anthropic Contextual Retrieval(上下文增强检索)是什么、怎么实现:给文档块自动补背景摘要结合缓存降失误率

    长文档切成小块后丢了公司名、年份和主语指代导致 RAG 频频搜错?本文按 Anthropic 官方技术文章详解 Contextual Retrieval 原理、官方公开评测失误率下降 49% 至 67% 的组合架构,以及用 Claude 提示词缓存低成本批量生成切片背景的完整 Python 代码。

    Claude其他 AI 工具0
  6. 06

    RAG 知识库回答不准怎么调优:切片大小(Chunking)、BM25 + 向量混合检索与 Rerank 重排序三步排查法

    搭好的 RAG 企业知识库一问具体型号、报错码或跨行表格就答非所问?本文按 OpenAI 与 Anthropic 官方检索文档,给出先隔离检索与生成故障、再按结构化切片(Chunking)、BM25 加向量混合召回(RRF)与 Rerank 重排序逐层调优的三步法。

    Claude其他 AI 工具0

0 条评论

登录 后参与评论

还没有评论,来抢沙发~