BroadRouter
Inizia

Migrare dall’API di OpenAI: il codice in Python, Node e cURL

A cura del team di BroadNet Inference · 6 min di lettura · Pubblicato

Cambia base URL, chiave API e ID del modello del client. Per le chiamate Chat Completions basta questo. Il codice sulla Responses API va riscritto per Chat Completions: input diventa messages, output_text diventa choices[0].message.content e gli strumenti perdono un livello di annidamento. Tieni gli embedding su un client separato se il nuovo provider non li offre, poi esegui uno smoke test prima di spostare il traffico.

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 come broadnet/glm-5.3.
  • Risposte vuote dai modelli di ragionamento con un max_tokens basso.
  • 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.

Domande frequenti

Mi serve un SDK diverso per usare un’API compatibile con OpenAI?

No. Tieni il pacchetto ufficiale openai e passa una base_url diversa (Python) o baseURL (Node), più la chiave del nuovo provider. Gli oggetti di richiesta e risposta restano gli stessi per gli endpoint che il provider supporta.

Un’API compatibile con OpenAI supporta la Responses API?

Alcune sì; molte supportano solo Chat Completions. Controlla l’elenco degli endpoint del provider. BroadNet Inference documenta /v1/chat/completions e /v1/audio/transcriptions, quindi il codice Responses va riscritto per Chat Completions.

Che fine fanno i miei embedding quando cambio provider?

Si rompono se il nuovo provider non ha un endpoint per gli embedding e hai cambiato la base URL a livello globale. BroadNet non vende embedding, quindi tieni un client per gli embedding puntato sul tuo provider di embedding. Non mescolare mai in uno stesso indice vettori di due modelli di embedding diversi.

Devo inviare max_tokens o max_completion_tokens?

OpenAI indica max_tokens come deprecato a favore di max_completion_tokens. Molti provider compatibili documentano invece max_tokens, e la documentazione di BroadNet usa max_tokens. Invia quello che il provider documenta e verifica nello smoke test che il limite venga applicato.

Gli helper di OpenAI per l’output strutturato funzioneranno ancora?

Solo se il provider accetta response_format con json_schema sul modello che usi. BroadNet indica l’output strutturato per GLM 5.3 e Qwen3.8 27B ma non specifica il parametro della richiesta, quindi provalo, e continua a validare il risultato del parsing.

Leggi in MarkdownChiedi a ChatGPTChiedi a ClaudeChiedi a Perplexity