Pydantic-AI项目中嵌套Schema的性能问题分析与解决方案

在Pydantic-AI项目中，开发者们发现了一个与嵌套Schema相关的性能问题，这个问题在使用特定LLM模型时表现得尤为明显。本文将深入分析问题的本质，并提供有效的解决方案。

问题现象

当开发者尝试使用嵌套的Pydantic模型作为输出类型时，某些Qwen系列的大型语言模型（如Qwen2.5-72B-Instruct-Turbo、Qwen3-4B-fast等）会返回400错误。而其他模型如Llama-3.3-70B-Instruct-Turbo则能正常处理相同的请求。

错误信息主要分为两类：

1. 工具语法无效错误（invalid tools grammar）
2. JSON解析错误（Invalid JSON）

根本原因分析

经过深入研究，发现问题出在JSON Schema的生成方式上。Pydantic-AI默认会生成包含$ref引用的Schema结构，这在某些LLM实现中会导致解析失败。具体来说：

1. 当Schema中包含嵌套引用时（如NameAndCount模型中的Count字段），系统会生成带有$ref的Schema结构
2. 部分Qwen模型的API实现对这种引用式Schema处理不够完善
3. 更简单的Schema（如直接内联定义）则能被所有模型正确处理

技术解决方案

针对这一问题，可以通过自定义Schema生成器来强制内联所有定义，避免使用$ref引用。具体实现方式是创建一个继承自OpenAIModel的QwenModel类，并重写其Schema生成逻辑：

class QwenModel(OpenAIModel):
    def customize_request_parameters(self, model_request_parameters):
        return _customize_request_parameters(model_request_parameters)

class _QwenJsonSchema(_OpenAIJsonSchema):
    def __init__(self, schema, strict=None):
        super().__init__(schema, strict=strict)
        self.prefer_inlined_defs = True  # 关键设置，强制内联定义

这个解决方案的核心在于将prefer_inlined_defs设置为True，这会使得Schema生成器将所有嵌套定义直接内联展开，而不是使用引用方式。

实际效果验证

经过测试，这个解决方案能够：

1. 解决所有Qwen模型的400错误问题
2. 保持与Llama等模型的兼容性
3. 不改变原有的功能逻辑

最佳实践建议

对于使用Pydantic-AI的开发者，建议：

1. 当使用Qwen系列模型时，优先采用上述解决方案
2. 对于复杂的嵌套Schema，考虑简化结构或手动内联定义
3. 在模型选择上，了解不同模型对Schema复杂度的支持程度

这个问题展示了在实际AI应用开发中，模型实现细节对系统稳定性的重要影响。通过深入理解底层机制，开发者能够更好地规避这类兼容性问题。