模型

PydanticAI 是模型无关的，并内置支持以下模型提供商

OpenAI
Anthropic
通过两种不同的 API 使用 Gemini：Generative Language API 和 VertexAI API
Ollama
Groq
Mistral
Cohere
Bedrock

请参阅 OpenAI 兼容模型，了解有关如何使用 OpenRouter 和 Grok (xAI) 等支持 OpenAI SDK 的模型的更多示例。

您还可以添加对其他模型的支持。

PydanticAI 还附带 TestModel 和 FunctionModel，用于测试和开发。

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

模型、接口和提供商

PydanticAI 使用一些关键术语来描述它如何与不同的 LLM 交互

模型：这指的是您想要处理请求的特定 LLM 模型（例如，gpt-4o、claude-3-5-sonnet-latest、gemini-1.5-flash）。它是处理您的提示并生成响应的“大脑”。您将模型指定为接口的参数。
接口：这指的是一个 PydanticAI 类，用于按照特定的 LLM API 发出请求（通常通过包装供应商提供的 SDK，例如 openai python SDK）。这些类实现了与供应商 SDK 无关的 API，确保单个 PydanticAI 代理可以移植到不同的 LLM 供应商，而无需任何其他代码更改，只需更换它使用的接口。目前，接口类的命名格式大致为 <VendorSdk>Model，例如，我们有 OpenAIModel、AnthropicModel、GeminiModel 等。这些 Model 类将很快重命名为 <VendorSdk>Interface，以更好地反映此术语。
提供商：这指的是接口特定的类，用于处理与 LLM 供应商的身份验证和连接。将非默认提供商作为参数传递给接口，您可以确保您的代理将向特定端点发出请求，或使用特定的身份验证方法（例如，您可以通过 VertexProvider 将 Vertex 特定的身份验证与 GeminiModel 一起使用）。特别是，这就是您如何使用 AI 网关或 LLM 供应商的方式，这些供应商提供与现有接口使用的供应商 SDK 的 API 兼容性（例如 OpenAIModel）。

简而言之，您选择一个模型，PydanticAI 使用适当的接口类，而提供商处理与底层服务的连接和身份验证。

OpenAI

安装

要使用 OpenAI 模型，您需要安装 pydantic-ai，或者安装带有 openai 可选组的 pydantic-ai-slim

pipuv

pip install "pydantic-ai-slim[openai]"

uv add "pydantic-ai-slim[openai]"

配置

要通过其主 API 使用 OpenAIModel，请访问 platform.openai.com 并按照指示找到生成 API 密钥的位置。

环境变量

获得 API 密钥后，您可以将其设置为环境变量

export OPENAI_API_KEY='your-api-key'

然后，您可以通过名称使用 OpenAIModel

openai_model_by_name.py

from pydantic_ai import Agent

agent = Agent('openai:gpt-4o')
...

或者直接使用模型名称初始化模型

openai_model_init.py

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIModel

model = OpenAIModel('gpt-4o')
agent = Agent(model)
...

默认情况下，OpenAIModel 使用 OpenAIProvider，并将 base_url 设置为 https://api.openai.com/v1。

`provider` 参数

您可以通过 provider 参数提供自定义的 Provider

openai_model_provider.py

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIModel
from pydantic_ai.providers.openai import OpenAIProvider

model = OpenAIModel('gpt-4o', provider=OpenAIProvider(api_key='your-api-key'))
agent = Agent(model)
...

自定义 OpenAI 客户端

OpenAIProvider 还通过 openai_client 参数接受自定义的 AsyncOpenAI 客户端，因此您可以自定义 OpenAI API 文档中定义的 organization、project、base_url 等。

您还可以使用 AsyncAzureOpenAI 客户端来使用 Azure OpenAI API。

openai_azure.py

from openai import AsyncAzureOpenAI

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIModel
from pydantic_ai.providers.openai import OpenAIProvider

client = AsyncAzureOpenAI(
    azure_endpoint='...',
    api_version='2024-07-01-preview',
    api_key='your-api-key',
)

model = OpenAIModel(
    'gpt-4o',
    provider=OpenAIProvider(openai_client=client),
)
agent = Agent(model)
...

