跳转到内容

OpenAI

安装

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

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

配置

要通过 OpenAI API 使用 OpenAIChatModel,请前往 platform.openai.com 并按步骤操作,直到找到生成 API 密钥的地方。

环境变量

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

export OPENAI_API_KEY='your-api-key'

然后,您就可以通过名称来使用 OpenAIChatModel

from pydantic_ai import Agent

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

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

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel

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

默认情况下,OpenAIChatModel 使用 OpenAIProvider,其 base_url 设置为 https://api.openai.com/v1

配置提供商

如果您想在代码中向提供商传递参数,可以通过编程方式实例化 OpenAIProvider 并将其传递给模型

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

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

自定义 OpenAI 客户端

OpenAIProvider 还通过 openai_client 参数接受一个自定义的 AsyncOpenAI 客户端,这样您就可以自定义在 OpenAI API 文档中定义的 organizationprojectbase_url 等参数。

custom_openai_client.py
from openai import AsyncOpenAI

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

client = AsyncOpenAI(max_retries=3)
model = OpenAIChatModel('gpt-4o', provider=OpenAIProvider(openai_client=client))
agent = Agent(model)
...

您也可以使用 AsyncAzureOpenAI 客户端来使用 Azure OpenAI API。请注意,AsyncAzureOpenAIAsyncOpenAI 的一个子类。

from openai import AsyncAzureOpenAI

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

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

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

OpenAI Responses API

Pydantic AI 还通过 OpenAIResponsesModel 类支持 OpenAI 的 Responses API

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIResponsesModel

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

Responses API 内置了一些工具,您可以使用它们来代替自己构建工具

  • 网页搜索:允许模型在生成响应前搜索网页以获取最新信息。
  • 文件搜索:允许模型在生成响应前搜索您的文件以获取相关信息。
  • 计算机使用:允许模型使用计算机代表您执行任务。

您可以使用 OpenAIResponsesModelSettings 类来利用这些内置工具

from openai.types.responses import WebSearchToolParam  # (1)!

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIResponsesModel, OpenAIResponsesModelSettings

model_settings = OpenAIResponsesModelSettings(
    openai_builtin_tools=[WebSearchToolParam(type='web_search_preview')],
)
model = OpenAIResponsesModel('gpt-4o')
agent = Agent(model=model, model_settings=model_settings)

result = agent.run_sync('What is the weather in Tokyo?')
print(result.output)
"""
As of 7:48 AM on Wednesday, April 2, 2025, in Tokyo, Japan, the weather is cloudy with a temperature of 53°F (12°C).
"""
  1. 文件搜索工具和计算机使用工具也可以从 openai.types.responses 导入。

您可以在 OpenAI API 文档中了解更多关于 Responses API 和 Chat Completions API 之间的区别。

兼容 OpenAI 的模型

许多提供商和模型都与 OpenAI API 兼容,并且可以在 Pydantic AI 中与 OpenAIChatModel 一起使用。在开始之前,请检查上文的安装和配置说明。

要使用其他兼容 OpenAI 的 API,您可以利用 OpenAIProviderbase_urlapi_key 参数

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

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

各种提供商也有自己的提供商类,这样您就不需要自己指定基础 URL,并且可以使用标准的 <PROVIDER>_API_KEY 环境变量来设置 API 密钥。当一个提供商有自己的提供商类时,您可以使用 Agent("<provider>:<model>") 的简写形式,例如 Agent("deepseek:deepseek-chat")Agent("openrouter:google/gemini-2.5-pro-preview"),而无需显式地构建 OpenAIChatModel。同样,您可以将提供商名称作为字符串传递给 OpenAIChatModelprovider 参数,而无需显式地实例化提供商类。

模型配置文件

有时,您正在使用的提供商或模型可能与 OpenAI 的 API 或模型有略微不同的要求,例如对工具定义的 JSON 模式有不同的限制,或者不支持将工具定义标记为严格模式。

