BroadRouter
Começar

Migrar para uma API compatível com a OpenAI: checklist de migração

Pela equipe da BroadNet Inference · 5 min de leitura · Publicado em · Atualizado em

Para migrar para uma API compatível com a OpenAI, troque três configurações (base_url, api_key e model) e depois confira o que muda: IDs de modelo, como os tokens de raciocínio contam no max_tokens, como o streaming informa o usage, quais erros repetir, rate limits e segurança das chaves. Na BroadNet Inference, a base URL é https://inference.broadnet.ai/v1.

Hoje a maioria dos provedores de LLM fala o formato da API da OpenAI. Isso faz a troca parecer uma mudança de uma linha, e para obter a primeira resposta é mesmo. Para rodar tráfego de produção, siga esta lista. Cada item vem de um jeito real como migrações quebram.

0. O que o seu app usa hoje?

Antes de mudar qualquer coisa, anote do que o seu app depende. Procure no código todas as chamadas ao SDK e liste. Se você chama a API Whisper da OpenAI, saiba que a OpenAI lista o whisper-1 com desativação em 26 de fevereiro de 2027; alternativas à API do Whisper cobre a parte de áudio.

Recurso Onde procurar Teste depois da troca
Chat completions Cada chat.completions.create Mesmos prompts, compare as respostas
Streaming stream=True Os chunks chegam, termina com [DONE], usage presente
Tool calling tools= As chamadas de ferramenta são parseadas e executadas
Saída estruturada response_format= O JSON valida contra o seu schema
Imagens Partes de imagem nas mensagens O modelo aceita
Transcrição de áudio audio.transcriptions Texto e idioma corretos
Embeddings, arquivos, batches Outros endpoints Confira se o provedor oferece

A última linha importa. “Compatível com a OpenAI” normalmente cobre primeiro as chat completions. O catálogo da BroadNet Inference lista modelos de chat em /v1/chat/completions e modelos de fala para texto em /v1/audio/transcriptions; se você usa outros endpoints, mantenha-os no provedor atual ou encontre um substituto.

1. Quais três configurações mudam?

from openai import OpenAI
import os

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

O nome da configuração de base URL muda de biblioteca para biblioteca: base_url no SDK Python e no ChatOpenAI do LangChain, baseURL no SDK Node.js. Segundo o README, o SDK Python também lê a variável de ambiente OPENAI_BASE_URL. Verifique se não sobrou um valor antigo no seu ambiente, ou as requisições podem ir para o provedor antigo sem nenhum erro.

Guarde as chaves de API em variáveis de ambiente ou num gerenciador de segredos, nunca no código. Configuração de cada SDK: Python, Node.js, LangChain. Para montar e testar uma primeira requisição à mão, use o construtor de requisições de API. Para aplicar as mudanças de base URL, chave e modelo ao código que você já tem, cole-o no assistente de migração da OpenAI para a BroadNet, que também lista o que conferir.

2. Quais são os novos IDs de modelo?

Cada provedor dá nome aos modelos do seu jeito. Na BroadNet Inference:

Modelo 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

Coloque o ID do modelo na configuração, não no código, para que uma troca futura seja um deploy e não uma reescrita. Os limites e preços de cada modelo estão na página dele: DeepSeek V4.1 Flash, GLM 5.3, Qwen3.8 27B e Gemma 4 VL 26B.

3. Por que as respostas voltam vazias depois da troca?

Essa é a surpresa mais comum. DeepSeek V4.1 Flash, GLM 5.3 e Qwen3.8 27B raciocinam antes de responder, e os tokens de raciocínio contam no max_tokens. Um limite de 256 que funcionava num modelo sem raciocínio pode ser gasto inteiro pensando, e a resposta volta vazia. Deixe 1.000 tokens ou mais, ou defina reasoning_effort como low para tarefas simples. Explicação completa.

4. O streaming ainda informa o usage?

Os streams usam Server-Sent Events e terminam com data: [DONE]. O uso de tokens só chega no último chunk se você pedir:

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

Sem isso, o seu painel de custos marca zero. Se um stream terminar antes do [DONE], trate-o como incompleto. Guia de streaming.

5. Quais erros vale repetir?

Status Significado O que fazer
401 Chave errada ou revogada, ou franquia de pagamento por uso esgotada Corrija, não repita
402 Saldo ou orçamento Faça uma recarga, não repita
403 Recusada pela política de modelo, rota ou IP Corrija a divergência
413 Requisição grande demais Reduza, não repita
429 Limite de taxa, simultaneidade ou gasto Faça backoff e repita
5xx Lado do servidor Repita com backoff limitado

