Suivre l’utilisation du modèle

Surveillez l’utilisation des services Unity Gateway avec la system.ai_gateway.usage table système. Il capture les requêtes adressées aux services de modèle, aux services de fournisseur de modèles et aux services MCP provenant de diverses sources, y compris AI Query, les agents de codage, les applications Databricks, AI Playground et d’autres applications.

Les enregistrements d’utilisation incluent les détails du demandeur et du service, l’état de la réponse, l’utilisation et la latence du token de modèle, les métadonnées des appels MCP et les métadonnées de session de l’agent de codage. Interrogez 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 de comptes et d’espaces de travail peuvent également consulter un aperçu consolidé de l’utilisation de l’IA sur la page IA dans Governance Hub.

Requirements

Interroger le tableau d'utilisation

Unity Gateway enregistre les données d’utilisation dans la system.ai_gateway.usage table système. Vous pouvez afficher la table dans l’interface utilisateur ou interroger la table à partir de Databricks SQL ou d’un notebook.

Remarque

Les enregistrements sont généralement disponibles dans l’heure. La livraison des données pour de nouveaux espaces de travail peut prendre plus de temps que cela.

Pour afficher la table dans l’interface utilisateur, cliquez sur le lien de la table de suivi de l’utilisation sur la page du service de modèle pour ouvrir la table dans l’Explorateur de catalogues.

Pour interroger la table à partir de Databricks SQL ou d’un notebook :

SELECT * FROM system.ai_gateway.usage;

Tip

Genie Code peut faire ça pour vous. Essayez cet exemple d’invite suivant :

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.

Pricing

Le suivi de l’utilisation est une fonctionnalité facturée de Unity Gateway. Azure Databricks facture l’utilisation qu’il enregistre à la system.ai_gateway.usage table. Voir les tarifs de Unity Gateway.

Tableau de bord d’utilisation intégré

Le tableau de bord d’utilisation intégré de Unity Gateway offre une vue consolidée de l’utilisation, des dépenses, de l’adoption et des performances à travers les modèles, services MCP, agents de codage et compétences.

Créez le tableau de bord

Les administrateurs de compte peuvent créer le tableau de bord depuis la page Unity Gateway :

  1. Cliquez sur Govern > Créer un tableau de bord d’utilisation.
  2. Choisissez l’utilisation du compte pour analyser l’utilisation dans l’ensemble des espaces de travail, ou l’utilisation de l’espace de travail pour restreindre l’analyse à l’espace de travail actuel.
  3. Configurez les autorisations de données :
    • Autorisation de partage des données : Les lecteurs effectuent des requêtes de tableau de bord en utilisant vos autorisations de données.
    • Permission individuelle des données : Chaque utilisateur exécute des requêtes de tableau de bord en utilisant ses propres permissions de données.
  4. Choisissez d’activer les mises à jour automatiques et la mise à jour programmée des données.
  5. Cliquez sur Configurer et publier.

L’entrepôt SQL par défaut est sélectionné automatiquement. L’identité qui exécute les requêtes sur le tableau de bord a besoin d’accéder aux tables système sous-jacentes. Voir Accorder l’accès aux tables système et aux permissions de données du tableau de bord.

Options de mise à jour du tableau de bord ai-gateway

Remarque

Dans les espaces de travail sans le menu déroulant Gouverner, utilisez les boutons autonomes Créer un tableau de bord, Afficher le tableau de bord et Mettre à jour sur la page Unity Gateway.

Explorez le tableau de bord

Cliquez sur Govern > Usage Dashboard pour ouvrir le tableau de bord dans un nouvel onglet.

Tableau de bord d’utilisation de la passerelle ai-gateway

Tab Analyse
Overview Examinez l’utilisation, les jetons, les utilisateurs actifs et les sessions des agents de codage. Comparez les modèles et les utilisateurs selon les dépenses, les tendances de dépense et les dépenses par token ou demande.
Dépense Analysez les dépenses par modèle et utilisateur, comparez la consommation de tokens et le cache, et attribuez les dépenses via les balises service et requête.
Agents de programmation Comparez l’adoption des agents, l’utilisation du harness, les sessions, la consommation de tokens et les sous-agents. Examinez les sessions individuelles classées selon les dépenses estimées.
MCPs Suivez les appels d’outils et les utilisateurs actifs, identifiez les services et outils fréquemment utilisés, et comparez les sources d’utilisation.
Compétences Suivez les téléchargements et les utilisations des compétences, comparez l’adoption des compétences et examinez l’activité par utilisateur.
Efficacité Comparez la latence du modèle et du MCP, le temps de streaming jusqu’au premier octet, les tokens de sortie/s, les taux de hits du cache, les erreurs et les appels soumis à une limitation de débit.
README Examinez les capacités des tableaux de bord, les changements récents et les liens vers les sources de données sous-jacentes.

