Pydantic AI项目中OpenRouter与Gemini模型集成问题的技术解析

在Pydantic AI项目中使用OpenRouter作为API网关调用Gemini模型时，开发者可能会遇到模型输出不符合预期的问题。本文将从技术角度深入分析这一现象的原因，并提供解决方案。

问题现象

当开发者通过OpenRouter的API网关调用Gemini模型时，模型的输出行为与直接使用Google Vertex API调用存在显著差异。具体表现为：

1. 模型输出的JSON结构不符合预期
2. 参数验证频繁失败
3. 需要多次重试才能获得有效结果

根本原因

这一问题源于Pydantic AI内部处理机制的特殊性。OpenAIModel类默认使用标准的JSON Schema转换逻辑，而Gemini模型需要特定的Schema转换方式。当通过OpenRouter调用Gemini模型时，系统没有自动应用Gemini特有的JSON Schema转换规则。

技术解决方案

要解决这一问题，我们需要创建一个自定义的模型类，手动应用Gemini的JSON Schema转换规则。以下是实现方案：

from dataclasses import replace
from pydantic_ai.models import ModelRequestParameters
from pydantic_ai.models._json_schema import JsonSchema
from pydantic_ai.models.openai import OpenAIModel
from pydantic_ai.models.gemini import _GeminiJsonSchema
from pydantic_ai.tools import ToolDefinition

class ORGeminiModel(OpenAIModel):
    def customize_request_parameters(self, model_request_parameters: ModelRequestParameters) -> ModelRequestParameters:
        def _customize_tool_def(t: ToolDefinition):
            return replace(t, parameters_json_schema=_GeminiJsonSchema(t.parameters_json_schema).walk())

        return ModelRequestParameters(
            function_tools=[_customize_tool_def(tool) for tool in model_request_parameters.function_tools],
            allow_text_output=model_request_parameters.allow_text_output,
            output_tools=[_customize_tool_def(tool) for tool in model_request_parameters.output_tools],
        )

实现原理

这个解决方案的核心在于：

1. 继承OpenAIModel类，保留其基本功能
2. 重写customize_request_parameters方法
3. 使用_GeminiJsonSchema对每个工具的parameters_json_schema进行转换
4. 确保输出工具和函数工具都应用相同的转换规则

最佳实践建议

1. 对于混合使用不同API网关和模型的情况，建议创建专门的适配器类
2. 在项目初期就考虑模型API的差异性，设计可扩展的架构
3. 对于关键业务场景，建议增加输出验证和重试机制

未来展望

Pydantic AI团队已经意识到这一问题，并计划在未来版本中提供更通用的解决方案，以更好地支持不同API网关和模型组合的使用场景。开发者可以关注项目的更新动态，及时获取更优雅的解决方案。

通过本文的分析和解决方案，开发者可以更好地理解Pydantic AI框架中模型调用的内部机制，并在实际项目中灵活应对类似的技术挑战。