Como avaliar um AI API Gateway: checklist para produção

Avalie um AI API gateway executando seu Protocol Contract real, forçando Failure Modes importantes e verificando Request-level Evidence. Uma lista de recursos ou um “hello world” bem-sucedido não prova streaming correto, Tool Compatibility, fallback seguro, custos exatos, Security Boundary nem Exit Path utilizável.

O processo mais confiável separa Mandatory Gates, que eliminam o candidato, de qualidades operacionais pontuadas apenas depois que todos os gates passam.

Definir primeiro o Workload Contract

Não comece por tabela de vendors. Selecione um workload representativo e documente os invariantes:

• endpoint exato: Responses, Chat Completions, Embeddings, Images ou outra API;
• Model IDs exatos e se Aliases são permitidos;
• modos Streaming e Non-streaming usados;
• Structured Outputs, Function Calling, Hosted Tools, Reasoning e campos obrigatórios;
• comprimentos típicos e de alto percentil de Input/Output;
• Concurrency, Request Rate, Region e User-facing Deadline;
• campos necessários de Usage, Cache, Cost e Request Correlation;
• Fallback Routes permitidas e proibição de Model Substitution;
• Data Retention, Access, Residency e Deletion;
• Application Operations que criam Side Effects.

O mesmo gateway pode passar para um assistente interno de texto e falhar para um coding agent em streaming. “OpenAI-compatible” não define workload: Compatibility varia por Endpoint, Event Type, Tool, Schema Keyword e Provider Route.

Se a equipe ainda decide entre proxy e Model-aware Control Plane, comece por LLM Proxy vs AI Gateway. Esta checklist assume que a categoria gateway já foi justificada e testa uma implementação específica.

Aplicar desqualificadores rápidos antes de um trial longo

A primeira revisão deve remover candidatos incapazes de cumprir um limite obrigatório. Exija comportamento reproduzível, não promessa de roadmap.

Gate	Condição de falha imediata	Evidência solicitada
Protocol	Request Field, Output Item ou Stream Event obrigatório é perdido ou reescrito incorretamente	Request/response redigidos e Parser Result
Model Identity	Requested Model é trocado silenciosamente	Attempt Record com modelo pedido e real
Streaming	Buffer completo, Cancellation perdida ou Tool Argument Fragments corrompidos	Event Sequence com timestamps e Cancel Trace
Authentication	Browser ou Workload Client recebe Provider Credentials	Credential Flow e exercício real de Key Rotation
Tenant Isolation	Um Project usa ou inspeciona Keys, Usage ou Logs de outro	Verificações com contas realmente isoladas
Cost Evidence	Final Charge não se conecta a Model, Route, Price Basis e Usage	Ledger reconciliado de uma Request
Failure Safety	Partial Stream é repetido ou Cancel inicia outro Attempt	Traces forçados de Partial Stream e Cancellation
Export and Exit	Configuration e Contract não são recuperáveis sem reescrever aplicação	Export Sample e Provider-native Rollback Drill

Falha em Mandatory Gate não pode ser compensada por pontuação alta. Dashboard bom não corrige Tenant Isolation e preço baixo não corrige Tool Contract incorreto.

Construir um pequeno Protocol Conformance Corpus

Use Inputs determinísticos e não sensíveis e versione o Wire Behavior esperado. O corpus deve chamar o endpoint real; não use Provider Mock nem reimplemente Conversion Logic como Test Oracle.

Caso	Request	Observação obrigatória
Basic Non-streaming Text	Pinned Model e Prompt fixo	Status, Model Identity, Text Location, Usage, Request ID corretos
Streaming Text	Mesmo Prompt com Streaming	Events ordenados, First Effective Output, Final Event, Cancellation
Structured Output	Strict Schema com Required e additionalProperties: false	Output válido ou Unsupported Error explícito, sem Silent Downgrade
Function Calling	Função Read-only e Result retornado	Function Name, JSON Arguments, Call ID Correlation, Final Answer
No-tool Path	Tools declaradas, mas desnecessárias	Texto normal sem Tool Call fabricada
Invalid Field	Request Unsupported ou Malformed de propósito	Client Error estável; fallback não esconde defeito
Long Input Boundary	Input logo abaixo e acima do limite	Aceitação documentada ou rejeição explícita, sem truncamento silencioso
Usage Detail	Request que aciona Cache ou Reasoning Usage	Campos atravessam route e reconciliam com Billing Record
Cancellation	Cancel após conexão e após First Output	Upstream Work para e nenhum novo Fallback Attempt inicia
Partial Stream	Falha após Effective Output	Um Partial Failure explícito, sem segunda resposta invisível