Sélectionnez une plage de dates pour focaliser l’analyse, ou sélectionnez une clé Service Tag et une ou plusieurs entrées de valeur Service Tag pour restreindre l’utilisation et les dépenses à des équipes ou projets spécifiques. Les tableaux de bord à portée de compte incluent également un filtre ID d’espace de travail. Les filtres par étiquette de service ne s’appliquent pas à l’onglet Compétences.

Mettre à jour le tableau de bord

Lorsqu’une nouvelle version du tableau de bord est disponible, un administrateur de compte peut cliquer sur Update dans la ligne de version du tableau de bord du menu déroulant Govern. Avec les mises à jour automatiques activées, un modèle 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 modèle et peut écraser les personnalisations. Sauvegardez une copie avant de mettre à jour si vous souhaitez préserver vos modifications.

Actualiser les données du tableau de bord

Le rafraîchissement des données programmé actualise les résultats de la requête toutes les six heures.

Gérez la planification de l’actualisation dans le tableau de bord. Consultez Créer une planification.

Schéma de table d'utilisation

Le system.ai_gateway.usage tableau comporte le schéma suivant :

Nom de la colonne Type Description Example
account_id STRING ID de compte. 11d77e21-5e05-4196-af72-423257f74974
workspace_id STRING Identifiant de l’espace de travail. 1653573648247579
request_id STRING Identificateur unique de la requête. b4a47a30-0e18-4ae3-9a7f-29bcb07e0f00
invocation_id STRING Identificateur unique pour chaque appel d’inférence individuel. Plusieurs invocations peuvent partager le même request_id, comme les vérifications de garde-fou ou les appels à un agent sur plusieurs tours. Permet invocation_id de les distinguer. c0a8012e-9f3b-4d21-8a7e-1b2c3d4e5f60
schema_version INTEGER La version du schéma de l’enregistrement d’utilisation. 1
service_type STRING Le type de service qui générait l’enregistrement d’utilisation. Les valeurs sont MODEL_SERVICE, MCP_SERVICE, et MODEL_PROVIDER_SERVICE. MODEL_SERVICE
service_id STRING L’identifiant du Service Modèle, du Service MCP ou du Service Fournisseur Modèle. 43addf89-d802-3ca2-bd54-fe4d2a60d58a
service_name STRING Le Unity Catalog a pleinement qualifié le nom du service. main.default.github_tools
service_tags MAP Les balises de ressources appliquées au catalogue Unity sont sécurisées au moment de la création ou de la mise à jour. Ils s’appliquent à toutes les requêtes au service et sont utiles pour catégoriser l’utilisation par équipe, centre de coûts ou projet. {"team": "engineering"}
endpoint_id STRING L’ID unique du service modèle Unity Gateway. 43addf89-d802-3ca2-bd54-fe4d2a60d58a
endpoint_name STRING Le nom du service modèle Unity Gateway. system.ai.gpt-5-2
endpoint_tags MAP Balises configurées sur le service de modèle au moment de la création ou de la mise à jour. Ils s’appliquent à toutes les requêtes au service de modèle et sont utiles pour catégoriser les services par équipe, centre de coûts ou projet. {"team": "engineering"}
endpoint_metadata STRUCT Métadonnées du service de modèle, notamment creator, creation_time, last_updated_time, destinations, inference_table et fallbacks. {"creator": "user.name@email.com", "creation_time": "2026-01-06T12:00:00.000Z", ...}
event_time TIMESTAMP L'horodatage correspondant à la réception de la demande. 2026-01-20T19:48:08.000+00:00
latency_ms LONG Latence totale en millisecondes. 300
time_to_first_byte_ms LONG Temps jusqu'au premier octet en millisecondes. 300
destination_type STRING Type de destination (par exemple, modèle externe ou modèle de base). PAY_PER_TOKEN_FOUNDATION_MODEL
destination_name STRING Nom du modèle ou du fournisseur de destination. system.ai.gpt-5-2
destination_id STRING ID unique de la destination. 507e7456151b3cc89e05ff48161efb87
destination_model STRING Modèle spécifique utilisé pour la requête. GPT-5.2
requester STRING ID de l’utilisateur ou du principal de service qui a effectué la demande. user.name@email.com
requester_type STRING Type de demandeur (utilisateur, principal de service ou groupe d’utilisateurs). USER
ip_address STRING Adresse IP du demandeur. 1.2.3.4
url STRING URL de la demande. https://<workspace-url>/ai-gateway/mlflow/v1/chat/completions
user_agent STRING Agent utilisateur du demandeur. OpenAI/Python 2.13.0
api_type STRING Type d’appel d’API (par exemple, conversation, achèvements ou incorporations). mlflow/v1/chat/completions
request_tags MAP Balises fournies par l’utilisateur envoyées avec des requêtes individuelles à l’aide de l’en-tête Databricks-Ai-Gateway-Request-Tags HTTP. Utilisez des balises de demande pour attribuer l’utilisation à des projets, équipes, environnements ou utilisateurs finaux spécifiques. Voir Marquer des requêtes pour le suivi de l’utilisation et Étiquetage des requêtes. {"project": "chatbot", "team": "ml-platform"}
invocation_metadata STRUCT Informations sur l’origine de la requête, le niveau de service rapporté par le fournisseur de modèle, et si la requête utilisait un abonnement Claude. {"source": "EXTERNAL_CLIENT", "service_tier": "priority", "relayed": false}
input_tokens LONG Nombre de jetons d’entrée. 100
output_tokens LONG Nombre de jetons de sortie. 100
total_tokens LONG Nombre total de jetons (entrée + sortie). 200
token_details STRUCT Décomposition détaillée de l’utilisation des jetons et des outils, incluant cache_read_input_tokens, cache_creation_input_tokens, output_reasoning_tokens, cache_creation_5m_input_tokens, cache_creation_1h_input_tokens, file_search_count, et num_web_search_queries. {"cache_read_input_tokens": 100, ...}
response_content_type STRING Type de contenu de la réponse. application/json
status_code INT Code d’état HTTP de la réponse. 200
routing_information STRUCT Détails du routage des tentatives de repli. Contient un attempts tableau avec priority, action, destination, destination_id, status_code, error_code, latency_ms, start_time et end_time pour chaque modèle essayé pendant la demande. {"attempts": [{"priority": "1", ...}]}
mcp_metadata STRUCT Détails d’une requête à un service MCP, y compris l’outil invoqué, le type de serveur et l’opération JSON-RPC. Renseigné pour MCP_SERVICE lignes. {"tool_name": "echo", "server_type": "EXTERNAL", "json_rpc_method": "tools/call"}
session_metadata STRUCT Contexte de session et client, incluant les identifiants de session et de sous-agents, le nom et la version codage de l’agent, l’interface client, l’effort de raisonnement et la recette de routage intelligent. Utilisez ces champs pour regrouper les requêtes liées et analyser l’utilisation par agent ou session. {"coding_agent": "claude-code", "agent_version": "2.1.282", "reasoning_effort": "high", ...}
auth_mode STRING Le type de crédent Databricks utilisé pour authentifier la requête : un jeton d’accès personnel (PAT) ou un jeton OAuth (OAUTH). OAUTH

