Pydantic-AI：基于类型安全的智能体开发框架实战指南

1. 项目概述当Pydantic遇上AI一个全新的智能体开发范式如果你最近在关注AI应用开发特别是基于大语言模型LLM构建智能体Agent或工作流那么“pydantic-ai”这个项目绝对值得你花时间深入研究。简单来说它不是一个全新的AI模型而是一个构建在著名数据验证库Pydantic之上的开发框架。它的核心目标是让开发者能用一种极其优雅、类型安全且可预测的方式来编排和驱动AI模型如OpenAI的GPT、Anthropic的Claude等完成任务。想象一下你正在构建一个客服机器人。传统的做法可能是拼接一段提示词Prompt发给API然后祈祷返回的JSON结构是你想要的再写一堆if-else和try-except去解析、验证、处理可能千奇百怪的响应。这个过程充满了不确定性调试起来像在走钢丝。而pydantic-ai的思路是用Pydantic模型来定义你“期望”AI返回的结构让AI的响应从一开始就被约束在可控、可验证的轨道上。这不仅仅是“格式化输出”它从根本上改变了我们与AI协作的编程模型——从“请求-解析”的被动模式转变为“定义-执行”的声明式模式。这个项目由Pydantic团队官方维护这意味着它天生就继承了Pydantic在数据验证、序列化、设置管理方面的所有优秀基因。它适合任何希望将LLM集成到生产级应用中的开发者无论你是想快速构建一个原型还是需要一个健壮、可维护、易于测试的AI驱动模块。接下来我将带你深入拆解它的设计哲学、核心用法并分享我在实际项目中踩过的坑和总结出的最佳实践。2. 核心设计哲学类型即契约模型即指令要理解pydantic-ai必须先理解它的两个基石Pydantic和智能体Agent范式。2.1 为什么是PydanticPydantic的核心价值在于“运行时类型提示”。通过Python的类型注解你可以定义一个数据模型继承自BaseModel这个模型不仅是一个数据结构描述更是一个强大的验证器。任何输入数据无论是来自API、数据库还是用户输入只要塞进这个模型就会被自动、严格地按类型和规则进行校验无效数据会被立即拒绝并给出清晰的错误信息。在AI应用开发中我们面临的最大痛点之一就是LLM输出的“非结构化”。尽管你可以要求它“返回JSON”但模型可能会返回残缺的JSON、多一个逗号、少一个引号或者干脆用自然语言解释为什么不能返回JSON。传统的字符串解析和正则匹配在这种场景下脆弱不堪。pydantic-ai的巧妙之处在于它将Pydantic模型作为与AI沟通的“强类型接口”。你不再需要手动解析文本而是告诉AI“请根据这个Pydantic模型的结构来生成你的回答。” AI的响应会直接尝试反序列化到这个模型中利用Pydantic强大的校验能力成功则得到结构化的数据对象失败则能获得明确的校验错误便于进行重试或降级处理。2.2 智能体Agent范式的抽象pydantic-ai将一次AI交互抽象为一个“智能体”Agent。一个智能体由几个关键部分组成模型Model背后实际执行推理的LLM比如OpenAIChat。结果类型Result Type一个Pydantic模型定义了本次交互期望的输出结构。系统提示System Prompt指导AI行为的背景指令和角色设定。运行器Runner执行智能体、管理对话状态如消息历史的核心组件。这种抽象将杂乱的API调用、提示词工程、上下文管理和输出处理封装成了一个干净、可复用的对象。你可以像调用一个普通函数一样调用智能体并期待一个类型明确的返回结果。注意这里的“智能体”概念与能自主使用工具的AutoGPT式智能体略有不同。pydantic-ai的Agent更侧重于“单次或有限次对话中具有明确输出格式约束的AI功能单元”。它是构建更复杂智能体的理想基础模块。3. 从零开始你的第一个pydantic-ai智能体理论说得再多不如亲手跑一个例子来得实在。我们从一个最简单的场景开始让AI从一个产品描述中提取结构化信息。3.1 环境准备与安装首先确保你的Python环境在3.8以上。然后安装pydantic-ai及其可选依赖。我强烈建议在虚拟环境中进行。# 创建并激活虚拟环境以venv为例 python -m venv .venv source .venv/bin/activate # Linux/macOS # .venv\Scripts\activate # Windows # 安装pydantic-ai。基础包包含了核心框架。 pip install pydantic-ai # 根据你要使用的AI提供商安装对应的额外依赖。 # 例如使用OpenAI pip install pydantic-ai[openai] # 使用Anthropic Claude # pip install pydantic-ai[anthropic] # 使用Google Gemini # pip install pydantic-ai[google]安装完成后你需要设置API密钥。以OpenAI为例将你的密钥设置为环境变量export OPENAI_API_KEYsk-... # Linux/macOS # set OPENAI_API_KEYsk-... # Windows在代码中你也可以通过os.environ来设置但出于安全考虑更推荐使用.env文件或秘密管理工具。3.2 定义你的数据模型Result Type这是最关键的一步。你需要用Pydantic清晰地定义你希望从AI那里得到什么。假设我们正在构建一个电商产品信息提取器我们希望AI从一段自由文本描述中提取出产品名称、价格、主要特点和颜色。from pydantic import BaseModel, Field from typing import List, Optional class ProductInfo(BaseModel): 从文本中提取的产品信息 product_name: str Field(description产品的完整名称) price_usd: float Field(description产品价格以美元为单位, ge0) # ge0 表示价格必须大于等于0 key_features: List[str] Field(description产品的关键特性列表至少3项, min_items3) available_colors: Optional[List[str]] Field(defaultNone, description可选的颜色列表)看这个ProductInfo类不仅仅是一个数据结构。Field中的description会被pydantic-ai巧妙地用于构建给AI的指令告诉它每个字段代表什么。而ge0、min_items3这些验证规则会在AI返回结果后自动执行确保数据的有效性。3.3 创建并运行你的第一个智能体现在我们创建一个智能体它的任务就是接收一段文本并返回一个ProductInfo对象。from pydantic_ai import Agent from pydantic_ai.models.openai import OpenAIChat # 1. 创建智能体 # result_type 指定了我们期望的输出模型 # system_prompt 设定了AI的角色和任务 product_agent Agent( modelOpenAIChat(gpt-4o), # 使用GPT-4o模型 result_typeProductInfo, system_prompt你是一个专业的产品信息提取助手。请从用户提供的描述中准确提取结构化信息。如果某些信息不存在请合理推断或留空。, ) # 2. 运行智能体 async def main(): product_description 全新一代旗舰智能手机“银河Z30”拥有惊人的200W超级快充12分钟内即可充满5000mAh大电池。 搭载第三代骁龙处理器性能提升40%。后置三摄系统主摄2亿像素支持8K视频录制。 采用6.8英寸AMOLED曲面屏峰值亮度达3000尼特。提供“宇宙黑”、“星耀白”、“晨曦金”三种配色。 官方售价为999美元起。 # 使用 run 方法执行智能体传入用户消息即产品描述 result await product_agent.run(product_description) # result.data 就是成功验证后的 ProductInfo 对象 product result.data print(f产品名称: {product.product_name}) print(f价格: ${product.price_usd}) print(f核心特性: {, .join(product.key_features)}) print(f可选颜色: {product.available_colors}) # 你还可以访问原始响应、使用token数等信息 print(f\n本次调用消耗token数: {result.usage.total_tokens}) print(fAI回复的原始消息: {result.message_content()}) # 如果是脚本运行需要异步执行 import asyncio asyncio.run(main())运行这段代码你会看到类似以下的输出产品名称: 银河Z30 价格: $999.0 核心特性: 200W超级快充12分钟充满电, 第三代骁龙处理器性能提升40%, 后置2亿像素三摄系统支持8K录制, 6.8英寸AMOLED曲面屏3000尼特峰值亮度 可选颜色: [宇宙黑, 星耀白, 晨曦金]发生了什么pydantic-ai内部将你的ProductInfo模型定义、系统提示和用户输入产品描述组合成一段优化的提示词发送给GPT-4o。GPT-4o理解指令并试图生成一个符合ProductInfo结构的JSON对象。返回的文本被pydantic-ai捕获并尝试用Pydantic解析成ProductInfo实例。如果解析和验证成功你就能在result.data中得到一个类型安全、数据可靠的Python对象。如果失败比如AI返回了非JSON或价格是负数result.data会是None而错误信息会存在于result.error中。这个过程将原本需要数十行校验和错误处理的代码简化成了几行声明式的代码。这就是pydantic-ai生产力的体现。4. 核心功能深度解析超越基础用法掌握了基础用法我们来看看pydantic-ai那些真正提升开发体验和系统健壮性的高级特性。4.1 依赖注入Deps为智能体提供上下文智能体很少在真空中运行。它们通常需要访问外部信息比如数据库连接、用户会话、配置参数等。pydantic-ai通过“依赖注入”Deps机制优雅地解决了这个问题。假设我们的产品提取器需要根据用户所在地区调整货币单位并且需要记录操作日志。from pydantic_ai import Agent, Dep from pydantic_ai.models.openai import OpenAIChat from pydantic import BaseModel import logging from typing import Annotated # 定义一个依赖类也可以是简单函数 class AppContext: def __init__(self, user_region: str, logger: logging.Logger): self.user_region user_region self.logger logger def get_currency(self) - str: currency_map {US: USD, EU: EUR, CN: CNY} return currency_map.get(self.user_region, USD) def log_extraction(self, product_name: str): self.logger.info(f为用户 {self.user_region} 提取了产品 {product_name}) # 定义结果模型现在价格字段的描述可以动态化 class ProductInfoWithContext(BaseModel): product_name: str price: float currency: str # 新增货币字段 key_features: list[str] # 创建智能体并声明依赖 # 使用 Annotated 和 Dep 来标记参数是一个依赖 product_agent_ctx Agent( modelOpenAIChat(gpt-4o), result_typeProductInfoWithContext, system_prompt提取产品信息。价格请以{currency}为单位。, deps_typeAppContext, # 声明智能体依赖的上下文类型 ) async def main_with_deps(): # 模拟应用上下文 logger logging.getLogger(__name__) ctx AppContext(user_regionEU, loggerlogger) product_description 某品牌耳机售价249欧元支持主动降噪和30小时续航。 # 运行智能体时传入依赖对象 # 注意run方法的第一个参数是用户消息之后可以跟任意数量的依赖实例 result await product_agent_ctx.run( product_description, ctx, # 传入依赖 ) if result.data: product result.data print(f产品: {product.product_name}) print(f价格: {product.price} {product.currency}) # 将显示 EUR # 使用上下文记录日志 ctx.log_extraction(product.product_name) # 依赖也可以是函数pydantic-ai会自动解析和调用。 def get_current_user() - str: 从请求上下文中获取当前用户ID # 模拟实现 return user_123 user_agent Agent( modelOpenAIChat(gpt-4o), result_typeSomeResult, deps_type(AppContext, get_current_user), # 可以声明多个依赖 ) # 运行时需要按顺序传入所有依赖实例 # result await user_agent.run(message, ctx, user_123)依赖注入使得智能体与业务逻辑解耦易于测试你可以传入模拟的上下文并且能安全地访问共享资源。4.2 消息历史Message History与多轮对话默认情况下agent.run()是单次调用。但很多场景需要多轮对话。pydantic-ai通过AgentRun对象来管理对话状态。from pydantic_ai import Agent from pydantic_ai.models.openai import OpenAIChat class ConversationState(BaseModel): topic: str user_mood: str neutral chat_agent Agent( modelOpenAIChat(gpt-4o), result_typeConversationState, system_prompt你是一个友好的聊天助手请识别对话主题和用户情绪。, ) async def multi_turn_chat(): # 第一次运行创建对话 first_result await chat_agent.run(我今天刚看完《星际穿越》太震撼了) print(f第一轮识别: 主题-{first_result.data.topic}, 情绪-{first_result.data.user_mood}) # first_result 是一个 AgentRun 对象它包含了到当前为止的所有消息历史 # 我们可以基于它进行第二轮对话 second_result await first_result.run(是的特别是那个五维空间的设定。你觉得时间能倒流吗) print(f第二轮识别: 主题-{second_result.data.topic}, 情绪-{second_result.data.user_mood}) # 你可以随时访问完整的消息历史 for msg in second_result.all_messages(): print(f{msg.role}: {msg.content})AgentRun对象保存了上下文使得后续的run调用能继承之前的对话历史实现连贯的多轮交互。这对于构建聊天机器人、需要记忆的助手至关重要。4.3 工具调用Tool Calling与函数执行这是pydantic-ai最强大的功能之一。你可以让AI模型调用你预先定义好的Python函数工具从而突破纯文本的局限执行实际动作如查询数据库、调用API、进行计算等。from pydantic_ai import Agent, Tool from pydantic_ai.models.openai import OpenAIChat from pydantic import BaseModel import httpx import asyncio # 1. 定义一个工具函数并用 Tool 装饰器装饰 Tool async def get_weather(city: str) - str: 获取指定城市的当前天气情况。 # 这里模拟一个API调用 async with httpx.AsyncClient() as client: # 假设我们有一个天气API # resp await client.get(fhttps://api.weather.com/{city}) # return resp.json()[description] await asyncio.sleep(0.5) # 模拟网络延迟 weather_map {北京: 晴朗25°C, 上海: 多云22°C, 伦敦: 小雨15°C} return weather_map.get(city, 未知城市) Tool def calculate_discount(original_price: float, discount_percent: float) - float: 计算打折后的价格。 if discount_percent 0 or discount_percent 100: raise ValueError(折扣比例必须在0-100之间) return original_price * (1 - discount_percent / 100) # 2. 定义结果模型对于工具调用结果模型可以是任何结构甚至是None # 这里我们定义一个简单的确认模型 class ToolResult(BaseModel): confirmation: str details: str # 3. 创建智能体并传入工具列表 tool_agent Agent( modelOpenAIChat(gpt-4o), result_typeToolResult, system_prompt你可以使用工具来帮助用户。请根据用户问题决定是否需要以及调用哪个工具。, tools[get_weather, calculate_discount], # 注册工具 ) async def use_tools(): # 用户询问一个需要工具调用的问题 result await tool_agent.run(请问北京现在的天气怎么样然后再帮我算一下原价200美元的商品打8折后是多少钱) if result.data: print(fAI确认: {result.data.confirmation}) print(f详情: {result.data.details}) # 更重要的是我们可以查看工具调用的历史 for call in result.tool_calls(): print(f\n工具调用记录:) print(f 工具名: {call.tool_name}) print(f 参数: {call.arguments}) print(f 结果: {call.result_data}) asyncio.run(use_tools())在这个例子中AI会分析用户的问题识别出需要调用get_weather和calculate_discount两个工具。pydantic-ai框架会自动处理工具调用的编排将函数签名和描述提供给AI接收AI的工具调用请求执行对应的Python函数并将结果返回给AI让AI生成最终的回答给用户。实操心得工具描述Tool装饰器下的文档字符串至关重要。AI主要依靠它来决定是否以及如何调用工具。描述应清晰、简洁准确说明函数的用途、参数含义和返回值。好的描述能极大提升工具调用的准确率。4.4 流式响应Streaming对于需要长时间生成内容或希望提供实时反馈的应用流式响应是必备功能。pydantic-ai原生支持流式输出。from pydantic_ai import Agent from pydantic_ai.models.openai import OpenAIChat import asyncio stream_agent Agent( modelOpenAIChat(gpt-4o), result_typestr, # 流式输出通常直接是文本 system_prompt你是一个讲故事的人。, ) async def stream_response(): print(故事开始了: , end, flushTrue) # 使用 run_stream 方法 async for chunk in stream_agent.run_stream(讲一个关于机器人和小猫的短故事。): # chunk 可能包含文本增量、工具调用请求等 if chunk.is_text: print(chunk.text_delta, end, flushTrue) # 逐词打印 elif chunk.is_tool_call: print(f\n[AI正在请求调用工具: {chunk.tool_name}]) print(\n--- 故事结束 ---) asyncio.run(stream_response())流式处理不仅提升了用户体验还能在生成过程中提前处理部分内容如检测到特定关键词时中断为构建交互式应用提供了可能。5. 实战构建一个需求分析智能体让我们综合运用以上知识构建一个稍复杂的实战项目一个软件需求分析智能体。它的目标是接收用户模糊的需求描述如“我想要一个能管理个人财务的网站”输出结构化的需求规格包括功能列表、技术栈建议和复杂度评估。5.1 定义复杂的结果模型首先我们需要一个能承载丰富信息的Pydantic模型。from pydantic import BaseModel, Field from typing import List, Literal from enum import Enum class Complexity(str, Enum): SIMPLE simple MEDIUM medium COMPLEX complex class Feature(BaseModel): name: str Field(description功能点名称) description: str Field(description功能的详细描述) priority: Literal[P0, P1, P2] Field(description优先级P0最高) estimated_story_points: int Field(description预估的故事点数1-13, ge1, le13) class TechStackSuggestion(BaseModel): frontend: List[str] Field(description推荐的前端技术栈) backend: List[str] Field(description推荐的后端技术栈) database: List[str] Field(description推荐的数据库) class RequirementAnalysis(BaseModel): 需求分析结果 project_title: str Field(description项目标题) summary: str Field(description需求摘要) core_problem: str Field(description待解决的核心问题) features: List[Feature] Field(description分解出的功能列表, min_items3) tech_stack: TechStackSuggestion Field(description技术栈建议) overall_complexity: Complexity Field(description整体复杂度评估) potential_risks: List[str] Field(description潜在风险点)这个模型定义了嵌套结构Feature列表TechStackSuggestion对象和枚举类型Complexity。pydantic-ai能够很好地处理这种复杂结构。5.2 创建具备工具和依赖的智能体我们将为这个智能体添加两个工具一个用于估算开发时间模拟一个用于检查技术栈的流行度模拟。同时我们注入一个“分析师角色”的依赖。from pydantic_ai import Agent, Tool, Dep from pydantic_ai.models.openai import OpenAIChat from typing import Annotated # --- 工具定义 --- Tool def estimate_development_weeks(story_points: int, team_size: int 3) - float: 根据故事点数和团队规模估算所需周数。 假设一个标准开发者一周能完成3个故事点。 velocity team_size * 3 # 团队每周速度 if velocity 0: return 0.0 return round(story_points / velocity, 1) Tool async def check_tech_trend(technology: str) - str: 检查某项技术的当前流行趋势模拟。 # 这里可以集成真实的数据源如Stack Overflow趋势、GitHub Star数等 trend_data { React: 非常流行社区活跃生态丰富, Vue.js: 流行易于上手国内生态好, Svelte: 新兴性能优秀增长快, Django: 稳健全功能适合快速开发, FastAPI: 现代高性能异步支持好, PostgreSQL: 功能强大的开源关系型数据库首选, MongoDB: 文档数据库适合非结构化数据, } await asyncio.sleep(0.1) # 模拟异步调用 return trend_data.get(technology, 趋势未知) # --- 依赖定义 --- class AnalystProfile: def __init__(self, experience_years: int, domain: str): self.experience_years experience_years self.domain domain # 分析师专长领域如 web, mobile, ai def get_analysis_style(self) - str: if self.experience_years 10: return 资深注重可扩展性和长期维护 elif self.experience_years 5: return 熟练注重平衡和最佳实践 else: return 新颖注重创新和新技术 # --- 创建智能体 --- req_agent Agent( modelOpenAIChat(gpt-4o), result_typeRequirementAnalysis, system_prompt 你是一名资深的软件需求分析师。请根据用户模糊的需求描述进行深入分析输出结构化的需求规格。 你的分析应包含清晰的项目定义、核心问题提炼、分解的功能点带优先级和故事点估算、合理的技术栈建议、复杂度评估以及潜在风险。 在分析技术栈和估算时间时请善用提供的工具。 你的输出必须严格符合给定的JSON格式。 , tools[estimate_development_weeks, check_tech_trend], deps_typeAnalystProfile, ) # --- 运行智能体 --- async def analyze_requirement(): # 模拟一个资深Web分析师 analyst AnalystProfile(experience_years8, domainweb) user_request 我们想做一个面向自由职业者的项目管理和协作平台。核心是要能管理项目、任务、时间跟踪支持团队聊天和文件共享。 预算有限希望快速上线验证市场。 print(正在分析需求...) result await req_agent.run(user_request, analyst) if result.data: analysis result.data print(f\n 需求分析报告 ) print(f项目: {analysis.project_title}) print(f核心问题: {analysis.core_problem}) print(f\n--- 主要功能 ---) for idx, feat in enumerate(analysis.features, 1): print(f {idx}. [{feat.priority}] {feat.name} - {feat.description} ({feat.estimated_story_points}点)) print(f\n--- 技术栈建议 ---) print(f 前端: {, .join(analysis.tech_stack.frontend)}) print(f 后端: {, .join(analysis.tech_stack.backend)}) print(f 数据库: {, .join(analysis.tech_stack.database)}) print(f\n整体复杂度: {analysis.overall_complexity.value}) print(f潜在风险: {; .join(analysis.potential_risks)}) # 查看工具调用情况 print(f\n--- 工具调用日志 ---) for call in result.tool_calls(): print(f 工具 {call.tool_name} 被调用参数: {call.arguments} 结果: {call.result_data}) else: print(f分析失败: {result.error}) asyncio.run(analyze_requirement())这个例子展示了pydantic-ai如何将复杂的AI交互封装成一个清晰、可维护的模块。分析师依赖影响了系统提示的生成虽然这里没直接展示但你可以将analyst.get_analysis_style()动态插入到提示词中工具函数被AI在推理过程中按需调用最终产出一个高度结构化、可直接用于下游开发流程如导入Jira、生成技术方案的数据对象。6. 部署、测试与性能优化将pydantic-ai智能体集成到生产环境还需要考虑部署、测试和性能。6.1 错误处理与重试机制LLM API调用可能因网络、速率限制、内容过滤等失败。pydantic-ai智能体的run方法可能抛出异常或返回包含错误的result。from pydantic_ai import Agent, RunError import backoff import openai backoff.on_exception(backoff.expo, (openai.APITimeoutError, openai.APIConnectionError), max_tries3) async def robust_agent_run(agent, message, depsNone): 一个带有重试和错误处理的智能体运行包装函数 try: result await agent.run(message, deps) if deps else await agent.run(message) if result.error: # 处理智能体级别的错误如输出格式不符合模型 print(f智能体逻辑错误: {result.error}) # 可以根据错误类型进行重试例如修改提示词后重新运行 return None return result.data except (openai.APITimeoutError, openai.APIConnectionError) as e: print(fAPI网络错误: {e}) raise # 让backoff装饰器处理重试 except openai.RateLimitError as e: print(f速率限制: {e}) # 等待一段时间后重试 await asyncio.sleep(60) return await robust_agent_run(agent, message, deps) except Exception as e: print(f未知错误: {e}) return None对于输出格式错误result.error一种高级策略是实现“链式修复”当Pydantic验证失败时捕获错误信息将其作为新的上下文反馈给AI要求它纠正输出。6.2 测试策略测试AI应用颇具挑战因为输出具有不确定性。pydantic-ai的类型安全特性让单元测试成为可能。模拟Mock模型层你可以创建一个模拟的模型类返回预定义的响应从而在不调用真实API的情况下测试智能体的逻辑流、工具调用和依赖处理。from pydantic_ai import Agent from pydantic_ai.models.mock import MockModel from pydantic import BaseModel class MockResponse(BaseModel): answer: str # 创建一个总是返回固定内容的Mock模型 mock_model MockModel( result_typeMockResponse, mock_resultMockResponse(answer这是一个模拟回答。), # 也可以模拟工具调用 # mock_tool_calls[...] ) test_agent Agent(modelmock_model, result_typeMockResponse) # 现在运行 test_agent.run() 不会产生网络调用适合CI/CD快照测试Snapshot Testing对于给定的固定输入将AI的输出或关键字段保存为“快照”。在后续测试中比较新输出与快照的差异。这有助于检测AI行为是否发生意外漂移。pydantic-ai的结构化输出使这种比较变得容易。集成测试在预发布环境中使用真实模型但限定的测试用例集进行端到端测试重点关注功能的正确性而非输出的逐字匹配。6.3 性能优化与成本控制模型选择不是所有任务都需要GPT-4。对于简单的提取、分类任务gpt-3.5-turbo可能就足够了成本更低速度更快。pydantic-ai允许你轻松切换模型。提示词优化清晰、简洁的提示词能减少不必要的tokens消耗并提高输出质量。充分利用Pydantic字段的description来指导AI。缓存对于相同输入可能产生相同输出的场景如解析固定格式的文档可以考虑在应用层添加缓存如functools.lru_cache或Redis避免重复调用API。批量处理如果需要处理大量独立项目可以考虑异步并发运行多个智能体实例但要注意API的并发限制。import asyncio async def batch_process(items: list, agent): tasks [agent.run(item) for item in items] results await asyncio.gather(*tasks, return_exceptionsTrue) # 处理结果和异常7. 常见问题与排查技巧实录在实际使用中你肯定会遇到各种问题。以下是我总结的一些典型场景和解决方法。7.1 AI不按模型格式输出问题result.data为Noneresult.error显示Pydantic验证错误。原因提示词不够清晰或者任务对AI来说太复杂。解决强化系统提示在系统提示中明确强调“你必须返回一个有效的JSON对象严格符合以下结构...”。简化模型如果模型嵌套太深或字段太多AI可能难以理解。尝试先输出一个更简单的结构或者分步进行先用一个智能体提取大类再用另一个智能体解析细节。提供示例Few-Shot在系统提示或用户消息中给出一两个输入输出的具体例子。pydantic-ai支持在消息历史中插入示例。7.2 工具调用不准确或不被触发问题AI应该调用工具但没有调用或者用错了参数。原因工具函数描述不清晰或者AI对问题理解有偏差。解决优化工具描述确保Tool下的文档字符串精确描述功能、参数类型和含义和返回值。可以像写API文档一样写它。在系统提示中引导明确告诉AI“你可以使用以下工具来帮助你...”并简要说明每个工具的适用场景。检查参数类型确保工具函数的参数类型是简单的Python类型str,int,float,bool,list,dict等或对应的Pydantic模型。过于复杂的类型可能导致AI无法正确生成参数。7.3 处理长上下文和令牌限制问题对话历史很长导致超出模型的上下文窗口。解决摘要历史定期对过往对话进行摘要然后用摘要替换掉详细的历史消息。你可以设计另一个智能体专门负责生成摘要。选择性记忆只保留与当前任务最相关的历史消息丢弃过时或无关的。使用支持长上下文的模型如gpt-4-turbo或Claude 3系列。7.4 控制输出中的“废话”问题AI在返回JSON前后添加了额外的解释性文字导致解析失败。解决这是提示词工程问题。在系统提示中强烈要求“只返回JSON不要有任何额外的解释、前缀或后缀”。某些模型如OpenAI有response_format参数可以强制JSON输出。pydantic-ai的OpenAIChat模型包装器通常会自动设置这个参数但如果你遇到问题可以检查模型配置。7.5 调试与日志当智能体行为不符合预期时详细的日志是救命稻草。import logging # 设置pydantic-ai的日志级别为DEBUG logging.basicConfig(levellogging.DEBUG) # 或者只针对pydantic-ai库 logging.getLogger(pydantic_ai).setLevel(logging.DEBUG)这将打印出模型请求和响应的详细信息包括发送的提示词和接收到的原始响应对于调试提示词和解析问题非常有帮助。pydantic-ai将我们从与LLM API交互的繁琐细节中解放出来让我们能更专注于定义“做什么”而非“怎么做”。它通过类型安全、依赖注入和工具调用等模式为构建可靠、可维护的AI驱动应用提供了坚实的工程基础。从我个人的使用经验来看它特别适合需要将AI能力嵌入到现有工作流或产品中的场景比如数据提取、内容分类、智能审核、代码生成辅助等。虽然它有一定的学习曲线但一旦掌握开发效率的提升是巨大的。