BroadRouter
开始使用

在 BroadNet Inference 上用 Instructor 获取结构化输出

更新于

用 instructor.from_openai 包装一个 OpenAI 客户端(base_url 为 https://inference.broadnet.ai/v1,密钥为你的 BroadNet 密钥),然后调用 chat.completions.create,把 response_model 设为你的 Pydantic 类,model 设为 broadnet/glm-5.3 或 broadnet/qwen3.8-27b。BroadNet 只为这两个模型列出了工具和结构化输出。默认是 Mode.TOOLS,Mode.JSON_SCHEMA 也可以用。

Instructor 是一个 Python 库,能把大模型的回复转换成经过校验的 Pydantic 对象,校验失败时还可以重试。它会给 OpenAI 客户端打补丁,它的文档也介绍了如何通过 base_url 连接 OpenAI 兼容服务器。BroadNet Inference 在 https://inference.broadnet.ai/v1 上提供 chat completions,并为 GLM 5.3 和 Qwen3.8 27B 列出了工具和结构化输出。BroadRouter 是 BroadNet 自己的网站;本文依据 Instructor 1.17.0 版的文档。

安装

pip install instructor
export BROADNET_API_KEY='your-broadnet-key'

提取一个对象

import os
import instructor
from openai import OpenAI
from pydantic import BaseModel

class Invoice(BaseModel):
    vendor: str
    total: float
    currency: str

client = instructor.from_openai(
    OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"]),
    mode=instructor.Mode.TOOLS,
)

invoice = client.chat.completions.create(
    model="broadnet/glm-5.3",
    response_model=Invoice,
    max_tokens=4000,
    messages=[{"role": "user", "content": "Acme Trading invoice, total 1,250.00 SAR"}],
)
print(invoice)

Instructor 会把 Invoice 转换成工具 schema,用 tool_choice 强制模型调用它,再校验返回的参数。对象校验不通过时,Instructor 会带着校验错误再次请求;用 max_retries 控制重试次数。

或者用 from_provider

pclient = instructor.from_provider(
    "openai/broadnet/glm-5.3",
    base_url="https://inference.broadnet.ai/v1",
    api_key=os.environ["BROADNET_API_KEY"],
)
invoice = pclient.create(response_model=Invoice, max_tokens=4000,
                         messages=[{"role": "user", "content": "Acme Trading, 1,250.00 SAR"}])

openai/ 这一段决定用哪个客户端,剩下的 broadnet/glm-5.3 作为模型 ID 发送。

选哪种 mode

Mode 发送的内容 在 BroadNet 上能否使用
Mode.TOOLS(默认) 带你的 schema 的强制工具调用 可以,用 GLM 5.3 或 Qwen3.8 27B
Mode.JSON_SCHEMA 类型为 json_schema 的 response_format 可以,用 GLM 5.3 或 Qwen3.8 27B
Mode.MD_JSON 普通请求;从文本中解析 JSON 其他模型的后备方案;先测试
Mode.RESPONSES_TOOLS Responses API 不行:BroadNet 提供的是 chat completions

图片

Qwen3.8 27B 同时支持图片和工具,可以直接把照片或扫描件读成你的模型对象:

import base64
img = base64.b64encode(open("invoice.jpg", "rb").read()).decode()
invoice = client.chat.completions.create(
    model="broadnet/qwen3.8-27b",
    response_model=Invoice,
    max_tokens=4000,
    messages=[{"role": "user", "content": [
        {"type": "text", "text": "Extract the invoice fields."},
        {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64," + img}},
    ]}],
)

使用按量付费密钥时,图片按输入 token 计费。参见用视觉模型读取阿拉伯语发票。

我们是怎么测试的

2026-11-15,我们在一个干净的虚拟环境中安装了 instructor 1.17.0 和 openai 3.3.0,用上面的示例去请求一个模拟 BroadNet chat completions 格式的本地 mock 服务器,并查看了记录下来的请求。Mode.TOOLS 把 schema 作为工具发送,并强制设置了 tool_choice;Mode.JSON_SCHEMA 发送了 json_schema 类型的 response format;两者都返回了有效的 Invoice。from_provider 原样发送了模型 ID。我们的 mock 不会输出自由文本形式的 JSON,所以没有测试 Mode.MD_JSON,也没有发送图片示例。我们没有 BroadNet 密钥,因此没有测试真实的模型输出。

故障排查

  • 校验一直重试却始终不成功。 在 GLM 5.3 和 Qwen3.8 27B 上,思考内容计入 max_tokens。上限太低可能会把工具参数截断。调高它。为什么回答会是空的。
  • 请求返回 400。 确认你用的是 GLM 5.3 或 Qwen3.8 27B。如果强制的 tool_choice 被拒绝,试试 Mode.JSON_SCHEMA。
  • 401。 密钥不对、已过期或额度已用完。
  • 404。 base_url 必须以 /v1 结尾。GLM 5.3 和 Qwen3.8 27B 需要先充值;$5 额度不覆盖它们。
  • 批量提取时出现 429。 按量付费密钥每分钟允许 30 个请求,同时最多 4 个进行中的请求。每次校验重试都是一个新请求。参见错误码与重试。

常见问题

接 BroadNet 时 Instructor 应该用哪种 mode?

用默认的 Mode.TOOLS,配合 GLM 5.3 或 Qwen3.8 27B,BroadNet 为这两个模型列出了工具和结构化输出。Mode.JSON_SCHEMA 则改为发送 json_schema 类型的 response_format。在我们的 mock 服务器测试中,两者都得到了有效的对象。

可以用 Mode.RESPONSES_TOOLS 吗?

不可以。Instructor 的文档说,除非服务器实现了 Responses API,否则不要选它。BroadNet 只提供 chat completions。

Instructor 能配合 BroadNet 上的 DeepSeek V4.1 Flash 或 Gemma 使用吗?

BroadNet 没有为这两个模型列出工具或结构化输出。Mode.MD_JSON 会要求模型在纯文本中输出 JSON 再解析,也许可行,但请先用你自己的数据测试,再决定是否依赖它。

from_provider 的模型字符串怎么写?

写成 openai/broadnet/glm-5.3。Instructor 会把第一段拆出来作为供应商;在我们的测试中,它把 broadnet/glm-5.3 原样发给了服务器。

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