Instructor — библиотека для Python, которая превращает ответы LLM в провалидированные объекты Pydantic и умеет повторять запрос, если валидация не прошла. Она патчит клиент OpenAI, а её документация описывает работу с OpenAI-совместимыми серверами через base_url. BroadNet Inference отдаёт chat completions по адресу https://inference.broadnet.ai/v1 и указывает инструменты и структурированный вывод для 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 в схему инструмента, через tool_choice заставляет модель вызвать этот инструмент и валидирует аргументы. Параметр max_retries задаёт, сколько раз Instructor переспросит модель, передав ей ошибку валидации, если объект не прошёл проверку.
Или через 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 модели.
Какой режим выбрать
| Режим | Что отправляется | С BroadNet |
|---|---|---|
Mode.TOOLS (по умолчанию) |
Принудительный вызов инструмента с вашей схемой | Да, на GLM 5.3 или Qwen3.8 27B |
Mode.JSON_SCHEMA |
response_format типа json_schema |
Да, на 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}},
]}],
)
На ключе с оплатой по факту изображение учитывается как входные токены. См. чтение арабских счетов с помощью vision-моделей.
Как мы это проверяли
15 ноября 2026 г. мы установили instructor 1.17.0 и openai 3.3.0 в чистое виртуальное окружение и запустили примеры выше против локального mock-сервера, который отвечает в формате chat completions BroadNet. Мы прочитали записанные запросы. Mode.TOOLS отправил схему как инструмент с принудительным tool_choice, Mode.JSON_SCHEMA — формат ответа json_schema, и оба вернули валидный 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 одновременно. Каждый повтор валидации — это ещё один запрос. См. ошибки и повторные запросы.
