模型提供商

Pydantic AI 与模型无关，并内置了对多个模型提供商的支持。

OpenAI
Anthropic
Gemini（通过两种不同的 API：Generative Language API 和 VertexAI API）
Groq
Mistral
Cohere
Bedrock
Hugging Face

兼容 OpenAI 的提供商

此外，许多提供商都与 OpenAI API 兼容，可以在 Pydantic AI 中与 OpenAIChatModel 一起使用。

Pydantic AI 还附带了用于测试和开发的 TestModel 和 FunctionModel。

要使用每个模型提供商，您需要配置本地环境并确保已安装正确的软件包。如果您在未完成这些操作的情况下尝试使用模型，系统会提示您需要安装什么。

模型和提供商

Pydantic AI 使用几个关键术语来描述它如何与不同的 LLM 进行交互。

模型（Model）：这指的是 Pydantic AI 中用于遵循特定 LLM API 发出请求的类（通常通过包装供应商提供的 SDK，如 openai Python SDK）。这些类实现了一个与供应商 SDK 无关的 API，确保单个 Pydantic AI 代理只需更换其使用的模型，无需任何其他代码更改，即可移植到不同的 LLM 供应商。模型类的命名格式大致为 <VendorSdk>Model，例如，我们有 OpenAIChatModel、AnthropicModel、GoogleModel 等。在使用模型类时，您需要指定实际的 LLM 模型名称（例如，gpt-4o、claude-3-5-sonnet-latest、gemini-1.5-flash）作为参数。
提供商（Provider）：这指的是特定于提供商的类，它们处理与 LLM 供应商的身份验证和连接。将非默认的提供商作为参数传递给模型，可以确保您的代理向特定端点发出请求，或使用特定的身份验证方法（例如，您可以通过 AzureProvider 将 Azure 身份验证与 OpenAIChatModel 结合使用）。特别是，这使您能够利用 AI 网关，或利用那些与现有模型（如 OpenAIChatModel）所用供应商 SDK 兼容的 LLM 供应商。
配置文件（Profile）：这指的是一种描述，说明如何构建对特定模型或模型系列的请求以获得最佳结果，这与所使用的模型和提供商类无关。例如，不同的模型对可用于工具的 JSON 模式有不同的限制，无论您是使用模型名称为 gemini-2.5-pro-preview 的 GoogleModel，还是使用带有 OpenRouterProvider 且模型名称为 google/gemini-2.5-pro-preview 的 OpenAIChatModel，都需要为 Gemini 模型使用相同的模式转换器。

当您仅使用一个格式为 <provider>:<model> 的名称（例如 openai:gpt-4o 或 openrouter:google/gemini-2.5-pro-preview）来实例化一个 Agent 时，Pydantic AI 将自动选择合适的模型类、提供商和配置文件。如果您想使用不同的提供商或配置文件，可以直接实例化一个模型类，并传入 provider 和/或 profile 参数。

自定义模型

注意

如果一个模型 API 与 OpenAI API 兼容，您就不需要自定义模型类，而是可以提供自己的自定义提供商。

要为尚不支持的模型 API 实现支持，您需要子类化 Model 抽象基类。对于流式传输，您还需要实现 StreamedResponse 抽象基类。

最好的起点是查阅现有实现的源代码，例如 OpenAIChatModel。

有关我们何时接受向 Pydantic AI 添加新模型的贡献的详细信息，请参阅贡献指南。

备用模型

您可以使用 FallbackModel 按顺序尝试多个模型，直到其中一个成功返回结果。在底层，如果当前模型返回 4xx 或 5xx 状态码，Pydantic AI 会自动切换到下一个模型。

在下面的示例中，代理首先向 OpenAI 模型发出请求（由于 API 密钥无效而失败），然后回退到 Anthropic 模型。

fallback_model.py

from pydantic_ai import Agent
from pydantic_ai.models.anthropic import AnthropicModel
from pydantic_ai.models.fallback import FallbackModel
from pydantic_ai.models.openai import OpenAIChatModel

openai_model = OpenAIChatModel('gpt-4o')
anthropic_model = AnthropicModel('claude-3-5-sonnet-latest')
fallback_model = FallbackModel(openai_model, anthropic_model)

agent = Agent(fallback_model)
response = agent.run_sync('What is the capital of France?')
print(response.data)
#> Paris

