BroadRouter
Inizia

Passare a un’API compatibile con OpenAI: la checklist di migrazione

A cura del team di BroadNet Inference · 5 min di lettura · Pubblicato · Aggiornato

Per passare a un’API compatibile con OpenAI cambi tre impostazioni (base_url, api_key e model) e poi verifichi cosa è diverso: ID dei modelli, come i token di ragionamento contano in max_tokens, come lo streaming riporta l’usage, quali errori ritentare, rate limit e sicurezza delle chiavi. Per BroadNet Inference la base URL è https://inference.broadnet.ai/v1.

Ormai quasi tutti i provider LLM parlano il formato dell’API di OpenAI. Così il cambio sembra una modifica di una riga, e per ottenere una prima risposta lo è davvero. Per portare traffico di produzione, invece, segui questa lista. Ogni voce nasce da un modo reale in cui le migrazioni si rompono.

0. Cosa usa oggi la tua app?

Prima di cambiare qualsiasi cosa, annota da cosa dipende la tua app. Cerca nel codice ogni chiamata all’SDK ed elencale. Se chiami l’API Whisper di OpenAI, tieni presente che OpenAI indica la dismissione di whisper-1 il 26 febbraio 2027; per la parte audio vedi alternative all’API Whisper.

Funzione Dove guardare Test dopo il cambio
Chat completions Ogni chat.completions.create Stessi prompt, confronta le risposte
Streaming stream=True I chunk arrivano, finisce con [DONE], usage presente
Tool calling tools= Le chiamate ai tool si parsano e si eseguono
Output strutturato response_format= Il JSON è valido rispetto al tuo schema
Immagini Parti immagine nei messaggi Il modello le accetta
Trascrizione audio audio.transcriptions Testo e lingua corretti
Embeddings, file, batch Altri endpoint Verifica che il provider li offra

L’ultima riga conta. «Compatibile con OpenAI» di solito copre prima di tutto le chat completions. Il catalogo di BroadNet Inference elenca modelli chat su /v1/chat/completions e modelli speech-to-text su /v1/audio/transcriptions; se usi altri endpoint, lasciali sul provider attuale o trova un sostituto.

1. Quali sono le tre impostazioni da cambiare?

from openai import OpenAI
import os

client = OpenAI(
    base_url="https://inference.broadnet.ai/v1",
    api_key=os.environ["BROADNET_API_KEY"],
)

Il nome dell’impostazione della base URL cambia da libreria a libreria: base_url nell’SDK Python e in ChatOpenAI di LangChain, baseURL nell’SDK Node.js. Secondo il suo README, l’SDK Python legge anche la variabile d’ambiente OPENAI_BASE_URL. Controlla che nel tuo ambiente non sia rimasto un valore vecchio, altrimenti le richieste possono finire al vecchio provider senza alcun errore.

Tieni le chiavi API in variabili d’ambiente o in un secret manager, mai nel codice. Configurazione per ciascun SDK: Python, Node.js, LangChain. Per costruire e provare a mano una prima richiesta, usa il costruttore di richieste API. Per applicare le modifiche a base URL, chiave e modello al codice esistente, incollalo nell’assistente di migrazione da OpenAI a BroadNet, che elenca anche cosa controllare.

2. Quali sono i nuovi ID dei modelli?

Ogni provider dà ai modelli nomi suoi. Su BroadNet Inference:

Modello ID
DeepSeek V4.1 Flash broadnet/deepseek-v4.1-flash
GLM 5.3 broadnet/glm-5.3
Qwen3.8 27B broadnet/qwen3.8-27b
Gemma 4 VL 26B broadnet/gemma-4-26b-a4b

Metti l’ID del modello nella configurazione, non nel codice, così un cambio futuro è un deploy e non una riscrittura. Limiti e prezzi di ogni modello sono nella sua pagina: DeepSeek V4.1 Flash, GLM 5.3, Qwen3.8 27B e Gemma 4 VL 26B.

3. Perché dopo il cambio le risposte arrivano vuote?

È la sorpresa più comune. DeepSeek V4.1 Flash, GLM 5.3 e Qwen3.8 27B ragionano prima di rispondere, e i token di ragionamento contano in max_tokens. Un limite di 256 che andava bene con un modello senza ragionamento può finire tutto nel ragionamento, e la risposta arriva vuota. Lascia 1.000 token o più, oppure imposta reasoning_effort su low per i compiti semplici. Spiegazione completa.

4. Lo streaming riporta ancora l’usage?

Gli stream usano i Server-Sent Events e finiscono con data: [DONE]. L’usage dei token arriva nell’ultimo chunk solo se lo chiedi:

stream = client.chat.completions.create(
    model="broadnet/deepseek-v4.1-flash", messages=messages,
    stream=True, stream_options={"include_usage": True},
)

Senza questa opzione la tua dashboard dei costi segna zero. Se uno stream si chiude prima di [DONE], consideralo incompleto. Guida allo streaming.

5. Quali errori conviene ritentare?