Execute cada caso em todas as rotas que podem servir o workload. Primary Route aprovada não qualifica fallback. O guia Structured Outputs e a comparação Function Calling oferecem Field-level Cases.

Registre Gateway Version, Route Configuration Version, Model ID, Provider, Region, Timestamp e Sanitized Result Hash. Reavalie antes do rollout e após mudança material de route.

Testar Routing e Failure Behavior, não apenas sucesso

Reliability Claim só vale com Failure Policy visível. Force antes de Production:

• Primary Route indisponível antes de Headers;
• Provider Rate Limit com e sem Retry-After;
• Upstream Authentication ou Account Failure;
• Slow Headers e Slow First Effective Output;
• Malformed Provider Response;
• Caller Cancellation durante upstream pending;
• Connection Loss após output visível;
• todas as rotas elegíveis esgotadas.

Capture Attempt Order, Selected Route, Status, Timing, início do Output, Terminal Reason, Usage e Cost. Confirme que modelo e protocolo solicitados são preservados sem Model-substitution Policy explícita.

Meça Attempt Amplification entre SDK, aplicação, gateway e provider. Uma camada cuida do Same-contract Fallback imediato; a aplicação decide repetir a User Action completa. AI API Fallback Strategy fornece Failure Matrix por fase e Retry Budget.

Latência exige precisão. Compare Upstream Headers, First SSE Event, First Effective Output, First Visible Text, Completion e Visible Output Speed sob Concurrency realista. Não aceite uma média “Latency” sem definição. Consulte AI API Latency Metrics.

Reconciliar Usage e Cost por Request

Siga várias Requests concluídas por toda a cadeia:

application request ID
  → gateway attempt sequence
  → selected model and route
  → provider or normalized usage
  → applicable price basis
  → final recorded charge

A avaliação precisa responder:

• Input, Output, Cached, Reasoning e Tool-related Units aparecem quando aplicáveis?
• Quais valores vêm do Provider e quais são Estimated?
• Quando o Model Price é escolhido e congelado para a Request?
• Como Group, Service Tier, Discount ou Surcharge alteram User Charge?
• Quais Failed Attempts geram Provider Cost e como são registrados?
• Fallback final bem-sucedido esconde Attempts anteriores billable?
• Currency Conversion e Rounding Rules são explícitas?
• Finance reproduz Daily Total a partir de Immutable Request Records?

Teste Normal Completion, Same-contract Fallback, Cancelled Request e Upstream Error. Dashboard Total não basta; é necessário um Per-request Record defensável. AI API Cost Tracking separa Provider Usage, Platform Pricing, Customer Charge e Supplier Cost.

Não compare economia sem manter constantes Model, Workload, Cache Behavior, Output Length, Failure Rate e Provider Price Basis. Custo aparente menor pode vir de Missing Usage ou Silent Model Substitution.

Verificar Security e Data Boundary

Desenhe o Data Flow real do Client ao Gateway e a cada Provider. Em cada Hop, identifique acesso a Credentials, Request/Response Content, Metadata e Administrative Configuration.

Verifique pelo menos:

• Provider Credentials Server-side, At-rest Encrypted e nunca devolvidas a clientes comuns;
• Application Keys com Scope por Project/Workload e revogação independente;
• Authorization Server-side em todos os Management e Log Endpoints;
• Logs sem API Key completa e Prompt/Response Retention explícita;
• Support Access atribuível e limitado;
• mudanças com Actor, Time, Before/After e Rollback Evidence;
• Exported Traces sem Secrets ou conteúdo pessoal/proprietário;
• Deletion e Retention demonstráveis;
• Region e Subprocessor Claims alinhadas à route usada;
• Abuse Limits antes de Upstream Work caro quando possível.

Pergunte sobre Key Rotation, Operator Departure, Application Key comprometida e vazamento de Provider Key. Execute Rotation e Revocation com Test Credentials isoladas, sem copiar Production Secret.

O gateway não torna Application Tools inseguras automaticamente seguras. Tool Authorization, Transactionality, Approval e Idempotency continuam como Application Responsibilities. AI API Key Security and Cost Controls separa Credentials e Workload Limits.

Avaliar o Operational Control Plane

O Data Plane pode funcionar enquanto o Control Plane cria risco.

Área	Perguntas obrigatórias
Versioning	Cada mudança de Route, Price, Policy e Key tem versão ou Actor?
Validation	Invalid Route ou Incompatible Model é rejeitado antes de ativar?
Rollout	Mudança pode atingir primeiro workload ou porcentagem pequena?
Rollback	Last-known-good Configuration é restaurada rapidamente?
Availability	O que ocorre com Existing/New Requests sem Control Plane?
Health	Channel Health usa evidência atual e Auto-disable é auditável?
Incidents	Uma Request é reconstruída sem vários sistemas desconectados?
Limits	Rate/Quota Decisions continuam corretas com Concurrency?
Change Ownership	Emergency Edits são separadas de Product Configuration?

