Suivre l'utilisation des modèles
Surveillez l’utilisation des services Unity Gateway avec la table système system.ai_gateway.usage. Il capture les requêtes adressées aux services de modèles, aux services de fournisseurs de modèles et aux services MCP à partir de diverses sources, y compris AI Query, les agents de codage, les applications Databricks Apps, AI Playground et d’autres applications.
Les enregistrements d'utilisation incluent les détails du demandeur et du service, le statut de la réponse, l'utilisation des jetons du modèle et la latence, les métadonnées des appels MCP et les métadonnées de la session de l'agent de codage. Query la table pour une analyse personnalisée, ou utilisez le tableau de bord d'utilisation intégré pour surveiller l'utilisation, les dépenses, l'adoption et les performances.
Les administrateurs du compte et du workspace peuvent également consulter un aperçu consolidé de l’utilisation de l’IA sur la page IA du Governance Hub.
Exigences
- Un workspace Databricks dans une région prise en charge par Unity Gateway.
- Unity Catalog activé pour votre workspace. Consultez Activer un workspace pour Unity Catalog.
- Les rôles d'administrateur de compte et de métastore sont tous deux requis pour afficher ou effectuer une query sur la table
system.ai_gateway.usagepar default. Les administrateurs peuvent gérer l'accès aux tables système pour contrôler les autorisations des utilisateurs, des groupes et des Service Principal.
Query la table d'utilisation
Unity Gateway Logs les données d’utilisation dans la table système system.ai_gateway.usage. Vous pouvez visualiser la table dans l'interface utilisateur, ou query la table depuis Databricks SQL ou un Notebook.
Les enregistrements sont généralement disponibles en une heure. La livraison de données pour les nouveaux Workspace peut prendre plus de temps.
Pour visualiser la table dans l'interface utilisateur, cliquez sur le link de la table de suivi d'utilisation sur la page du service de modèle pour ouvrir la table dans Catalog Explorer.
Pour interroger la table à partir de Databricks SQL ou d'un Notebook :
SELECT * FROM system.ai_gateway.usage;
Genie Code peut faire cela pour vous. Essayez cet exemple de prompt :
Query the system.ai_gateway.usage table to analyze AI Gateway usage showing request count and total tokens, grouped by endpoint name for the last 7 days.
Tarifs
Le suivi de l’utilisation est une fonctionnalité facturable de Unity Gateway. Databricks facture l’utilisation qu’il consigne dans la table system.ai_gateway.usage. Voir les tarifs de Unity Gateway.
Tableau de bord d'utilisation intégré
Le tableau de bord d’utilisation de Unity Gateway intégré offre une vue consolidée de l’utilisation, des dépenses, de l’adoption et des performances pour les modèles, les services MCP, les agents de codage et les compétences.
Créer le tableau de bord
Les administrateurs de compte peuvent créer le tableau de bord à partir de la page passerelle Unity :
-
Cliquez sur Gouverner > Créer un tableau de bord d’utilisation .
-
Choisissez Utilisation du compte pour analyser l'utilisation sur les différents Workspace, ou Utilisation du Workspace pour restreindre l'analyse au Workspace actuel.
-
Configurez les autorisations de données :
- Autorisation de données partagées : les observateurs exécutent des queries de tableau de bord en utilisant vos autorisations de données.
- Autorisation de données individuelles : chaque observateur exécute des queries de tableau de bord en utilisant ses propres autorisations de données.
-
Choisissez si vous souhaitez activer les Mises à jour automatiques et l’ Actualisation automatique des données refresh .
-
Cliquez sur Configuration et publication .
Le SQL Warehouse default est sélectionné automatiquement. L'identité qui exécute les queries du tableau de bord nécessite un accès aux tables système sous-jacentes. Consultez Accorder l'accès aux tables système et Autorisations de données du tableau de bord.
Dans les Workspace sans le menu déroulant Gouvernance , utilisez les boutons autonomes Créer un tableau de bord , Afficher le tableau de bord et Mettre à jour sur la page Unity Gateway.
Explorer le tableau de bord
Cliquez sur Gouvernance > Tableau de bord d’utilisation pour ouvrir le tableau de bord dans un nouvel tab.
Tab | Analyse |
|---|---|
Présentation | Examinez l’utilisation, les jetons, les utilisateurs actifs et les sessions d’agent de codage. Comparez les modèles et les utilisateurs en fonction des dépenses, des tendances des dépenses et des dépenses par jeton ou par demande. |
Dépenses | Analysez les dépenses par modèle et par utilisateur, comparez la consommation et la mise en cache des jetons, et attribuez les dépenses via des balises de service et de demande. |
Agents de code | Comparez l’adoption des agents, l’utilisation des outils, les sessions, la consommation de jetons et les sous-agents. Examinez les sessions individuelles classées par dépenses estimées. |
Protocoles MCP | Suivez les appels d’outils et les utilisateurs actifs, identifiez les services et les outils fréquemment utilisés et comparez les sources d’utilisation. |
Compétences | Suivez les download et les chargements de compétences, comparez l’adoption des compétences et examinez l’activité par utilisateur. |
Performance | Comparez la latence du modèle et du MCP, le temps de streaming jusqu’au premier octet, les jetons de sortie par seconde, les taux de réussite du cache, les erreurs et les appels limités en débit. |
Lisez-moi | Passez en revue les fonctionnalités du tableau de bord, les changements récents et les Link vers les sources de données sous-jacentes. |
Sélectionnez une plage de dates pour concentrer l'analyse, ou sélectionnez une clé de tag de service et une ou plusieurs valeurs de tag de service pour limiter l'utilisation et les dépenses à des équipes ou des projets spécifiques. Les tableaux de bord au niveau du compte incluent également un filtre ID de workspace . Les filtres de tag de service ne s'appliquent pas au tab Compétences.
Mettre à jour le tableau de bord
Lorsqu’une version de tableau de bord plus récente est disponible, un administrateur de compte peut cliquer sur Mettre à jour sur la ligne de version du tableau de bord dans le menu déroulant Gouverner . Avec les Mises à jour automatiques activées, un template plus récent est appliqué lorsqu’un administrateur de compte visite la page Unity Gateway.
La mise à jour remplace le contenu du tableau de bord par le dernier template et peut écraser les personnalisations. Enregistrez une copie avant la mise à jour si vous souhaitez conserver vos modifications.
refresh les données du tableau de bord
La planification de l'actualisation des données refresh refresh actualise les résultats de la query toutes les six heures.
Gérez le planning de refresh dans le tableau de bord. Voir Créer un planning.
Schéma de la table d'utilisation
La table system.ai_gateway.usage a le schéma suivant :
Nom de colonne | Type | Description | Exemple |
|---|---|---|---|
| CHAÎNE | L'ID du compte. |
|
| CHAÎNE | L'ID du workspace. |
|
| CHAÎNE | Un identifiant unique pour la requête. |
|
| CHAÎNE | Un identifiant unique pour chaque appel d'inférence individuel. Plusieurs invocations peuvent partager le même |
|
| INTEGER | La version du schéma de l'enregistrement d'utilisation. |
|
| CHAÎNE | Type de service ayant généré l’enregistrement d’utilisation. Les valeurs sont |
|
| CHAÎNE | ID du service de modèle, du service MCP ou du service de fournisseur de modèle. |
|
| CHAÎNE | Le nom pleinement qualifié Unity Catalog du service. |
|
| Carte | Tags de ressources appliqués à l’élément sécurisable Unity Catalog lors de la création ou de la mise à jour. Ils s’appliquent à toutes les requêtes adressées au service et sont utiles pour classer l’utilisation par équipe, centre de coûts ou projet. |
|
| CHAÎNE | L'ID unique du service de modèle Unity Gateway. |
|
| CHAÎNE | Le nom du service de modèle Unity Gateway. |
|
| Carte | Tags configurés sur le service de modèle au moment de la création ou de la mise à jour. Ils s'appliquent à toutes les requêtes adressées au modèle de service et sont utiles pour catégoriser les services par équipe, centre de coûts ou projet. |
|
| Structure | Métadonnées du service de modèle incluant |
|
| Horodatage | Le Timestamp lorsque la requête a été reçue. |
|
| LONG | La latence totale en millisecondes. |
|
| LONG | Le temps de premier octet en millisecondes. |
|
| CHAÎNE | Le type de destination (par exemple, modèle externe ou modèle de fondation). |
|
| CHAÎNE | Le nom du modèle ou du fournisseur de destination. |
|
| CHAÎNE | L'ID unique de la destination. |
|
| CHAÎNE | Le modèle spécifique utilisé pour la requête. |
|
| CHAÎNE | L'ID de l'utilisateur ou du Service Principal qui a effectué la demande. |
|
| CHAÎNE | Le type de demandeur (utilisateur, Service Principal ou groupe d'utilisateurs). |
|
| CHAÎNE | L'adresse IP du demandeur. |
|
| CHAÎNE | L’URL de la requête. |
|
| CHAÎNE | L’agent utilisateur du demandeur. |
|
| CHAÎNE | Le type d'appel API (par exemple, chat, complétions ou embeddings). |
|
| Carte | Tags fournis par l’utilisateur envoyés avec les requêtes individuelles à l’aide de l’en-tête HTTP |
|
| Structure | Informations sur l'origine de la requête, le niveau de service indiqué par le fournisseur du modèle et l'utilisation éventuelle d'un abonnement Claude. |
|
| LONG | Le nombre de jetons d'entrée. |
|
| LONG | Le nombre de jetons de sortie. |
|
| LONG | Le nombre total de jetons (entrée + sortie). |
|
| Structure | Répartition détaillée de l'utilisation des jetons et des outils, y compris |
|
| CHAÎNE | Le type de contenu de la réponse. |
|
| INT | Le code de statut HTTP de la réponse. |
|
| Structure | Détails de routage pour les tentatives de fallback. Contient un tableau |
|
| Structure | Détails d’une requête adressée à un service MCP, incluant l’outil invoqué, le type de serveur et l’opération JSON-RPC. Renseigné pour |
|
| Structure | Contexte de la session et du client, incluant les ID de session et de sous-agent, le nom et la version de l’agent de codage, l’interface client, l’effort de raisonnement et la méthode de routage intelligent. Utilisez ces champs pour regrouper les requêtes associées et analyser l’usage par agent ou par session. |
|
| CHAÎNE | Type d’identifiant Databricks utilisé pour authentifier la requête : un jeton d’accès personnel ( |
|
Schémas de colonnes imbriquées
Les tables suivantes décrivent les champs des colonnes STRUCT imbriquées. La disponibilité des champs dépend du service, du modèle et du client utilisés pour la requête.
Métadonnées d’invocation et de jeton
Chemin d’accès au champ | Type | Description |
|---|---|---|
| CHAÎNE | L’application, le service ou l’API qui a initié la requête. Utilisez ce champ pour attribuer l’utilisation à sa source. Les valeurs incluent |
| CHAÎNE | Le niveau de service indiqué par le fournisseur de modèle dans la réponse d'inférence, tel que |
| BOOLEAN | Indique si la requête a été transmise à Anthropic à l’aide de l’abonnement Claude de l’appelant. |
| LONG | Le nombre de jetons lus à partir du cache de prompt. |
| LONG | Le nombre de jetons écrits dans le cache de prompt. |
| LONG | Nombre de jetons de raisonnement dans la sortie. |
| LONG | Le nombre de jetons d’entrée écrits dans le cache de prompt avec une durée de vie de 5 minutes. |
| LONG | Le nombre de jetons d’entrée écrits dans le cache de prompt avec une durée de vie d’une heure. |
| LONG | Le nombre d’appels d’outils de recherche de fichiers effectués dans le cadre de la requête. |
| LONG | Le nombre de query de recherche web facturables effectuées dans le cadre de la requête. |
Métadonnées du service MCP
Ces champs sont renseignés dans mcp_metadata pour MCP_SERVICE lignes.
Chemin d’accès au champ | Type | Description |
|---|---|---|
| CHAÎNE | Le nom de l'outil invoqué par une requête MCP |
| CHAÎNE | La catégorie de serveur MCP gérant la requête, telle que |
| CHAÎNE | L’opération JSON-RPC demandée par le client, telle que |
Métadonnées de session
Les champs session_metadata aident à corréler les requêtes au sein d’une session et à distinguer les agents de codage, les interfaces client et les paramètres de requête. Chaque champ est renseigné lorsque l’information correspondante est disponible auprès du client ou de la demande.
Chemin d’accès au champ | Type | Description |
|---|---|---|
| CHAÎNE | L'ID de session fourni par le client. Utilisez-le pour regrouper les requêtes effectuées au cours de la même conversation ou de la même session d'agent de codage. |
| CHAÎNE | L’ID de sous-agent fourni par le client. Utilisez-le avec |
| CHAÎNE | Le nom normalisé de l’agent de codage qui a envoyé la demande, tel que |
| CHAÎNE | La version déclarée de l’agent de code. Utilisez-le avec |
| CHAÎNE | L’interface client à partir de laquelle l’agent de codage a envoyé la requête, telle qu’une interface en ligne de commande, un IDE ou une application de bureau. |
| CHAÎNE | L’effort de raisonnement spécifié dans la requête, tel que |
| CHAÎNE | Le nom de la recette de routage intelligent sélectionnée par le client. Utilisez-le pour regrouper l’utilisation par recette de routage. |
Requêtes de tags pour le suivi de l'utilisation
Les tags de requête sont des paires clé-valeur personnalisées que l'appelant attache aux requêtes individuelles. Utilisez les tags de requête pour attribuer l'utilisation par projet, équipe, environnement, utilisateur final ou toute autre dimension pertinente pour votre organisation. Les tags de requête sont enregistrés dans la table system.ai_gateway.usage et peuvent être utilisés pour filtrer, agréger et analyser les données d'utilisation.
Pour étiqueter les requêtes individuelles, incluez l'en-tête HTTP Databricks-Ai-Gateway-Request-Tags avec un objet JSON mappant les clés de chaîne aux valeurs de chaîne. Les étiquettes de requête sont enregistrées dans la colonne request_tags de la table d'utilisation et dans les tables d'inférence.
Pour des exemples montrant comment définir des étiquettes de requête avec l’API REST, le SDK OpenAI et le SDK Anthropic, consultez Étiquetage des requêtes.
Par exemple, vous pouvez agréger l'utilisation par projet à l'aide de balises de requête :
SELECT
request_tags['project'] AS project,
COUNT(*) AS request_count,
SUM(total_tokens) AS total_tokens
FROM system.ai_gateway.usage
WHERE request_tags['project'] IS NOT NULL
GROUP BY request_tags['project']
ORDER BY total_tokens DESC;
Limitations
- Unity Gateway ne suit pas l'utilisation des jetons pour les réponses non-streaming et non-embedding supérieures à 1 MiB.