Schémas de colonnes imbriqués

Les tableaux suivants décrivent les champs à l’intérieur des colonnes imbriquées STRUCT . La disponibilité sur le terrain dépend du service, du modèle et du client utilisé pour la requête.

Métadonnées d’invocation et de jetons

Chemin d’accès au champ Type Description
invocation_metadata.source STRING L’application, le service ou l’API qui a lancé la requête. Utilisez ce champ pour attribuer l’usage à sa source. Les valeurs incluent AI_PLAYGROUND, EXTERNAL_CLIENT, AI_QUERY, GUARDRAIL, MANAGED_AGENT, ROUTER, WEB_SEARCH, , et SAFEGUARD_CLASSIFIER.
invocation_metadata.service_tier STRING Le niveau de service rapporté par le fournisseur du modèle dans la réponse d’inférence, tel que default ou priority. Utilisez ce champ pour comparer l’utilisation selon les niveaux tarifaires des fournisseurs.
invocation_metadata.relayed BOOLEAN Si la demande a été transmise à Anthropic via l'abonnement Claude de l'appelant.
token_details.cache_read_input_tokens LONG Le nombre de jetons lus depuis le cache de prompts.
token_details.cache_creation_input_tokens LONG Le nombre de jetons écrits dans le cache de prompts.
token_details.output_reasoning_tokens LONG Le nombre de tokens de raisonnement dans la réponse.
token_details.cache_creation_5m_input_tokens LONG Le nombre de tokens d’entrée enregistrés dans le cache de prompt avec une durée de vie de 5 minutes.
token_details.cache_creation_1h_input_tokens LONG Le nombre de tokens d’entrée écrits dans le cache de prompt pour une durée de vie d’une heure.
token_details.file_search_count LONG Le nombre d’appels à l’outil de recherche de fichiers effectués dans le cadre de la requête.
token_details.num_web_search_queries LONG Le nombre de requêtes de recherche web facturables effectuées dans le cadre de la demande.

