---
title: "Pydantic AI con un base_url compatibile con OpenAI | BroadRouter"
description: "Esegui agenti Pydantic AI su BroadNet Inference con OpenAIChatModel e OpenAICompatibleProvider, con tool call, output strutturato e correzioni del profilo."
url: https://broadrouter.com/it/guides/pydantic-ai-openai-compatible/
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/pydantic-ai-openai-compatible/) (aggiornato il 2026-11-16).

# Usare Pydantic AI con BroadNet Inference (OpenAICompatibleProvider)

Aggiornato 2026-11-16

Installa pydantic-ai-slim\[openai\], poi crea OpenAIChatModel con un ID di modello BroadNet come broadnet/glm-5.3 e un OpenAICompatibleProvider con base URL https://inference.broadnet.ai/v1 e la tua chiave BroadNet come chiave API. Passa il modello ad Agent. Usa OpenAIChatModel, non il modello Responses, perché BroadNet serve chat completions. Secondo la documentazione di Pydantic AI, OpenAIProvider con base\_url è pensato per OpenAI stessa.

Pydantic AI è un framework Python per agenti creato dal team di Pydantic. Per un servizio senza provider integrato, la sua documentazione dice di usare `OpenAICompatibleProvider` con il `base_url` del servizio. BroadNet Inference serve chat completions standard su `https://inference.broadnet.ai/v1`, quindi la strada è questa. BroadRouter è il sito di BroadNet; questa guida segue la documentazione di Pydantic AI alla versione 2.68.

## Installazione

```bash
pip install "pydantic-ai-slim[openai]"
export BROADNET_API_KEY='your-broadnet-key'
```

## Connessione

```python
import os
from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai_compatible import OpenAICompatibleProvider

model = OpenAIChatModel(
    'broadnet/glm-5.3',
    provider=OpenAICompatibleProvider(
        'broadnet',
        base_url='https://inference.broadnet.ai/v1',
        api_key=os.environ['BROADNET_API_KEY'],
    ),
)

agent = Agent(model)
result = agent.run_sync('Give me three names for a Go linting tool.')
print(result.output)
```

Eseguirlo è già il test: se stampa una risposta, chiave, URL e ID del modello sono corretti.

-   **Il primo argomento è l’ID del modello** inviato a BroadNet. Usalo esattamente così, con il prefisso `broadnet/`.
-   **Il nome del provider** (qui `'broadnet'`) viene registrato su ogni risposta. La documentazione di Pydantic AI dice di mantenerlo stabile, perché decide quali dati delle risposte precedenti vengono rimandati al servizio.
-   **Resta su `OpenAIChatModel`.** La documentazione di Pydantic AI dice di usare `OpenAIResponsesModel` solo se il servizio implementa la Responses API. BroadNet non la elenca.

## Strumenti e output strutturato

```python
from pydantic import BaseModel

class City(BaseModel):
    name: str
    country: str

agent = Agent(model, output_type=City)
print(agent.run_sync('Which city hosts the Burj Khalifa?').output)
```

Per strumenti e output strutturato usa `broadnet/glm-5.3` o `broadnet/qwen3.8-27b`; la documentazione di BroadNet indica entrambe le funzionalità solo per questi due modelli.

## Quando impostare un profilo del modello

Pydantic AI sceglie un profilo di richiesta in base al nome del modello. Se una funzionalità viene ignorata o rifiutata, la sua documentazione dice di passare un tuo `OpenAIModelProfile`. Per BroadNet conviene conoscere due impostazioni:

```python
from pydantic_ai.profiles.openai import OpenAIModelProfile

model = OpenAIChatModel(
    'broadnet/glm-5.3',
    provider=OpenAICompatibleProvider('broadnet', base_url='https://inference.broadnet.ai/v1', api_key=os.environ['BROADNET_API_KEY']),
    profile=OpenAIModelProfile(
        openai_chat_supports_max_completion_tokens=False,  # send max_tokens, the field BroadNet documents
        openai_supports_strict_tool_definition=False,      # only if strict tool schemas are rejected
    ),
)
```

