# 用显式 Chat 模型把 Pydantic AI 接到 Router One

> https://router.one/zh/integrations/pydantic-ai 的 Markdown 镜像，供 AI 助手与爬虫使用。Router One 是 OpenAI 兼容的统一 LLM API 网关。
> 最后更新：2026-09-05

Pydantic AI 用 Python 构建带类型化结果和应用工具的 Agent。把 Router One 设为模型 provider 后，Agent 循环、结果校验、工具执行和消息历史仍由 Pydantic AI 与你的应用管理。本指南先跑通普通文本 Chat Completions，再说明增加结构化输出或多次模型请求时需要核对什么。

## 安装 OpenAI 集成并设置凭证

使用 Python 3.10 或更新版本，在该环境安装带 openai 扩展的 pydantic-ai-slim；完整 pydantic-ai 包也包含该集成。下面是 macOS/Linux 的 shell 示例。运行前替换两个占位符，分别填入 Router One Key，以及当前目录中支持 Chat Completions 的精确模型 ID。ROUTER_ONE_* 是本示例定义并在代码中读取的环境变量，运行 Python 文件时需沿用同一环境。

`terminal`

```bash
python -m pip install "pydantic-ai-slim[openai]"
export ROUTER_ONE_API_KEY="sk-your-router-one-key"
export ROUTER_ONE_MODEL_ID="<exact-model-id-from-/models>"
```

## 把 Pydantic AI 配置到 Router One base URL

保存为 pydantic_ai_router_one.py，再运行 python pydantic_ai_router_one.py。OpenAIChatModel 显式选择 /v1/chat/completions；OpenAIProvider 接收带 /v1 的 base URL 和你的 Key。目录中的模型 ID 原样传入，若 ID 自带 provider 前缀也应保留。output_type=str 请求普通文本，让首次验证不依赖工具调用或 JSON schema 输出。request_limit=3 限制 Pydantic AI 为本次运行记录的模型请求次数。

`pydantic_ai_router_one.py`

```python
import os

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

model = OpenAIChatModel(
    os.environ["ROUTER_ONE_MODEL_ID"],
    provider=OpenAIProvider(
        base_url="https://api.router.one/v1",
        api_key=os.environ["ROUTER_ONE_API_KEY"],
    ),
)
agent = Agent(model, output_type=str)
result = agent.run_sync(
    "Reply with one short greeting.",
    usage_limits=UsageLimits(request_limit=3),
)
print(result.output)
```

## 文本跑通后，再选择类型化输出模式

需要类型化结果时，先用 pydantic.BaseModel 定义 schema，再选择输出模式。使用下表包装器时，从 pydantic_ai 导入 ToolOutput、NativeOutput 或 PromptedOutput；MySchema 表示你定义的模型类。Python 类型声明不能证明上游模型具备对应能力。Pydantic 在应用侧校验返回数据，校验重试可能产生新的模型请求。

| Agent 的 output_type | 工作方式 | 需要核对 |
| --- | --- | --- |
| str | 普通模型文本，即上面的示例 | Chat Completions 请求能够成功 |
| MySchema 或 ToolOutput(MySchema) | 通过输出工具返回结果；直接传 schema 类型时默认使用此模式 | 所选模型和端点支持 function/tool 调用 |
| NativeOutput(MySchema) | 使用模型原生 JSON schema 响应格式 | 原生结构化输出支持，以及该模型接受的 schema 约束 |
| PromptedOutput(MySchema) | 把 schema 放进提示，再解析和校验结果 | 模型仍可能返回无效数据，提示词并不强制执行 schema |

## 控制 Agent 预算，并逐次核对模型请求

一次 Agent 运行可能因工具执行或结果校验重试，包含多次模型请求。UsageLimits(request_limit=3) 是应用侧请求限制，不是「最多计费三次」或金额预算保证：SDK 的 HTTP 重试与网关的 provider 重试属于不同机制。为应用单独建立 Router One Key，并设置 maxSpend。在 Dashboard → Logs 按该 Key、时间、精确模型和 request_id 核对请求，再用网关记录的费用核账。Agent 级用量或成本估算不一定采用你的 Router One 费率。Router One 记录模型调用元数据，不执行 Python 工具，也不提供 Pydantic AI 的 Agent 状态和存储。

## Pydantic AI 该填哪个模型 ID？

从 /models 页复制精确的模型 ID，保留大小写、连字符和版本后缀，不要用展示名称代替。打开该模型的详情页，核对支持的 API 端点、上下文窗口和工具调用等能力，再与 Pydantic AI 当前选择的 provider 和功能对应。模型出现在目录里，不等于当前客户端能调用它的所有功能。建议为每个工具单独建 API Key，并设置 maxSpend 消费上限。

## Pydantic AI 用的是哪种 API 协议？

