---
title: "Instructor con base_url compatibile OpenAI (Pydantic)"
description: "Estrai oggetti Pydantic da BroadNet Inference con Instructor, usando from_openai o from_provider con un base_url personalizzato, e scegli il Mode giusto."
url: https://broadrouter.com/it/guides/instructor-structured-output/
lang: it
updated: 2026-11-16
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

Tradotto dall’inglese con l’aiuto dell’IA. [Leggi l’originale in inglese](https://broadrouter.com/guides/instructor-structured-output/) (aggiornato il 2026-11-16).

# Output strutturato con Instructor su BroadNet Inference

Aggiornato 2026-11-16

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

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

## Estrarre un oggetto

```python
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

```python
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:

```python
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](https://broadrouter.com/it/guides/read-arabic-invoices-with-vision/).

## 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](https://broadrouter.com/it/guides/reasoning-tokens-empty-response/).
-   **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](https://broadrouter.com/it/guides/errors-and-retries/).

## Termini in questa guida

[Pagamento a consumo (pay-as-you-go)](https://broadrouter.com/it/glossary/pay-as-you-go/)

Il pagamento a consumo è un modello di prezzo in cui paghi solo ciò che usi, misurato per unità come token, richieste o minuti di audio, senza abbonamento né impegno minimo. La maggior parte delle API LLM fattura così, da un saldo prepagato o con una fattura periodica.

[Chat Completions API](https://broadrouter.com/it/glossary/chat-completions-api/)

La Chat Completions API è l’endpoint HTTP di OpenAI, POST /v1/chat/completions, che riceve il nome di un modello e una lista di messaggi con un ruolo e restituisce il messaggio successivo del modello. La forma della sua richiesta e risposta è diventata il formato comune che riusano provider e SDK compatibili con OpenAI.

[Concorrenza (concurrency)](https://broadrouter.com/it/glossary/concurrency/)

La concorrenza è il numero di richieste che un client ha in corso nello stesso momento. Le API LLM spesso la limitano per chiave o per piano, separatamente dalle richieste al minuto, perché ogni richiesta aperta occupa capacità GPU finché la sua risposta non è terminata.

[Rate limit (limite di frequenza)](https://broadrouter.com/it/glossary/rate-limit/)

Un rate limit è un tetto che un’API pone a quanto un client può usarla in un intervallo di tempo, per esempio richieste al minuto o token al minuto. Le richieste oltre il limite vengono rifiutate, di solito con HTTP 429 Too Many Requests, finché l’uso non torna sotto la soglia.

[Token](https://broadrouter.com/it/glossary/token/)

Un token è l’unità di testo che un modello linguistico legge e scrive: una parola, una parte di parola, un segno di punteggiatura o una sequenza di byte prodotta dal tokenizer del modello. Le API LLM contano, limitano e di solito fatturano l’uso in token.

[Tool calling (chiamata di strumenti)](https://broadrouter.com/it/glossary/tool-calling/)

Il tool calling, detto anche function calling, è una funzionalità delle API LLM in cui il modello restituisce una richiesta strutturata di eseguire una funzione definita dallo sviluppatore, con argomenti JSON. L’applicazione esegue la funzione e rimanda il risultato; il modello non esegue mai codice da solo.

[Credito prepagato (prepaid credit)](https://broadrouter.com/it/glossary/prepaid-credit/)

Il credito prepagato è denaro aggiunto a un account API prima dell’uso. Ogni richiesta scala il proprio costo dal saldo e, quando il saldo si esaurisce, le richieste a consumo si fermano finché non ricarichi. Limita la spesa a quanto hai versato.

[Output strutturato (structured output)](https://broadrouter.com/it/glossary/structured-output/)

L’output strutturato è una funzionalità delle API LLM che vincola la risposta di un modello a un formato indicato dallo sviluppatore, di solito un JSON Schema, così il codice può interpretarla in modo affidabile. È più rigoroso della JSON mode, che garantisce un JSON valido ma non una struttura precisa.

## 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.

## Guide correlate

-   [Usare l’SDK Python di OpenAI con BroadNet Inference](https://broadrouter.com/it/guides/openai-python-sdk/)
-   [Usare Pydantic AI con BroadNet Inference (OpenAICompatibleProvider)](https://broadrouter.com/it/guides/pydantic-ai-openai-compatible/)
-   [Leggere fatture e scontrini in arabo con un modello vision](https://broadrouter.com/it/guides/read-arabic-invoices-with-vision/)
-   [Perché un modello di ragionamento restituisce una risposta vuota](https://broadrouter.com/it/guides/reasoning-tokens-empty-response/)
-   [Tutti gli strumenti che funzionano con BroadNet Inference (in inglese)](https://broadrouter.com/integrations/): SDK, agenti di coding, interfacce di chat e strumenti di automazione, con le impostazioni esatte per ciascuno

Provalo sul tuo carico di lavoro reale. I nuovi account partono con USD 5 di credito per Gemma e trascrizione. DeepSeek, GLM e Qwen3.8 richiedono una ricarica.

[Inizia](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=it-guides-instructor-structured-output&utm_content=page-cta) ·

**Fonti**

-   [Documentazione di Instructor, OpenAI e server compatibili con OpenAI (verificata il 2026-11-15)](https://python.useinstructor.com/integrations/openai/)
-   [PyPI, instructor 1.17.0 (verificato il 2026-11-15)](https://pypi.org/project/instructor/)
-   [Riferimento API di BroadNet Inference (verificato il 2026-11-15) (in inglese)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=it-guides-instructor-structured-output&utm_content=sources)