当使用 Pydantic AI 提供的替代提供商类时,通常会根据模型名称自动选择合适的模型配置文件。如果您使用的模型开箱即用时无法正常工作,您可以通过提供自己的 ModelProfile(用于所有模型类共享的行为)或 OpenAIModelProfile(用于 OpenAIChatModel 特有的行为)来调整模型请求构建的各个方面

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.profiles import InlineDefsJsonSchemaTransformer
from pydantic_ai.profiles.openai import OpenAIModelProfile
from pydantic_ai.providers.openai import OpenAIProvider

model = OpenAIChatModel(
    'model_name',
    provider=OpenAIProvider(
        base_url='https://<openai-compatible-api-endpoint>.com', api_key='your-api-key'
    ),
    profile=OpenAIModelProfile(
        json_schema_transformer=InlineDefsJsonSchemaTransformer,  # Supported by any model class on a plain ModelProfile
        openai_supports_strict_tool_definition=False  # Supported by OpenAIModel only, requires OpenAIModelProfile
    )
)
agent = Agent(model)

DeepSeek

要使用 DeepSeek 提供商,请首先按照快速入门指南创建一个 API 密钥。获得 API 密钥后,您可以将其与 DeepSeekProvider 一起使用

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

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

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

from httpx import AsyncClient

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

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

Ollama

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

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

然后,您可以将该模型与 OllamaProvider 一起使用。

本地使用示例

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

ollama run llama3.2

(如果您尚未下载 llama3.2 模型,此命令将会拉取该模型)

然后运行您的代码,这里是一个最小化的示例

from pydantic import BaseModel

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.ollama import OllamaProvider


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


ollama_model = OpenAIChatModel(
    model_name='llama3.2',
    provider=OllamaProvider(base_url='https://:11434/v1'),
)
agent = Agent(ollama_model, output_type=CityLocation)

result = agent.run_sync('Where were the olympics held in 2012?')
print(result.output)
#> city='London' country='United Kingdom'
print(result.usage())
#> RunUsage(input_tokens=57, output_tokens=8, requests=1)

使用远程服务器的示例

from pydantic import BaseModel

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.ollama import OllamaProvider

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


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


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

result = agent.run_sync('Where were the olympics held in 2012?')
print(result.output)
#> city='London' country='United Kingdom'
print(result.usage())
#> RunUsage(input_tokens=57, output_tokens=8, requests=1)
  1. 远程服务器上运行的模型的名称
  2. 远程服务器的 URL

Azure AI Foundry

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

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