Métadonnées du service MCP

Ces champs sont renseignés dans mcp_metadata pour les lignes MCP_SERVICE.

Chemin d’accès au champ Type Description
mcp_metadata.tool_name STRING Le nom de l’outil invoqué par une requête MCP tools/call . Utilisez ce champ pour analyser l’utilisation des outils individuels sur un serveur.
mcp_metadata.server_type STRING La catégorie de serveur MCP traitant la requête, telle que EXTERNAL ou SYSTEM.
mcp_metadata.json_rpc_method STRING L’opération JSON-RPC demandée par le client, comme tools/call invoquer un outil, tools/list découvrir des outils ou initialize lancer une session.

Métadonnées de session

Ces session_metadata champs aident à corréler les requêtes au sein d’une session et à distinguer les agents de codage, les interfaces clients et les paramètres de requêtes. Chaque champ est rempli lorsque les informations correspondantes sont disponibles auprès du client ou de la demande.

Chemin d’accès au champ Type Description
session_metadata.client_session_id STRING L’identifiant de session fourni par le client. Utilisez-le pour regrouper les requêtes faites lors de la même conversation ou session d’agent de codage.
session_metadata.client_subagent_id STRING L’identifiant du sous-agent fourni par le client. Utilisez-le avec client_session_id pour distinguer les requêtes des sous-agents au sein d’une session parent.
session_metadata.coding_agent STRING Le nom normalisé de l’agent codant qui a envoyé la requête, tel que claude-code ou codex.
session_metadata.agent_version STRING La version rapportée par l’agent de codage. Utilisez-le avec coding_agent pour comparer l’utilisation entre les versions de l’agent.
session_metadata.surface STRING L’interface client depuis laquelle l’agent de codage envoyait la requête, telle qu’une interface en ligne de commande, un IDE ou une application de bureau.
session_metadata.reasoning_effort STRING L’effort de raisonnement spécifié dans la requête, tel que low, medium, ou high. Les valeurs disponibles dépendent du modèle et de l’API.
session_metadata.smart_router_name STRING Le nom de la recette de routage intelligent sélectionnée par le client. Utilisez-le pour regrouper l’utilisation par recette de routage.

Étiqueter les requêtes pour le suivi de l'utilisation

Les balises de requête sont des paires clé-valeur personnalisées que l’appelant attache à des requêtes individuelles. Utilisez des balises de demande pour attribuer l’utilisation par projet, équipe, environnement, utilisateur final ou toute autre dimension pertinente pour votre organisation. Les balises de requête sont consignées dans la system.ai_gateway.usage table et peuvent être utilisées pour filtrer, agréger et analyser les données d’utilisation.

Pour étiqueter des requêtes individuelles, incluez l’en-tête HTTP Databricks-Ai-Gateway-Request-Tags avec un objet JSON qui associe des clés de type chaîne à des valeurs de type chaîne. Les balises de requête sont consignées dans la request_tags colonne de la table d’utilisation et dans les tables d’inférence.

Pour des exemples montrant comment définir des balises de requête avec l’API REST, le SDK OpenAI et le SDK Anthropic, voir É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

Ressources supplémentaires

  • Dernière mise à jour :