Anthropic

安装

要使用 AnthropicModel 模型，您需要安装 pydantic-ai，或者安装带有 anthropic 可选组的 pydantic-ai-slim

pipuv

pip install "pydantic-ai-slim[anthropic]"

uv add "pydantic-ai-slim[anthropic]"

配置

要通过其 API 使用 Anthropic，请访问 console.anthropic.com/settings/keys 以生成 API 密钥。

AnthropicModelName 包含可用 Anthropic 模型的列表。

环境变量

获得 API 密钥后，您可以将其设置为环境变量

export ANTHROPIC_API_KEY='your-api-key'

然后，您可以通过名称使用 AnthropicModel

anthropic_model_by_name.py

from pydantic_ai import Agent

agent = Agent('anthropic:claude-3-5-sonnet-latest')
...

或者直接使用模型名称初始化模型

anthropic_model_init.py

from pydantic_ai import Agent
from pydantic_ai.models.anthropic import AnthropicModel

model = AnthropicModel('claude-3-5-sonnet-latest')
agent = Agent(model)
...

`provider` 参数

您可以通过 provider 参数提供自定义的 Provider

anthropic_model_provider.py

from pydantic_ai import Agent
from pydantic_ai.models.anthropic import AnthropicModel
from pydantic_ai.providers.anthropic import AnthropicProvider

model = AnthropicModel(
    'claude-3-5-sonnet-latest', provider=AnthropicProvider(api_key='your-api-key')
)
agent = Agent(model)
...

自定义 HTTP 客户端

您可以使用自定义的 httpx.AsyncClient 自定义 AnthropicProvider

anthropic_model_custom_provider.py

from httpx import AsyncClient

from pydantic_ai import Agent
from pydantic_ai.models.anthropic import AnthropicModel
from pydantic_ai.providers.anthropic import AnthropicProvider

custom_http_client = AsyncClient(timeout=30)
model = AnthropicModel(
    'claude-3-5-sonnet-latest',
    provider=AnthropicProvider(api_key='your-api-key', http_client=custom_http_client),
)
agent = Agent(model)
...

Gemini

安装

要使用 GeminiModel 模型，您只需安装 pydantic-ai 或 pydantic-ai-slim，无需额外的依赖项。

配置

GeminiModel 让您可以通过 Google 的 Generative Language API generativelanguage.googleapis.com 使用 Google 的 Gemini 模型。

GeminiModelName 包含可以通过此接口使用的可用 Gemini 模型的列表。

要使用 GeminiModel，请访问 aistudio.google.com 并选择“创建 API 密钥”。

环境变量

获得 API 密钥后，您可以将其设置为环境变量

export GEMINI_API_KEY=your-api-key

然后，您可以通过名称使用 GeminiModel

gemini_model_by_name.py

from pydantic_ai import Agent

agent = Agent('google-gla:gemini-2.0-flash')
...

注意

google-gla 提供商前缀代表 Google Generative Language API 用于 GeminiModel。google-vertex 与 Vertex AI 一起使用。

或者直接使用模型名称和提供商初始化模型

gemini_model_init.py

from pydantic_ai import Agent
from pydantic_ai.models.gemini import GeminiModel

model = GeminiModel('gemini-2.0-flash', provider='google-gla')
agent = Agent(model)
...

`provider` 参数

您可以通过 provider 参数提供自定义的 Provider

gemini_model_provider.py

from pydantic_ai import Agent
from pydantic_ai.models.gemini import GeminiModel
from pydantic_ai.providers.google_gla import GoogleGLAProvider

model = GeminiModel(
    'gemini-2.0-flash', provider=GoogleGLAProvider(api_key='your-api-key')
)
agent = Agent(model)
...

您还可以使用自定义的 http_client 自定义 GoogleGLAProvider

gemini_model_custom_provider.py

from httpx import AsyncClient

from pydantic_ai import Agent
from pydantic_ai.models.gemini import GeminiModel
from pydantic_ai.providers.google_gla import GoogleGLAProvider

custom_http_client = AsyncClient(timeout=30)
model = GeminiModel(
    'gemini-2.0-flash',
    provider=GoogleGLAProvider(api_key='your-api-key', http_client=custom_http_client),
)
agent = Agent(model)
...

