BroadRouter

在 BroadNet Inference 上使用 Pydantic AI(OpenAICompatibleProvider)

更新于

安装 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 版的文档。

安装

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

连接

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。

工具和结构化输出

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 来说,有两个设置值得了解:

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 上下文)

各模型价格。

故障排查

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

常见问题

接入 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 参考文档所描述的字段。

以 Markdown 格式阅读问 ChatGPT问 Claude问 Perplexity