Mover um app da OpenAI para um provedor compatível com a OpenAI é uma pequena mudança de código se você usa Chat Completions, e uma reescrita se você usa a Responses API. Este post mostra os diffs exatos em Python, Node e cURL, o que fazer com Responses, ferramentas, saída estruturada e embeddings, e um smoke test para rodar antes de mover qualquer tráfego. Os exemplos usam a BroadNet Inference em https://inference.broadnet.ai/v1; os mesmos passos valem para qualquer provedor.
Este é o complemento em código do checklist de migração, que cobre rate limits, erros e o planejamento da virada. Para as base URLs de outros provedores, veja base URLs compatíveis com a OpenAI, conferidas.
O que muda na configuração do cliente?
Três valores: base URL, chave de API e ID do modelo.
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."}]}'
Repare no caminho: a base URL já termina em /v1, então o SDK acrescenta /chat/completions. Duplicar o /v1 é o primeiro erro mais comum.
Dá para trocar sem mexer no código?
Sim, para código de Chat Completions. O SDK Python lê OPENAI_BASE_URL quando nenhuma base_url é passada, e o cliente Node usa process.env['OPENAI_BASE_URL'] como padrão de baseURL. Os dois leem OPENAI_API_KEY. Definir duas variáveis de ambiente move todas as chamadas.
E esse também é o risco. Todas as chamadas mudam, incluindo embeddings, moderação, upload de arquivos e qualquer outra coisa que o novo provedor talvez não tenha. Use a troca por variável de ambiente só quando o seu app faz chamadas de chat e nada mais.
E se o meu código usa a Responses API?
Os READMEs dos SDKs da OpenAI agora chamam a Responses API de API principal; o README do Python chama o Chat Completions de “the previous standard (supported indefinitely)” (tradução: o padrão anterior, suportado por tempo indeterminado). Muitos provedores compatíveis implementam só Chat Completions. A BroadNet documenta POST /v1/chat/completions e POST /v1/audio/transcriptions, então as chamadas de Responses precisam ser reescritas. O mapeamento:
| Responses API | Chat Completions |
|---|---|
client.responses.create(...) |
client.chat.completions.create(...) |
instructions="..." |
Primeira mensagem {"role": "system", "content": "..."} |
input="..." ou uma lista de itens |
messages=[...] |
response.output_text |
response.choices[0].message.content |
max_output_tokens |
max_tokens (documentação da BroadNet) ou max_completion_tokens |
text={"format": {...}} |
response_format={...} |
previous_response_id, conversas |
Reenvie você mesmo o histórico completo de mensagens |
Ferramenta {"type": "function", "name": ...} |
Ferramenta {"type": "function", "function": {"name": ...}} |
Item de saída function_call, resposta com function_call_output e call_id |
message.tool_calls, resposta com role tool e tool_call_id |
| Ferramentas embutidas (busca na web, busca em arquivos) | Não disponíveis; rode a sua própria ferramenta |
O antes e o depois de uma chamada simples:
# 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
A maior mudança estrutural é o estado. A Responses pode manter o estado da conversa do lado da OpenAI com previous_response_id. O Chat Completions não tem estado no servidor, então o seu código guarda a lista de mensagens e envia tudo a cada turno. Inclua isso no orçamento: o histórico inteiro vira tokens de entrada em cada chamada.
Como mudam as chamadas de ferramentas?
No Chat Completions, a definição de uma ferramenta aninha a função sob a chave function, e a resposta volta como uma mensagem 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)
O modelo importa mais que o formato. A documentação da BroadNet lista ferramentas apenas para o GLM 5.3 e o Qwen3.8 27B. Não aponte um loop de ferramentas para um modelo cuja documentação não lista ferramentas, e valide os argumentos antes de executar qualquer coisa. Tool calling com modelos abertos traz um loop completo com validação.
E a saída estruturada?
client.chat.completions.parse(..., response_format=MyPydanticModel) e o zodResponseFormat do Node enviam response_format com um JSON schema. Eles só funcionam se o provedor aceitar esse formato naquele modelo. A BroadNet lista saída estruturada para o GLM 5.3 e o Qwen3.8 27B, mas não informa o parâmetro da requisição. Rode o teste de quatro passos de JSON mode vs json_schema uma vez por modelo e continue validando o resultado do parse, prometa o provedor o que prometer.
O que acontece com os embeddings?
Se você troca a base URL num cliente compartilhado e o provedor não tem endpoint de embeddings, toda chamada client.embeddings.create falha. A BroadNet não vende embeddings. Mantenha dois clientes:
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)))
Nunca misture vetores de dois modelos de embedding no mesmo índice. Se você também trocar de provedor de embeddings, gere de novo os embeddings do corpus inteiro. A calculadora de custo de embeddings mostra quanto isso custa.
O mesmo vale para tudo o que não é chat: geração de imagens, texto para fala, moderação, a Batch API e armazenamento de arquivos. A BroadNet não oferece nenhum deles. A fala para texto, sim, migra: client.audio.transcriptions.create funciona com /v1/audio/transcriptions usando WAV ou MP3 e um campo language (guia de fala para texto em árabe).
Como muda o código de streaming?
A Responses API transmite eventos tipados, como response.output_text.delta e response.completed. O Chat Completions transmite chunks, e o texto fica em choices[0].delta.content. O usage não é enviado a menos que você peça, e então chega num chunk final com a lista choices vazia.
// 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
}
Dois hábitos mantêm o código de stream seguro depois da troca. Proteja o acesso a choices[0], porque o chunk de usage não tem choices. E trate como incompleto um stream que termina antes da linha final data: [DONE]; a documentação da BroadNet diz para registrar o X-Request-ID e decidir se uma nova requisição é segura. Streaming de chat completions traz o padrão completo em Python.
O tratamento de erros e as novas tentativas mudam?
As classes de erro do SDK continuam as mesmas: AuthenticationError para 401, RateLimitError para 429, APIStatusError para o resto. O que muda é o que cada status significa no novo provedor. Na BroadNet, um 401 pode indicar uma franquia de pagamento por uso esgotada, não só uma chave errada, e um 402 indica saldo insuficiente para uma compra. Nenhum dos dois se resolve com uma nova tentativa. Um 429 pode vir do limite de taxa, de concorrência, de tokens por minuto ou de gasto. Tente de novo 429 e 5xx com backoff e corrija todo o resto. O guia de erros e novas tentativas traz a tabela completa.
O SDK repete por padrão erros de conexão, 408, 409, 429 e 5xx duas vezes. Se você adicionar o seu próprio loop de novas tentativas, defina max_retries=0 no cliente para que os dois não se somem.
Quais parâmetros se comportam de forma diferente?
| Parâmetro | O que verificar |
|---|---|
max_tokens / max_completion_tokens |
A OpenAI descontinua max_tokens; a documentação da BroadNet o usa. Em modelos de raciocínio ele inclui o raciocínio, então valores pequenos devolvem respostas vazias (por quê) |
reasoning_effort |
A BroadNet documenta low; teste outros valores antes de depender deles |
stream_options: {"include_usage": true} |
Documentado pela BroadNet; o usage chega no último chunk |
n, logprobs, seed, logit_bias |
Não estão na documentação da BroadNet; teste ou remova |
store, metadata |
Recursos de armazenamento da OpenAI; remova |
Partes de conteúdo image_url |
Só nos modelos listados com imagens: DeepSeek V4.1 Flash, Qwen3.8 27B, Gemma 4 VL 26B |
Como testar a troca?
Rode um smoke test curto contra o novo provedor antes de mover qualquer tráfego. Este verifica chat simples, usage em streaming, o orçamento de raciocínio e a autenticação. Acrescente um caso de chamada de ferramenta se você usa ferramentas.
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")
Depois compare a qualidade, não só o formato. Rode de novo uma amostra de prompts reais nos dois provedores e avalie as respostas; avaliar um LLM antes de trocar mostra como. A ferramenta de migração da OpenAI para a BroadNet ajuda a reescrever um trecho de código e lista os recursos que ele usa.
O que quebra com mais frequência?
- Uma base URL global que também move os embeddings e as chamadas de arquivos.
- Helpers exclusivos da Responses, como
output_text, esquecidos em código que agora chama Chat Completions. - IDs de modelos. Nomes
gpt-...não existem em outros lugares. Na BroadNet eles têm o formatobroadnet/glm-5.3. - Respostas vazias de modelos de raciocínio com
max_tokenspequeno. - Rate limits. Uma chave de pagamento por uso da BroadNet permite 30 requisições por minuto e 4 em andamento. Jobs em lote precisam de uma fila (como lidar com 429).
Onde a BroadNet Inference se encaixa
A BroadNet Inference combina com apps que usam a OpenAI para chat e transcrição: assistentes, extração, resumo, tradução e fala em árabe. Também combina com apps que querem planos de preço fixo do DeepSeek V4.1 Flash para agentes. É o destino errado se você depende do estado no servidor da Responses API, das ferramentas embutidas, de embeddings, de geração de imagens, de texto para fala, de voz em tempo real ou da Batch API. Leve esses recursos para provedores que os oferecem, ou mantenha-os na OpenAI e mova só as chamadas de chat. O Gemma 4 VL 26B e os dois modelos de transcrição rodam com o crédito inicial de $5; o GLM 5.3, o Qwen3.8 27B e o DeepSeek V4.1 Flash exigem recarga antes.
