Comment évaluer un AI API Gateway : checklist de production
Processus reproductible pour protocole, pannes, latence, usage et coûts, sécurité, control plane et risque de sortie.
Évaluez un AI API gateway en exécutant votre véritable Protocol Contract, en forçant les Failure Modes importants et en inspectant les Request-level Evidence. Une liste de fonctionnalités ou un « hello world » réussi ne prouve ni le streaming, ni la compatibilité des Tools, ni la sûreté du fallback, ni l’exactitude des coûts, ni l’isolation, ni l’Exit Path.
Le processus le plus fiable sépare les Mandatory Gates qui éliminent un candidat des qualités opérationnelles notées uniquement après réussite de tous les gates.
Définir d’abord le Workload Contract
Ne commencez pas par un tableau de Vendors. Sélectionnez un workload représentatif et consignez ses invariants :
- endpoint exact : Responses, Chat Completions, Embeddings, Images ou autre API ;
- Model IDs exacts et autorisation éventuelle des Aliases ;
- modes Streaming et Non-streaming utilisés ;
- Structured Outputs, Function Calling, Hosted Tools, Reasoning et champs requis ;
- longueurs Input/Output typiques et de haut percentile ;
- Concurrency, Request Rate, Region et User-facing Deadline ;
- champs Usage, Cache, Cost et Request Correlation nécessaires ;
- Fallback Routes autorisées et interdiction éventuelle de Model Substitution ;
- Data Retention, Access, Residency et Deletion ;
- opérations applicatives créant des Side Effects.
Un même gateway peut convenir à un assistant texte interne et échouer pour un coding agent en streaming. « OpenAI-compatible » ne suffit pas : la compatibilité varie par Endpoint, Event Type, Tool, Schema Keyword et Provider Route.
Si l’équipe hésite encore entre proxy et Model-aware Control Plane, commencez par LLM Proxy ou AI Gateway. Cette checklist suppose la catégorie justifiée et teste une implémentation précise.
Appliquer des critères éliminatoires avant un long essai
Le premier examen élimine les candidats qui ne respectent pas une frontière obligatoire. Exigez un comportement reproductible, pas une promesse de roadmap.
| Gate | Condition d’élimination immédiate | Preuve demandée |
|---|---|---|
| Protocol | Request Field, Output Item ou Stream Event requis perdu ou mal réécrit | Request/response expurgées et Parser Result |
| Model Identity | Requested Model changé silencieusement | Attempt Record avec modèle demandé et réel |
| Streaming | Buffer complet, Cancellation perdue ou Tool Argument Fragments corrompus | Event Sequence horodatée et Cancel Trace |
| Authentication | Browser ou Workload Client reçoit des Provider Credentials | Credential Flow et véritable Key Rotation |
| Tenant Isolation | Un Project accède aux Keys, Usage ou Logs d’un autre | Vérifications avec comptes réellement isolés |
| Cost Evidence | Final Charge non relié à Model, Route, Price Basis et Usage | Ledger réconcilié d’une Request |
| Failure Safety | Partial Stream rejoué ou Cancel déclenchant un nouvel Attempt | Traces forcées Partial Stream et Cancellation |
| Export and Exit | Configuration et Contract irrécupérables sans réécriture | Export Sample et Provider-native Rollback Drill |
Un échec obligatoire ne se compense pas par un score total élevé. Un bon dashboard ne corrige pas une mauvaise Tenant Isolation, et un prix bas ne corrige pas un Tool Contract erroné.
Construire un petit Protocol Conformance Corpus
Utilisez des Inputs déterministes et non sensibles, et versionnez le Wire Behavior attendu. Le corpus doit appeler le véritable endpoint ; ne mockez pas le Provider et ne recopiez pas la Conversion Logic comme Test Oracle.
| Cas | Request | Observation obligatoire |
|---|---|---|
| Basic Non-streaming Text | Pinned Model et Prompt fixe | Status, Model Identity, Text Location, Usage, Request ID corrects |
| Streaming Text | Même Prompt avec Streaming | Events ordonnés, First Effective Output, Final Event, Cancellation |
| Structured Output | Strict Schema avec Required et additionalProperties: false |
Output valide ou Unsupported Error explicite, sans Silent Downgrade |
| Function Calling | Fonction Read-only et Result retourné | Function Name, JSON Arguments, Call ID Correlation, Final Answer |
| No-tool Path | Tools déclarés mais non nécessaires | Texte normal sans Tool Call inventé |
| Invalid Field | Request Unsupported ou Malformed volontairement | Client Error stable ; aucun fallback ne masque le défaut |
| Long Input Boundary | Juste sous et au-dessus de la limite | Acceptation documentée ou rejet explicite, jamais de troncature silencieuse |
| Usage Detail | Request exerçant Cache ou Reasoning Usage | Champs conservés et réconciliés avec Billing Record |
| Cancellation | Cancel après connexion et après First Output | Upstream Work arrêté, aucun nouvel Fallback Attempt |
| Partial Stream | Échec après Effective Output | Un Partial Failure explicite, aucune seconde réponse invisible |
Exécutez chaque cas sur toute route susceptible de servir le workload. Une Primary Route validée ne qualifie pas son fallback. Le guide Structured Outputs et la comparaison Function Calling proposent des Field-level Cases.
Consignez Gateway Version, Route Configuration Version, Model ID, Provider, Region, Timestamp et Sanitized Result Hash. Réexécutez avant rollout et après tout changement matériel de route.
Tester Routing et Failure Behavior, pas seulement le succès
Une promesse de fiabilité n’a de valeur que si la Failure Policy est visible. Forcez avant Production :
- Primary Route indisponible avant Headers ;
- Provider Rate Limit avec et sans
Retry-After; - Upstream Authentication ou Account Failure ;
- Slow Headers et Slow First Effective Output ;
- Malformed Provider Response ;
- Caller Cancellation pendant l’attente upstream ;
- Connection Loss après le début de l’output visible ;
- épuisement de toutes les routes éligibles.
Capturez Attempt Order, Selected Route, Status, Timing, état de l’Output, Terminal Reason, Usage et Cost. Vérifiez que modèle et protocole demandés sont préservés sans Model-substitution Policy explicite.
Mesurez Attempt Amplification entre SDK, application, gateway et Provider. Une couche gère le Same-contract Fallback immédiat, l’application décide si la User Action complète peut être répétée. AI API Fallback Strategy fournit la Failure Matrix par phase et le Retry Budget.
La latence doit aussi être précise : comparez Upstream Headers, First SSE Event, First Effective Output, First Visible Text, Completion et Visible Output Speed sous Concurrency réaliste. Refusez une moyenne « Latency » non définie. Consultez AI API Latency Metrics.
Réconcilier Usage et Cost depuis une Request
Suivez plusieurs Requests complètes sur toute la chaîne :
application request ID
→ gateway attempt sequence
→ selected model and route
→ provider or normalized usage
→ applicable price basis
→ final recorded charge
L’évaluation doit répondre :
- Input, Output, Cached, Reasoning et Tool-related Units sont-ils représentés ?
- Quelles valeurs viennent du Provider et lesquelles sont Estimated ?
- Quand le Model Price est-il choisi et figé pour la Request ?
- Comment Group, Service Tier, Discount ou Surcharge modifient-ils le User Charge ?
- Quels Failed Attempts créent un Provider Cost et comment sont-ils enregistrés ?
- Un fallback réussi masque-t-il des Billable Attempts antérieurs ?
- Currency Conversion et Rounding Rules sont-elles explicites ?
- Finance peut-elle reproduire un Daily Total depuis des Immutable Records ?
Testez Normal Completion, Same-contract Fallback, Cancelled Request et Upstream Error. Un Dashboard Total ne suffit pas : il faut un Per-request Record défendable. AI API Cost Tracking sépare Provider Usage, Platform Pricing, Customer Charge et Supplier Cost.
Ne comparez pas les économies sans garder constants Model, Workload, Cache Behavior, Output Length, Failure Rate et Provider Price Basis. Un coût apparent inférieur peut provenir de Missing Usage ou Silent Model Substitution.
Vérifier Security et Data Boundary
Dessinez le Data Flow réel du Client au Gateway et à chaque Provider. Pour chaque Hop, identifiez l’accès aux Credentials, Request/Response Content, Metadata et Administrative Configuration.
Vérifiez au minimum :
- Provider Credentials Server-side, At-rest Encrypted, jamais retournées aux clients ordinaires ;
- Application Keys scopées par Project/Workload et révocables indépendamment ;
- Authorization Server-side sur tous les Management et Log Endpoints ;
- Logs sans API Key complète et Prompt/Response Retention explicite ;
- Support Access attribuable et borné ;
- changements avec Actor, Time, Before/After et Rollback Evidence ;
- Exported Traces sans Secrets ni contenu personnel/propriétaire ;
- Deletion et Retention démontrables ;
- Region et Subprocessor Claims alignées sur la route utilisée ;
- Abuse Limits avant un Upstream Work coûteux si possible.
Demandez le comportement lors de Key Rotation, Operator Departure, compromis d’Application Key et fuite de Provider Key. Exécutez rotation et révocation avec de vraies Test Credentials isolées, sans Production Secret.
Le gateway ne sécurise pas automatiquement des Application Tools dangereux. Tool Authorization, Transactionality, Approval et Idempotency restent des Application Responsibilities. AI API Key Security and Cost Controls sépare Credentials et Workload Limits.
Évaluer l’Operational Control Plane
Le Data Plane peut fonctionner tandis que le Control Plane crée un risque.
| Zone | Questions |
|---|---|
| Versioning | Chaque changement Route, Price, Policy, Key est-il versionné ou attribuable ? |
| Validation | Invalid Route et Incompatible Model sont-ils rejetés avant activation ? |
| Rollout | Un changement peut-il cibler un petit Workload ou Percentage ? |
| Rollback | Last-known-good Configuration est-elle rapidement restaurable ? |
| Availability | Que deviennent Existing/New Requests sans Control Plane ? |
| Health | Channel Health utilise-t-il des preuves récentes et Auto-disable est-il inspectable ? |
| Incidents | Une Request est-elle reconstructible sans systèmes disparates ? |
| Limits | Rate/Quota Decisions restent-elles correctes sous Concurrency ? |
| Change Ownership | Emergency Edits sont-ils séparés de Product Configuration ? |
Effectuez réellement un Configuration Rollback et un retrait de route défaillante. Mesurez les Operator Steps et vérifiez le Data-plane Behavior. Une capture du bouton ne vaut pas un drill.
Tester l’Exit Path avant de signer
Un gateway peut créer des dépendances aux Model Aliases, Custom Headers, Proprietary Route Names, Log APIs, Normalized Error Shapes ou Hosted Prompt/Tool Configuration. Classez chacune comme bénéfice volontaire ou Lock-in accidentel.
Un Exit Drill pratique doit :
- exporter Route, Key Policy, Price et Audit Configuration dans un format documenté ;
- déplacer un Workload vers un Provider-native Test Endpoint ;
- remplacer Headers/Aliases exclusifs par une Application Configuration explicite ;
- préserver Request Correlation et Usage Reconciliation ;
- documenter les fonctions impossibles à déplacer sans Redesign ;
- estimer l’Exit Engineering à partir du travail observé.
L’Exit Path n’exige pas l’interchangeabilité avec tous les Providers. Il exige que l’équipe sache ce qu’elle possède, ce que possède le gateway et comment récupérer le Protocol Contract sous-jacent.
Noter uniquement après les Mandatory Gates
Utilisez pass/fail pour les Hard Boundaries et une petite échelle pour l’Evidence opérationnelle :
| Score | Signification |
|---|---|
| 0 | Unsupported ou contredit par le test |
| 1 | Claimed ou démontré une fois manuellement, preuve faible |
| 2 | Démontré de façon répétable avec Request-level Evidence |
| 3 | Répétable, monitored et recoverable via un contrôle testé |
Évaluez Protocol Coverage, Route Reliability, Attempt Evidence, Latency Diagnostics, Usage Accuracy, Cost Reconciliation, Key Isolation, Auditability, Configuration Rollback, Supportability et Exit Effort. Pondérez selon le workload et gardez Raw Evidence près de chaque score.
Évitez une fausse précision comme 87.4/100. Documentez Gates et résultats, scores avec preuves, Accepted Gaps et Owner, Remediation Deadline, hypothèses Cost/Contract, candidats retenus et rejetés, puis Review Date après le premier mois Production.
Comparer Build et Buy par Ownership
La bonne question n’est pas l’absence de License Fee interne, mais les responsabilités que l’équipe peut assumer durablement.
| Responsabilité | Build interne | Purchased ou Managed |
|---|---|---|
| Protocol Updates | Suivre Provider Schemas et Regressions | Vérifier Vendor Updates et Route Compatibility |
| Routing and Retry | Concevoir State Machine et Failure Evidence | Configurer Policy et auditer les Attempts réels |
| Usage and Billing | Normaliser Usage et maintenir Pricing Logic | Réconcilier Vendor Records et Finance Truth |
| Security | Stocker Secrets, appliquer Tenancy, auditer Access | Valider Vendor Boundary et Least Privilege |
| Reliability | Opérer Data Plane, Control Plane et On-call | Surveiller Vendor et Integration, garder Exit Path |
| Product Support | Diagnostiquer chaque interaction Application/Provider | Trier les fautes Gateway, Provider et Application |
N’utilisez pas de chiffres génériques de salaire ou de « temps économisé ». Estimez depuis On-call Load, Protocol-change History, Incident Frequency, Finance Requirements et Compliance Work. Un Managed Product requiert toujours un Accountable Internal Owner.
Appliquer précisément la checklist à Modelflare
Le périmètre actuel de Modelflare doit être explicite. Il fournit des Workload API Keys, le routing du Requested Model sur Groups et Channels éligibles, des Ordered Fallback Groups pour les clés standard, la Strategy-based Group Selection pour Smart API Keys, le Group RPM Admission avant upstream et des records Request-level de Usage, Cost, Status et Timing.
Le trafic GPT, Codex et OpenAI est la cible de compatibilité entièrement adaptée. Les autres familles OpenAI-compatible doivent être évaluées comme Raw Chat Completions Pass-through jusqu’à validation spécifique. Une Base URL commune ne prouve pas Responses, Hosted Tools, Structured Outputs ou Function Calling identiques sur chaque route.
Le fallback Modelflare doit rechercher un chemin éligible pour le Requested Model, sans choisir silencieusement un autre modèle. Channel Failover s’arrête après le début du Downstream Output. Testez ces claims avec Corpus et Failure Drills plutôt que de les accepter comme marketing.
Utilisez Models & Pricing pour la surface Model/Group actuelle et Modelflare Docs pour une Test Key isolée. Gardez des Requests non sensibles, pinnez le modèle exact et conservez les Request IDs nécessaires à l’inspection des Attempts.
La décision finale doit être reproductible : un autre Engineer exécute le même corpus, examine les mêmes catégories d’Evidence et comprend pourquoi le candidat a réussi. C’est plus lent qu’une page comparative, mais bien plus rapide que de découvrir après mise en Production un Tool Contract incompatible, une facture introuvable ou un fallback dangereux.