Routage de l'effort de raisonnement dans une passerelle API AI : contrôlez les jetons de réflexion, la latence et les coûts entre les fournisseurs

La profondeur du raisonnement n'est plus une simple option de modèle. Certains fournisseurs exposent des niveaux d’effort de type énumération. D’autres exposent des budgets symboliques, une pensée dynamique ou des familles modèles où la pensée ne peut pas être complètement désactivée. La réponse visible peut être courte tandis que le raisonnement caché consomme des jetons de sortie facturables. Si chaque équipe d'application définit ces contrôles directement, le coût, la latence et la qualité deviennent difficiles à expliquer.

La réponse pratique consiste à déplacer le contrôle de l'effort de raisonnement vers la passerelle API. La passerelle doit classer la charge de travail, la mapper à un contrôle de raisonnement spécifique au fournisseur, appliquer les budgets des locataires, enregistrer l'utilisation réelle du raisonnement et rendre les décisions de rétrogradation visibles dans les analyses. L'ID du modèle, le niveau de service, le rendement maximal et la profondeur du raisonnement doivent être des dimensions politiques distinctes.

Problème du lecteur : les requêtes simples paient pour un raisonnement approfondi

Les équipes qui adoptent des modèles capables de raisonner commencent généralement avec un objectif raisonnable : améliorer la qualité des tâches difficiles. Le problème apparaît plus tard, lorsque les mêmes valeurs par défaut sont réutilisées pour l'extraction, les résumés courts, le formatage et la classification. Ces requêtes ne nécessitent pas de calcul coûteux au moment du test, mais elles peuvent quand même le déclencher.

Cela crée trois échecs opérationnels :

• Opacité des coûts : l'utilisateur voit une réponse courte, mais le grand livre contient des jetons de raisonnement cachés ou des équivalents spécifiques au fournisseur.
• Dérive de latence : un flux de travail qui semblait interactif devient lent car l'effort de raisonnement a augmenté derrière le même modèle alias.
• Fragmentation des politiques : chaque équipe produit apprend différents paramètres de fournisseur et applique des plafonds différents.

Une politique de raisonnement au niveau de la passerelle résout le problème de contrôle avant qu'il ne devienne un problème de facturation.

Faits : les contrôles de raisonnement du fournisseur ne sont pas équivalents

Ce qui suit sont des faits de mise en œuvre, pas des recommandations.

• Les API capables de raisonnement OpenAI exposent un Objet reasoning pour les modèles pris en charge, y compris les valeurs d'effort telles que aucun, minimal, low, medium, high et xhigh. Un effort moindre peut réduire les jetons de raisonnement et améliorer la vitesse de réponse.
• La documentation OpenAI indique que les max_output_tokens peuvent limiter le total des jetons générés, y compris les jetons de raisonnement et de sortie finale.
• La pensée étendue anthropique peut être activée avec une valeur budget_tokens. Les jetons de réflexion sont facturés en tant que jetons de sortie et comptent pour max_tokens aux côtés du texte de réponse visible.
• La documentation anthropique note également que le nombre de jetons de sortie facturés peut ne pas correspondre au nombre de jetons de réponse visibles, car les jetons de réflexion internes peuvent être facturés même s'ils ne sont pas entièrement visibles.
• La documentation de réflexion Gemini indique que la tarification des réponses peut inclure à la fois les jetons de sortie et les jetons de réflexion, avec des champs d'utilisation qui séparent les jetons de pensée et la sortie. jetons.
• Les contrôles de style Gemini 2.5 incluent thinkingBudget, avec une réflexion dynamique sur les modèles pris en charge et une désactivation du budget zéro sur certaines familles de modèles. Certains modèles ne peuvent pas désactiver la réflexion.
• Les nouvelles directives Gemini recommandent des valeurs thinking_level telles que minimal, low, medium et high pour les modèles de style Gemini 3.x au lieu de budgets numériques bruts.

L'implication de base de l'architecture est simple : n'exposez pas les contrôles de raisonnement natifs du fournisseur comme seul contrat. Ils ne sont pas assez stables, assez portables ou suffisamment comparables pour une gouvernance multi-fournisseurs.

