模型提供商

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

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

与OpenAI兼容的提供商

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

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

要使用每个模型提供商，您需要配置本地环境并确保已安装正确的软件包。

模型和提供商

Pydantic AI 使用一些关键术语来描述它如何与不同的 LLM（大语言模型）进行交互

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

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

自定义模型

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

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

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

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

备用模型

您可以使用 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 OpenAIModel

openai_model = OpenAIModel('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',
        vendor_id=None,
    ),
]
"""

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

注意

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

各模型的设置

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

fallback_model_per_settings.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 OpenAIModel
from pydantic_ai.settings import ModelSettings

# Configure each model with provider-specific optimal settings
openai_model = OpenAIModel(
    '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
from pydantic_ai.exceptions import ModelHTTPError
from pydantic_ai.models.anthropic import AnthropicModel
from pydantic_ai.models.fallback import FallbackModel
from pydantic_ai.models.openai import OpenAIModel

openai_model = OpenAIModel('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
from pydantic_ai.exceptions import ModelHTTPError
from pydantic_ai.models.anthropic import AnthropicModel
from pydantic_ai.models.fallback import FallbackModel
from pydantic_ai.models.openai import OpenAIModel


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


openai_model = OpenAIModel('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 参数来自定义此行为。