PT ▾
Obter chave de API

Teste de Migração de API para Apps LLM: Um Plano Prático

O teste de migração de API para um app LLM é diferente de testar uma API REST normal, porque o mesmo prompt nunca retorna o mesmo texto duas vezes. Você testa propriedades da resposta, não strings exatas.

Última atualização

Dois frascos de vidro vertendo luz sobre balanças iguais para ilustrar a comparação de saída entre provedor antigo e novo

Resumo

  • Construa um conjunto de referência de 50 a 200 prompts reais com verificações baseadas em regras, não expectativas de correspondência exata.
  • Fixe a temperatura e a semente para reduzir o ruído, mas nunca espere texto idêntico.
  • Registre percentis de latência e custo por requisição na rota antiga e nova.
  • Registre os gatilhos de reversão antes do início do lançamento.

O que você está testando realmente

Com uma API clássica você compara respostas byte a byte. Com um modelo de linguagem isso falha imediatamente. Em vez disso, decida quais propriedades da resposta seu produto depende e teste essas.

  • Formato. JSON válido, chaves obrigatórias, uma chamada de função com os argumentos corretos.
  • Conteúdo. Menciona os fatos necessários, segue o formato e mantém a persona.
  • Segurança do produto. Sem recusa onde uma resposta é esperada, sem vazamento de prompt do sistema.
  • Operações. Latência, taxa de erro, comportamento de limite de requisições, custo.

Se você ainda precisa das etapas de troca, o plano está no guia de migração neste site, e as falhas encontradas ao longo do caminho são cobertas em erros comuns de integração LLM. Este artigo cobre a verificação.

Construa o conjunto de prompts de referência

Puxe 50 a 200 prompts reais dos seus logs (remova dados pessoais primeiro). Cubra o caminho comum, os casos difíceis e os casos que falharam antes. Armazene cada um como um registro com suas mensagens, parâmetros e as verificações que deve passar.

{
  "id": "invoice-json-03",
  "messages": [
    {"role": "system", "content": "Extract fields. Reply with JSON only."},
    {"role": "user", "content": "Invoice 4471 from Acme, total 1,250 EUR, due 2025-03-01"}
  ],
  "json": true,
  "required_keys": ["number", "vendor", "total"],
  "must_contain": ["4471"]
}

Classifique os casos por risco: chamadas de ferramentas, contexto longo, streaming, idiomas não ingleses, respostas muito curtas e muito longas. Quando um bug aparecer em produção posteriormente, adicione-o ao conjunto. O conjunto cresce para sua suíte de regressão.

Escreva uma suíte que registre tudo

Um script deve executar o conjunto inteiro contra uma rota, aplicar as verificações e salvar os números. Use temperature=0 e uma seed fixa para reduzir a variação. Ambos são passados por esta API, mas trate-os como redução de ruído, não como garantia.

import json, time
from openai import OpenAI

client = OpenAI(base_url="https://api.apimigration.com/v1", api_key="YOUR_KEY")
PRICE_IN, PRICE_OUT = 0.15, 0.50  # USD per 1M tokens

def run(case):
    t0 = time.perf_counter()
    raw = client.chat.completions.with_raw_response.create(
        model="uncensored",
        messages=case["messages"],
        temperature=0,
        seed=42,
    )
    elapsed = time.perf_counter() - t0
    resp = raw.parse()
    text = resp.choices[0].message.content or ""
    u = resp.usage
    return {
        "id": case["id"],
        "text": text,
        "seconds": elapsed,
        "cost": (u.prompt_tokens * PRICE_IN + u.completion_tokens * PRICE_OUT) / 1e6,
        "balance": raw.headers.get("X-Balance-USD"),
        "request_id": raw.headers.get("X-Request-Id"),
    }

Mantenha o X-Request-Id para cada caso falho. É isso que você cita ao pedir suporte sobre uma requisição específica.

Compare por regras, não por strings

Aplique as verificações de cada registro. Qualquer coisa que falhar vai para uma lista curta para leitura humana.

def check(case, text):
    problems = []
    if case.get("json"):
        try:
            obj = json.loads(text)
        except ValueError:
            return ["invalid json"]
        for key in case.get("required_keys", []):
            if key not in obj:
                problems.append("missing key " + key)
    for needle in case.get("must_contain", []):
        if needle.lower() not in text.lower():
            problems.append("missing text " + needle)
    if len(text.strip()) < case.get("min_chars", 1):
        problems.append("answer too short")
    return problems

Para respostas de texto livre, adicione uma faixa de tamanho barata (por exemplo, entre metade e o dobro da resposta antiga) e uma lista curta de frases de recusa para sinalizar. Depois, leia 20 saídas lado a lado visualmente. As regras capturam regressões; a leitura captura o tom. Faça os dois.

Para saídas JSON, defina response_format para {"type":"json_object"} e ainda valide, já que as verificações acima são baratas.

Teste os caminhos de falha de propósito

