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_choiceforçado for recusado, tenteMode.JSON_SCHEMA. - 401. A chave está errada, expirou ou ficou sem cota.
- 404.
base_urlprecisa 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.
