---
title: "Vercel AI SDK: createOpenAICompatible con base URL custom"
description: "Chiama BroadNet Inference dal Vercel AI SDK con createOpenAICompatible di @ai-sdk/openai-compatible: generateText, streamText, strumenti e reasoning effort."
url: https://broadrouter.com/it/guides/vercel-ai-sdk-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/vercel-ai-sdk-openai-compatible/) (aggiornato il 2026-11-16).

# Usare il Vercel AI SDK con BroadNet Inference

Aggiornato 2026-11-16

Installa ai e @ai-sdk/openai-compatible, poi chiama createOpenAICompatible con name broadnet, baseURL https://inference.broadnet.ai/v1 e la tua chiave BroadNet come apiKey. Passa al provider un ID di modello BroadNet, per esempio broadnet/glm-5.3, e usa generateText o streamText come al solito. Tieni la chiave sul server e dai ai modelli di ragionamento un maxOutputTokens generoso.

L’[AI SDK](https://ai-sdk.dev/providers/openai-compatible-providers) di Vercel è un toolkit TypeScript per app basate su LLM. Il suo pacchetto `@ai-sdk/openai-compatible` crea un provider per qualsiasi API che segue il formato chat completions di OpenAI. BroadNet Inference lo segue, quindi cambi solo base URL, chiave e ID dei modelli. Se invece vuoi il client OpenAI puro, vedi [la guida all’SDK Node](https://broadrouter.com/it/guides/openai-node-sdk/).

## Configurazione

1.  **Installa i pacchetti.** Nel momento in cui scriviamo, npm distribuisce `ai` 7.x e `@ai-sdk/openai-compatible` 3.x.
    
    ```bash
    npm install ai @ai-sdk/openai-compatible
    export BROADNET_API_KEY='your-broadnet-key'
    ```
    
2.  **Crea il provider.** L’opzione `includeUsage` aggiunge i dati di usage alle risposte in streaming.
    
    ```ts
    // broadnet.ts
    import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
    
    export const broadnet = createOpenAICompatible({
      name: 'broadnet',
      baseURL: 'https://inference.broadnet.ai/v1',
      apiKey: process.env.BROADNET_API_KEY,
      includeUsage: true, // usage data in streaming responses
    });
    ```
    
3.  **Genera il testo.** Il ragionamento conta in `maxOutputTokens`.
    
    ```ts
    import { generateText } from 'ai';
    import { broadnet } from './broadnet';
    
    const { text, usage, finishReason } = await generateText({
      model: broadnet('broadnet/glm-5.3'),
      prompt: 'Explain idempotency keys in two sentences.',
      maxOutputTokens: 4000, // reasoning counts toward this
    });
    
    console.log(text, finishReason, usage);
    ```
    
4.  **Passa allo streaming.** Sostituisci `generateText` con `streamText` e leggi `textStream`. La [guida allo streaming](https://broadrouter.com/it/guides/streaming-chat-completions/) spiega il formato dei dati che viaggiano sotto.
    

Il `name` che passi diventa la chiave per le opzioni e i metadati del provider, quindi sceglilo breve e stabile. `provider('id')` e `provider.chatModel('id')` creano entrambi un modello di chat; non c’è una configurazione separata per ogni modello. Tieni la chiave sul server. Non importare questo file in codice che gira nel browser, altrimenti la chiave arriva a ogni visitatore.

La documentazione del provider elenca tra le funzionalità supportate generazione di testo, streaming, tool calling, output strutturati, contenuto di ragionamento e input di immagini, con la nota che alcune dipendono dal provider. Su BroadNet l’input di immagini funziona con DeepSeek V4.1 Flash, Qwen3.8 27B e Gemma 4 VL 26B. GLM 5.3 accetta solo testo.

## Opzioni che conviene impostare

-   **reasoningEffort.** Passalo tramite `providerOptions`, sotto il nome del provider. La documentazione dell’AI SDK dice che i valori esatti dipendono dal provider; la documentazione di BroadNet mostra `low`.

```ts
const result = await generateText({
  model: broadnet('broadnet/deepseek-v4.1-flash'),
  prompt: 'Classify: "refund my order" -> intent?',
  providerOptions: { broadnet: { reasoningEffort: 'low' } },
});
```

-   **supportsStructuredOutputs.** L’AI SDK invia gli schemi JSON solo se questa opzione è `true` sul provider. BroadNet indica l’output strutturato per GLM 5.3 e Qwen3.8 27B. Se la attivi, usa quei modelli per l’output con schema.
-   **maxRetries.** `generateText` ritenta due volte per impostazione predefinita. Impostalo in base al tuo rate limit.
-   **Output del ragionamento.** L’AI SDK legge il contenuto di ragionamento quando il provider lo restituisce. Il campo di primo livello `reasoningText` nel risultato ora è segnato come deprecato a favore di `finalStep.reasoningText`. Non costruire logica che dipende dalla presenza del ragionamento.

## Quale modello scegliere

| Esigenza | Modello | Contesto |
| --- | --- | --- |
| Tool calling, output strutturato | [`broadnet/glm-5.3`](https://broadrouter.com/it/models/glm-5.3/) | 1.048.576 |
| Immagini più strumenti, arabo | [`broadnet/qwen3.8-27b`](https://broadrouter.com/it/models/qwen3.8-27b/) | 262.144 |
| Contesto lungo, piano flat | [`broadnet/deepseek-v4.1-flash`](https://broadrouter.com/it/models/deepseek-v4.1-flash/) | 1.048.576 |
| Chiamate economiche con testo e immagini | [`broadnet/gemma-4-26b-a4b`](https://broadrouter.com/it/models/gemma-4-vl-26b/) | 32.768 |

I prezzi per token di ogni modello sono nella [pagina dei prezzi](https://broadrouter.com/it/pricing/).

## Risoluzione dei problemi

-   **401.** `BROADNET_API_KEY` manca nel runtime (controlla le impostazioni delle variabili d’ambiente del tuo hosting), è sbagliata, scaduta o ha esaurito la quota a consumo.
-   **providerOptions ignorate.** La chiave deve corrispondere al `name` del provider in camelCase. Con `name: 'broadnet'`, usa `providerOptions.broadnet`.
-   **Errori sul modello.** L’ID deve corrispondere esattamente a quello di BroadNet, con il prefisso `broadnet/`. GLM 5.3, Qwen3.8 27B e DeepSeek V4.1 Flash richiedono una ricarica; il credito iniziale di $5 copre Gemma 4 VL 26B e i due modelli Transcribe.
-   **Testo vuoto, finishReason “length”.** Il ragionamento ha consumato il budget. Alza `maxOutputTokens` o abbassa `reasoningEffort`. [Perché le risposte arrivano vuote](https://broadrouter.com/it/guides/reasoning-tokens-empty-response/).
-   **429 sotto carico.** Una chiave a consumo consente 30 richieste al minuto e 4 in corso contemporaneamente. Le funzioni serverless scalano in fretta, quindi limita la concorrenza nella tua app. Vedi [errori e retry](https://broadrouter.com/it/guides/errors-and-retries/).
-   **Agenti in parallelo con una chiave di piano.** Una [sessione del piano illimitato](https://broadrouter.com/it/guides/unlimited-llm-api-sessions/) esegue una richiesta alla volta. Lanciare `Promise.all` su più agenti richiede una sessione per agente, altrimenti le richieste finiscono in coda.

## Termini in questa guida

[Streaming](https://broadrouter.com/it/glossary/streaming/)

Lo streaming è un modo di restituire la risposta di un modello linguistico in piccoli pezzi mentre viene ancora generata, invece che in un’unica risposta alla fine. Le API compatibili con OpenAI trasmettono in streaming tramite server-sent event quando la richiesta imposta stream a true.

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

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

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

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

[Base URL (URL di base)](https://broadrouter.com/it/glossary/base-url/)

La base URL è l’indirizzo radice fisso di un’API, come https://api.example.com/v1, che un client antepone a ogni percorso di endpoint, come /chat/completions. Negli SDK compatibili con OpenAI, cambiare la base URL, insieme alla chiave API e all’ID del modello, punta lo stesso codice verso un altro provider.

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

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

## Domande frequenti

### Devo usare @ai-sdk/openai o @ai-sdk/openai-compatible?

Usa @ai-sdk/openai-compatible per le API di terze parti compatibili con OpenAI. Chiama l’endpoint chat completions, che è quello servito da BroadNet Inference.

### Perché il testo generato è vuoto?

Su BroadNet il ragionamento conta in max\_tokens. Se maxOutputTokens è basso, il modello può consumarlo tutto prima che inizi la risposta. Alzalo o imposta reasoningEffort su low.

### Come ottengo l’uso dei token durante lo streaming?

Imposta includeUsage a true quando crei il provider. La documentazione dell’AI SDK dice che aggiunge i dati di usage alle risposte in streaming. Il valore predefinito è false.

### Serve una configurazione separata per ogni modello BroadNet?

No. Un solo provider createOpenAICompatible copre tutti i modelli. Chiama broadnet('model-id') o broadnet.chatModel('model-id') con qualsiasi ID di modello di chat BroadNet.

## Guide correlate

-   [Usare l’SDK Node.js di OpenAI con BroadNet Inference](https://broadrouter.com/it/guides/openai-node-sdk/)
-   [Streaming delle chat completions e connessioni interrotte](https://broadrouter.com/it/guides/streaming-chat-completions/)
-   [Perché un modello di ragionamento restituisce una risposta vuota](https://broadrouter.com/it/guides/reasoning-tokens-empty-response/)
-   [Aggiungere BroadNet Inference a opencode come provider personalizzato](https://broadrouter.com/it/guides/opencode-custom-provider/)
-   [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-vercel-ai-sdk-openai-compatible&utm_content=page-cta) ·

**Fonti**

-   [Documentazione dell’AI SDK, provider OpenAI Compatible (verificata il 2026-11-14)](https://ai-sdk.dev/providers/openai-compatible-providers)
-   [Documentazione dell’AI SDK, riferimento di generateText (verificata il 2026-11-14)](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-text)
-   [npm, pacchetto @ai-sdk/openai-compatible (3.x, verificato il 2026-11-14)](https://www.npmjs.com/package/@ai-sdk/openai-compatible)
-   [Riferimento API di BroadNet Inference (in inglese)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=it-guides-vercel-ai-sdk-openai-compatible&utm_content=sources)