Prompts de happy-path passam em quase qualquer provedor. Falhas são onde as migrações doem, então provoque-as deliberadamente antes que os usuários façam.

  • Chave inválida. Envie uma requisição com uma chave errada e confirme que seu app mostra uma mensagem razoável e não tenta novamente em loop.
  • Limites de requisições. Dispare mais de 8 requisições simultâneas em uma chave completa (2 em uma chave de teste) e confirme que seu código lida com o HTTP 429 com o código concurrency, depois com o código rate_limited se você ultrapassar o limite por minuto.
  • Sobrecarga temporária. Um 429 com Retry-After: 5 deve levar a uma espera de cinco segundos, não a uma tentativa agressiva de retry.
  • Entrada excessiva. Envie um prompt próximo da janela de 100.000 tokens e outro além dela. Seu app deve truncar ou resumir, não falhar.
  • Corpos grandes. O limite é de 8 MB. Confirme que você rejeita payloads maiores por conta própria.
  • Streams descartados. Encerre a conexão durante o streaming e confirme que o slot de concorrência é liberado.

Cada um desses deve ter um teste automatizado que roda em CI contra um servidor fake, mais uma passagem manual contra o real.

Verifique streaming e chamadas de funções

Streaming e ferramentas mudam o formato da resposta, então um conjunto de referência construído em texto puro os perde. Adicione um caso para cada.

tools = [{
    "type": "function",
    "function": {
        "name": "get_order_status",
        "description": "Look up an order by id",
        "parameters": {
            "type": "object",
            "properties": {"order_id": {"type": "string"}},
            "required": ["order_id"],
        },
    },
}]

r = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Where is order A-1042?"}],
    tools=tools,
    tool_choice="auto",
)
calls = r.choices[0].message.tool_calls or []
assert calls and calls[0].function.name == "get_order_status"
print(calls[0].function.arguments)

A asserção verifica a existência da chamada e se os argumentos são analisados como o JSON esperado. Adicione uma verificação de que o segundo turno, com o resultado enviado de volta como uma mensagem com role: "tool", produza uma resposta normal. Para streams, afirme que os chunks chegam, que o uso final aparece e que seu código para de ler no final do stream.

Rastreie latência e custo por rota

Execute o conjunto na rota antiga e nova e compare as mesmas colunas: mediana e percentil 95 de segundos, contagem de erros, tokens, custo. Este artigo não fornece números de latência para nenhum provedor, porque os seus dependerão dos seus prompts e rede. Meça os seus próprios.

O custo para a nova rota é o número de tokens vezes as taxas, $0,15 por 1M de entrada e $0,50 por 1M de saída. Exemplo: 200 prompts golden com média de 1.200 tokens de entrada e 300 de saída.

  • Entrada: 240.000 tokens x $0,15 / 1.000.000 = $0,036.
  • Saída: 60.000 tokens x $0,50 / 1.000.000 = $0,03.
  • Uma execução completa: $0,066.

O crédito de teste de $0,50 cobre cerca de sete execuções assim. Uma chave de teste permite 2 requisições simultâneas e 60 por minuto, então 200 prompts levam pelo menos três minutos e meio. Requisições falhas ou recusadas não são cobradas. Você também pode ler o saldo no cabeçalho X-Balance-USD após cada chamada para confirmar seus próprios cálculos.

Tráfego sombra e lançamento gradual

Depois que o conjunto golden passar, copie as requisições reais para a nova rota sem mostrar as respostas. Registre os resultados e compare-os com as respostas reais usando as mesmas verificações. Execuções sombra precisam de um limite de concorrência: uma chave completa permite 8 requisições de uma vez, então enfileire as chamadas espelhadas em vez de dispará-las todas juntas.

Depois, mova usuários reais em etapas, como 5%, 25%, 50% e 100%. Mantenha cada etapa até que a taxa de erro, as verificações falhas e as reclamações permaneçam estáveis.

Defina as regras de reversão antecipadamente

Escreva os limites antes de mover o primeiro usuário, para que a decisão no momento seja mecânica.

SinalExemplo de gatilho
Falhas de verificação no tráfego realMais do que sua cota combinada falham nas regras de verificação
Taxa HTTP 429 ou 5xxSustentado acima da linha de base da rota antiga
Latência p95Acima do orçamento de tempo limite do seu produto
Custo por requisiçãoAcima da estimativa por uma margem definida
Relatórios de usuáriosUm cluster com o mesmo comportamento

O rollback deve ser uma alteração de configuração, não uma implantação. Mantenha a rota antiga financiada e configurada por pelo menos alguns dias após 100%. Quando estiver pronto para executar os testes, obtenha uma chave de API e reivindique o teste, verifique preços para execuções maiores e use a documentação para detalhes do endpoint.

Perguntas frequentes

Quantos prompts de referência eu preciso?

Cinquenta a duzentos prompts reais cobrem a maioria dos aplicativos. A qualidade é mais importante que a quantidade, então inclua os casos difíceis e anteriormente problemáticos.

Posso comparar saídas com um diff de correspondência exata?

Não de forma confiável. Mesmo com temperatura 0 e uma semente fixa, trate as saídas como variáveis e teste regras como JSON válido, fatos obrigatórios e comprimento.

Como rastrear o custo durante os testes?

Multiplique os tokens de uso por $0,15 por 1M de entrada e $0,50 por 1M de saída, e monitore o cabeçalho X-Balance-USD para o saldo real.

O que deve acionar uma reversão?

Defina os limites primeiro: verificações falhas, taxas de 429 ou 5xx, latência em relação ao seu tempo limite e custo em relação à estimativa.

Obtenha sua chave de API

Registre-se, copie a chave, atualize a URL base. A configuração está completa.

Obter chave de API