Guia de Migração de API: Troque de provedores LLM com segurança
Este guia de migração de API mostra como mover um app que já usa um endpoint de chat estilo OpenAI para outro provedor. A maior parte do trabalho não são as duas linhas que você altera, mas descobrir o que dependia do provedor antigo por acaso.
Última atualização

Resumo
- Para um destino compatível com OpenAI, você altera a URL base, a chave e o ID do modelo, e depois verifica o comportamento.
- Inventário de recursos primeiro: embeddings, imagens e ajustes finos não serão transferidos para uma API apenas de texto.
- Implemente por porcentagem com um sinalizador para que a reversão exija apenas uma alteração de configuração.
- Estime a nova fatura com base na contagem de tokens antes da migração.
O plano em seis etapas
- Inventarie todos os recursos de API chamados pelo seu app.
- Mova as configurações do provedor para a configuração.
- Mapeie parâmetros e nomes de modelos.
- Adicione tratamento de erros e limite de requisições compatível com os novos limites.
- Roteie uma pequena parte do tráfego para o novo provedor e compare.
- Verifique o custo, faça o cutover e mantenha a rota antiga por um tempo.
O alvo nos exemplos é https://api.apimigration.com/v1 com ID do modelo uncensored. As mesmas etapas se aplicam a qualquer provedor compatível com OpenAI, então leia-as como uma lista de verificação, não como uma receita de fornecedor. Se algo quebrar no caminho, o artigo de solução de problemas sobre erros comuns de integração LLM cobre as causas habituais.
Passo 1: Inventário do que seu app usa
Procure em seu código todas as chamadas ao provedor antigo e liste os recursos, bem como os endpoints. Uma única chamada de chat frequentemente oculta várias dependências: um prompt do sistema que depende de um estilo específico, um esquema de ferramenta, um formato de resposta JSON, um contexto grande.
| Recurso no seu app | Nesta API |
|---|---|
Compleções de chat, /v1/responses | Suportado |
| Streaming sobre SSE | Suportado, uso enviado no final |
| Chamada de funções | Suportado, incluindo tool_calls transmitidos |
| Modo JSON | Suportado via response_format |
| Contexto | 100.000 tokens, prompt mais conclusão |
| Embeddings, imagens, áudio, ajuste fino | Não oferecido, mantenha isso em outro provedor |
Se o provedor antigo também lidava com embeddings ou geração de imagens, divida a migração: mova apenas as chamadas de texto e deixe o resto onde está.
Passo 2: Coloque as configurações do provedor na configuração
URLs codificadas são o que transformam uma migração em uma alteração de código. Leia a URL base, a chave e o ID do modelo do ambiente para que você possa alternar sem precisar de uma nova implantação.
export LLM_BASE_URL="https://api.apimigration.com/v1"
export LLM_API_KEY="YOUR_KEY"
export LLM_MODEL="uncensored"
import os
from openai import OpenAI
client = OpenAI(
base_url=os.environ["LLM_BASE_URL"],
api_key=os.environ["LLM_API_KEY"],
)
MODEL = os.environ.get("LLM_MODEL", "uncensored")
A autenticação usa o cabeçalho padrão Authorization: Bearer, que o SDK define para você. Para confirmar a chave e ver o que o servidor oferece, chame GET /v1/models.
curl https://api.apimigration.com/v1/models \
-H "Authorization: Bearer $LLM_API_KEY"Passo 3: Mapeie parâmetros e prompts
Parâmetros que passam nesta API: temperature, top_p, stop, seed e as penalidades de frequência e presença. max_tokens é opcional. Se seu código antigo o define para proteger contra custos descontrolados, mantenha-o.
Três coisas merecem uma verificação deliberada.
- Campos específicos do fornecedor. Qualquer coisa fora do formato de solicitação OpenAI pode ser ignorada ou rejeitada. Envie uma solicitação com seu payload de produção exato e leia a resposta.
- Comportamento do modelo. Um modelo diferente lê o mesmo prompt de outra forma. System prompts ajustados para o modelo antigo muitas vezes precisam de pequenas edições. Teste-os, não assuma.
- Recusas. Se seus prompts antigos continham soluções alternativas para evitar recusas, você geralmente pode excluí-los aqui, o que encurta o prompt.
O modelo também difere no que ele responderá. Este é ajustado para uso adulto legal sem recusas de conteúdo, e conteúdo sexual envolvendo menores de idade é bloqueado.
Passo 4: Ajuste o tratamento de erros aos novos limites
Uma chave completa permite 8 requisições simultâneas e 300 por minuto. Uma chave de teste permite 2 e 60. Acima do limite, você recebe HTTP 429 com código de erro rate_limited ou concurrency. Em sobrecarga temporária, você também recebe 429, com Retry-After: 5.
import time
from openai import RateLimitError
def chat(messages, retries=4):
for attempt in range(retries):
try:
return client.chat.completions.create(model=MODEL, messages=messages)
except RateLimitError:
time.sleep(5 * (attempt + 1))
raise RuntimeError("still rate limited after retries")
As requisições em streaming mantêm sua slot de concorrência até o fim do streaming, então um cliente travado pode esvaziar o restante. Feche streams em um bloco finally. Se seu provedor antigo permitia mais chamadas paralelas, adicione um semáforo dimensionado para o novo limite. Requisições falhas não são cobradas, o que torna as retentativas seguras para seu orçamento.
Passo 5: Faça rollout por porcentagem
Não altere tudo de uma vez. Envie uma pequena parcela estável de usuários para o novo provedor e mantenha o antigo como reserva. A hash do ID do usuário mantém cada usuário em um lado, para que as conversas não mudem de voz no meio do caminho.
import hashlib
def use_new(user_id: str, percent: int) -> bool:
bucket = int(hashlib.sha256(user_id.encode()).hexdigest(), 16) % 100
return bucket < percent
# 5 percent, then 25, 50, 100 as metrics hold
new_client = OpenAI(base_url="https://api.apimigration.com/v1", api_key=os.environ["NEW_KEY"])
old_client = OpenAI(base_url=os.environ["OLD_BASE_URL"], api_key=os.environ["OLD_KEY"])
def pick(user_id):
return new_client if use_new(user_id, int(os.environ.get("ROLLOUT_PERCENT", "0"))) else old_client
Aumente a porcentagem apenas após a etapa anterior ter rodado limpa por um dia ou mais. O rollback é então uma variável de ambiente definida de volta para 0.
O que geralmente surpreende as equipes após a migração
A alteração da URL base funciona na primeira tentativa. As surpresas vêm depois.
- Deriva de tom e formato. O mesmo prompt gera uma resposta com palavras diferentes. Recursos que analisam texto livre, como uma regex para prefixos "Resposta:", são os primeiros a falhar. Prefira o modo JSON ou chamadas de funções para qualquer coisa que um programa vai ler.
- Contagens de token diferentes. Cada modelo tokeniza o texto do seu próprio jeito. Sua estimativa de custo baseada nas contagens de token do provedor antigo estará incorreta em algum grau, então meça novamente usando o campo
usage. - Comprimento da saída. Sem
max_tokens, a conclusão pode usar o restante da janela de 100.000 tokens. Se sua configuração antiga tinha um limite padrão, defina um com propósito. - Tempo limite. O tempo limite do seu cliente foi ajustado para o provedor antigo. Respostas longas em um novo podem ultrapassá-lo. Use streaming onde possível e aumente o tempo limite para chamadas sem streaming.
- Recusas silenciosas mudando. Se seu produto costumava capturar mensagens de recusa e mostrar uma resposta alternativa, esse código pode parar de ser executado. Decida se você ainda quer mantê-lo.
Uma lista de verificação curta antes da virada
- Cada recurso no seu inventário tem um equivalente testado ou uma lacuna documentada.
- Base URL, chave e modelo vêm da configuração em todos os serviços que chamam a API.
- Limite de requisições e limites de concorrência no seu código correspondem aos novos limites.
- Os streams são fechados na desconexão do cliente.
- Os logs incluem o cabeçalho
X-Request-Id, para que você possa citar uma requisição ao pedir ajuda. - O saldo é monitorado através de
X-Balance-USDouGET /v1/balance, com um alerta antes que fique baixo. - O provedor antigo ainda possui fundos configurados e está preparado para reversão.
- Uma pessoa designada é responsável pela decisão de reverter.
Esse último item parece bobo até um incidente às 2 da manhã. Alguém precisa ter permissão para inverter a bandeira.
Passo 6: Verifique o custo, então realize a migração
Calcule a nova conta a partir do seu próprio tráfego. Os preços são $0,15 por 1M tokens de entrada e $0,50 por 1M tokens de saída.
Exemplo: 10.000 requisições por dia, cada uma com 1.500 tokens de entrada e 400 tokens de saída.
- Entrada: 15.000.000 tokens x $0,15 / 1.000.000 = $2,25.
- Saída: 4.000.000 tokens x $0,50 / 1.000.000 = $2,00.
- Total: $4,25 por dia.
Compare isso com a fatura antiga, usando a página de preços atual do provedor antigo. A cobrança aqui é crédito pré-pago sem assinatura, e o crédito nunca expira. Recargas variam de $20 a $500 em valores inteiros, com bônus de 5% a partir de $50, 10% a partir de $100 e 15% a partir de $200, pagos em cripto (USDT em TRC20 ou USDC em Base). O saldo aparece no cabeçalho de resposta X-Balance-USD, para que você possa configurar um alerta.
Novas contas podem reivindicar $0,50 de crédito de teste para os primeiros testes. Consulte preços, depois obter uma chave de API e mantenha a documentação aberta enquanto mapeia os parâmetros.
Mais guias
Perguntas frequentes
Posso migrar alterando apenas a URL base?
Para uma API compatível com OpenAI, a URL base, a chave e o ID do modelo são as alterações necessárias. Você ainda deve testar prompts, já que um modelo diferente responde de forma diferente.
Minhas chamadas de funções e modo JSON ainda funcionarão?
Chamada de ferramentas e modo JSON (response_format json_object) são suportados. Valide seus esquemas com prompts reais antes da migração.
E se meu app usa embeddings?
Esta API é apenas de texto e não oferece embeddings, geração de imagens ou ajuste fino. Mantenha essas chamadas no seu provedor atual.
Como reverter rapidamente?
Redirecione o tráfego por meio de um sinalizador de ambiente, como uma porcentagem de lançamento, e mantenha o cliente antigo configurado até que a nova rota funcione corretamente por alguns dias.
Obtenha sua chave de API
Registre-se, copie a chave, atualize a URL base. A configuração está completa.