7 Testes de Migração Antes de Alterar uma URL Base de API de IA

Os testes de migração da URL base da API de IA devem ocorrer antes da alteração da variável de ambiente, não depois que o tráfego de produção começar a falhar. Alterar um único baseURL ou base_url pode mover autenticação, seleção de modelo, streaming, chamada de ferramenta, registros de uso, comportamento de cota e controle de reversão para um novo caminho ao mesmo tempo.

O Flatkey foi projetado para equipes que desejam uma única chave, uma camada de roteamento compatível com OpenAI e uma revisão mais clara de faturamento e uso entre provedores de modelos. A página inicial pública do Flatkey, verificada em 7 de julho de 2026, mostrava a rota de exemplo https://router.flatkey.ai/v1/chat/completions, enquanto as páginas atuais de modelos e preços expunham o contexto de modelo, endpoint, provedor e faturamento para revisão. Trate essas páginas como evidência do dia da migração e, em seguida, execute seus próprios testes de fumaça (smoke tests) na conta antes de mover o tráfego.

Use este guia como uma sequência prática de testes de migração de URL base de API de IA. O objetivo não é provar todos os caminhos do aplicativo. O objetivo é provar o menor caminho seguro através da nova URL base e, em seguida, adicionar recursos uma camada de cada vez.

Os 7 Testes de Migração de URL Base de API de IA

Execute os testes nesta ordem. Cada um deve produzir evidências que você pode anexar a um ticket de implantação.

Não pule os testes iniciais porque um wrapper de framework já funcionou em staging. A maioria dos testes de migração de URL base de API de IA falha porque o SDK lê silenciosamente uma chave diferente, recebe a raiz da URL base errada ou envia um modelo válido para a família de endpoints errada.

Teste 1: Autenticação e Composição da URL Base

Comece fora do aplicativo. Você precisa provar que a chave e a URL base podem alcançar a forma mais simples de endpoint.

O erro comum da URL base é passar o endpoint completo para o SDK. Para um SDK compatível com OpenAI, a URL base geralmente é a raiz da API, como https://router.flatkey.ai/v1, e o SDK anexa /chat/completions, /responses ou outro endpoint. Passar https://router.flatkey.ai/v1/chat/completions como a URL base pode criar um caminho duplicado.

Use primeiro uma verificação de ambiente editada:

test -n "$FLATKEY_API_KEY" && echo "FLATKEY_API_KEY is set"
printf '%s' "$FLATKEY_API_KEY" | wc -c
printf '%s\n' "$FLATKEY_BASE_URL"

Em seguida, faça uma solicitação direta:

export FLATKEY_BASE_URL="https://router.flatkey.ai/v1"
export FLATKEY_MODEL="your-current-flatkey-model-alias"

curl -sS "$FLATKEY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLATKEY_MODEL"'",
    "messages": [
      {"role": "user", "content": "Reply with exactly: base url ok"}
    ]
  }'

Se isso retornar 401, corrija a chave e o cabeçalho de autenticação antes de alterar os modelos. Se retornar 404, verifique o host, a raiz /v1 e se o caminho do endpoint foi duplicado. Se retornar 403, verifique a conta, o projeto, o modelo, a região ou a política de IP. A documentação de códigos de erro da OpenAI trata 401 como autenticação, 429 como taxa ou cota, e 500 ou 503 como condições de servidor ou sobrecarga; um gateway pode adicionar mais detalhes, então salve o corpo da resposta.

Teste 2: Catálogo de Modelos e Família de Endpoints

Uma URL base compatível com OpenAI não torna todos os nomes de modelo portáteis. A API da OpenAI tem um endpoint para Listar modelos, e seus endpoints de Conclusões de Chat e Respostas usam formatos de solicitação diferentes. Uma rota de gateway ou compatível com o provedor pode expor um modelo para uma família de endpoints, mas não para outra.

Antes de alterar a configuração de produção, crie um pequeno mapa de modelos:

A condição de aprovação não é "o nome do modelo parece correto". A condição de aprovação é que o console Flatkey atual, o diretório de modelos ou o catálogo do provedor mostre o alias exato para a família de endpoints exata que você planeja chamar. Vincule este trabalho à sua governança de modelos mais ampla com o guia de nomes de modelos compatíveis com OpenAI.

