---
title: "Pydantic AI 配置自定义 OpenAI 兼容 base_url | BroadRouter"
description: "用 OpenAIChatModel 和 OpenAICompatibleProvider 在 BroadNet Inference 上运行 Pydantic AI agent，包括工具调用、结构化输出和模型 profile 的调整。"
url: https://broadrouter.com/zh/guides/pydantic-ai-openai-compatible/
lang: zh-Hans
updated: 2026-11-16
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

本页由英文原文借助 AI 翻译。[阅读英文原文](https://broadrouter.com/guides/pydantic-ai-openai-compatible/)（2026-11-16 更新）。

# 在 BroadNet Inference 上使用 Pydantic AI（OpenAICompatibleProvider）

更新于 2026-11-16

安装 pydantic-ai-slim\[openai\]，然后创建 OpenAIChatModel：模型 ID 例如 broadnet/glm-5.3，provider 用 OpenAICompatibleProvider，base URL 设为 https://inference.broadnet.ai/v1，API 密钥填你的 BroadNet 密钥。再把模型传给 Agent。请使用 OpenAIChatModel 而不是 Responses 模型，因为 BroadNet 提供的是对话补全。Pydantic AI 的文档说，带 base\_url 的 OpenAIProvider 是给 OpenAI 本身用的。

Pydantic AI 是 Pydantic 团队开发的 Python agent 框架。对于没有内置供应商的服务，它的文档建议使用 `OpenAICompatibleProvider` 并传入该服务的 `base_url`。BroadNet Inference 在 `https://inference.broadnet.ai/v1` 上提供标准的对话补全，所以走的就是这条路。BroadRouter 是 BroadNet 自己的网站；本文依据 Pydantic AI 2.68 版的文档。

## 安装

```bash
pip install "pydantic-ai-slim[openai]"
export BROADNET_API_KEY='your-broadnet-key'
```

## 连接

```python
import os
from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai_compatible import OpenAICompatibleProvider

model = OpenAIChatModel(
    'broadnet/glm-5.3',
    provider=OpenAICompatibleProvider(
        'broadnet',
        base_url='https://inference.broadnet.ai/v1',
        api_key=os.environ['BROADNET_API_KEY'],
    ),
)

agent = Agent(model)
result = agent.run_sync('Give me three names for a Go linting tool.')
print(result.output)
```

运行这段代码就是测试：能打印出回答，说明密钥、URL 和模型 ID 都正确。

-   **第一个参数是模型 ID**，会原样发送给 BroadNet。请完整写上 `broadnet/` 前缀。
-   **供应商名称**（这里是 `'broadnet'`）会记录在每个响应上。Pydantic AI 的文档说要保持它不变，因为它决定了之前响应中的哪些数据会被回传给服务。
-   **坚持用 `OpenAIChatModel`。** Pydantic AI 的文档说，只有服务实现了 Responses API 时才使用 `OpenAIResponsesModel`。BroadNet 没有列出这个 API。

## 工具和结构化输出

```python
from pydantic import BaseModel

class City(BaseModel):
    name: str
    country: str

agent = Agent(model, output_type=City)
print(agent.run_sync('Which city hosts the Burj Khalifa?').output)
```

工具和结构化输出请使用 `broadnet/glm-5.3` 或 `broadnet/qwen3.8-27b`；BroadNet 的文档只为这两个模型列出了这两项功能。

## 什么时候需要设置模型 profile

Pydantic AI 会根据模型名称选择请求 profile。如果某个功能被忽略或被拒绝，它的文档建议传入你自己的 `OpenAIModelProfile`。对 BroadNet 来说，有两个设置值得了解：

```python
from pydantic_ai.profiles.openai import OpenAIModelProfile

model = OpenAIChatModel(
    'broadnet/glm-5.3',
    provider=OpenAICompatibleProvider('broadnet', base_url='https://inference.broadnet.ai/v1', api_key=os.environ['BROADNET_API_KEY']),
    profile=OpenAIModelProfile(
        openai_chat_supports_max_completion_tokens=False,  # send max_tokens, the field BroadNet documents
        openai_supports_strict_tool_definition=False,      # only if strict tool schemas are rejected
    ),
)
```

输出上限通过模型设置传入，例如 `agent.run_sync(prompt, model_settings={'max_tokens': 2000})`。在 DeepSeek V4.1 Flash、GLM 5.3 和 Qwen3.8 27B 上，思考内容计入这个上限。

## 选哪个模型

| Agent | 模型 |
| --- | --- |
| 工具、结构化输出 | `broadnet/glm-5.3` |
| 图片或阿拉伯语文本，带工具 | `broadnet/qwen3.8-27b` |
| 长文档、固定价格套餐 | `broadnet/deepseek-v4.1-flash` |
| 免费初始额度 | `broadnet/gemma-4-26b-a4b`（32,768 token 上下文） |

[各模型价格](https://broadrouter.com/zh/pricing/)。

## 故障排查

-   **401。** 密钥错误、已过期或额度已用完。
-   **404 或找不到模型。** `base_url` 必须以 `/v1` 结尾。检查模型 ID。付费模型需要先充值；$5 额度只能用于 `broadnet/gemma-4-26b-a4b` 和两个 Transcribe 模型。
-   **输出为空或陷入校验重试循环。** 思考用掉了输出预算。调高 `max_tokens`。[为什么回答会是空的](https://broadrouter.com/zh/guides/reasoning-tokens-empty-response/)。
-   **工具定义报 400。** 在 profile 中设置 `openai_supports_strict_tool_definition=False`，并使用 BroadNet 列出了工具的模型。
-   **并发运行 agent 时出现 429。** 按量付费密钥每分钟允许 30 个请求，同时最多 4 个在处理中。见[错误码与重试](https://broadrouter.com/zh/guides/errors-and-retries/)。

## 本指南涉及的术语

[结构化输出（structured output）](https://broadrouter.com/zh/glossary/structured-output/)

结构化输出是大模型 API 的一项功能，它把模型的回复约束为开发者指定的格式（通常是 JSON Schema），让代码能可靠地解析。它比 JSON mode 更严格：JSON mode 只保证输出是合法 JSON，不保证特定结构。

[AI 智能体（AI agent）](https://broadrouter.com/zh/glossary/agent/)

AI 智能体是由语言模型自主决定步骤、朝目标推进的系统：它决定调用哪些工具、读取结果，然后重复，直到给出最终回答或触及上限。在固定位置调用模型的固定脚本，通常称为工作流（workflow）。

[按量付费（pay-as-you-go）](https://broadrouter.com/zh/glossary/pay-as-you-go/)

按量付费是一种计价模式：你只为实际用量付费，按 token、请求次数或音频分钟等单位计量，没有订阅费，也没有最低消费承诺。大多数大模型 API 都这样计费，从预付余额中扣减或定期开具账单。

[并发（concurrency）](https://broadrouter.com/zh/glossary/concurrency/)

并发（concurrency）是客户端在同一时刻正在进行中的请求数。大模型 API 往往按密钥或套餐单独限制并发，与每分钟请求数分开计算，因为每个未完成的请求在响应结束前都会占用 GPU 资源。

[大模型包月套餐（flat-rate LLM plan）](https://broadrouter.com/zh/glossary/flat-rate-llm-plan/)

大模型包月套餐（固定价格套餐）是按一个周期（如一个月）收取固定费用、提供大模型 API 使用权的计价方式，不按 token 计费。这类套餐通常会限制别的东西，如并发、速度、模型或使用时间窗口，所以限制条件和价格同样重要。

[速率限制（rate limit）](https://broadrouter.com/zh/glossary/rate-limit/)

速率限制是 API 对客户端在一个时间窗口内的使用量设定的上限，例如每分钟请求数或每分钟 token 数。超出限制的请求会被拒绝，通常返回 HTTP 429 Too Many Requests，直到用量回落到限制以下。

[Token（词元）](https://broadrouter.com/zh/glossary/token/)

token（词元）是大语言模型读写文本的基本单位：由模型的分词器切分出的一个词、词的一部分、一个标点或一段字节序列。大模型 API 按 token 计数、设定限制，通常也按 token 计费。

## 常见问题

### 接入 BroadNet 该用 OpenAIProvider 还是 OpenAICompatibleProvider？

用 OpenAICompatibleProvider。Pydantic AI 的文档说，OpenAIProvider 虽然也能接收 base\_url，但它是给 OpenAI 本身或透明转发到 OpenAI 的代理用的，并且默认使用 OpenAI 的模型和功能。

### 为什么用 OpenAIChatModel，而不用默认的 OpenAI 模型？

Pydantic AI 默认的 OpenAI 模型使用 Responses API。BroadNet 在 /v1/chat/completions 上提供对话补全，而 OpenAIChatModel 调用的正是这个端点。

### 工具和结构化输出能用吗？

在 BroadNet 列出了工具和结构化输出的模型上可以，也就是 GLM 5.3 和 Qwen3.8 27B。BroadNet 的文档没有为 DeepSeek V4.1 Flash 列出工具，所以在它上面运行使用工具的 agent 之前请先测试。

### 怎么让 Pydantic AI 不发送 max\_completion\_tokens？

给 OpenAIChatModel 传入 profile=OpenAIModelProfile(openai\_chat\_supports\_max\_completion\_tokens=False)。这样 Pydantic AI 会改为发送旧的 max\_tokens 字段，也就是 BroadNet 的 API 参考文档所描述的字段。

## 相关指南

-   [用 OpenAI Python SDK 调用 BroadNet Inference](https://broadrouter.com/zh/guides/openai-python-sdk/)
-   [在 LangChain 中调用 BroadNet Inference](https://broadrouter.com/zh/guides/langchain-openai-base-url/)
-   [在 CrewAI 中把 BroadNet Inference 用作自定义 OpenAI 端点](https://broadrouter.com/zh/guides/crewai-custom-openai-endpoint/)
-   [推理模型为什么返回空回答](https://broadrouter.com/zh/guides/reasoning-tokens-empty-response/)
-   [所有可与 BroadNet Inference 配合使用的工具（英文）](https://broadrouter.com/integrations/)：SDK、编程智能体、聊天界面和自动化工具，并附每个工具的具体设置

用你的真实业务负载试一试。新账户可获得 US$5 初始额度，用于 Gemma和转写。DeepSeek、GLM和Qwen3.8 需要先充值。

[开始使用](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=zh-guides-pydantic-ai-openai-compatible&utm_content=page-cta) ·

**来源**

-   [Pydantic AI 文档：Other compatible APIs（Other endpoints、Model profile）（核对于 2026-11-15）](https://pydantic.dev/docs/ai/models/compatible-apis/)
-   [Pydantic AI 文档：OpenAI models（核对于 2026-11-15）](https://pydantic.dev/docs/ai/models/openai/)
-   [PyPI 上的 pydantic-ai 2.68.0（Python 3.11+）（核对于 2026-11-15）](https://pypi.org/project/pydantic-ai/)
-   [BroadNet Inference API 参考文档（核对于 2026-11-15）（英文）](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=zh-guides-pydantic-ai-openai-compatible&utm_content=sources)
