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 个进行中的请求。每次校验重试都是一个新请求。参见错误码与重试。