Teste 3: Conclusão de Chat Simples

O terceiro teste de migração de URL base de API de IA é a menor solicitação de geração real. Mantenha-o sem streaming. Não inclua ferramentas, esquema JSON, arquivos, imagens, novas tentativas ou middleware de aplicativo.

Salve:

Se a solicitação simples falhar, não depure o streaming ainda. Use o guia de solução de problemas de API compatível com OpenAI para isolar primeiro os problemas de chave, rota, família de endpoints e alias do modelo.

Teste 4: Paridade de SDK

Depois que o curl funcionar, prove que o SDK constrói a mesma rota. Os documentos oficiais atuais da OpenAI direcionam os desenvolvedores para os SDKs oficiais para JavaScript e Python. O livro de receitas da OpenAI também mostra o uso de endpoints personalizados, onde um cliente é criado com um token e uma URL base personalizada. Para a migração, torne isso explícito no código em vez de depender de valores restantes de OPENAI_API_KEY ou OPENAI_BASE_URL.

Modelo Python:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["FLATKEY_API_KEY"],
    base_url=os.environ.get("FLATKEY_BASE_URL", "https://router.flatkey.ai/v1"),
)

response = client.chat.completions.create(
    model=os.environ["FLATKEY_MODEL"],
    messages=[{"role": "user", "content": "Reply with exactly: sdk ok"}],
)

print(response.choices[0].message.content)
print(response.usage)

Modelo Node:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.FLATKEY_API_KEY,
  baseURL: process.env.FLATKEY_BASE_URL ?? "https://router.flatkey.ai/v1",
});

const response = await client.chat.completions.create({
  model: process.env.FLATKEY_MODEL!,
  messages: [{ role: "user", content: "Reply with exactly: sdk ok" }],
});

console.log(response.choices[0]?.message?.content);
console.log(response.usage);

Registre a URL base resolvida na inicialização do processo, mas não registre a chave. Se o curl for bem-sucedido e o SDK falhar, inspecione a precedência das variáveis de ambiente, a versão do SDK, a junção de caminhos, os cabeçalhos de organização/projeto e o comportamento do proxy antes de alterar o modelo.

Teste 5: Streaming ou SSE

O streaming é onde muitas migrações parecem saudáveis na camada HTTP, mas falham no aplicativo. A referência de Conclusões de Chat da OpenAI retorna um objeto JSON ou pedaços de conclusão de chat transmitidos quando o streaming está ativado. A API de Respostas também pode retornar text/event-stream, com nomes de eventos que diferem dos pedaços de Conclusões de Chat.

Execute isto depois que a solicitação sem streaming funcionar:

curl -N "$FLATKEY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLATKEY_MODEL"'",
    "stream": true,
    "messages": [
      {"role": "user", "content": "Conte de um a cinco lentamente."}
    ]
  }'

Condições de aprovação:

Para uma análise de stream mais aprofundada, compare com o teste de streaming SSE compatível com OpenAI existente.

Teste 6: Chamada de Ferramenta ou Função

A chamada de ferramenta adiciona risco de esquema e capacidade. O guia de chamada de função da OpenAI descreve um fluxo de várias etapas: enviar ferramentas, receber uma chamada de ferramenta, executar o código do aplicativo, retornar a saída da ferramenta e, em seguida, receber a resposta final do modelo. Uma migração de URL base pode falhar em qualquer um desses limites, mesmo quando o texto simples funciona.

Não comece com toda a sua superfície de ferramentas de produção. Use uma função minúscula:

{
  "model": "your-current-flatkey-model-alias",
  "messages": [
    {"role": "user", "content": "Use a ferramenta para o pedido A123."}
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "lookup_order",
        "description": "Retornar o status de um pedido de teste.",
        "parameters": {
          "type": "object",
          "properties": {
            "order_id": {"type": "string"}
          },
          "required": ["order_id"],
          "additionalProperties": false
        }
      }
    }
  ],
  "tool_choice": "auto"
}