Passa il limite di output tramite le impostazioni del modello, per esempio `agent.run_sync(prompt, model_settings={'max_tokens': 2000})`. Su DeepSeek V4.1 Flash, GLM 5.3 e Qwen3.8 27B il ragionamento conta in quel limite.

## Quale modello scegliere

| Agente | Modello |
| --- | --- |
| Strumenti, output strutturato | `broadnet/glm-5.3` |
| Immagini o testo arabo, con strumenti | `broadnet/qwen3.8-27b` |
| Documenti lunghi, piano a prezzo fisso | `broadnet/deepseek-v4.1-flash` |
| Credito iniziale gratuito | `broadnet/gemma-4-26b-a4b` (contesto da 32.768 token) |

[Prezzi di tutti i modelli](https://broadrouter.com/it/pricing/).

## Risoluzione dei problemi

-   **401.** La chiave è sbagliata, scaduta o ha esaurito la quota.
-   **404 o modello non trovato.** `base_url` deve terminare con `/v1`. Controlla l’ID del modello. I modelli a pagamento richiedono una ricarica; il credito di $5 copre solo `broadnet/gemma-4-26b-a4b` e i due modelli Transcribe.
-   **Output vuoto o un ciclo di retry di validazione.** Il ragionamento ha consumato il budget di output. Alza `max_tokens`. [Perché le risposte arrivano vuote](https://broadrouter.com/it/guides/reasoning-tokens-empty-response/).
-   **400 sulle definizioni degli strumenti.** Imposta `openai_supports_strict_tool_definition=False` nel profilo e usa un modello per cui BroadNet indica gli strumenti.
-   **429 quando esegui agenti in parallelo.** Una chiave a consumo consente 30 richieste al minuto e 4 in corso. Vedi [errori e nuovi tentativi](https://broadrouter.com/it/guides/errors-and-retries/).

## Termini in questa guida

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

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

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

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

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

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

## Domande frequenti

### Per BroadNet devo usare OpenAIProvider o OpenAICompatibleProvider?

OpenAICompatibleProvider. La documentazione di Pydantic AI dice che anche OpenAIProvider accetta un base\_url, ma è pensato per OpenAI stessa o per un proxy trasparente verso OpenAI, e presuppone i modelli e le funzionalità di OpenAI.

### Perché usare OpenAIChatModel e non il modello OpenAI predefinito?

Il modello OpenAI predefinito di Pydantic AI usa la Responses API. BroadNet serve chat completions su /v1/chat/completions, ed è quello che chiama OpenAIChatModel.

### Strumenti e output strutturato funzionano?

Sì, sui modelli per cui BroadNet indica strumenti e output strutturato: GLM 5.3 e Qwen3.8 27B. La documentazione di BroadNet non indica gli strumenti per DeepSeek V4.1 Flash, quindi prima prova lì gli agenti che usano strumenti.

### Come evito che Pydantic AI invii max\_completion\_tokens?

Passa profile=OpenAIModelProfile(openai\_chat\_supports\_max\_completion\_tokens=False) a OpenAIChatModel. Pydantic AI invierà allora il vecchio campo max\_tokens, quello descritto dal riferimento API di BroadNet.

## Guide correlate

-   [Usare l’SDK Python di OpenAI con BroadNet Inference](https://broadrouter.com/it/guides/openai-python-sdk/)
-   [Usare LangChain con BroadNet Inference](https://broadrouter.com/it/guides/langchain-openai-base-url/)
-   [CrewAI con BroadNet Inference come endpoint OpenAI personalizzato](https://broadrouter.com/it/guides/crewai-custom-openai-endpoint/)
-   [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-pydantic-ai-openai-compatible&utm_content=page-cta) ·

**Fonti**

-   [Documentazione di Pydantic AI, Other compatible APIs (Other endpoints, Model profile) (verificata il 2026-11-15)](https://pydantic.dev/docs/ai/models/compatible-apis/)
-   [Documentazione di Pydantic AI, modelli OpenAI (verificata il 2026-11-15)](https://pydantic.dev/docs/ai/models/openai/)
-   [PyPI, pydantic-ai 2.68.0, Python 3.11+ (verificato il 2026-11-15)](https://pypi.org/project/pydantic-ai/)
-   [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-pydantic-ai-openai-compatible&utm_content=sources)
