如何用 Pydantic AI Gateway 用一个 key 访问多个模型 provider

如何用 Pydantic AI Gateway 用一个 key 访问多个模型 provider

【免费下载链接】pydantic-aiHow Python does AI. Agents, realtime voice, image generation, embeddings. Every model, every interface, typed end to end.项目地址: https://gitcode.com/GitHub_Trending/py/pydantic-ai

如果你的 Python 服务同时调用 OpenAI、Anthropic、Google、Groq、AWS Bedrock 等多家模型，目前需要分别保存各家 API key、配置各自的 base URL 与 SDK。Pydantic AI Gateway 提供了一条替代路径：在 Pydantic Logfire 中开通 Gateway 并创建一把 Gateway API key，之后所有模型请求都通过gateway/<api_format>:<model_name>模型串发往同一个网关，由网关按请求路由到上游 provider。本文的主路径是：在 Pydantic AI 项目中用这把 key 替换掉多家 key，并用同一把 key 依次请求不同 provider 的模型完成验证。适用前提：pydantic-ai版本 1.16 或更高（Gateway 文档明确给出该版本要求），Python 3.10+（安装文档的要求）。

1. 在 Logfire 中开通 Gateway 并创建 API key

按 Gateway 文档 的 Quick Start，这是一组在 Logfire 控制台（logfire.pydantic.dev）完成的操作：

1. 注册并选择一个区域创建账户——区域（gateway-us或gateway-eu）会影响后续网关地址，创建后无法在代码里绕过；
2. 在组织设置（organization's settings）中激活 Gateway；
3. 进入组织的 Gateway settings，创建一把 API key，形如pylf_v...。

注意这把 key 是单 key 多 provider的核心：文档明确列出 "API key management: Access multiple LLM providers with a single Gateway key"。key 同时决定了计费方式——你可以选择 BYOK（自带各 provider 的 key）或直接在平台付费，两种模式共用同一把 Gateway key。

2. 升级 pydantic-ai 并配置密钥

Gateway 功能要求pydantic-ai1.16 及以上。升级命令（Gateway 文档原文给出两种）：

uv sync -P pydantic-ai

或：

pip install -U pydantic-ai

然后把 Gateway key 设置为环境变量：

export PYDANTIC_AI_GATEWAY_API_KEY="pylf_v..."

其中pylf_v...替换为你在 Logfire Gateway settings 中创建的 key。若环境变量未设置，gateway_provider(...)会直接抛出UserError，提示设置PYDANTIC_AI_GATEWAY_API_KEY或通过gateway_provider(..., api_key=...)传入（见 providers/gateway.py），这是"key 没配好"时最直接的报错现象。

3. 用gateway/<provider>:<model>模型串请求不同 provider

配置好环境变量后，Agent的模型串从直接指定 provider 改为gateway/<api_format>:<model_name>格式，代码其余部分不变：

from pydantic_ai import Agent agent = Agent('gateway/openai:gpt-5.2') result = agent.run_sync('Where does "hello world" come from?') print(result.output)

文档示例输出（仅示例，实际回复以模型为准）：

The first known use of "hello, world" was in a 1974 textbook about the C programming language.

同一把 key 访问其他 provider，只需要改模型串。Gateway 文档给出的 provider / API 格式 / 示例模型对照如下：

也就是说，上面脚本中的Agent('gateway/openai:gpt-5.2')换成Agent('gateway/anthropic:claude-sonnet-4-6')即改为请求 Anthropic 的模型，PYDANTIC_AI_GATEWAY_API_KEY保持不变。一个边界说明：gateway/google是gateway/google-cloud的便捷别名，二者落到同一后端（源码中见 normalize_gateway_provider 的别名表）；图片生成经由网关时使用的就是gateway/google:<model>形式。

4. 可选：直接传 key 或用 route 指定上游端点

如果你不想依赖环境变量，可以在代码里直接创建 provider（Gateway 文档"Passing API Key directly"一节）：

from pydantic_ai import Agent from pydantic_ai.models.openai import OpenAIChatModel from pydantic_ai.providers.gateway import gateway_provider provider = gateway_provider('openai', api_key='pylf_v...') model = OpenAIChatModel('gpt-5.2', provider=provider) agent = Agent(model)

这里api_key='pylf_v...'需替换为你的 Gateway key。gateway_provider还支持route参数，用于选择替代的上游 provider 或自定义网关端点：

provider = gateway_provider( 'openai', api_key='pylf_v...', route='builtin-openai', )

route取的是 Logfire 中网关端点的 slug（不传时使用该 API 格式的默认端点，见 gateway_provider 的文档说明）。base_url参数同理：不传时会依次读取PYDANTIC_AI_GATEWAY_BASE_URL环境变量，再不行就从 key 中编码的区域推断（如https://gateway-us.pydantic.dev/proxy）；若 key 无法推断区域，源码会抛出要求"重新生成 key 或显式设置PYDANTIC_AI_GATEWAY_BASE_URL"的UserError。

5. 验证接入是否生效

文档给出的验证方式是直接跑请求：run_sync返回非空回复（如第 3 节示例输出）即说明这把 key 已成功路由到上游。要确认"一把 key 访问多个 provider"，把模型串依次替换为对照表中的gateway/anthropic:...、gateway/groq:...、gateway/bedrock:...等再各跑一次即可。

仓库内还有一个更完整的验证脚本可供参考：tests/providers/test_gateway_catalog.py 会对所有已知的gateway/模型串做冒烟测试，断言agent.run与run_stream都能拿到非空输出；该测试需要--run-gateway-live参数与PYDANTIC_AI_GATEWAY_API_KEY（或旧名PAIG_API_KEY），且会向真实上游发起请求，属于仓库 CI 用途，不需要在日常接入中运行。

6. 常见问题与限制

• 请求被拒，报"无法计算花费"：每个 provider 设置中有一个Require pricing data开关（默认开启）。开启时，网关对没有定价数据的模型会在转发前直接拒绝——内置（Pydantic 托管）provider 返回404，提示到 Slack 反馈以便补录模型；自定义（BYOK）provider 返回400，提示需要定价数据，并说明可以关闭该开关放行。关闭后请求能过，但花费不计入成本限额。这是接入新模型时最容易遇到的拦截。
• 支持范围有限：当前网关覆盖 OpenAI、Anthropic、Google Vertex、Groq、AWS Bedrock 五家（文档注明 "More providers coming soon"）；模型串里的 API 格式必须以这五家之一为准，不支持的格式会抛出Unknown upstream provider错误。
• 区域绑定：key 与 Logfire 区域绑定，推断出的 base URL 为https://gateway-{region}.pydantic.dev/proxy；跨区域访问需要换 key 或显式设置 base URL。
• 多 provider 容灾与负载：如需让同一模型在多个 provider 之间 failover 或按权重负载均衡，在 Logfire 的 Gateway -> Endpoints 中创建网关端点（为各 provider 设置 Priority、Weight、Active），再在gateway_provider(..., route='<端点 slug>')中引用该 slug——这属于网关端配置，代码侧只改route一个参数。

Gateway 文档同时还给出了 Claude Code、Codex、OpenAI SDK / Anthropic SDK / Vercel AI SDK 直连网关 proxy 路径的配置方式（gateway-us/gateway-eu两套 base URL），如果你的调用方不是 Pydantic AI 而是这些工具，可按 Gateway 文档 的对应章节操作，key 仍是同一把。

【免费下载链接】pydantic-aiHow Python does AI. Agents, realtime voice, image generation, embeddings. Every model, every interface, typed end to end.项目地址: https://gitcode.com/GitHub_Trending/py/pydantic-ai