---
title: "Instructor 配置 OpenAI 兼容 base_url（Pydantic） | BroadRouter"
description: "用 Instructor 从 BroadNet Inference 提取 Pydantic 对象：通过 from_openai 或 from_provider 设置自定义 base_url，并选对 Mode。"
url: https://broadrouter.com/zh/guides/instructor-structured-output/
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/instructor-structured-output/) (2026-11-16 更新).

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

更新于 2026-11-16

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

## 安装

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

## 提取一个对象

```python
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

```python
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 同时支持图片和工具，可以直接把照片或扫描件读成你的模型对象：

```python
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 计费。参见[用视觉模型读取阿拉伯语发票](https://broadrouter.com/zh/guides/read-arabic-invoices-with-vision/)。

## 我们是怎么测试的

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`。上限太低可能会把工具参数截断。调高它。[为什么回答会是空的](https://broadrouter.com/zh/guides/reasoning-tokens-empty-response/)。
-   **请求返回 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 个进行中的请求。每次校验重试都是一个新请求。参见[错误码与重试](https://broadrouter.com/zh/guides/errors-and-retries/)。

## 本指南涉及的术语

[Chat Completions API（对话补全接口）](https://broadrouter.com/zh/glossary/chat-completions-api/)

Chat Completions API 是 OpenAI 的 HTTP 端点 POST /v1/chat/completions，它接收模型名称和一组带角色标记的消息，返回模型的下一条消息。它的请求与响应结构已成为 OpenAI 兼容服务商和各类 SDK 通用的格式。

[按量付费（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 资源。

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

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

[输入 token 与输出 token](https://broadrouter.com/zh/glossary/input-and-output-tokens/)

输入 token 是语言模型在一次请求中读取的 token，包括系统提示词、对话历史、工具定义和图片。输出 token 是模型生成回复的 token，包括思考内容。大模型 API 通常分别计价，输出一般更贵。

[速率限制（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 计费。

[tool\_choice（工具选择参数）](https://broadrouter.com/zh/glossary/tool-choice/)

tool\_choice 是控制工具使用的请求参数。在 OpenAI 的 Chat Completions 中，它可以是 auto（由模型决定）、required（必须调用一个或多个工具）、none（不用工具），或指定某个函数强制调用。Anthropic 对应的取值是 auto、any、tool 和 none。

## 常见问题

### 接 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 原样发给了服务器。

## 相关指南

-   [用 OpenAI Python SDK 调用 BroadNet Inference](https://broadrouter.com/zh/guides/openai-python-sdk/)
-   [在 BroadNet Inference 上使用 Pydantic AI（OpenAICompatibleProvider）](https://broadrouter.com/zh/guides/pydantic-ai-openai-compatible/)
-   [用视觉模型识别阿拉伯语发票和收据](https://broadrouter.com/zh/guides/read-arabic-invoices-with-vision/)
-   [推理模型为什么返回空回答](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-instructor-structured-output&utm_content=page-cta) ·

**来源**

-   [Instructor 文档：OpenAI 与 OpenAI 兼容服务器（核对于 2026-11-15）](https://python.useinstructor.com/integrations/openai/)
-   [PyPI：instructor 1.17.0（核对于 2026-11-15）](https://pypi.org/project/instructor/)
-   [BroadNet Inference API 参考文档（核对于 2026-11-15） （英文）](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=zh-guides-instructor-structured-output&utm_content=sources)