通过 VertexAI 使用 Gemini

如果您是企业用户，则应将 google-vertex 提供商与 GeminiModel 一起使用，后者使用 *-aiplatform.googleapis.com API。

GeminiModelName 包含可以通过此接口使用的可用 Gemini 模型的列表。

安装

要将 google-vertex 提供商与 GeminiModel 一起使用，您需要安装 pydantic-ai，或者安装带有 vertexai 可选组的 pydantic-ai-slim

pipuv

pip install "pydantic-ai-slim[vertexai]"

uv add "pydantic-ai-slim[vertexai]"

配置

此接口比上面记录的 generativelanguage.googleapis.com 具有许多优势

VertexAI API 具有更高的企业就绪保证。
您可以购买 VertexAI 的预配置吞吐量以保证容量。
如果您在 GCP 内部运行 PydanticAI，则无需设置身份验证，它应该“开箱即用”。
您可以决定要使用的区域，这可能从监管角度来看很重要，并且可能会提高延迟。

最大的缺点是，对于本地开发，您可能需要创建和配置“服务账户”，我发现在过去这非常痛苦。

无论您以哪种方式进行身份验证，都需要在您的 GCP 账户中启用 VertexAI。

应用程序默认凭据

幸运的是，如果您在 GCP 内部运行 PydanticAI，或者您已安装并配置了 gcloud CLI，您应该能够使用 VertexAIModel 而无需任何额外设置。

要使用配置了应用程序默认凭据的 VertexAIModel（例如使用 gcloud），您可以简单地使用

vertexai_application_default_credentials.py

from pydantic_ai import Agent
from pydantic_ai.models.gemini import GeminiModel

model = GeminiModel('gemini-2.0-flash', provider='google-vertex')
agent = Agent(model)
...

在内部，这使用 google-auth 包中的 google.auth.default() 来获取凭据。

在 agent.run() 之前不会失败

由于 google.auth.default() 需要网络请求并且可能很慢，因此在您调用 agent.run() 之前不会运行它。

如果应用程序默认凭据未设置项目，您可能还需要将 project_id 参数传递给 GoogleVertexProvider；如果您传递 project_id 并且它与应用程序默认凭据设置的项目冲突，则会引发错误。

服务账户

如果除了应用程序默认凭据之外，您还想使用服务账户进行身份验证，则需要创建一个服务账户，将其添加到您的 GCP 项目（注意：据我所知，即使您在项目内创建了服务账户，此步骤也是必要的），为该服务账户授予“Vertex AI Service Agent”角色，并下载服务账户 JSON 文件。

获得 JSON 文件后，您可以这样使用它

vertexai_service_account.py

from pydantic_ai import Agent
from pydantic_ai.models.gemini import GeminiModel
from pydantic_ai.providers.google_vertex import GoogleVertexProvider

model = GeminiModel(
    'gemini-2.0-flash',
    provider=GoogleVertexProvider(service_account_file='path/to/service-account.json'),
)
agent = Agent(model)
...

或者，如果您已经将服务账户信息存储在内存中，则可以将其作为字典传递

vertexai_service_account.py

import json

from pydantic_ai import Agent
from pydantic_ai.models.gemini import GeminiModel
from pydantic_ai.providers.google_vertex import GoogleVertexProvider

service_account_info = json.loads(
    '{"type": "service_account", "project_id": "my-project-id"}'
)
model = GeminiModel(
    'gemini-2.0-flash',
    provider=GoogleVertexProvider(service_account_info=service_account_info),
)
agent = Agent(model)
...

自定义区域

无论您以哪种方式进行身份验证，都可以通过 region 参数指定将请求发送到的区域。

使用靠近您应用程序的区域可以提高延迟，并且可能从监管角度来看很重要。

vertexai_region.py

from pydantic_ai import Agent
from pydantic_ai.models.gemini import GeminiModel
from pydantic_ai.providers.google_vertex import GoogleVertexProvider

model = GeminiModel(
    'gemini-2.0-flash', provider=GoogleVertexProvider(region='asia-east1')
)
agent = Agent(model)
...

