Pydantic

Pydantic

一、介绍

  • 核心思想:用类型注解(type hints)来同时做”静态提示 + 运行时验证 + 数据转换 + 序列化“;

    • 数据验证:验证用户传递给函数的参数是否合法,如果不合法就会输出静态提示;

    • 序列化:将用户输入的普通字符串转换为规范的JSON数据。

二、参数模型

  • 定义模型:使用 Pydantic 定义一个模型非常简单,只需创建一个继承自 pydantic.BaseModel 的类,并在其中定义字段;

    from pydantic import BaseModel, Field, field_validator
    
    class OrderQuerySchema(BaseModel):
        """查询订单所需的参数"""
        order_id: str = Field(
            ..., 
            description="标准的订单号,必须以 'ORD-' 开头,例如 ORD-1001"
        )
    
  • 使用 Pydantic 模型:通过类型注解使参数模型在Tools上生效。

    @tool(args_schema=OrderQuerySchema)
    def query_order_status(order_id: str) -> str:
        """查询指定订单号的当前状态。"""
        print(f"\n[后台日志] 🔧 调用查询工具,参数: {order_id}")
        order = FAKE_DATABASE.get(order_id)
        return f"订单号 {order_id} 包含商品: {order['item']},状态为: {order['status']}" if order else "未找到订单。"
    

三、示例

对LangChain Tools中的示例代码进行优化,增加Pydantic的参数模型校验。

import os
from typing import Literal
from pydantic import BaseModel, Field, field_validator
from langchain_openai import ChatOpenAI
from langchain_core.tools import tool
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
from langchain.agents import create_tool_calling_agent, AgentExecutor

# ==========================================
# 第一步:定义 Pydantic 参数模型 (关键改进)
# ==========================================

class OrderQuerySchema(BaseModel):
    """查询订单所需的参数"""
    order_id: str = Field(
        ..., 
        description="标准的订单号,必须以 'ORD-' 开头,例如 ORD-1001"
    )

    @field_validator("order_id")
    @classmethod
    def validate_order_format(cls, v: str):
        if not v.startswith("ORD-"):
            # 这个报错信息会被 LangChain 捕获并传回给 LLM
            raise ValueError("订单号格式非法!必须以 'ORD-' 开头。")
        return v

class RefundSchema(BaseModel):
    """申请退款所需的参数"""
    order_id: str = Field(..., description="订单号")
    reason: str = Field(..., min_length=5, description="退款原因,至少包含5个字")
    confirm_checked: bool = Field(
        ..., 
        description="确认是否已经通过 query_order_status 检查过订单状态"
    )

# ==========================================
# 第二步:将模型绑定到工具
# ==========================================

FAKE_DATABASE = {
    "ORD-1001": {"status": "未发货", "item": "机械键盘"},
    "ORD-1002": {"status": "已发货", "item": "苹果手机"}
}

# 使用 args_schema 指定 Pydantic 模型
@tool(args_schema=OrderQuerySchema)
def query_order_status(order_id: str) -> str:
    """查询指定订单号的当前状态。"""
    print(f"\n[后台日志] 🔧 调用查询工具,参数: {order_id}")
    order = FAKE_DATABASE.get(order_id)
    return f"订单号 {order_id} 包含商品: {order['item']},状态为: {order['status']}" if order else "未找到订单。"

@tool(args_schema=RefundSchema)
def apply_refund(order_id: str, reason: str, confirm_checked: bool) -> str:
    """为用户发起退款申请。注意:调用前必须确认状态为'未发货'。"""
    print(f"\n[后台日志] ⚠️ 调用退款工具,参数: {order_id}, 理由: {reason}")
    order = FAKE_DATABASE.get(order_id)
    if not order or order["status"] != "未发货":
        return "退款失败:系统校验该订单状态不支持直接退款。"
    
    FAKE_DATABASE[order_id]["status"] = "已退款"
    return "退款成功!"

# ==========================================
# 第三步:后续逻辑 (保持不变,但 LLM 表现会更稳)
# ==========================================

llm = ChatOpenAI(model="gpt-4o", temperature=0)
tools = [query_order_status, apply_refund]

prompt = ChatPromptTemplate.from_messages([
    ("system", "你是一个专业电商客服。如果用户订单号格式不对,请指出来。执行高危操作前必须先查询状态。"),
    ("user", "{input}"),
    MessagesPlaceholder(variable_name="agent_scratchpad"),
])

agent = create_tool_calling_agent(llm, tools, prompt)
# 关键参数:handle_parsing_errors=True
# 这样当 Pydantic 校验失败时,错误会反馈给 LLM 让其自我修正
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True, handle_parsing_errors=True)

if __name__ == "__main__":
    # 测试 1:测试 Pydantic 的 Validator 拦截(输入错误的订单号格式)
    print("\n--- 测试:输入错误格式 ---")
    agent_executor.invoke({"input": "帮我查一下订单 1001"}) 
    # LLM 可能会尝试调用工具,但 Pydantic 会报错,LLM 收到报错后会礼貌地要求你提供 ORD- 开头的单号
posted @ 2026-03-13 15:52  Neur0toxin  阅读(53)  评论(0)    收藏  举报