Conclua um Configuration Rollback e uma Unhealthy-route Removal. Meça Operator Steps e valide Data-plane Behavior. Screenshot do botão não é drill.

Testar o Exit Path antes de assinar

Gateway pode criar dependências em Model Aliases, Custom Headers, Proprietary Route Names, Log APIs, Normalized Error Shapes ou Hosted Prompt/Tool Configuration. Classifique cada uma como benefício intencional ou Lock-in acidental.

Um Exit Drill deve:

1. exportar Route, Key Policy, Price e Audit Configuration em formato documentado;
2. mover um Workload a Provider-native Test Endpoint;
3. substituir Headers/Aliases exclusivos por Application Configuration explícita;
4. preservar Request Correlation e Usage Reconciliation;
5. documentar funções que exigem Redesign;
6. estimar Exit Engineering a partir do trabalho observado.

Não é preciso intercâmbio com todos os Providers. A equipe precisa saber o que possui, o que o gateway possui e como recuperar o Protocol Contract subjacente.

Pontuar apenas após todos os Gates

Use pass/fail para Hard Boundaries e escala pequena para Evidence operacional:

Score	Significado
0	Unsupported ou contradito pelo teste
1	Claimed ou demonstrado uma vez, evidência fraca
2	Demonstrado repetidamente com Request-level Evidence
3	Repetível, monitorado e recuperável por controle testado

Pontue Protocol Coverage, Route Reliability, Attempt Evidence, Latency Diagnostics, Usage Accuracy, Cost Reconciliation, Key Isolation, Auditability, Configuration Rollback, Supportability e Exit Effort conforme workload. Guarde Raw Evidence junto a cada Score.

Evite falsa precisão como 87.4/100. Registre Mandatory Gates e resultados, scores com links, Accepted Gaps e Owner, Remediation Deadline, Cost/Contract Assumptions, candidatos escolhidos e rejeitados e Review Date após o primeiro mês.

Comparar Build e Buy por Ownership

A pergunta não é se a solução interna evita licença, mas quais responsabilidades a equipe sustenta continuamente.

Responsabilidade	Build interno	Purchased ou Managed
Protocol Updates	Acompanhar Provider Schemas e Regressions	Verificar Vendor Updates e Route Compatibility
Routing and Retry	Projetar State Machine e Failure Evidence	Configurar Policy e auditar Attempts reais
Usage and Billing	Normalizar Usage e manter Pricing Logic	Reconciliar Vendor Records e Finance Truth
Security	Armazenar Secrets, impor Tenancy, auditar Access	Validar Vendor Boundary e Least Privilege
Reliability	Operar Data Plane, Control Plane e On-call	Monitorar Vendor e Integration, manter Exit Path
Product Support	Diagnosticar cada interação Application/Provider	Separar falha de Gateway, Provider e Application

Não use salários genéricos ou “tempo de engenharia poupado”. Estime por On-call Load, Protocol-change History, Incident Frequency, Finance Requirements e Compliance Work próprios. Um Managed Product ainda exige Accountable Internal Owner.

Aplicar a checklist à Modelflare com precisão

O escopo atual da Modelflare deve ser explícito. Ela fornece Workload API Keys, routing do Requested Model por Groups e Channels elegíveis, Ordered Group Fallback para Keys regulares, Strategy-based Group Selection para Smart API Keys, Group RPM Admission antes do upstream e Request-level Records de Usage, Cost, Status e Timing.

GPT, Codex e tráfego OpenAI são o alvo de compatibilidade totalmente adaptado. Outras famílias OpenAI-compatible devem ser avaliadas como Raw Chat Completions Pass-through até verificação específica. Uma Base URL compartilhada não prova Responses, Hosted Tools, Structured Outputs ou Function Calling idênticos em cada route.

O fallback da Modelflare deve procurar caminho elegível para Requested Model em vez de escolher outro modelo silenciosamente. Channel Failover para após Downstream Output começar. Teste esses claims com Corpus e Failure Drills.

Use Models & Pricing para a superfície atual de Models/Groups e Modelflare Docs para configurar Test Key isolada. Mantenha Requests não sensíveis, fixe o modelo exato e guarde Request IDs para investigar Attempts.

A decisão final precisa ser reproduzível: outro Engineer executa o mesmo corpus, inspeciona as mesmas categorias de Evidence e entende por que o candidato passou. É mais lento que uma página comparativa, mas muito mais rápido que descobrir Tool Contract incompatível, conta sem rastreio ou fallback inseguro depois que o gateway já serve Production Traffic.