您还可以使用自定义的 http_client 自定义 GoogleVertexProvider

vertexai_custom_provider.py

from httpx import AsyncClient

from pydantic_ai import Agent
from pydantic_ai.models.gemini import GeminiModel
from pydantic_ai.providers.google_vertex import GoogleVertexProvider

custom_http_client = AsyncClient(timeout=30)
model = GeminiModel(
    'gemini-2.0-flash',
    provider=GoogleVertexProvider(region='asia-east1', http_client=custom_http_client),
)
agent = Agent(model)
...

Groq

安装

要使用 GroqModel，您需要安装 pydantic-ai，或者安装带有 groq 可选组的 pydantic-ai-slim

pipuv

pip install "pydantic-ai-slim[groq]"

uv add "pydantic-ai-slim[groq]"

配置

要通过其 API 使用 Groq，请访问 console.groq.com/keys 并按照指示找到生成 API 密钥的位置。

GroqModelName 包含可用 Groq 模型的列表。

环境变量

获得 API 密钥后，您可以将其设置为环境变量

export GROQ_API_KEY='your-api-key'

然后，您可以通过名称使用 GroqModel

groq_model_by_name.py

from pydantic_ai import Agent

agent = Agent('groq:llama-3.3-70b-versatile')
...

或者直接使用模型名称初始化模型

groq_model_init.py

from pydantic_ai import Agent
from pydantic_ai.models.groq import GroqModel

model = GroqModel('llama-3.3-70b-versatile')
agent = Agent(model)
...

`provider` 参数

您可以通过 provider 参数提供自定义的 Provider

groq_model_provider.py

from pydantic_ai import Agent
from pydantic_ai.models.groq import GroqModel
from pydantic_ai.providers.groq import GroqProvider

model = GroqModel(
    'llama-3.3-70b-versatile', provider=GroqProvider(api_key='your-api-key')
)
agent = Agent(model)
...

您还可以使用自定义的 httpx.AsyncHTTPClient 自定义 GroqProvider

groq_model_custom_provider.py

from httpx import AsyncClient

from pydantic_ai import Agent
from pydantic_ai.models.groq import GroqModel
from pydantic_ai.providers.groq import GroqProvider

custom_http_client = AsyncClient(timeout=30)
model = GroqModel(
    'llama-3.3-70b-versatile',
    provider=GroqProvider(api_key='your-api-key', http_client=custom_http_client),
)
agent = Agent(model)
...

Mistral

安装

要使用 MistralModel，您需要安装 pydantic-ai，或者安装带有 mistral 可选组的 pydantic-ai-slim

pipuv

pip install "pydantic-ai-slim[mistral]"

uv add "pydantic-ai-slim[mistral]"

配置

要通过其 API 使用 Mistral，请访问 console.mistral.ai/api-keys/ 并按照指示找到生成 API 密钥的位置。

LatestMistralModelNames 包含最流行的 Mistral 模型的列表。

环境变量

获得 API 密钥后，您可以将其设置为环境变量

export MISTRAL_API_KEY='your-api-key'

然后，您可以通过名称使用 MistralModel

mistral_model_by_name.py

from pydantic_ai import Agent

agent = Agent('mistral:mistral-large-latest')
...

或者直接使用模型名称初始化模型

mistral_model_init.py

from pydantic_ai import Agent
from pydantic_ai.models.mistral import MistralModel

model = MistralModel('mistral-small-latest')
agent = Agent(model)
...

`provider` 参数

您可以通过 provider 参数提供自定义的 Provider

groq_model_provider.py

from pydantic_ai import Agent
from pydantic_ai.models.mistral import MistralModel
from pydantic_ai.providers.mistral import MistralProvider

model = MistralModel(
    'mistral-large-latest', provider=MistralProvider(api_key='your-api-key')
)
agent = Agent(model)
...

您还可以使用自定义的 httpx.AsyncHTTPClient 自定义提供商

groq_model_custom_provider.py

from httpx import AsyncClient

from pydantic_ai import Agent
from pydantic_ai.models.mistral import MistralModel
from pydantic_ai.providers.mistral import MistralProvider