print(response.all_messages())
"""
[
    ModelRequest(
        parts=[
            UserPromptPart(
                content='What is the capital of France?',
                timestamp=datetime.datetime(...),
                part_kind='user-prompt',
            )
        ],
        kind='request',
    ),
    ModelResponse(
        parts=[TextPart(content='Paris', part_kind='text')],
        model_name='claude-3-5-sonnet-latest',
        timestamp=datetime.datetime(...),
        kind='response',
        provider_response_id=None,
    ),
]
"""

上面的 ModelResponse 消息在其 model_name 字段中表明，输出是由 Anthropic 模型返回的，该模型是 FallbackModel 中指定的第二个模型。

注意

每个模型的选项都应单独配置。例如，base_url、api_key 和自定义客户端应在每个模型本身上设置，而不是在 FallbackModel 上。

各模型的独立设置

您可以通过在创建每个模型时传递 settings 参数，为备用链中的每个模型配置不同的 ModelSettings。当不同的提供商有不同的最佳配置时，这尤其有用。

fallback_model_per_settings.py

from pydantic_ai import Agent, ModelSettings
from pydantic_ai.models.anthropic import AnthropicModel
from pydantic_ai.models.fallback import FallbackModel
from pydantic_ai.models.openai import OpenAIChatModel

# Configure each model with provider-specific optimal settings
openai_model = OpenAIChatModel(
    'gpt-4o',
    settings=ModelSettings(temperature=0.7, max_tokens=1000)  # Higher creativity for OpenAI
)
anthropic_model = AnthropicModel(
    'claude-3-5-sonnet-latest',
    settings=ModelSettings(temperature=0.2, max_tokens=1000)  # Lower temperature for consistency
)

fallback_model = FallbackModel(openai_model, anthropic_model)
agent = Agent(fallback_model)

result = agent.run_sync('Write a creative story about space exploration')
print(result.output)
"""
In the year 2157, Captain Maya Chen piloted her spacecraft through the vast expanse of the Andromeda Galaxy. As she discovered a planet with crystalline mountains that sang in harmony with the cosmic winds, she realized that space exploration was not just about finding new worlds, but about finding new ways to understand the universe and our place within it.
"""

在此示例中，如果 OpenAI 模型失败，代理将自动回退到具有其自身已配置设置的 Anthropic 模型。FallbackModel 本身没有设置——它使用成功处理请求的那个模型的独立设置。

在下一个示例中，我们演示了 FallbackModel 的异常处理能力。如果所有模型都失败，将引发一个 FallbackExceptionGroup，其中包含在 run 执行期间遇到的所有异常。

Python >=3.11Python <3.11

fallback_model_failure.py

from pydantic_ai import Agent, ModelHTTPError
from pydantic_ai.models.anthropic import AnthropicModel
from pydantic_ai.models.fallback import FallbackModel
from pydantic_ai.models.openai import OpenAIChatModel

openai_model = OpenAIChatModel('gpt-4o')
anthropic_model = AnthropicModel('claude-3-5-sonnet-latest')
fallback_model = FallbackModel(openai_model, anthropic_model)

agent = Agent(fallback_model)
try:
    response = agent.run_sync('What is the capital of France?')
except* ModelHTTPError as exc_group:
    for exc in exc_group.exceptions:
        print(exc)

由于 except* 仅在 Python 3.11+ 中受支持，我们为早期的 Python 版本使用了 exceptiongroup 向后移植包。

fallback_model_failure.py

from exceptiongroup import catch

from pydantic_ai import Agent, ModelHTTPError
from pydantic_ai.models.anthropic import AnthropicModel
from pydantic_ai.models.fallback import FallbackModel
from pydantic_ai.models.openai import OpenAIChatModel


def model_status_error_handler(exc_group: BaseExceptionGroup) -> None:
    for exc in exc_group.exceptions:
        print(exc)


openai_model = OpenAIChatModel('gpt-4o')
anthropic_model = AnthropicModel('claude-3-5-sonnet-latest')
fallback_model = FallbackModel(openai_model, anthropic_model)

agent = Agent(fallback_model)
with catch({ModelHTTPError: model_status_error_handler}):
    response = agent.run_sync('What is the capital of France?')

默认情况下，只有当当前模型引发 ModelHTTPError 时，FallbackModel 才会移至下一个模型。您可以通过向 FallbackModel 构造函数传递一个自定义的 fallback_on 参数来定制此行为。