Recommandation : créer des profils de raisonnement neutres par rapport au fournisseur

Définissez un petit vocabulaire interne que les équipes produit peuvent comprendre sans lire chaque référence d'API de fournisseur.Pour la plupart des passerelles, cinq profils suffisent :

Le profil est le contrat orienté vers l'application. Les paramètres du fournisseur deviennent des détails sur l'adaptateur. Cela permet de conserver le code client portable et de permettre aux propriétaires de plates-formes de mettre à jour les mappages à mesure que les API des fournisseurs changent.

Mapper les classes de charge de travail avant les fournisseurs de mappage

L'effort de raisonnement doit être choisi en fonction de l'intention de la charge de travail, et non en fonction des préférences personnelles ou de la popularité du modèle. Ajoutez un champ de passerelle tel que workload_class, soit fourni par le client, soit déduit d'une configuration de route approuvée.

Exemple de politique de charge de travail

{
  "workload_policies": {
    "extract_invoice_fields": {
      "default_reasoning_profile": "aucun",
      "max_reasoning_profile": "faible",
      "max_output_tokens" : 800
    },
    "classify_support_ticket": {
      "default_reasoning_profile": "aucun",
      "max_reasoning_profile": "faible",
      "max_output_tokens" : 300
    },
    "draft_customer_reply": {
      "default_reasoning_profile": "faible",
      "max_reasoning_profile": "standard",
      "max_output_tokens" : 1200
    },
    "code_review": {
      "default_reasoning_profile": "standard",
      "max_reasoning_profile": "profond",
      "max_output_tokens" : 4000
    },
    "security_review": {
      "default_reasoning_profile": "profond",
      "max_reasoning_profile": "plafonné en profondeur",
      "max_output_tokens" : 6000
    },
    "agent_plan": {
      "default_reasoning_profile": "standard",
      "max_reasoning_profile": "profond",
      "max_output_tokens" : 5000
    }
  }
}

Cette stratégie fait deux choses utiles. Premièrement, cela empêche les points de terminaison simples d’hériter de paramètres par défaut coûteux. Deuxièmement, cela donne aux administrateurs une surface d'examen concrète : quels flux de travail sont autorisés à demander un raisonnement approfondi et dans quelles limites ?

Créer une matrice de compatibilité

L'adaptateur de passerelle doit maintenir une matrice pour chaque fournisseur et famille de modèles. Au minimum, indiquez si le modèle prend en charge la désactivation du raisonnement, l'effort d'énumération, le budget numérique, la pensée dynamique, le budget maximum pris en charge et les champs d'utilisation pour les jetons de raisonnement.

Exemple de forme de matrice

{
  "fournisseurs": {
    "fournisseur_a": {
      "model_family_x": {
        "supports_reasoning": vrai,
        "control_type": "effort_enum",
        "allowed_values": ["aucun", "minimal", "low", "medium", "high", "xhigh"],
        "can_disable": vrai,
        "reports_reasoning_tokens" : vrai
      }
    },
    "fournisseur_b": {
      "model_family_y": {
        "supports_reasoning": vrai,
        "control_type": "budget_tokens",
        "min_budget_tokens": 1024,
        "max_budget_tokens" : 32 000,
        "can_disable": faux,
        "reports_reasoning_tokens" : vrai
      }
    },
    "provider_c": {
      "model_family_z": {
        "supports_reasoning": vrai,
        "control_type": "thinking_level",
        "allowed_values": ["minimal", "low", "medium", "high"],
        "can_disable": faux,
        "reports_reasoning_tokens" : vrai
      }
    }
  }
}

Une matrice de compatibilité n'est pas une documentation réservée aux humains. Ce devrait être une politique exécutable. Le routeur de requêtes doit l'utiliser avant l'envoi et le grand livre de facturation doit l'utiliser lors du règlement.

Traduire les profils internes en paramètres du fournisseur

Les mappages des fournisseurs doivent être explicites et versionnés. Ne vous fiez pas à une expression vague telle que « utilisez un raisonnement plus intelligent ». La passerelle doit savoir exactement quel paramètre du fournisseur a été envoyé.