model = OpenAIChatModel(
    '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 密钥后,您可以将其与 OpenRouterProvider 一起使用

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openrouter import OpenRouterProvider

model = OpenAIChatModel(
    'anthropic/claude-3.5-sonnet',
    provider=OpenRouterProvider(api_key='your-openrouter-api-key'),
)
agent = Agent(model)
...

Vercel AI 网关

要使用 Vercel 的 AI 网关,请首先按照文档说明获取 API 密钥或 OIDC 令牌。

您可以使用以下环境变量之一来设置您的凭据

export VERCEL_AI_GATEWAY_API_KEY='your-ai-gateway-api-key'
# OR
export VERCEL_OIDC_TOKEN='your-oidc-token'

设置环境变量后,您可以将其与 VercelProvider 一起使用

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.vercel import VercelProvider

# Uses environment variable automatically
model = OpenAIChatModel(
    'anthropic/claude-4-sonnet',
    provider=VercelProvider(),
)
agent = Agent(model)

# Or pass the API key directly
model = OpenAIChatModel(
    'anthropic/claude-4-sonnet',
    provider=VercelProvider(api_key='your-vercel-ai-gateway-api-key'),
)
agent = Agent(model)
...

Grok (xAI)

前往 xAI API 控制台并创建一个 API 密钥。获得 API 密钥后,您可以将其与 GrokProvider 一起使用

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.grok import GrokProvider

model = OpenAIChatModel(
    'grok-2-1212',
    provider=GrokProvider(api_key='your-xai-api-key'),
)
agent = Agent(model)
...

MoonshotAI (月之暗面)

月之暗面控制台中创建一个 API 密钥。有了该密钥,您就可以实例化 MoonshotAIProvider

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.moonshotai import MoonshotAIProvider

model = OpenAIChatModel(
    'kimi-k2-0711-preview',
    provider=MoonshotAIProvider(api_key='your-moonshot-api-key'),
)
agent = Agent(model)
...

GitHub 模型

要使用 GitHub 模型,您需要一个具有 models: read 权限的 GitHub 个人访问令牌。

获得令牌后,您可以将其与 GitHubProvider 一起使用

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.github import GitHubProvider

model = OpenAIChatModel(
    'xai/grok-3-mini',  # GitHub Models uses prefixed model names
    provider=GitHubProvider(api_key='your-github-token'),
)
agent = Agent(model)
...

您也可以设置 GITHUB_API_KEY 环境变量

export GITHUB_API_KEY='your-github-token'

GitHub 模型支持多种具有不同前缀的模型系列。您可以在 GitHub Marketplace 或公共的 目录端点上查看完整列表。

Perplexity

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

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

model = OpenAIChatModel(
    '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 密钥后,您可以将其与 FireworksProvider 一起使用

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.fireworks import FireworksProvider

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

Together AI

前往 Together.ai 并在您的账户设置中创建一个 API 密钥。获得 API 密钥后,您可以将其与 TogetherProvider 一起使用

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.together import TogetherProvider

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

Heroku AI

要使用 Heroku AI,您可以使用 HerokuProvider

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.heroku import HerokuProvider

model = OpenAIChatModel(
    'claude-3-7-sonnet',
    provider=HerokuProvider(api_key='your-heroku-inference-key'),
)
agent = Agent(model)
...

您可以设置 HEROKU_INFERENCE_KEYHEROKU_INFERENCE_URL 环境变量来分别设置 API 密钥和基础 URL

export HEROKU_INFERENCE_KEY='your-heroku-inference-key'
export HEROKU_INFERENCE_URL='https://us.inference.heroku.com'

Cerebras

要使用 Cerebras,您需要在 Cerebras 控制台中创建一个 API 密钥。

设置好 CEREBRAS_API_KEY 环境变量后,您可以运行以下代码

from pydantic_ai import Agent

agent = Agent('cerebras:llama3.3-70b')
result = agent.run_sync('What is the capital of France?')
print(result.output)
#> The capital of France is Paris.

如果您需要配置提供商,可以使用 CerebrasProvider

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.cerebras import CerebrasProvider

model = OpenAIChatModel(
    'llama3.3-70b',
    provider=CerebrasProvider(api_key='your-cerebras-api-key'),
)
agent = Agent(model)

result = agent.run_sync('What is the capital of France?')
print(result.output)
#> The capital of France is Paris.

LiteLLM

要使用 LiteLLM,请按照文档中的说明进行配置。在 LiteLLMProvider 中,您可以传递 api_baseapi_key。这些配置的值将取决于您的设置。例如,如果您使用 OpenAI 模型,那么您需要将 https://api.openai.com/v1 作为 api_base 传递,并将您的 OpenAI API 密钥作为 api_key 传递。如果您正在使用运行在本地机器上的 LiteLLM 代理服务器,那么您需要将 https://:<port> 作为 api_base 传递,并将您的 LiteLLM API 密钥(或一个占位符)作为 api_key 传递。

要使用自定义的 LLM,请在模型名称中使用 custom/ 前缀。

完成配置后,按如下方式使用 LiteLLMProvider

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.litellm import LiteLLMProvider

model = OpenAIChatModel(
    'openai/gpt-3.5-turbo',
    provider=LiteLLMProvider(
        api_base='<api-base-url>',
        api_key='<api-key>'
    )
)
agent = Agent(model)

result = agent.run_sync('What is the capital of France?')
print(result.output)
#> The capital of France is Paris.
...