Instructor è una libreria Python che trasforma le risposte di un LLM in oggetti Pydantic validati e può riprovare quando la validazione fallisce. Applica una patch al client OpenAI, e la sua documentazione copre i server compatibili con OpenAI tramite base_url. BroadNet Inference serve chat completions su https://inference.broadnet.ai/v1 e indica strumenti e output strutturato per GLM 5.3 e Qwen3.8 27B. BroadRouter è il sito di BroadNet; la guida segue la documentazione di Instructor alla versione 1.17.0.
Installazione
pip install instructor
export BROADNET_API_KEY='your-broadnet-key'
Estrarre un oggetto
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 trasforma Invoice in uno schema di strumento, obbliga il modello a chiamarlo con tool_choice e valida gli argomenti. Con max_retries decidi quante volte richiedere, passando l’errore di validazione, quando l’oggetto non è valido.
Oppure usa 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"}])
La parte openai/ sceglie il client. Il resto, broadnet/glm-5.3, viene inviato come ID del modello.
Quale mode
| Mode | Cosa invia | Da usare con BroadNet |
|---|---|---|
Mode.TOOLS (default) |
Una chiamata forzata a uno strumento con il tuo schema | Sì, su GLM 5.3 o Qwen3.8 27B |
Mode.JSON_SCHEMA |
response_format di tipo json_schema |
Sì, su GLM 5.3 o Qwen3.8 27B |
Mode.MD_JSON |
Una richiesta semplice; JSON estratto dal testo | Ripiego per gli altri modelli; provalo prima |
Mode.RESPONSES_TOOLS |
La Responses API | No: BroadNet serve chat completions |
Immagini
Qwen3.8 27B accetta immagini oltre agli strumenti, quindi può leggere una foto o una scansione e riversarla direttamente nel tuo modello:
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}},
]}],
)
Con una chiave a consumo un’immagine conta come token di input. Vedi leggere fatture in arabo con la visione.
Come l’abbiamo testato
Il 2026-11-15 abbiamo installato instructor 1.17.0 con openai 3.3.0 in un ambiente virtuale pulito ed eseguito gli esempi qui sopra contro un mock server locale che riproduce il formato chat completions di BroadNet. Abbiamo letto le richieste registrate. Mode.TOOLS ha inviato lo schema come strumento con un tool_choice forzato, Mode.JSON_SCHEMA ha inviato un response format json_schema, ed entrambi hanno restituito un Invoice valido. from_provider ha inviato l’ID del modello invariato. Il nostro mock non scrive JSON come testo libero, quindi non abbiamo testato Mode.MD_JSON, e non abbiamo inviato l’esempio con l’immagine. Non avevamo una chiave BroadNet, quindi non abbiamo testato l’output reale dei modelli.
Risoluzione dei problemi
- Retry di validazione che non vanno mai a buon fine. Su GLM 5.3 e Qwen3.8 27B il ragionamento conta in
max_tokens. Un limite basso può troncare gli argomenti dello strumento. Alzalo. Perché le risposte arrivano vuote. - 400 sulla richiesta. Controlla di usare GLM 5.3 o Qwen3.8 27B. Se un
tool_choiceforzato viene rifiutato, provaMode.JSON_SCHEMA. - 401. La chiave è sbagliata, scaduta o ha esaurito la quota.
- 404.
base_urldeve finire con/v1. GLM 5.3 e Qwen3.8 27B richiedono una ricarica; il credito di $5 non li copre. - 429 durante l’estrazione in batch. Una chiave a consumo consente 30 richieste al minuto e 4 in corso contemporaneamente. Ogni retry di validazione è un’altra richiesta. Vedi errori e retry.
