BroadRouter
Começar

Saída estruturada com o Instructor na BroadNet Inference

Atualizado em

Envolva com instructor.from_openai um cliente OpenAI com base_url https://inference.broadnet.ai/v1 e a sua chave da BroadNet, depois chame chat.completions.create com response_model igual à sua classe Pydantic e model como broadnet/glm-5.3 ou broadnet/qwen3.8-27b. São os dois modelos que a BroadNet lista com ferramentas e saída estruturada. O padrão é Mode.TOOLS; Mode.JSON_SCHEMA também funciona.

O Instructor é uma biblioteca Python que transforma respostas de LLM em objetos Pydantic validados e pode tentar de novo quando a validação falha. Ele modifica o cliente OpenAI, e a documentação dele cobre servidores compatíveis com a OpenAI por meio de base_url. A BroadNet Inference oferece chat completions em https://inference.broadnet.ai/v1 e lista ferramentas e saída estruturada para GLM 5.3 e Qwen3.8 27B. O BroadRouter é o site da própria BroadNet; este guia segue a documentação do Instructor na versão 1.17.0.

Instalação

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

Extrair um objeto

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)

O Instructor transforma Invoice em um schema de ferramenta, obriga o modelo a chamá-la com tool_choice e valida os argumentos. Passe max_retries para controlar quantas vezes ele pede de novo, enviando o erro de validação, quando o objeto não valida.

Ou use 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"}])

A parte openai/ escolhe o cliente. O resto, broadnet/glm-5.3, é enviado como ID do modelo.

Qual mode usar

Mode O que envia Usar com a BroadNet
Mode.TOOLS (padrão) Uma chamada de ferramenta forçada com o seu schema Sim, no GLM 5.3 ou no Qwen3.8 27B
Mode.JSON_SCHEMA response_format do tipo json_schema Sim, no GLM 5.3 ou no Qwen3.8 27B
Mode.MD_JSON Uma requisição simples; JSON extraído do texto Alternativa para outros modelos; teste antes
Mode.RESPONSES_TOOLS A Responses API Não: a BroadNet oferece chat completions

Imagens

O Qwen3.8 27B aceita imagens além de ferramentas, então consegue ler uma foto ou um documento digitalizado direto para o seu modelo:

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}},
    ]}],
)

Em uma chave de pagamento por uso, a imagem conta como tokens de entrada. Veja leitura de notas fiscais em árabe com visão.

Como testamos

Em 2026-11-15 instalamos o instructor 1.17.0 com o openai 3.3.0 em um ambiente virtual limpo e rodamos os exemplos acima contra um servidor mock local que imita o formato de chat completions da BroadNet. Lemos as requisições registradas. Mode.TOOLS enviou o schema como ferramenta com um tool_choice forçado, Mode.JSON_SCHEMA enviou um response format json_schema, e os dois retornaram um Invoice válido. O from_provider enviou o ID do modelo sem alteração. O nosso mock não escreve JSON em texto livre, então não testamos Mode.MD_JSON, e não enviamos o exemplo com imagem. Não tínhamos uma chave da BroadNet, então não testamos a saída real dos modelos.

Solução de problemas

  • Novas tentativas de validação que nunca dão certo. No GLM 5.3 e no Qwen3.8 27B, o raciocínio conta para max_tokens. Um limite baixo pode cortar os argumentos da ferramenta. Aumente o valor. Por que as respostas vêm vazias.
  • 400 na requisição. Confira se você está usando GLM 5.3 ou Qwen3.8 27B. Se um tool_choice forçado for recusado, tente Mode.JSON_SCHEMA.
  • 401. A chave está errada, expirou ou ficou sem cota.
  • 404. base_url precisa terminar em /v1. GLM 5.3 e Qwen3.8 27B exigem uma recarga; o crédito de $5 não cobre esses modelos.
  • 429 em extração em lote. Uma chave de pagamento por uso permite 30 requisições por minuto e 4 em andamento. Cada nova tentativa de validação é mais uma requisição. Veja erros e novas tentativas.

Perguntas frequentes

Qual mode do Instructor devo usar com a BroadNet?

Mode.TOOLS, o padrão, no GLM 5.3 ou no Qwen3.8 27B, que a BroadNet lista com ferramentas e saída estruturada. Mode.JSON_SCHEMA envia um response_format json_schema. Os dois geraram objetos válidos no nosso teste com servidor mock.

Posso usar Mode.RESPONSES_TOOLS?

Não. A documentação do Instructor diz para não escolhê-lo a menos que o servidor implemente a Responses API. A BroadNet oferece só chat completions.

O Instructor funciona com DeepSeek V4.1 Flash ou Gemma na BroadNet?

A BroadNet não lista ferramentas nem saída estruturada para esses modelos. Mode.MD_JSON pede JSON em texto simples e faz o parse, o que pode funcionar, mas teste com os seus próprios dados antes de depender disso.

Como escrevo a string do modelo no from_provider?

Use openai/broadnet/glm-5.3. O Instructor separa o primeiro segmento como provedor e, no nosso teste, enviou broadnet/glm-5.3 ao servidor sem alteração.

Ler em MarkdownPerguntar ao ChatGPTPerguntar ao ClaudePerguntar ao Perplexity