BroadRouter
Начать

Структурированный вывод через Instructor на BroadNet Inference

Обновлено

Оберните клиент OpenAI с base_url https://inference.broadnet.ai/v1 и ключом BroadNet в instructor.from_openai, затем вызовите chat.completions.create с response_model — вашим классом Pydantic — и model broadnet/glm-5.3 или broadnet/qwen3.8-27b. Только для этих двух моделей BroadNet указывает инструменты и структурированный вывод. По умолчанию используется Mode.TOOLS; Mode.JSON_SCHEMA тоже работает.

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 одновременно. Каждый повтор валидации — это ещё один запрос. См. ошибки и повторные запросы.

Вопросы и ответы

Какой режим Instructor использовать с BroadNet?

Mode.TOOLS, режим по умолчанию, на GLM 5.3 или Qwen3.8 27B — для них BroadNet указывает инструменты и структурированный вывод. Mode.JSON_SCHEMA вместо этого отправляет response_format типа json_schema. В нашем тесте с mock-сервером оба режима вернули валидные объекты.

Можно ли использовать Mode.RESPONSES_TOOLS?

Нет. Документация Instructor советует выбирать его, только если сервер реализует Responses API. BroadNet отдаёт только chat completions.

Работает ли Instructor с DeepSeek V4.1 Flash или Gemma на BroadNet?

Для этих моделей BroadNet не указывает инструменты и структурированный вывод. Mode.MD_JSON просит JSON обычным текстом и разбирает его; это может сработать, но сначала проверьте на своих данных.

Как записать строку модели для from_provider?

Пишите openai/broadnet/glm-5.3. Instructor отделяет первый сегмент как провайдера, и в нашем тесте отправил на сервер broadnet/glm-5.3 без изменений.

Открыть в MarkdownСпросить ChatGPTСпросить ClaudeСпросить Perplexity