custom_http_client = AsyncClient(timeout=30)
model = MistralModel(
    'mistral-large-latest',
    provider=MistralProvider(api_key='your-api-key', http_client=custom_http_client),
)
agent = Agent(model)
...

Cohere

安装

要使用 CohereModel，您需要安装 pydantic-ai，或者安装带有 cohere 可选组的 pydantic-ai-slim

pipuv

pip install "pydantic-ai-slim[cohere]"

uv add "pydantic-ai-slim[cohere]"

配置

要通过其 API 使用 Cohere，请访问 dashboard.cohere.com/api-keys 并按照指示找到生成 API 密钥的位置。

CohereModelName 包含最流行的 Cohere 模型的列表。

环境变量

获得 API 密钥后，您可以将其设置为环境变量

export CO_API_KEY='your-api-key'

然后，您可以通过名称使用 CohereModel

cohere_model_by_name.py

from pydantic_ai import Agent

agent = Agent('cohere:command')
...

或者直接使用模型名称初始化模型

cohere_model_init.py

from pydantic_ai import Agent
from pydantic_ai.models.cohere import CohereModel

model = CohereModel('command', api_key='your-api-key')
agent = Agent(model)
...

`api_key` 参数

如果您不想或不能设置环境变量，则可以在运行时通过 api_key 参数传递它

cohere_model_api_key.py

from pydantic_ai import Agent
from pydantic_ai.models.cohere import CohereModel

model = CohereModel('command', api_key='your-api-key')
agent = Agent(model)
...

Bedrock

安装

要使用 BedrockConverseModel，您需要安装 pydantic-ai，或者安装带有 bedrock 可选组的 pydantic-ai-slim

pipuv

pip install "pydantic-ai-slim[bedrock]"

uv add "pydantic-ai-slim[bedrock]"

配置

要使用 AWS Bedrock，您需要一个启用了 Bedrock 并具有适当凭据的 AWS 账户。您可以直接使用 AWS 凭据或预配置的 boto3 客户端。

BedrockModelName 包含可用的 Bedrock 模型列表，包括来自 Anthropic、Amazon、Cohere、Meta 和 Mistral 的模型。

环境变量

您可以将 AWS 凭据设置为环境变量

export AWS_ACCESS_KEY_ID='your-access-key'
export AWS_SECRET_ACCESS_KEY='your-secret-key'
export AWS_REGION='us-east-1'  # or your preferred region

然后，您可以通过名称使用 BedrockConverseModel

bedrock_model_by_name.py

from pydantic_ai import Agent

agent = Agent('bedrock:anthropic.claude-3-sonnet-20240229-v1:0')
...

或者直接使用模型名称初始化模型

bedrock_model_init.py

from pydantic_ai import Agent
from pydantic_ai.models.bedrock import BedrockConverseModel

model = BedrockConverseModel('anthropic.claude-3-sonnet-20240229-v1:0')
agent = Agent(model)
...

`provider` 参数

您可以通过 provider 参数提供自定义的 BedrockProvider。当您想要直接指定凭据或使用自定义 boto3 客户端时，这很有用

bedrock_model_provider.py

from pydantic_ai import Agent
from pydantic_ai.models.bedrock import BedrockConverseModel
from pydantic_ai.providers.bedrock import BedrockProvider

# Using AWS credentials directly
model = BedrockConverseModel(
    'anthropic.claude-3-sonnet-20240229-v1:0',
    provider=BedrockProvider(
        region_name='us-east-1',
        aws_access_key_id='your-access-key',
        aws_secret_access_key='your-secret-key',
    ),
)
agent = Agent(model)
...

您还可以传递预配置的 boto3 客户端

bedrock_model_boto3.py

import boto3

from pydantic_ai import Agent
from pydantic_ai.models.bedrock import BedrockConverseModel
from pydantic_ai.providers.bedrock import BedrockProvider

# Using a pre-configured boto3 client
bedrock_client = boto3.client('bedrock-runtime', region_name='us-east-1')
model = BedrockConverseModel(
    'anthropic.claude-3-sonnet-20240229-v1:0',
    provider=BedrockProvider(bedrock_client=bedrock_client),
)
agent = Agent(model)
...

OpenAI 兼容模型

