BroadRouter
Inizia

Output strutturato con Instructor su BroadNet Inference

Aggiornato

Avvolgi con instructor.from_openai un client OpenAI con base_url https://inference.broadnet.ai/v1 e la tua chiave BroadNet, poi chiama chat.completions.create con response_model uguale alla tua classe Pydantic e model su broadnet/glm-5.3 o broadnet/qwen3.8-27b. Sono i due modelli per cui BroadNet indica strumenti e output strutturato. Il default è Mode.TOOLS; funziona anche Mode.JSON_SCHEMA.

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_choice forzato viene rifiutato, prova Mode.JSON_SCHEMA.
  • 401. La chiave è sbagliata, scaduta o ha esaurito la quota.
  • 404. base_url deve 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.

Domande frequenti

Quale mode di Instructor devo usare con BroadNet?

Mode.TOOLS, il default, su GLM 5.3 o Qwen3.8 27B, per cui BroadNet indica strumenti e output strutturato. Mode.JSON_SCHEMA invia invece un response_format json_schema. Entrambi hanno prodotto oggetti validi nel nostro test con un mock server.

Posso usare Mode.RESPONSES_TOOLS?

No. La documentazione di Instructor dice di non sceglierlo se il server non implementa la Responses API. BroadNet serve solo chat completions.

Instructor funziona con DeepSeek V4.1 Flash o Gemma su BroadNet?

BroadNet non indica strumenti né output strutturato per quei modelli. Mode.MD_JSON chiede il JSON come testo semplice e poi lo interpreta, il che potrebbe funzionare, ma provalo sui tuoi dati prima di farci affidamento.

Come scrivo la stringa del modello per from_provider?

Usa openai/broadnet/glm-5.3. Instructor separa il primo segmento come provider e, nel nostro test, ha inviato broadnet/glm-5.3 al server senza modificarlo.

Leggi in MarkdownChiedi a ChatGPTChiedi a ClaudeChiedi a Perplexity