Spostare un’app da OpenAI a un provider compatibile con OpenAI è una piccola modifica al codice se usi Chat Completions, e una riscrittura se usi la Responses API. Questo articolo mostra le diff esatte in Python, Node e cURL, cosa fare con Responses, strumenti, output strutturato ed embedding, e uno smoke test da eseguire prima di spostare il traffico. Gli esempi usano BroadNet Inference su https://inference.broadnet.ai/v1; gli stessi passaggi valgono per qualsiasi provider.
Questo è il complemento in codice della checklist per la migrazione, che tratta rate limit, errori e pianificazione del passaggio. Per le base URL degli altri provider, vedi le base URL compatibili con OpenAI, verificate.
Che cosa cambia nella configurazione del client?
Tre valori: base URL, chiave API e ID del modello.
Python
import os
from openai import OpenAI
# before: client = OpenAI() # reads OPENAI_API_KEY, calls api.openai.com
client = OpenAI(
base_url="https://inference.broadnet.ai/v1",
api_key=os.environ["BROADNET_API_KEY"],
)
r = client.chat.completions.create(
model="broadnet/gemma-4-26b-a4b", # was e.g. "gpt-..."
messages=[{"role": "user", "content": "Reply with one short sentence."}],
)
print(r.choices[0].message.content)
Node
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://inference.broadnet.ai/v1",
apiKey: process.env.BROADNET_API_KEY,
});
const r = await client.chat.completions.create({
model: "broadnet/gemma-4-26b-a4b",
messages: [{ role: "user", content: "Reply with one short sentence." }],
});
console.log(r.choices[0].message.content);
cURL
curl https://inference.broadnet.ai/v1/chat/completions \
-H "Authorization: Bearer $BROADNET_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"broadnet/gemma-4-26b-a4b","messages":[{"role":"user","content":"Reply with one short sentence."}]}'
Fai attenzione al percorso: la base URL finisce già con /v1, quindi l’SDK aggiunge /chat/completions. Raddoppiare /v1 è il primo errore più comune.
Posso cambiare senza toccare il codice?
Sì, per il codice Chat Completions. L’SDK Python legge OPENAI_BASE_URL quando non passi base_url, e il client Node usa come valore predefinito di baseURL process.env['OPENAI_BASE_URL']. Entrambi leggono OPENAI_API_KEY. Impostando due variabili d’ambiente sposti tutte le chiamate.
Ed è proprio questo il rischio. Si sposta ogni chiamata, compresi embedding, moderazione, upload di file e qualsiasi altra cosa che il nuovo provider potrebbe non avere. Usa il cambio tramite variabili d’ambiente solo quando la tua app fa chiamate di chat e nient’altro.
E se il mio codice usa la Responses API?
I README degli SDK di OpenAI ora definiscono la Responses API come l’API principale; il README Python chiama Chat Completions “the previous standard (supported indefinitely)” (traduzione: lo standard precedente, supportato a tempo indeterminato). Molti provider compatibili implementano solo Chat Completions. BroadNet documenta POST /v1/chat/completions e POST /v1/audio/transcriptions, quindi le chiamate Responses vanno riscritte. La corrispondenza:
| Responses API | Chat Completions |
|---|---|
client.responses.create(...) |
client.chat.completions.create(...) |
instructions="..." |
Primo messaggio {"role": "system", "content": "..."} |
input="..." o un elenco di elementi |
messages=[...] |
response.output_text |
response.choices[0].message.content |
max_output_tokens |
max_tokens (documentazione di BroadNet) o max_completion_tokens |
text={"format": {...}} |
response_format={...} |
previous_response_id, conversazioni |
Reinvia tu l’intera cronologia dei messaggi |
Strumento {"type": "function", "name": ...} |
Strumento {"type": "function", "function": {"name": ...}} |
Elemento di output function_call, risposta con function_call_output e call_id |
message.tool_calls, risposta con ruolo tool e tool_call_id |
| Strumenti integrati (ricerca web, ricerca nei file) | Non disponibili; usa un tuo strumento |
Il prima e il dopo di una chiamata semplice:
# Before: Responses API
r = client.responses.create(model="gpt-...", instructions="Be brief.", input="What is RAG?")
text = r.output_text
# After: Chat Completions
r = client.chat.completions.create(
model="broadnet/gemma-4-26b-a4b",
messages=[{"role": "system", "content": "Be brief."},
{"role": "user", "content": "What is RAG?"}],
)
text = r.choices[0].message.content
Il cambiamento strutturale più grande è lo stato. Responses può mantenere lo stato della conversazione lato OpenAI con previous_response_id. Chat Completions non ha stato lato server, quindi è il tuo codice a salvare l’elenco dei messaggi e a inviarlo per intero a ogni turno. Mettilo in conto: l’intera cronologia diventa token di input a ogni chiamata.
Come cambiano le chiamate agli strumenti?
In Chat Completions, la definizione di uno strumento annida la funzione sotto una chiave function, e la risposta torna come messaggio tool:
import json
tools = [{
"type": "function",
"function": {
"name": "get_order",
"description": "Look up an order by ID.",
"parameters": {"type": "object",
"properties": {"order_id": {"type": "string"}},
"required": ["order_id"]},
},
}]
messages = [{"role": "user", "content": "Where is order A-1042?"}]
r = client.chat.completions.create(model="broadnet/glm-5.3", messages=messages, tools=tools)
msg = r.choices[0].message
if msg.tool_calls:
messages.append(msg) # keep the assistant turn
for call in msg.tool_calls:
args = json.loads(call.function.arguments) # a JSON string: parse and validate it
messages.append({"role": "tool", "tool_call_id": call.id,
"content": json.dumps(lookup_order(args["order_id"]))})
r = client.chat.completions.create(model="broadnet/glm-5.3", messages=messages, tools=tools)
Il modello conta più della forma. La documentazione di BroadNet indica gli strumenti solo per GLM 5.3 e Qwen3.8 27B. Non puntare un loop di strumenti su un modello la cui documentazione non li elenca, e valida gli argomenti prima di eseguire qualsiasi cosa. Tool calling con i modelli open contiene un loop completo con validazione.
E l’output strutturato?
client.chat.completions.parse(..., response_format=MyPydanticModel) e zodResponseFormat in Node inviano entrambi response_format con uno schema JSON. Funzionano solo se il provider accetta quella forma su quel modello. BroadNet indica l’output strutturato per GLM 5.3 e Qwen3.8 27B ma non specifica il parametro della richiesta. Esegui il test in quattro passi di JSON mode o json_schema una volta per modello, e continua a validare il risultato del parsing, qualunque cosa prometta il provider.
Che cosa succede agli embedding?
Se cambi la base URL su un client condiviso e il provider non ha un endpoint per gli embedding, ogni chiamata client.embeddings.create fallisce. BroadNet non vende embedding. Tieni due client:
chat = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])
embed = OpenAI(api_key=os.environ["OPENAI_API_KEY"]) # or any embeddings provider
vec = embed.embeddings.create(model="text-embedding-3-small", input=query).data[0].embedding
answer = chat.chat.completions.create(model="broadnet/glm-5.3", messages=build_prompt(query, search(vec)))
Non mescolare mai in uno stesso indice vettori di due modelli di embedding diversi. Se cambi anche provider di embedding, ricalcola gli embedding dell’intero corpus. Il calcolatore dei costi degli embedding ti dice quanto costa.
Lo stesso vale per tutto ciò che non è chat: generazione di immagini, text-to-speech, moderazione, Batch API e archiviazione di file. BroadNet non offre nessuno di questi. Lo speech-to-text invece si sposta: client.audio.transcriptions.create funziona su /v1/audio/transcriptions con WAV o MP3 e un campo language (guida allo speech-to-text in arabo).
Come cambia il codice di streaming?
La Responses API trasmette eventi tipizzati, come response.output_text.delta e response.completed. Chat Completions trasmette chunk, e il testo si trova in choices[0].delta.content. L’usage non viene inviato se non lo chiedi, e in quel caso arriva in un chunk finale con un elenco choices vuoto.
// Before (Responses): for await (const e of stream) if (e.type === "response.output_text.delta") out(e.delta);
const stream = await client.chat.completions.create({
model: "broadnet/gemma-4-26b-a4b",
messages: [{ role: "user", content: "Count from one to three." }],
stream: true,
stream_options: { include_usage: true },
});
for await (const chunk of stream) {
const text = chunk.choices[0]?.delta?.content;
if (text) process.stdout.write(text);
if (chunk.usage) console.log("\ntokens:", chunk.usage.total_tokens); // last chunk
}
Due abitudini rendono sicuro il codice di streaming dopo il cambio. Proteggi l’accesso a choices[0], perché il chunk con l’usage non ha choices. E considera incompleto uno stream che termina prima della riga finale data: [DONE]; la documentazione di BroadNet dice di registrare l’X-Request-ID e decidere se una nuova richiesta è sicura. Streaming delle chat completions mostra lo schema completo in Python.
Cambiano la gestione degli errori e i retry?
Le classi di errore dell’SDK restano le stesse: AuthenticationError per il 401, RateLimitError per il 429, APIStatusError per il resto. Cambia il significato di ogni stato presso il nuovo provider. Su BroadNet, un 401 può indicare un plafond a consumo esaurito, non solo una chiave sbagliata, e un 402 indica saldo insufficiente per un acquisto. Nessuno dei due si risolve con un retry. Un 429 può venire dal limite di frequenza, di concorrenza, di token al minuto o di spesa. Ritenta 429 e 5xx con backoff, e correggi tutto il resto. La guida a errori e retry contiene la tabella completa.
L’SDK ritenta per impostazione predefinita errori di connessione, 408, 409, 429 e 5xx due volte. Se aggiungi un tuo loop di retry, imposta max_retries=0 sul client, così i due non si sommano.
Quali parametri si comportano diversamente?
| Parametro | Che cosa verificare |
|---|---|
max_tokens / max_completion_tokens |
OpenAI depreca max_tokens; la documentazione di BroadNet lo usa. Sui modelli di ragionamento include il ragionamento, quindi valori bassi restituiscono risposte vuote (perché) |
reasoning_effort |
BroadNet documenta low; prova gli altri valori prima di farci affidamento |
stream_options: {"include_usage": true} |
Documentato da BroadNet; l’usage arriva nell’ultimo chunk |
n, logprobs, seed, logit_bias |
Non presenti nella documentazione di BroadNet; provali o rimuovili |
store, metadata |
Funzionalità di archiviazione di OpenAI; eliminali |
Parti di contenuto image_url |
Solo sui modelli indicati con supporto alle immagini: DeepSeek V4.1 Flash, Qwen3.8 27B, Gemma 4 VL 26B |
Come si prova il cambio?
Esegui un breve smoke test sul nuovo provider prima di spostare qualsiasi traffico. Questo verifica chat semplice, usage in streaming, budget di ragionamento e autenticazione. Aggiungi un caso con chiamata a uno strumento se usi gli strumenti.
import os, openai
from openai import OpenAI
client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"], max_retries=0)
FAST, REASONING = "broadnet/gemma-4-26b-a4b", "broadnet/qwen3.8-27b"
msg = [{"role": "user", "content": "Reply with the word ok."}]
# 1. Plain chat returns text and usage
r = client.chat.completions.create(model=FAST, messages=msg)
assert r.choices[0].message.content and r.usage.prompt_tokens > 0
# 2. Streaming reports usage in the last chunk
chunks = list(client.chat.completions.create(model=FAST, messages=msg, stream=True,
stream_options={"include_usage": True}))
assert chunks[-1].usage is not None
# 3. A reasoning model needs room: a tiny budget can come back empty
r = client.chat.completions.create(model=REASONING, messages=msg, max_tokens=2000)
assert r.choices[0].finish_reason == "stop" and r.choices[0].message.content
# 4. A bad key raises AuthenticationError (401), which you should not retry
bad = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key="invalid", max_retries=0)
try:
bad.chat.completions.create(model=FAST, messages=msg)
raise AssertionError("expected 401")
except openai.AuthenticationError:
pass
print("smoke test passed")
Poi confronta la qualità, non solo la forma. Riesegui un campione di prompt reali su entrambi i provider e valuta le risposte; valutare un LLM prima di cambiarlo spiega come. Lo strumento di migrazione da OpenAI a BroadNet ti aiuta a riscrivere uno snippet ed elenca le funzionalità che usa.
Che cosa si rompe più spesso?
- Una base URL globale che sposta anche gli embedding e le chiamate ai file.
- Helper esclusivi di Responses come
output_text, rimasti in codice che ora chiama Chat Completions. - ID dei modelli. I nomi
gpt-...non esistono altrove. Su BroadNet hanno una forma comebroadnet/glm-5.3. - Risposte vuote dai modelli di ragionamento con un
max_tokensbasso. - Rate limit. Una chiave BroadNet a consumo consente 30 richieste al minuto e 4 in corso. I job massivi hanno bisogno di una coda (gestione dei 429).
Dove si colloca BroadNet Inference
BroadNet Inference è adatto alle app che usano OpenAI per chat e trascrizione: assistenti, estrazione, riassunti, traduzione e voce in arabo. È adatto anche alle app che vogliono piani flat di DeepSeek V4.1 Flash per gli agenti. È la destinazione sbagliata se dipendi dallo stato lato server della Responses API, dagli strumenti integrati, dagli embedding, dalla generazione di immagini, dal text-to-speech, dalla voce in tempo reale o dalla Batch API. Sposta queste funzioni su provider che le offrono, oppure lasciale su OpenAI e sposta solo le chiamate di chat. Gemma 4 VL 26B ed entrambi i modelli di trascrizione funzionano con il credito iniziale di $5; GLM 5.3, Qwen3.8 27B e DeepSeek V4.1 Flash richiedono prima una ricarica.