OpenAI 兼容描述的是接口格式，不能据此推断 Chat Completions（/v1/chat/completions）、Responses（/v1/responses）和 Anthropic Messages（/v1/messages）可以互换。先核对工具当前版本、provider 配置和实际请求路径，再查模型详情与 API 兼容性事实页。一次普通对话成功，也不能证明服务端工具、历史状态或文件编辑功能都受支持。

## 在 trace 里验证 Pydantic AI 的调用

先在 Pydantic AI 发出一次简单文本请求，再到 Dashboard → Logs 按时间、模型和 request_id 核对 trace：tokens、花费、延迟和状态码。成功后再分别验证流式输出、工具调用和多轮历史。失败时保留实际请求路径、完整错误消息及 request_id；没有对应日志时，先查客户端配置和网络，不能仅凭客户端报错认定是网关或上游故障。

## 常见问题

### 为什么显式使用 OpenAIChatModel，而不是 Agent('openai:...')？

按当前 Pydantic AI 官方文档，仅写 openai: 前缀时，会使用 OpenAIResponsesModel。本指南直接构造 OpenAIChatModel，让调用明确使用 Chat Completions，不依赖简写的默认行为。若主动改用 OpenAIResponsesModel，需重新核对模型与各项功能的 /v1/responses 支持；普通 Chat 请求成功不能证明这些能力兼容。

### 普通文本能跑，但类型化输出或 Agent 工具报错，区别在哪里？

先确认所用输出模式。把 BaseModel 传给 output_type 通常会增加工具 schema，NativeOutput 则使用 JSON schema 响应格式。核对精确模型与端点是否支持该能力，再查看完整错误及 request_id。工具 schema、strict 模式和 model profile 可能有 provider 特定要求，只按实际 API 文档调整。可先恢复 output_type=str，分别排查基础连接与输出模式支持。

### 在异步服务或 Notebook 里应该怎么调用？

示例使用 run_sync，适用于独立 Python 脚本。在已有异步事件循环内，改用 await agent.run(..., usage_limits=UsageLimits(request_limit=3))，再读取 result.output。工具执行、历史存储和框架埋点仍留在应用中，Router One Trace 对应每次到达网关的模型请求。

### Pydantic AI 能通过网关用哪些模型？

选用当前目录中同时支持 Pydantic AI 所用端点和所需功能的模型。精确 ID、当前单价与能力以 /models 及模型详情为准；不要仅按 GPT、Claude 等系列名判断兼容性。客户端能列出模型，只证明模型发现成功，仍需验证实际调用。

### 能列出模型，但调用报 400 或 404，怎么办？

先记录实际请求路径和错误消息，再核对精确模型 ID。400 可能是参数、工具类型或模型与端点不匹配；404 可能是请求路径或资源不存在，不能直接判定模型下线。若错误提示 must be called via，按它指明的端点调整客户端 provider，或换用支持当前端点的模型。不要在所有工具里统一增删 /v1 或 /chat/completions。

### 中国大陆能直连吗？

能。网关在大陆可直连、无需 VPN，配置与全球环境完全一致。

### 报 401/402/403/429 怎么排查？

先到 Dashboard → Logs 核对请求及错误消息。401 查 Key 是否传入和有效；402 查钱包余额与 maxSpend；403 查 Key 权限和访问限制；429 查请求频率、token 限额及上游限流，按错误来源处理。保留 request_id，再按错误码速查页逐项排查。

## 相关页面

- 全部接入指南：https://router.one/zh/integrations
- Pydantic AI 的 API 错误排查：https://router.one/zh/llm-api-error-codes
- API 兼容性：端点与功能对照：https://router.one/zh/facts/api-compatibility.md
- Responses API 配置与限制：https://router.one/zh/codex-responses-api
- Cline 接入：https://router.one/zh/integrations/cline
- Aider 接入：https://router.one/zh/integrations/aider
- OpenAI Python SDK 接入：https://router.one/zh/integrations/openai-sdk
- 结构化输出的 API 要求：https://router.one/zh/llm-structured-outputs
- 按 Key 追踪模型调用成本：https://router.one/zh/llm-cost-tracking
- Pydantic AI 官方文档：OpenAI 兼容 provider：https://pydantic.dev/docs/ai/models/openai/
- Pydantic AI 官方文档：输出模式：https://pydantic.dev/docs/ai/core-concepts/output/
- Pydantic AI 官方文档：UsageLimits：https://pydantic.dev/docs/ai/api/pydantic-ai/usage/
- 网关层负责什么：https://router.one/zh/llm-api-gateway
- OpenAI 兼容 API：https://router.one/zh/openai-compatible-api
- API 文档：https://router.one/zh/docs
- 本页规范地址：https://router.one/zh/integrations/pydantic-ai
- 模型与每模型 token 价格：https://router.one/zh/models （markdown：https://router.one/zh/models.md ）
- 定价：https://router.one/zh/pricing
- API 文档（markdown）：https://router.one/zh/docs.md
- 公司事实（markdown）：https://router.one/zh/facts/company.md