Se isso falhar enquanto o chat simples funcionar, você não está mais depurando a URL base. Você está depurando a capacidade do modelo, a família de endpoints, a rigidez do esquema, tool_choice ou o suporte do gateway para a rota selecionada. O guia de compatibilidade de chamada de ferramentas publicado abrange uma lista de verificação de provedores maior.

Teste 7: Uso, Cota e Reversão

Os testes finais de migração da URL base da API de IA são operacionais. Uma resposta gerada não é suficiente se o financeiro não puder reconciliá-la, as cotas não se comportarem como esperado ou a reversão exigir uma alteração de código de emergência.

Após um teste de fumaça bem-sucedido, verifique:

Use um arquivo de reversão que seja simples o suficiente para executar sob pressão:

# ativo
AI_API_BASE_URL=https://router.flatkey.ai/v1
AI_API_MODEL=your-current-flatkey-model-alias

# reversão
AI_API_BASE_URL_ROLLBACK=https://previous-provider.example/v1
AI_API_MODEL_ROLLBACK=previous-production-model
AI_API_ROLLBACK_OWNER=platform-oncall

Não confie na memória para a reversão. Armazene a configuração anterior, a feature flag, o comando de implantação e o comando de verificação no mesmo ticket de implantação que os testes de migração da URL base da API de IA.

O Pacote de Evidências a Manter

Para cada ambiente, mantenha um pacote que responda a estas perguntas:

Esta é a vantagem prática de executar testes de migração da URL base da API de IA antes da transição. O artefato é útil para revisão de implantação, resposta a incidentes, reconciliação de uso e evidência de aquisição.

Onde o Flatkey se Encaixa

O Flatkey pode reduzir a proliferação da migração centralizando o acesso ao modelo, roteamento, faturamento, análise de uso e revisão operacional por trás de uma única chave. Isso não elimina a necessidade de testar. Ele dá à equipe um único ponto de controle onde engenharia, finanças e operações podem inspecionar as mesmas evidências de rota.

Antes de migrar, revise as páginas de modelos Flatkey e preços ao vivo, confirme a URL base do console atual e comece com um pequeno teste de rota. Se você ainda está planejando a transição mais ampla, combine este guia com o guia de migração de API compatível com OpenAI. Quando estiver pronto para executar seus próprios testes, obtenha uma chave e mantenha a primeira solicitação pequena o suficiente para inspecionar manualmente.

FAQ

O que são testes de migração de URL base de API de IA?

Testes de migração de URL base de API de IA são verificações pré-transição que provam que a nova raiz da API funciona para autenticação, roteamento de modelo, chat simples, uso de SDK, streaming, ferramentas, leitura de uso, comportamento de cota e reversão.

Devo testar o curl ou o SDK primeiro?

Teste o curl primeiro. O curl prova a chave, a URL, o caminho do endpoint e o alias do modelo sem o comportamento do framework. Em seguida, teste o SDK com os mesmos valores.

A URL base deve incluir /chat/completions?

Geralmente não. Forneça ao SDK a raiz da API, como /v1, e deixe o SDK anexar o endpoint. Use o endpoint completo apenas para solicitações curl diretas.

Por que o streaming falha quando o chat simples funciona?

O streaming pode falhar porque a rota armazena as respostas em buffer, o analisador do cliente espera o formato de evento errado, o middleware consome o stream ou a família de endpoints selecionada não suporta o formato de stream que você está usando.

E se eu ainda não puder executar solicitações Flatkey ao vivo?

Mantenha os trechos de código como modelos, valide os documentos públicos e a configuração do console e não mova o tráfego de produção até que uma chave real comprove os sete testes de migração da URL base da API de IA em seu próprio ambiente.

Conclusão

Alterar uma URL base de API de IA é uma migração de produção, não uma edição de string. Execute os testes de migração da URL base da API de IA na ordem: autenticação, catálogo de modelos, chat simples, paridade de SDK, streaming, ferramentas e uso mais reversão. Quando todos os sete forem aprovados, a alteração da URL base torna-se uma transição controlada em vez de uma sessão de depuração tardia.