Exemple de mappage

{
  "reasoning_profile_mappings": {
    "aucun": {
      "effort_enum": "aucun",
      "budget_tokens": 0,
      "thinking_level": "minimal"
    },
    "faible": {
      "effort_enum": "faible",
      "budget_tokens": 2048,
      "thinking_level": "faible"
    },
    "standard": {
      "effort_enum": "moyen",
      "budget_tokens": 8192,"thinking_level": "moyen"
    },
    "profond": {
      "effort_enum": "élevé",
      "budget_tokens": 20 000,
      "thinking_level": "élevé"
    },
    "plafonné en profondeur": {
      "effort_enum": "élevé",
      "budget_tokens": 12 000,
      "thinking_level": "élevé"
    }
  }
}

Ces numéros sont des exemples et non des valeurs par défaut universelles. Les bons budgets dépendent de la famille de modèles, des prix, des exigences de latence et des résultats de l'évaluation. Le détail important de l'implémentation est que la passerelle est propriétaire du mappage et enregistre le paramètre de fournisseur résolu pour chaque requête.

Échec de fermeture lorsqu'un mappage n'est pas sécurisé

Les contrôles de raisonnement non pris en charge ne doivent pas devenir silencieusement les valeurs par défaut du fournisseur. Les valeurs par défaut peuvent être coûteuses et peuvent changer au fil du temps.

Utilisez l'un des trois résultats suivants lorsqu'un profil demandé ne peut pas être mappé en toute sécurité :

• Autoriser : le fournisseur/modèle prend en charge le profil demandé et la politique du locataire le permet.
• Déclasser : le profil demandé est supérieur à la politique, de sorte que la passerelle applique le profil approuvé le plus élevé et enregistre la rétrogradation.
• Rejeter : le profil ne peut pas être représenté. en toute sécurité, le locataire exige un comportement strict, sinon une rétrogradation violerait les attentes du produit.

Exemple d'enregistrement de décision

{
  "request_id": "req_123",
  "tenant_id": "tenant_42",
  "api_key_id": "key_abc",
  "workflow": "code_review",
  "requested_reasoning_profile": "profond",
  "applied_reasoning_profile": "standard",
  "decision": "déclassé",
  "decision_reason": "tenant_monthly_deep_reasoning_budget_exceeded",
  "served_provider": "provider_a",
  "served_model": "model_family_x",
  "provider_reasoning_param": {
    "effort": "moyen"
  }
}

Cet enregistrement de décision est précieux lors des opérations d'assistance, de litiges de facturation et d'enquêtes qualité. Cela évite également les régressions de qualité invisibles en cas de pression budgétaire.

Les contrôles budgétaires nécessitent plus que le nombre maximal de jetons de sortie

Une limite maximale de jetons de sortie est nécessaire, mais elle n'est pas suffisante. Pour les modèles capables de raisonner, le modèle peut consacrer une grande partie du raisonnement limite et laisser trop peu de place à la réponse finale. L'utilisateur peut alors payer pour une réponse tronquée inutilisable.

Utilisez des plafonds en couches :

• max_reasoning_profile par locataire, clé API et workflow.
• max_thinking_budget ou équivalent par paire fournisseur/modèle.
• max_output_tokens pour le total des jetons générés où le fournisseur compte le raisonnement et la sortie visible. ensemble.
• daily_deep_reasoning_spend par client locataire ou revendeur.
• deep_reasoning_requests_per_hour pour les points de terminaison à volume élevé.
• reasoning_token_ratio_threshold pour les alertes d'anomalie.

La vérification du budget doit avoir lieu avant l'expédition. L'étape de règlement doit ensuite concilier l'utilisation réelle après l'arrivée de la réponse du fournisseur. Si le fournisseur déclare penser les jetons séparément, stockez-les séparément. S'il ne rapporte que le total des jetons de sortie, stockez les meilleurs champs normalisés disponibles et marquez le niveau de confiance.

Champs du grand livre pour l'utilisation du raisonnement

