Pydantic-AI项目中的自定义类型与输入处理实践

在Pydantic-AI项目中处理复杂数据结构时，开发者经常需要面对自定义类型的序列化挑战。本文将通过一个HR管理系统案例，深入探讨如何优雅地实现自定义类型与AI代理的集成。

核心场景分析

我们构建了一个包含部门(HRDepartment)和员工(HREmployee)数据结构的HR系统，其中：

• 部门包含ID和名称
• 员工包含ID、姓名及所属部门
• 整个HR系统维护员工列表

系统需要支持两种查询：

1. 统计员工总数（返回NumEmployees类型）
2. 查询特定员工部门信息（返回Department类型）

关键技术实现

1. 数据结构建模

使用Python的dataclass构建领域模型，这比直接使用Pydantic模型更灵活：

@dataclass
class HRDepartment:
    id: int
    name: str

@dataclass 
class HREmployee:
    id: int
    name: str
    department: HRDepartment

2. 自定义序列化

通过实现__str__方法控制对象序列化格式，确保AI模型能正确解析：

def __str__(self) -> str:
    return f"<employee>\nid: {self.id}\nname: {self.name}\n..."

3. 查询接口设计

创建统一的查询接口HRQuery，包含：

• 查询语句
• 依赖数据(HR实例)
• 预期返回类型

@dataclass
class HRQuery:
    query: str
    deps: HR
    result_type: type[NumEmployees] | type[Department]

4. 评估器实现

自定义评估器EvaluateHR继承自Evaluator，通过类型注解确保类型安全：

@dataclass
class EvaluateHR(Evaluator[HRQuery, NumEmployees | Department]):
    def evaluate(self, ctx: EvaluatorContext) -> bool:
        return ctx.output == ctx.expected_output

典型问题解决方案

类型序列化错误处理

最初会遇到PydanticSerializationError，原因是Pydantic无法直接序列化ModelMetaclass。解决方案包括：

1. 确保所有自定义类型都有明确的序列化方式
2. 对复杂类型实现专门的序列化逻辑
3. 使用最新版Pydantic的增强序列化能力

最佳实践建议

1. 领域建模：先用dataclass构建纯业务对象，再考虑Pydantic集成
2. 渐进式复杂化：从简单查询开始，逐步增加复杂度
3. 类型安全：充分利用Python的类型提示和Pydantic的类型验证
4. 评估设计：为每种查询类型设计专门的评估器

总结

通过这个案例，我们展示了如何在Pydantic-AI项目中处理复杂领域对象。关键在于：

• 清晰的领域模型设计
• 可控的序列化策略
• 灵活的类型系统集成
• 严谨的评估机制

这种模式可以扩展到各种企业应用场景，如CRM、ERP等需要结合AI能力处理复杂领域数据的系统。