许多模型与 OpenAI API 兼容，因此可以在 PydanticAI 中与 OpenAIModel 一起使用。在开始之前，请查看 OpenAI 部分以获取安装和配置说明。

要使用另一个 OpenAI 兼容的 API，您可以利用 OpenAIProvider 中的 base_url 和 api_key 参数

deepseek_model_init.py

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIModel
from pydantic_ai.providers.openai import OpenAIProvider

model = OpenAIModel(
    'model_name',
    provider=OpenAIProvider(
        base_url='https://<openai-compatible-api-endpoint>.com', api_key='your-api-key'
    ),
)
agent = Agent(model)
...

您还可以将 provider 参数与自定义提供商类（如 DeepSeekProvider）一起使用

deepseek_model_init_provider_class.py

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIModel
from pydantic_ai.providers.deepseek import DeepSeekProvider

model = OpenAIModel(
    'deepseek-chat',
    provider=DeepSeekProvider(api_key='your-deepseek-api-key'),
)
agent = Agent(model)
...

您还可以使用自定义的 http_client 自定义任何提供商

deepseek_model_init_provider_custom.py

from httpx import AsyncClient

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIModel
from pydantic_ai.providers.deepseek import DeepSeekProvider

custom_http_client = AsyncClient(timeout=30)
model = OpenAIModel(
    'deepseek-chat',
    provider=DeepSeekProvider(
        api_key='your-deepseek-api-key', http_client=custom_http_client
    ),
)
agent = Agent(model)
...

Ollama

要使用 Ollama，您必须首先下载 Ollama 客户端，然后使用 Ollama 模型库下载模型。

您还必须确保在尝试向 Ollama 服务器发出请求时，Ollama 服务器正在运行。有关更多信息，请参阅 Ollama 文档。

本地使用示例

安装 ollama 后，您可以使用要使用的模型运行服务器

terminal-run-ollama

ollama run llama3.2

（如果您尚未下载 llama3.2 模型，这将拉取该模型）

然后运行您的代码，这是一个最简单的示例

ollama_example.py

from pydantic import BaseModel

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIModel
from pydantic_ai.providers.openai import OpenAIProvider


class CityLocation(BaseModel):
    city: str
    country: str


ollama_model = OpenAIModel(
    model_name='llama3.2', provider=OpenAIProvider(base_url='https://#:11434/v1')
)
agent = Agent(ollama_model, result_type=CityLocation)

result = agent.run_sync('Where were the olympics held in 2012?')
print(result.data)
#> city='London' country='United Kingdom'
print(result.usage())
"""
Usage(requests=1, request_tokens=57, response_tokens=8, total_tokens=65, details=None)
"""

使用远程服务器的示例

ollama_example_with_remote_server.py

from pydantic import BaseModel

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIModel
from pydantic_ai.providers.openai import OpenAIProvider

ollama_model = OpenAIModel(
    model_name='qwen2.5-coder:7b',  # (1)!
    provider=OpenAIProvider(base_url='http://192.168.1.74:11434/v1'),  # (2)!
)


class CityLocation(BaseModel):
    city: str
    country: str


agent = Agent(model=ollama_model, result_type=CityLocation)

result = agent.run_sync('Where were the olympics held in 2012?')
print(result.data)
#> city='London' country='United Kingdom'
print(result.usage())
"""
Usage(requests=1, request_tokens=57, response_tokens=8, total_tokens=65, details=None)
"""

在远程服务器上运行的模型的名称
远程服务器的 URL

Azure AI Foundry

如果您想使用 Azure AI Foundry 作为您的提供商，您可以使用 AzureProvider 类。

azure_provider_example.py

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIModel
from pydantic_ai.providers.azure import AzureProvider

model = OpenAIModel(
    'gpt-4o',
    provider=AzureProvider(
        azure_endpoint='your-azure-endpoint',
        api_version='your-api-version',
        api_key='your-api-key',
    ),
)
agent = Agent(model)
...

OpenRouter

要使用 OpenRouter，请先在 openrouter.ai/keys 创建 API 密钥。

获得 API 密钥后，您可以将其与 OpenAIProvider 一起使用