Les analyses doivent montrer la différence entre la longueur de réponse visible et l'effort de raisonnement rémunéré. Une ligne de grand livre utile doit inclure :

• tenant_id, api_key_id, end_user_id et workflow.
• requested_model, served_model, fournisseur et alias de modèle.
• requested_reasoning_profile et applied_reasoning_profile.
• provider_reasoning_param, stocké sous forme de JSON structuré.
• input_tokens, visible_output_tokens, reasoning_tokens_or_equivalent, cached_tokens et total_billable_tokens.
• max_output_tokens et tout budget de réflexion spécifique au fournisseur.
• latency_to_first_token_ms, total_latency_ms et état d'achèvement du flux.
• estimated_cost_before_dispatch, reserved_budget, settled_cost et reconciliation_status.
• policy_decision, comme autorisé, rétrogradé, rejeté ou repli.

Ne consignez pas la chaîne de pensée brute par défaut. Pour la plupart des travaux de gouvernance et de FinOps, les décomptes et les décisions politiques suffisent. Le stockage de textes de raisonnement sensibles peut créer des problèmes évitables de confidentialité, de conformité et de rétention.

Flux de mise en œuvre

Une passerelle de production peut implémenter un routage d'effort de raisonnement en tant que pipeline de requêtes déterministe.

1. Authentifiez la demande. Résolvez le locataire, la clé API, l'utilisateur, l'équipe et le flux de travail.
2. Classez la charge de travail. Utilisez un champ client explicite lorsque cela est possible.Pour les points de terminaison connus, liez la classe de charge de travail à la configuration de l'itinéraire.
3. Charger la stratégie. Fusionner les contraintes globales, de locataire, de clé et de flux de travail.
4. Sélectionnez les modèles candidats. Utilisez l'alias de modèle existant ou la politique de sélection de modèle avant de résoudre les contrôles de raisonnement.
5. Résoudre le profil de raisonnement. Commencez à partir du profil demandé, puis appliquez les valeurs par défaut et maximales du flux de travail.
6. Vérifiez compatibilité. Confirmez que la paire fournisseur/modèle prend en charge le profil sélectionné en toute sécurité.
7. Estimez le coût et réservez le budget. Incluez l'utilisation de raisonnement probable, pas seulement la sortie visible.
8. Expédiez avec les paramètres natifs du fournisseur. Envoyez l'effort d'énumération, les jetons de budget, le niveau de réflexion ou aucun contrôle de raisonnement en fonction de l'adaptateur.
9. Normalisez l'utilisation en cas de réponse. Entrée séparée, sortie visible, raisonnement, mis en cache, et le total des jetons lorsque cela est possible.
10. Régler et alerter. Réconcilier les coûts réservés et réels, mettre à jour les quotas et émettre des signaux d'anomalie.

Ce pipeline permet de contrôler le contrôle du raisonnement. Cela donne également aux équipes de plate-forme un endroit unique pour modifier les valeurs par défaut lorsque les API des fournisseurs évoluent.

Évaluation avant de modifier les valeurs par défaut

Ne favorisez pas un effort de raisonnement plus poussé basé uniquement sur quelques exemples impressionnants. Exécutez des évaluations avant de modifier les valeurs par défaut d'une classe de charge de travail.

Mesurez au moins quatre résultats :

• Qualité de la tâche : précision, acceptation du réviseur, validité du schéma ou réussite de l'appel d'outil.
• Latence : temps jusqu'au premier jeton et temps d'exécution total.
• Coût : coût par demande et coût par réponse acceptée.
• Échec modes : troncature, refus, sortie mal formée, appels d'outils excessifs ou délai d'attente.

La métrique clé n'est pas « jetons par requête ». Une réponse avec un jeton inférieur qui échoue à la validation peut être plus coûteuse après les nouvelles tentatives. Une réponse plus argumentée peut être justifiée pour l'examen de sécurité, mais inutile pour l'étiquetage des tickets. Évaluez par flux de travail.

Compromis

La gouvernance du raisonnement ajoute du contrôle, mais elle n'est pas gratuite.

