Observabilité LLM dans une passerelle API multimodèle : traces, registres de jetons, analyses des locataires et journalisation sécurisée des invites
Une architecture d'observabilité pratique pour les passerelles d'IA multimodèles : suivez chaque appel LLM une fois, joignez la télémétrie aux registres de jetons et de coûts, rapprochez les factures des fournisseurs et déboguez en toute sécurité sans stocker les invites brutes par défaut.
Le nombre total de demandes et les dépenses mensuelles ne suffisent pas lorsqu'un client demande pourquoi un flux de travail est devenu hier plus lent, plus coûteux ou moins fiable. Une passerelle API multimodèle peut répondre à cette question si elle traite l'observabilité comme faisant partie du plan de contrôle : chaque requête obtient une trace, chaque appel de modèle met à jour un registre d'utilisation, chaque locataire et flux de travail est attribuable et le contenu sensible est protégé par défaut.
Cet article décrit une conception pratique pour l'analyse de l'utilisation de l'IA et l'observabilité LLM dans une passerelle qui fait face à plusieurs fournisseurs via une API compatible OpenAI. Ce modèle est utile même si vous n'utilisez aucun fournisseur spécifique : instrumentez une fois sur la passerelle, normalisez la télémétrie du modèle, préservez l'attribution de facturation et capturez le contenu des invites uniquement dans le cadre d'une politique explicite.
Le problème du lecteur : "Quel locataire, modèle, invite ou chemin de récupération a provoqué le changement ?"
La plupart des équipes finissent par être confrontées au même problème de débogage. Les journaux d'application montrent qu'une fonctionnalité a échoué. Les tableaux de bord des fournisseurs montrent que l’utilisation des jetons a augmenté. Les Finances voient une facture. Aucune de ces vues, à elle seule, n'explique le chemin complet depuis la demande du locataire jusqu'à l'appel du modèle jusqu'au contexte de récupération pour réessayer d'obtenir le coût facturé.
L'objectif n'est pas un autre tableau de bord avec un total de jetons. L'objectif est de répondre à des questions opérationnelles telles que :
- Quel locataire ou clé API a provoqué un pic de dépenses ?
- La latence a-t-elle augmenté après la modification de l'alias d'un modèle ?
- Les tentatives ou les tentatives de repli coûtent-elles en double ?
- Quelle version d'invite consomme le plus de budget d'erreur ?
- Un workflow RAG est-il devenu coûteux parce que la récupération ajoutait trop de jetons de contexte ?
- Peut-il prendre en charge le débogage d'un incident sans lire les invites des utilisateurs privés ?
Faits, recommandations et prédictions
Faits : OpenTelemetry documente les conventions sémantiques et les attributs de l'IA générative pour les opérations de modèle, y compris les noms d'opérations tels que chat, generate_content et text_completion. La même documentation avertit que les attributs des messages d'entrée et de sortie GenAI peuvent contenir des informations sensibles ou des informations personnelles et peuvent nécessiter un filtrage ou une troncature. Les principaux fournisseurs de modèles exposent également des tableaux de bord d'utilisation, des API ou des exportations qui peuvent prendre en charge la réconciliation côté fournisseur, bien que les détails diffèrent selon le fournisseur.
Recommandations : utilisez OpenTelemetry pour les traces indépendantes du fournisseur, mais conservez les dimensions commerciales appartenant à la passerelle dans vos propres attributs et registres. Ne stockez pas les invites ou les sorties brutes par défaut. Stockez d'abord les métadonnées, les hachages, le nombre de jetons, les ID de modèles d'invite, les noms de schéma, les classes d'erreur et les étiquettes de sécurité. Ajoutez la capture de contenu uniquement en tant que fonctionnalité de débogage facultative, à accès contrôlé et à courte conservation.
Prédiction : l'observabilité LLM concernera moins les tableaux de bord de fournisseurs isolés que les plans de contrôle inter-fournisseurs. Les équipes s'attendront à un seul endroit pour étudier la latence, le coût, la qualité, les événements de politique, le comportement des locataires et les deltas de facturation entre les modèles.
Architecture de référence : observez l'ensemble du chemin de la requête
Une passerelle peut voir le cycle de vie complet des requêtes sans que chaque équipe chargée des applications ne doive créer une télémétrie personnalisée. Un modèle de trace utile commence par un span parent pour la demande client entrante et des spans enfants pour les étapes qui affectent le coût, la latence et la qualité.
Structure de travée recommandée
- Durée de la demande de passerelle : demande acceptée, authentifiée, autorisée, à débit limité et acheminée.
- Période d'appel du modèle : fournisseur, modèle, fonctionnement, utilisation du jeton, état de la réponse et latence.
- Durée de récupération : index interrogé, ID de document ou ID hachés, nombre de fragments, latence de récupération et partage de jetons de contexte.
- Période d'appel de l'outil : nom de l'outil, état, latence, classe d'erreur et classification des effets secondaires.
- Durée des tentatives : motif des nouvelles tentatives, numéro de tentative, état du fournisseur et coût incrémentiel.
- Période de secours : modèle d'origine, modèle de secours, déclencheur, stratégie de compatibilité et résultat final.
- Garde-corps ou durée de modération : politique invoquée, décision, étiquettes et si la sortie a été bloquée ou transformée.
- Présentation du post-traitement : validation JSON, réparation du schéma, vérification des citations ou formatage final.
Le span parent doit porter des identifiants de corrélation stables. Les travées enfants doivent comporter des attributs techniques normalisés. Le grand livre d'utilisation doit contenir des enregistrements de facturation et d'analyse durables. Évitez de forcer toutes les informations dans les étiquettes de métriques ; les valeurs à cardinalité élevée telles que les ID de locataire, les hachages d'invite et les ID de document sont mieux stockées dans des traces, des journaux ou des tables de grand livre, puis agrégées dans des tableaux de bord.
Normaliser les métadonnées capturées à chaque appel LLM
Chaque demande de modèle doit produire un enregistrement cohérent, quel que soit le fournisseur. Le schéma exact peut varier, mais un minimum pratique ressemble à ceci :
{
"request_id": "req_01J...",
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"tenant_id": "tenant_123",
"team_id": "team_456",
"app_id": "support_bot",
"gateway_key_id": "key_789",
"opération": "discussion",
"provider": "nom_fournisseur",
"model": "id-modèle-fournisseur",
"model_alias": "fast-support-chat",
"prompt_template_id": "refund_policy_v5",
"prompt_hash": "sha256:...",
"response_schema": "support_answer_v2",
"statut": "terminé",
"classe_erreur": nul,
"latency_ms": 1842,
"input_tokens": 2110,
"output_tokens": 384,
"cached_input_tokens": 1200,
"estimated_cost_usd": "0,00492",
"final_billed_cost_usd": nul,
"finish_reason": "arrêter",
"retry_count": 0,
"fallback_used": faux,
"content_capture_policy": "metadata_only"
Gardez deux idées distinctes : la télémétrie explique ce qui s'est passé, tandis que le grand livre d'utilisation enregistre ce qui doit être facturé, rapproché et signalé. Ils se référencent mutuellement avec des ID de requête et des ID de trace, mais ils ne doivent pas nécessairement vivre dans le même système de stockage.
Créez un registre des jetons et des coûts, pas seulement des compteurs
Les compteurs de jetons sont utiles pour les graphiques, mais ils ne suffisent pas pour la facturation ou les enquêtes sur les incidents. Un grand livre doit représenter les transitions d’état. Créez une ligne lorsque la passerelle accepte une demande, puis mettez-la à jour au fur et à mesure de la progression de la demande.
États du grand livre utiles
- accepté : les vérifications d'authentification et de stratégie ont réussi.
- transféré : la demande a été envoyée à un fournisseur.
- streaming : le fournisseur a commencé à renvoyer des jetons.
- terminé : la réponse s'est terminée avec succès.
- user_aborted : le client s'est déconnecté avant la fin.
- nouvelle tentative : une tentative supplémentaire du fournisseur a été effectuée.
- fallback_used : un modèle ou un fournisseur différent a été sélectionné après un échec ou une correspondance avec les règles.
- échec : la requête s'est terminée sans réponse utilisable.
- rapprochement : les données d'utilisation ou de coût côté fournisseur ont été comparées et appliquées.
Ce modèle d'état permet de détecter les erreurs courantes de facturation et d'analyse : réponses diffusées en continu lorsque le client s'est déconnecté, nouvelles tentatives facturées par le fournisseur mais cachées à l'utilisateur, chemins de secours qui comptaient le mauvais modèle et cache les différences de comptabilité entre les fournisseurs.
Utilisez les conventions OpenTelemetry GenAI, puis étendez-les avec précaution
Les conventions sémantiques OpenTelemetry GenAI fournissent un vocabulaire portable pour les opérations de modèle. Utilisez ces conventions pour les attributs courants tels que le nom de l'opération, le fournisseur, le modèle, les paramètres de demande, les raisons de fin de réponse, l'utilisation du jeton et l'état d'erreur lorsqu'ils s'appliquent.
Cependant, les conventions indépendantes du fournisseur ne couvriront pas toutes les dimensions commerciales d'une passerelle. Ajoutez des attributs appartenant à la passerelle ou des colonnes de grand livre pour :
- ID de locataire, ID d'équipe, ID de client revendeur et ID d'application ;
- ID de clé API de passerelle et étendue de la clé ;
- plan de facturation, limite de dépenses et politique budgétaire ;
- Alias du modèle et version de la stratégie de routage ;
- ID du modèle d'invite et version de l'invite ;
- nom du workflow et étape du workflow ;
- coût estimé, coût final facturé et état du rapprochement.
Le compromis est la cardinalité. Ces champs sont précieux pour l’investigation, mais ils peuvent rendre les métriques coûteuses et bruyantes s’ils sont utilisés partout comme étiquettes de métriques. Une règle pratique est la suivante : les agrégats de faible cardinalité sont affectés aux métriques ; les identifiants à cardinalité élevée vont aux traces, aux journaux et aux grands livres.
Concevoir une journalisation sécurisée des invites et des sorties
La journalisation complète des invites facilite le débogage, mais augmente la confidentialité, la conformité, le stockage et l'exposition aux risques internes. La valeur par défaut la plus sûre est l'observabilité axée sur les métadonnées.
Par défaut : métadonnées uniquement
Pour la plupart du trafic de production, stockez :
- ID et version du modèle d'invite ;
- hachages d'invites et de sorties normalisées ;
- Nombre de jetons d'entrée, de sortie, mis en cache et contextuels ;
- nom du schéma de réponse et résultat de la validation ;
- étiquettes de sécurité et décisions politiques ;
- Résumés d'erreurs et classes d'erreurs du fournisseur ;
- Récupération de métadonnées, pas de documents bruts.
Opt-in : capture de contenu contrôlée
Si vous avez besoin de contenu brut ou rédigé pour un débogage approfondi, exigez une politique explicite. Les bons contrôles incluent les listes d'autorisation d'environnement, le consentement des locataires, l'échantillonnage, la longueur maximale de la charge utile, la rédaction automatique, les fenêtres de conservation courtes, le chiffrement, l'accès basé sur les rôles, les journaux d'audit et un chemin d'approbation sans faille pour les incidents sensibles.
Ne considérez pas la rédaction comme parfaite. Cela réduit les risques ; cela ne l'élimine pas. Pour les charges de travail réglementées ou à haute sensibilité, envisagez de stocker uniquement les hachages et de rejouer les problèmes dans un harnais synthétique avec des données de test approuvées.
Ajouter l'observabilité RAG en tant que couche distincte
La génération augmentée par la récupération peut modifier à la fois la qualité et le coût. La journalisation uniquement de l'appel final du modèle masque la cause première lorsque le récupérateur renvoie trop de fragments, de documents obsolètes ou un contexte non pertinent.
Pour chaque étape de récupération, capturez :
- index ou nom de la collection ;
- Stratégie de récupération et modèle d'intégration ;
- ID de document ou ID hachés ;
- nombre de fragments et nombre total de jetons de contexte ;
- latence de récupération ;
- répartition des meilleurs scores, si disponible ;
- couverture des citations ;
- si le contexte récupéré a été utilisé dans la réponse finale.
Cela vous permet de distinguer « le modèle s'est dégradé » de « le récupérateur a commencé à envoyer un contexte de mauvaise qualité ou excessif ». Cela permet également d'identifier les workflows dans lesquels les jetons de contexte dominent le coût total.
Réconcilier l'utilisation de la passerelle avec la facturation du fournisseur
Les estimations de la passerelle sont disponibles immédiatement. Les données de facturation côté fournisseur sont généralement plus lentes mais font plus autorité. Utilisez les deux.
Une tâche de rapprochement quotidienne doit comparer les lignes du grand livre de la passerelle avec les API d'utilisation des fournisseurs, les API de coûts, les exportations de tableaux de bord ou les exportations de factures. Regroupez les deltas par fournisseur, modèle, projet et fenêtre horaire. Suivez les différences séparément pour les jetons d'entrée, les jetons de sortie, les jetons mis en cache, le nombre de requêtes et le coût.
Différences de rapprochement courantes
- Déconnexions du streaming : la passerelle peut voir un client abandonné alors que le fournisseur facture toujours les jetons générés.
- Nouvelles tentatives : plusieurs tentatives peuvent être facturées même si une seule réponse finale est renvoyée.
- Mise en cache des invites : les fournisseurs peuvent exposer différemment la comptabilité des jetons mis en cache.
- Arrondi : de petites différences par requête peuvent devenir visibles à grande échelle.
- Remises par lots ou par niveaux : les factures des fournisseurs peuvent appliquer des prix que l'estimation en temps réel ne connaissait pas encore.
- Modifications côté fournisseur : la tarification du modèle, le comportement de tokenisation ou les exportations de facturation peuvent changer au fil du temps.
Lorsque le rapprochement détecte un delta, évitez d'écraser silencieusement votre grand livre. Stockez l'estimation d'origine, la valeur rapprochée par le fournisseur, la source de rapprochement et le code motif s'il est connu.
Des tableaux de bord qui répondent aux questions opérationnelles
Démarrez les tableaux de bord à partir de problèmes de lecteurs, et non de mesures vaniteuses. Les vues utiles incluent :
- coût par locataire, équipe, application et workflow ;
- coût par tâche réussie, et pas seulement par requête ;
- latence p50, p95 et p99 par fournisseur, modèle et alias de modèle ;
- taux de repli et taux de nouvelles tentatives par itinéraire ;
- Tendances du taux d'expiration et des classes d'erreurs du fournisseur ;
- taux de réussite du cache et estimation des économies de jetons mis en cache ;
- taux d'échec de la validation des résultats structurés ;
- principales versions d'invites par consommation de budget d'erreur ;
- Partage de jetons de contexte RAG par workflow ;
- blocs de garde-corps et accès au classificateur à injection rapide.
Pour alerter, combinez les signaux techniques et commerciaux. Une hausse soudaine des dépenses des locataires peut être plus urgente qu’une légère augmentation globale de la latence. Un saut de taux de repli après un changement d'alias de modèle peut indiquer un problème de compatibilité. Les réponses répétées 401, 429 ou 5xx peuvent indiquer des problèmes clés, un épuisement des quotas ou une instabilité du fournisseur.
Flux de mise en œuvre minimal pour un proxy compatible OpenAI
Pour un proxy /chat/completions, le flux peut être simple :
- Recevez la demande et attribuez un
request_idet un contexte de trace. - Authentifiez la clé de passerelle et résolvez la portée du locataire, de l'équipe, de l'application et de la stratégie.
- Créez l'étendue de la passerelle parent.
- Créez une ligne du grand livre avec l'état
accepté. - Résoudre l'alias du modèle en modèle de fournisseur et en version de stratégie de routage.
- Enregistrer les métadonnées : opération, ID du modèle d'invite, nom du schéma, hachage de l'invite et stratégie de capture de contenu.
- Démarrez la durée d'appel du modèle à l'aide des attributs sémantiques GenAI, le cas échéant.
- Transférer la demande au fournisseur sélectionné.
- Pour le streaming, mettez à jour l'état lorsque le premier fragment arrive et comptez l'utilisation aussi précisément que le permet la réponse du fournisseur.
- Une fois terminé, analysez l'utilisation du fournisseur, le motif de fin, l'état et la classe d'erreur.
- Mettez à jour le grand livre avec les jetons, le coût estimé, les détails des nouvelles tentatives/de secours et l'état final de la demande.
- Émettre des métriques à partir du grand livre et des données étendues.
- Effectuez un rapprochement quotidien et stockez le coût confirmé par le fournisseur séparément de l'estimation initiale.
Liste de contrôle du déploiement
- Définissez les ID de requête canonique et les ID de trace.
- Adopter les attributs OpenTelemetry GenAI pour la télémétrie de modèle commun.
- Créez un registre d'utilisation de la passerelle avec les transitions d'état des demandes.
- Normaliser les dimensions du fournisseur, du modèle, de l'alias de modèle, du locataire, de l'application et du workflow.
- Conservez les données d'investigation à cardinalité élevée hors des étiquettes de métriques.
- Désactiver la capture d'invite brute et de sortie par défaut.
- Ajoutez des règles explicites pour l'échantillonnage, la rédaction, la conservation et le contrôle d'accès.
- Capturez les métadonnées de récupération pour les workflows RAG.
- Créez des tableaux de bord pour les coûts, la latence, la fiabilité, la validation et le comportement des locataires.
- Rapprochez les estimations de la passerelle avec l'utilisation du fournisseur et les exportations de coûts.
- Alerte sur les pics de dépenses, les régressions de latence, les sauts de secours, les échecs de validation et les événements liés à la sécurité.
Conclusion
Une passerelle multimodèle est l'endroit idéal pour mettre en œuvre l'observabilité LLM, car elle détecte les demandes avant qu'elles n'atteignent un fournisseur et peut associer un contexte commercial que les fournisseurs ne connaissent pas. La conception la plus solide n’est pas de « tout enregistrer ». Il s'agit d'un modèle en couches : des traces indépendantes du fournisseur pour l'exécution, un jeton durable et un registre des coûts pour la facturation, des analyses de locataires pour la gouvernance, des métadonnées RAG pour la qualité de la récupération et une journalisation des invites axée sur la confidentialité pour un débogage sécurisé.
Commencez par les métadonnées, les transitions d'état et la réconciliation. Ajoutez la capture de contenu uniquement lorsque la politique, la rétention et les contrôles d'accès sont prêts. Cette séquence donne aux développeurs les preuves dont ils ont besoin pour déboguer la latence, la qualité et les dépenses sans transformer l'observabilité en un nouveau risque d'exposition des données.