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 文档中定义的 organization
、project
、base_url
等参数。
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。请注意,AsyncAzureOpenAI
是 AsyncOpenAI
的一个子类。
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).
"""
- 文件搜索工具和计算机使用工具也可以从
openai.types.responses
导入。
您可以在 OpenAI API 文档中了解更多关于 Responses API 和 Chat Completions API 之间的区别。
兼容 OpenAI 的模型
许多提供商和模型都与 OpenAI API 兼容,并且可以在 Pydantic AI 中与 OpenAIChatModel
一起使用。在开始之前,请检查上文的安装和配置说明。
要使用其他兼容 OpenAI 的 API,您可以利用 OpenAIProvider
的 base_url
和 api_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
。同样,您可以将提供商名称作为字符串传递给 OpenAIChatModel
的 provider
参数,而无需显式地实例化提供商类。
模型配置文件
有时,您正在使用的提供商或模型可能与 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)
- 远程服务器上运行的模型的名称
- 远程服务器的 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_KEY
和 HEROKU_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_base
和 api_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.
...