Stato Significato Cosa fare
401 Chiave errata o revocata, oppure plafond a consumo esaurito Correggi, non ritentare
402 Saldo o budget Ricarica, non ritentare
403 Rifiutata dalla policy su modello, percorso o IP Correggi la discrepanza
413 Richiesta troppo grande Riducila, non ritentare
429 Limite di frequenza, concorrenza o spesa Backoff e retry
5xx Lato server Retry con backoff limitato

L’SDK Python ufficiale ritenta già alcuni errori: il README dice che errori di connessione, 408, 409, 429 e risposte 5xx vengono ritentati due volte di default con un breve backoff esponenziale. Imposta max_retries in modo esplicito, così il comportamento è una tua scelta e non un default. Registra nei log l’ID richiesta di ogni risposta, così il supporto può ricostruire un problema. Tutti i codici.

6. Quali sono i nuovi rate limit?

Conosci i nuovi limiti prima che arrivi il traffico. Una chiave BroadNet a consumo consente 30 richieste al minuto e 4 in corso. I piani illimitati eseguono una richiesta alla volta per sessione. Dimensiona il pool di worker di conseguenza, o vedrai dei 429 dal primo giorno; il calcolatore dei rate limit fa il dimensionamento. Vedi dimensionare per agenti in parallelo.

7. I tuoi prompt ci stanno ancora?

Controlla le finestre di contesto: 1.048.576 token su DeepSeek V4.1 Flash e GLM 5.3, 262.144 su Qwen3.8 27B, 32.768 su Gemma 4 VL 26B. Un prompt che stava nel vecchio modello potrebbe non stare in una finestra più piccola; verificalo con il calcolatore della finestra di contesto. Metti all’inizio la parte stabile del prompt per sfruttare il prezzo dell’input in cache.

8. E le chiavi e la conservazione dei dati?

Blocca le chiavi di produzione sugli IP dei tuoi server con un elenco di IP consentiti. Chiedi al nuovo provider cosa conserva; vedi la checklist ZDR.

9. Come si fa il passaggio in sicurezza?

  1. Invia a entrambi i provider una copia delle richieste reali di un giorno.
  2. Confronta le risposte su un campione, più latenza, errori e costo per richiesta.
  3. Sposta il 10% del traffico, osserva per un giorno, poi sposta il resto.
  4. Tieni configurato il vecchio provider come fallback per una settimana.

Se gestisci molti servizi, un proxy come LiteLLM ti permette di cambiare provider in un solo punto invece che in ogni app.

Quali sono gli errori di migrazione più comuni?

  • Manca /v1 nella base URL. Le richieste restituiscono 404. Usa l’URL completo.
  • Vecchi nomi dei modelli nella configurazione. Il nuovo provider non li conosce.
  • Campi specifici del provider rimasti nelle richieste. I campi che capiva solo il vecchio provider possono essere rifiutati o ignorati. Toglili dai client generici.
  • Testare un solo prompt. Ripercorri l’inventario del passo 0, funzione per funzione.
  • Fare il passaggio di venerdì. Lasciati il tempo di osservare un’intera giornata di traffico reale.

Dove si colloca BroadNet Inference

BroadNet Inference è un sostituto diretto per le app che usano chat completions e trascrizione audio tramite gli SDK di OpenAI: cambi tre impostazioni e segui la lista qui sopra. Il suo catalogo elenca solo modelli chat e speech-to-text, quindi se dipendi da altri endpoint, come embeddings o archiviazione di file, lasciali presso un altro provider. I nuovi account partono con $5 di credito. Tra i modelli chat, ci gira solo Gemma 4 VL 26B (copre anche i due modelli Transcribe), quindi un test in parallelo su DeepSeek, GLM o Qwen richiede una ricarica.

Domande frequenti

Mi serve un SDK diverso?

No. Gli SDK ufficiali di OpenAI per Python e Node.js accettano una base URL personalizzata. La accettano anche i framework costruiti sopra, come ChatOpenAI di LangChain.

Come cambio la base URL nell’SDK di OpenAI?

Passa base_url al client in Python o baseURL in Node.js, oppure imposta la variabile d’ambiente OPENAI_BASE_URL. Per BroadNet Inference il valore è https://inference.broadnet.ai/v1 e la chiave va in api_key.

Perché dopo il cambio ricevo risposte vuote?

I modelli di ragionamento come DeepSeek V4.1 Flash, GLM 5.3 e Qwen3.8 27B ragionano prima di rispondere, e il ragionamento conta in max_tokens. Alza max_tokens a 1.000 o più, oppure imposta reasoning_effort su low.

Perché dopo il cambio ricevo un 404 o un errore «model not found»?

Di solito l’ID del modello è ancora il nome usato dal vecchio provider, oppure alla base URL manca il percorso /v1. Usa l’ID esatto del nuovo provider e la base URL completa.

Quali errori devo ritentare?

Ritenta 429 e 5xx con un backoff esponenziale limitato. Correggi 401, 402 e 413 prima di ritentare. La guida agli errori di questo sito elenca tutti i codici.

Compatibile con OpenAI vuol dire identico?

No. La forma di richieste e risposte è la stessa, ma ID dei modelli, parametri supportati, limiti, campi di usage e dettagli degli errori possono cambiare. Testa ogni funzione che la tua app usa.

Leggi in MarkdownChiedi a ChatGPTChiedi a ClaudeChiedi a Perplexity