• Portabilité par rapport aux fonctionnalités du fournisseur : les profils internes maintiennent le code d'application portable, mais les équipes avancées peuvent avoir besoin d'une trappe de secours approuvée pour les contrôles spécifiques au fournisseur.
• Certitude budgétaire par rapport à la qualité : les plafonds stricts protègent les locataires des dépenses incontrôlées, mais des plafonds trop serrés peuvent tronquer des réponses utiles une fois que les jetons de raisonnement ont déjà été dépensés.
• Pensée dynamique contre prévisibilité : les contrôles dynamiques des fournisseurs peuvent améliorer la commodité, mais ils affaiblissent les estimations de coûts avant expédition à moins que la passerelle n'enregistre l'utilisation réelle et n'applique les limites de règlement.
• Réduire la disponibilité par rapport à la cohérence : la rétrogradation du raisonnement en cas de pression budgétaire préserve la disponibilité, mais la réponse doit être étiquetée dans la télémétrie et incluse dans l'évaluation de la qualité.
• Analyse par rapport à la cohérence confidentialité : les métriques des jetons de raisonnement sont utiles, mais les traces brutes du raisonnement ne doivent pas être stockées à moins qu'il n'y ait une politique de rétention délibérée et approuvée.

Prédiction : la politique de raisonnement deviendra un contrôle de passerelle standard

Il s'agit d'une prédiction, pas d'un fait vérifié : l'effort de raisonnement deviendra un contrôle de production normal aux côtés du routage des modèles, des limites de débit, des niveaux de service et des budgets de jetons. À mesure que les fournisseurs continuent d'exposer différents contrôles de réflexion, les équipes d'application auront moins envie de coder en dur ces différences dans le code produit.

Les passerelles qui traitent le raisonnement comme une dimension d'exécution gouvernée auront une facturation des locataires plus claire, une portabilité plus propre et un meilleur contrôle de la latence.Les passerelles qui le traitent comme un paramètre de modèle accessoire auront du mal à expliquer pourquoi les réponses courtes coûtent parfois plus cher que les réponses longues.

Liste de contrôle exploitable

• Définissez les profils internes : aucun, faible, standard, profond et plafonné-profond.
• Attribuez des profils par défaut et maximum à chaque charge de travail. classe.
• Créez une matrice de compatibilité fournisseur/modèle pour les contrôles de raisonnement.
• Traduisez les profils en paramètres natifs du fournisseur dans la couche adaptateur.
• Échec de la fermeture lorsqu'un profil demandé ne peut pas être mappé en toute sécurité.
• Réservez le budget avant l'envoi à l'aide d'estimations fondées sur le raisonnement.
• Enregistrez le profil demandé, le profil appliqué, le paramètre du fournisseur, l'utilisation du raisonnement, la sortie visible, la latence et le coût.
• Ajoutez des alertes d'anomalie pour les niveaux élevés. ratios de jetons de raisonnement et raisonnement approfondi dans des workflows simples à grand volume.
• Exécutez des évaluations au niveau du workflow avant de modifier l'effort par défaut.
• Évitez de consigner le texte de raisonnement brut par défaut ; à la place, le nombre de magasins et les décisions politiques.

Conclusion

Les modèles capables de raisonnement sont utiles car ils peuvent consacrer plus de calculs à des problèmes difficiles. Cette même capacité devient coûteuse lorsqu’elle est appliquée sans discernement. La passerelle doit décider quand un raisonnement plus approfondi est autorisé, comment il est mappé à chaque fournisseur, combien de budget il peut consommer et comment le résultat est mesuré.

Le modèle durable consiste à séparer l'effort de raisonnement de l'ID du modèle. Acheminez par charge de travail, plafonnez par politique de locataire, adaptez par fournisseur et réglez l'utilisation réelle dans le grand livre. Cela transforme le raisonnement d'une variable de coût cachée en une surface de contrôle explicite pour le contrôle des coûts des API d'IA.

Lecture connexe

• grand livre de facturation qui réserve et règle chaque appel de modèle
• alias de modèle interne et contrats de capacité
• comptabilisation des jetons de streaming pour l'utilisation finale et partielle réponses