openrouter_model_init.py

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIModel
from pydantic_ai.providers.openai import OpenAIProvider

model = OpenAIModel(
    'anthropic/claude-3.5-sonnet',
    provider=OpenAIProvider(
        base_url='https://openrouter.ai/api/v1',
        api_key='your-openrouter-api-key',
    ),
)
agent = Agent(model)
...

Grok (xAI)

访问 xAI API 控制台并创建 API 密钥。获得 API 密钥后，您可以将其与 OpenAIProvider 一起使用

grok_model_init.py

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIModel
from pydantic_ai.providers.openai import OpenAIProvider

model = OpenAIModel(
    'grok-2-1212',
    provider=OpenAIProvider(base_url='https://api.x.ai/v1', api_key='your-xai-api-key'),
)
agent = Agent(model)
...

Perplexity

按照 Perplexity 入门指南创建 API 密钥。然后，您可以使用以下代码查询 Perplexity API

perplexity_model_init.py

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIModel
from pydantic_ai.providers.openai import OpenAIProvider

model = OpenAIModel(
    'sonar-pro',
    provider=OpenAIProvider(
        base_url='https://api.perplexity.ai',
        api_key='your-perplexity-api-key',
    ),
)
agent = Agent(model)
...

Fireworks AI

访问 Fireworks.AI 并在您的账户设置中创建 API 密钥。获得 API 密钥后，您可以将其与 OpenAIProvider 一起使用

fireworks_model_init.py

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIModel
from pydantic_ai.providers.openai import OpenAIProvider

model = OpenAIModel(
    'accounts/fireworks/models/qwq-32b',  # model library available at https://fireworks.ai/models
    provider=OpenAIProvider(
        base_url='https://api.fireworks.ai/inference/v1',
        api_key='your-fireworks-api-key',
    ),
)
agent = Agent(model)
...

Together AI

访问 Together.ai 并在您的账户设置中创建 API 密钥。获得 API 密钥后，您可以将其与 OpenAIProvider 一起使用

together_model_init.py

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIModel
from pydantic_ai.providers.openai import OpenAIProvider

model = OpenAIModel(
    'meta-llama/Llama-3.3-70B-Instruct-Turbo-Free',  # model library available at https://www.together.ai/models
    provider=OpenAIProvider(
        base_url='https://api.together.xyz/v1',
        api_key='your-together-api-key',
    ),
)
agent = Agent(model)
...

实现自定义模型

要实现对尚未支持的模型的支持，您需要子类化 Model 抽象基类。

对于流式传输，您还需要实现以下抽象基类

StreamedResponse

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

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

回退

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

在以下示例中，代理首先向 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', api_key='not-valid')
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',
    ),
]
"""

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

注意

每个模型的选项应单独配置。例如，base_url、api_key 和自定义客户端应在每个模型本身上设置，而不是在 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', api_key='not-valid')
anthropic_model = AnthropicModel('claude-3-5-sonnet-latest', api_key='not-valid')
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', api_key='not-valid')
anthropic_model = AnthropicModel('claude-3-5-sonnet-latest', api_key='not-valid')
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 才会移动到下一个模型。您可以通过将自定义的 fallback_on 参数传递给 FallbackModel 构造函数来自定义此行为。

模型

模型、接口和提供商

OpenAI

安装

配置

环境变量

provider 参数

自定义 OpenAI 客户端

Anthropic

安装

配置

环境变量

provider 参数

自定义 HTTP 客户端

Gemini

安装

配置

环境变量

provider 参数

通过 VertexAI 使用 Gemini

安装

配置

应用程序默认凭据

服务账户

自定义区域

Groq

安装

配置

环境变量

provider 参数

Mistral

安装

配置

环境变量

provider 参数

Cohere

安装

配置

环境变量

api_key 参数

Bedrock

安装

配置

环境变量

provider 参数

OpenAI 兼容模型

Ollama

本地使用示例

使用远程服务器的示例

Azure AI Foundry

OpenRouter

Grok (xAI)

Perplexity

Fireworks AI

Together AI

实现自定义模型

回退

`provider` 参数

`provider` 参数

`provider` 参数

`provider` 参数

`provider` 参数

`api_key` 参数

`provider` 参数