O SDK Python oficial já repete alguns erros: o README diz que erros de conexão, 408, 409, 429 e respostas 5xx são repetidos duas vezes por padrão, com um backoff exponencial curto. Defina max_retries explicitamente, para que o comportamento seja uma decisão sua e não um padrão. Registre em log o ID da requisição de cada resposta para que o suporte consiga rastrear um problema. Todos os códigos.

6. Quais são os novos rate limits?

Conheça os novos limites antes de o tráfego chegar. Uma chave BroadNet de pagamento por uso permite 30 requisições por minuto e 4 em andamento. Os planos ilimitados rodam uma requisição por vez por sessão. Dimensione o seu pool de workers de acordo, ou você vai ver 429 já no primeiro dia; a calculadora de rate limit faz o dimensionamento. Veja dimensionamento para agentes em paralelo.

7. Os seus prompts ainda cabem?

Confira as janelas de contexto: 1.048.576 tokens no DeepSeek V4.1 Flash e no GLM 5.3, 262.144 no Qwen3.8 27B, 32.768 no Gemma 4 VL 26B. Um prompt que cabia no modelo antigo pode não caber numa janela menor; confira com a calculadora de janela de contexto. Deixe o conteúdo estável do prompt no início para aproveitar o preço de entrada em cache.

8. E as chaves e a retenção de dados?

Restrinja as chaves de produção aos IPs dos seus servidores com uma lista de IPs permitidos. Pergunte ao novo provedor o que ele retém; veja o checklist de ZDR.

9. Como fazer a virada com segurança?

  1. Envie uma cópia das requisições reais de um dia para os dois provedores.
  2. Compare as respostas numa amostra, além de latência, erros e custo por requisição.
  3. Mova 10% do tráfego, observe por um dia e depois mova o resto.
  4. Mantenha o provedor antigo configurado como fallback por uma semana.

Se você roda muitos serviços, um proxy como o LiteLLM permite trocar de provedor num só lugar em vez de em cada app.

Quais são os erros de migração mais comuns?

  • Falta /v1 na base URL. As requisições retornam 404. Use a URL completa.
  • Nomes de modelo antigos na configuração. O novo provedor não os conhece.
  • Campos específicos do provedor esquecidos nas requisições. Campos que só o provedor antigo entendia podem ser rejeitados ou ignorados. Tire-os dos clients genéricos.
  • Testar só um prompt. Percorra o inventário do passo 0, recurso por recurso.
  • Fazer a virada numa sexta-feira. Reserve tempo para acompanhar um dia inteiro de tráfego real.

Onde a BroadNet Inference se encaixa

A BroadNet Inference é um destino plug-and-play para apps que usam chat completions e transcrição de áudio pelos SDKs da OpenAI: troque três configurações e siga a lista acima. O catálogo dela lista apenas modelos de chat e de fala para texto, então, se você depende de outros endpoints, como embeddings ou armazenamento de arquivos, mantenha-os em outro provedor. Contas novas começam com $5 de crédito. Entre os modelos de chat, ele só vale para o Gemma 4 VL 26B (também cobre os dois modelos Transcribe), então um teste em paralelo com DeepSeek, GLM ou Qwen exige uma recarga.

Perguntas frequentes

Preciso de outro SDK?

Não. Os SDKs oficiais da OpenAI para Python e Node.js aceitam uma base URL personalizada. Frameworks construídos sobre eles, como o ChatOpenAI do LangChain, também aceitam.

Como trocar a base URL no SDK da OpenAI?

Passe base_url para o client em Python ou baseURL em Node.js, ou defina a variável de ambiente OPENAI_BASE_URL. Na BroadNet Inference o valor é https://inference.broadnet.ai/v1, e a chave vai em api_key.

Por que recebo resposta vazia depois de trocar?

Modelos de raciocínio como DeepSeek V4.1 Flash, GLM 5.3 e Qwen3.8 27B pensam antes de responder, e esse raciocínio conta no max_tokens. Aumente o max_tokens para 1.000 ou mais, ou defina reasoning_effort como low.

Por que recebo erro 404 ou "model not found" depois de trocar?

Normalmente o ID do modelo ainda é o nome do provedor antigo, ou falta o caminho /v1 na base URL. Use o ID exato do novo provedor e a base URL completa.

Quais erros devo repetir?

Repita 429 e 5xx com backoff exponencial limitado. Corrija 401, 402 e 413 antes de tentar de novo. O guia de erros deste site lista todos os códigos.

Compatível com a OpenAI é o mesmo que idêntico?

Não. O formato de requisição e resposta é o mesmo, mas IDs de modelo, parâmetros suportados, limites, campos de usage e detalhes de erro podem mudar. Teste cada recurso que o seu app usa.

Ler em MarkdownPerguntar ao ChatGPTPerguntar ao ClaudePerguntar ao Perplexity