PydanticAI functioncall参数校验失败如何排查？

Question

在使用 PydanticAI 进行 function call 时，常因参数类型不匹配或缺少必填字段导致校验失败。例如，模型期望接收一个 `str` 类型的参数，但实际传入了 `int`，Pydantic 会抛出 `ValidationError`。此类错误通常表现为“validation error in AI function”并指出具体字段。排查时应首先检查调用函数的输入数据类型与定义的 Pydantic 模型是否一致，确认字段是否存在默认值或可选性（Optional）。同时，查看异常堆栈信息定位出错字段，结合日志打印原始输入有助于快速发现问题。建议在开发阶段启用严格模式并编写单元测试验证参数结构。

Answer 1

1. 问题背景与常见表现形式

在使用 PydanticAI 进行 function call 时，开发者常遇到因参数类型不匹配或缺少必填字段导致的校验失败。这类错误通常由 Pydantic 模型的强类型约束机制触发，当传入的数据不符合模型定义的结构时，系统会抛出 ValidationError。

典型错误信息如下：

ValidationError: 1 validation error for AI Function
input_data.name
  Input should be a valid string [type=string_type, ...]

该提示明确指出：期望一个字符串类型，但实际输入可能是整数或其他非字符串类型。此类问题多发生在动态数据源（如 API 请求、用户输入、数据库读取）未经过严格预处理的场景中。

2. 错误成因深度剖析

• 类型不匹配：例如模型定义字段为 name: str，但调用时传入了 name=123。
• 缺失必填字段：模型中某字段未设置默认值且非 Optional，但在调用时未提供。
• 嵌套模型结构错误：复杂对象（如 List[User], Dict 等）内部元素类型不符或层级错乱。
• 运行时数据污染：中间逻辑修改了原始输入，导致最终传参偏离预期结构。
• 异步上下文中的状态混淆：在并发或多任务环境中，共享变量被意外覆盖。

这些问题的根本原因在于缺乏对输入数据的“契约式”控制和验证前置机制。

3. 排查流程与诊断策略

1. 查看异常堆栈信息，定位具体出错字段名。
2. 打印原始输入数据（建议使用 logger.debug(repr(raw_input))）。
3. 比对 Pydantic 模型定义与实际传参结构。
4. 检查字段是否声明为 Optional[str] 或设置了默认值（如 = ""）。
5. 启用 Pydantic 的 config.json_encoders 输出完整序列化视图。
6. 使用断点调试进入 model_validate() 调用前一刻。
7. 结合 OpenTelemetry 或日志追踪链路，分析跨服务调用中的数据变形点。

4. 典型代码示例与修复方案

from pydantic import BaseModel, Field, ValidationError
from typing import Optional

class UserInput(BaseModel):
    name: str = Field(..., description="用户姓名")
    age: Optional[int] = None

def process_user(data):
    try:
        user = UserInput.model_validate(data)  # 替代旧版 parse_obj
        return f"Hello {user.name}, you are {user.age} years old."
    except ValidationError as e:
        print(f"Validation error in AI function:\n{e}")
        raise

调用示例：

输入数据	结果	说明
{"name": "Alice", "age": 30}	成功	完全符合模型
{"name": "Bob"}	成功	age 可选
{"name": 123}	失败	name 类型错误
{}	失败	缺少必填 name
{"name": "Carol", "age": "thirty"}	失败	age 类型错误

5. 防御性编程与工程化实践

graph TD
    A[原始输入] --> B{是否已知来源?}
    B -->|是| C[直接校验]
    B -->|否| D[清洗/转换]
    D --> E[类型归一化]
    E --> F[调用 model_validate]
    F --> G{通过?}
    G -->|是| H[执行 AI 逻辑]
    G -->|否| I[记录日志 + 抛出]
    I --> J[告警通知]

通过引入标准化的数据入口层，可显著降低校验失败概率。建议在微服务架构中将此模式封装为通用中间件。

6. 单元测试与持续集成保障

import pytest

def test_valid_input():
    assert process_user({"name": "TestUser"}) == "Hello TestUser, you are None years old."

def test_invalid_name_type():
    with pytest.raises(ValidationError):
        process_user({"name": 456})

def test_missing_required_field():
    with pytest.raises(ValidationError):
        process_user({})

在 CI 流程中加入 pytest --cov 覆盖率检测，确保所有边界情况都被测试覆盖，尤其是类型转换失败路径。