Utilisation du modèle pour les services Unity AI Gateway

info

Bêta

Cette fonctionnalité est en Bêta. Les administrateurs de compte peuvent contrôler l'accès à cette fonctionnalité depuis la page Aperçus de la console de compte. Consultez Gérer les aperçus Databricks.

Cette page décrit comment surveiller l’utilisation des services Unity AI Gateway à l’aide de la table système de suivi d’utilisation.

La table de suivi de l'utilisation capture automatiquement les détails des requêtes et des réponses pour un service de modèle, enregistrant les métriques essentielles comme l'utilisation des jetons et la latence. Vous pouvez utiliser les données de ce tableau pour surveiller les utilisateurs, suivre les coûts et obtenir des insights sur les performances et la consommation du service de modèle.

Le suivi de l'utilisation capture également les requêtes ai_query vers les services de modèles fournis par Databricks.

Exigences

• L'aperçu Unity AI Gateway au niveau du compte doit être activé pour votre compte. Un administrateur de compte active cet aperçu sur la page Aperçus de la console de compte avant que vous puissiez utiliser le suivi d'utilisation ou le tableau de bord d'utilisation intégré. Consultez Gérer les Aperçus Databricks.
• Un Databricks workspace dans une région prise en charge par Unity AI Gateway.
• Unity Catalog activé pour votre workspace. Consultez Activer un workspace pour Unity Catalog.

Query la table d'utilisation

Unity AI Gateway Logs les données d'utilisation dans la table système system.ai_gateway.usage. Vous pouvez afficher la table dans l'interface utilisateur, ou query la table à partir de Databricks SQL ou d'un Notebook.

remarque

Seuls les administrateurs de compte sont autorisés à afficher ou query la table system.ai_gateway.usage.

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 :

SQL

SELECT * FROM system.ai_gateway.usage;

prompt

Genie Code (mode Agent) peut le faire 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.

Tableau de bord d'utilisation intégré

remarque

Certains workspaces n’affichent pas encore le menu déroulant **Govern**. Dans ces Workspaces, utilisez plutôt les boutons autonomes Créer un tableau de bord , Afficher le tableau de bord et Mettre à jour sur la page Unity AI Gateway.

Créer un tableau de bord d'utilisation intégré

Les administrateurs de compte peuvent créer un tableau de bord d'utilisation intégré à Unity AI Gateway pour surveiller l'utilisation, suivre les coûts et obtenir des insights sur les performances et la consommation du service de modèle. Depuis la page Unity AI Gateway, cliquez sur Gérer en haut à droite, puis cliquez sur Créer un tableau de bord d'utilisation . Le warehouse qui exécute les queries du tableau de bord est sélectionné automatiquement.

remarque

La création de tableaux de bord est réservée aux administrateurs de compte car elle nécessite les autorisations SELECT sur la table system.ai_gateway.usage. Les données du tableau de bord sont soumises aux politiques de rétention de la table usage. Voir Quelles tables système sont disponibles ?

Lorsqu'une version plus récente du tableau de bord d'utilisation intégré est disponible, les administrateurs de compte peuvent cliquer sur **Mettre à jour** sur la ligne de version du tableau de bord dans le menu déroulant **Gouverner** sur la page Unity AI Gateway.

Vous pouvez utiliser les options de configuration de tableau de bord suivantes pour gérer le tableau de bord :

• Portée : sélectionnez si vous souhaitez limiter le tableau de bord au compte ou au workspace.
• Autorisations : choisissez si les queries s'exécutent en utilisant les permissions du propriétaire du tableau de bord ou les permissions de chaque spectateur. Voir Qu'est-ce que les permissions de partage de données ?.
• Mises à jour automatiques : Lorsque vous activez cette option, le tableau de bord se met à jour automatiquement dès qu’une nouvelle version est disponible et qu’un administrateur de compte visite la page Unity AI Gateway.

Lorsque le tableau de bord est mis à jour vers la version 0.3 ou supérieure, un calendrier est automatiquement créé pour refresh le tableau de bord toutes les 6 heures. Si nécessaire, ce calendrier peut être désactivé dans le tableau de bord Lakeview. Voir Créer un calendrier.

Afficher le tableau de bord d'utilisation

Pour afficher le tableau de bord, cliquez sur Govern en haut à droite de la page Unity AI Gateway, puis cliquez sur Usage Dashboard . Le tableau de bord s'ouvre dans un nouveau tab. Le tableau de bord intégré offre une visibilité complète sur l'utilisation, les performances et le coût du service de modèle Unity AI Gateway. Il comprend plusieurs pages de suivi des requêtes, de la consommation de jetons, des métriques de latence, des taux d'erreur, des analyses de coûts, du trafic des serveurs MCP externes et de l'activité des agents de codage.

Le tableau de bord fournit des analytiques inter-Workspace par default. Toutes les pages du tableau de bord peuvent être filtrées par plage de dates et par ID de Workspace.

• tab Vue d'ensemble : Affiche des métriques d'utilisation de haut niveau, y compris le volume quotidien de requêtes, les tendances d'utilisation des jetons au fil du temps, les principaux utilisateurs par consommation de jetons et le nombre total d'utilisateurs uniques. Utilisez cette tab pour obtenir un aperçu rapide de l'activité globale de Unity AI Gateway et identifier les utilisateurs et les modèles les plus actifs.
• Performance tab : suit les indicateurs de performance clés, notamment les centiles de latence (P50, P90, P95, P99), le temps jusqu’au premier octet, les taux d’erreur et la répartition des codes d’état HTTP. Utilisez cet tab pour surveiller l’état de santé du service de modèle et identifier les goulets d’étranglement en matière de performances ou les problèmes de fiabilité.
• Tab Usage : Affiche les répartitions détaillées de la consommation par service de modèle, Workspace et demandeur. Ce tab montre les schémas d'utilisation des jetons, les distributions des requêtes et les taux d'accès au cache.
• Cost Observability tab : Affiche les ventilations des coûts par service de modèle, modèle cible, utilisateur, tags de service et tags de requête. Cet tab inclut également le coût estimé des modèles externes. Voir Surveiller le coût de Unity AI Gateway.
• **Tab des serveurs MCP externes** : Affiche le volume des requêtes, les taux d'erreur, les utilisateurs et les connexions, ainsi que les tendances d'utilisation quotidiennes pour le trafic des serveurs MCP externes.
• tab Agents de codage : suit l'activité des agents de codage intégrés, y compris Cursor, Claude Code, Gemini CLI et Codex CLI. Cette tab affiche des métriques comme les jours actifs, les sessions de codage, les commit et les lignes de code ajoutées ou supprimées pour surveiller l'utilisation des outils de développement. Consultez le tableau de bord de l'agent de codage pour plus de détails.

Schéma de la table d'utilisation

La table system.ai_gateway.usage a le schéma suivant :

Nom de colonne	Type	Description	Exemple
account_id	CHAÎNE	L'ID du compte.	11d77e21-5e05-4196-af72-423257f74974
workspace_id	CHAÎNE	L'ID du workspace.	1653573648247579
request_id	CHAÎNE	Un identifiant unique pour la requête.	b4a47a30-0e18-4ae3-9a7f-29bcb07e0f00
invocation_id	CHAÎNE	Un identifiant unique pour chaque appel d'inférence individuel. Plusieurs invocations peuvent partager le même request_id, tels que les contrôles de garde-fou ou les appels d'agent multi-tours. Utilisez invocation_id pour les distinguer.	c0a8012e-9f3b-4d21-8a7e-1b2c3d4e5f60
schema_version	INTEGER	La version du schéma de l'enregistrement d'utilisation.	1
endpoint_id	CHAÎNE	L'identifiant unique du service de modèle Passerelle d'IA Unity.	43addf89-d802-3ca2-bd54-fe4d2a60d58a
endpoint_name	CHAÎNE	Le nom du service de modèle Unity AI Gateway.	databricks-gpt-5-2
endpoint_tags	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.	{"team": "engineering"}
endpoint_metadata	Structure	Métadonnées du service de modèle incluant 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	Horodatage	Le Timestamp lorsque la requête a été reçue.	2026-01-20T19:48:08.000+00:00
latency_ms	LONG	La latence totale en millisecondes.	300
time_to_first_byte_ms	LONG	Le temps de premier octet en millisecondes.	300
destination_type	CHAÎNE	Le type de destination (par exemple, modèle externe ou modèle de fondation).	PAY_PER_TOKEN_FOUNDATION_MODEL
destination_name	CHAÎNE	Le nom du modèle ou du fournisseur de destination.	databricks-gpt-5-2
destination_id	CHAÎNE	L'ID unique de la destination.	507e7456151b3cc89e05ff48161efb87
destination_model	CHAÎNE	Le modèle spécifique utilisé pour la requête.	GPT-5.2
requester	CHAÎNE	L'ID de l'utilisateur ou du Service Principal qui a effectué la demande.	user.name@email.com
requester_type	CHAÎNE	Le type de demandeur (utilisateur, Service Principal ou groupe d'utilisateurs).	USER
ip_address	CHAÎNE	L'adresse IP du demandeur.	1.2.3.4
url	CHAÎNE	L’URL de la requête.	https://<workspace-url>/ai-gateway/mlflow/v1/chat/completions
user_agent	CHAÎNE	L’agent utilisateur du demandeur.	OpenAI/Python 2.13.0
api_type	CHAÎNE	Le type d'appel API (par exemple, chat, complétions ou embeddings).	mlflow/v1/chat/completions
request_tags	Carte	Balises fournies par l'utilisateur envoyées avec des requêtes individuelles à l'aide de l'en-tête HTTP Databricks-Ai-Gateway-Request-Tags. Utilisez les balises de requête pour attribuer l'utilisation à des projets, des équipes, des environnements ou des utilisateurs finaux spécifiques. Voir Requêtes de tags pour le suivi de l'utilisation et Requêtes de tags pour le suivi de l'utilisation.	{"project": "chatbot", "team": "ml-platform"}
invocation_metadata	Structure	Métadonnées générées par le système concernant l'appel d'inférence. Contient source, le service ou le chemin qui a initié l'appel.	{"source": "EXTERNAL_CLIENT"}
input_tokens	LONG	Le nombre de jetons d'entrée.	100
output_tokens	LONG	Le nombre de jetons de sortie.	100
total_tokens	LONG	Le nombre total de jetons (entrée + sortie).	200
token_details	Structure	Ventilation détaillée du jeton, y compris cache_read_input_tokens, cache_creation_input_tokens et output_reasoning_tokens.	{"cache_read_input_tokens": 100, ...}
response_content_type	CHAÎNE	Le type de contenu de la réponse.	application/json
status_code	INT	Le code de statut HTTP de la réponse.	200
routing_information	Structure	Détails de routage pour les tentatives de fallback. Contient un tableau attempts avec priority, action, destination, destination_id, status_code, error_code, latency_ms, start_time et end_time pour chaque modèle testé pendant la requête.	{"attempts": [{"priority": "1", ...}]}

Nom de colonne	Type	Description	Exemple
account_id	CHAÎNE	L'ID du compte.	11d77e21-5e05-4196-af72-423257f74974
workspace_id	CHAÎNE	L'ID du workspace.	1653573648247579
request_id	CHAÎNE	Un identifiant unique pour la requête.	b4a47a30-0e18-4ae3-9a7f-29bcb07e0f00
invocation_id	CHAÎNE	Un identifiant unique pour chaque appel d'inférence individuel. Plusieurs invocations peuvent partager le même request_id, tels que les contrôles de garde-fou ou les appels d'agent multi-tours. Utilisez invocation_id pour les distinguer.	c0a8012e-9f3b-4d21-8a7e-1b2c3d4e5f60
schema_version	INTEGER	La version du schéma de l'enregistrement d'utilisation.	1
endpoint_id	CHAÎNE	L'identifiant unique du service de modèle Passerelle d'IA Unity.	43addf89-d802-3ca2-bd54-fe4d2a60d58a
endpoint_name	CHAÎNE	Le nom du service de modèle Unity AI Gateway.	databricks-gpt-5-2
endpoint_tags	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.	{"team": "engineering"}
endpoint_metadata	Structure	Métadonnées du service de modèle incluant 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	Horodatage	Le Timestamp lorsque la requête a été reçue.	2026-01-20T19:48:08.000+00:00
latency_ms	LONG	La latence totale en millisecondes.	300
time_to_first_byte_ms	LONG	Le temps de premier octet en millisecondes.	300
destination_type	CHAÎNE	Le type de destination (par exemple, modèle externe ou modèle de fondation).	PAY_PER_TOKEN_FOUNDATION_MODEL
destination_name	CHAÎNE	Le nom du modèle ou du fournisseur de destination.	databricks-gpt-5-2
destination_id	CHAÎNE	L'ID unique de la destination.	507e7456151b3cc89e05ff48161efb87
destination_model	CHAÎNE	Le modèle spécifique utilisé pour la requête.	GPT-5.2
requester	CHAÎNE	L'ID de l'utilisateur ou du Service Principal qui a effectué la demande.	user.name@email.com
requester_type	CHAÎNE	Le type de demandeur (utilisateur, Service Principal ou groupe d'utilisateurs).	USER
ip_address	CHAÎNE	L'adresse IP du demandeur.	1.2.3.4
url	CHAÎNE	L’URL de la requête.	https://<workspace-url>/ai-gateway/mlflow/v1/chat/completions
user_agent	CHAÎNE	L’agent utilisateur du demandeur.	OpenAI/Python 2.13.0
api_type	CHAÎNE	Le type d'appel API (par exemple, chat, complétions ou embeddings).	mlflow/v1/chat/completions
request_tags	Carte	Balises fournies par l'utilisateur envoyées avec des requêtes individuelles à l'aide de l'en-tête HTTP Databricks-Ai-Gateway-Request-Tags. Utilisez les balises de requête pour attribuer l'utilisation à des projets, des équipes, des environnements ou des utilisateurs finaux spécifiques. Voir Requêtes de tags pour le suivi de l'utilisation et Requêtes de tags pour le suivi de l'utilisation.	{"project": "chatbot", "team": "ml-platform"}
invocation_metadata	Structure	Métadonnées générées par le système concernant l'appel d'inférence. Contient source, le service ou le chemin qui a initié l'appel.	{"source": "EXTERNAL_CLIENT"}
input_tokens	LONG	Le nombre de jetons d'entrée.	100
output_tokens	LONG	Le nombre de jetons de sortie.	100
total_tokens	LONG	Le nombre total de jetons (entrée + sortie).	200
token_details	Structure	Ventilation détaillée du jeton, y compris cache_read_input_tokens, cache_creation_input_tokens et output_reasoning_tokens.	{"cache_read_input_tokens": 100, ...}
response_content_type	CHAÎNE	Le type de contenu de la réponse.	application/json
status_code	INT	Le code de statut HTTP de la réponse.	200
routing_information	Structure	Détails de routage pour les tentatives de fallback. Contient un tableau attempts avec priority, action, destination, destination_id, status_code, error_code, latency_ms, start_time et end_time pour chaque modèle testé pendant la requête.	{"attempts": [{"priority": "1", ...}]}

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 tags de requête avec l'API REST, l'SDK OpenAI et l'SDK Anthropic, consultez Tagger les requêtes pour le suivi de l'utilisation.

Par exemple, vous pouvez agréger l'utilisation par projet à l'aide de balises de requête :

SQL

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 AI Gateway ne suit pas l'utilisation des jetons pour les réponses non-streaming et non-embedding d'une taille supérieure à 1 Mio.

Ressources supplémentaires

• Gouvernance de l'IA avec Unity AI Gateway
• Créer et gérer des services de modèle
• Interroger les services de modèles
• intégration d'agent de codage
• Surveiller les services de modèle à l'aide de tables d'inférence
• Configurez les limites de débit pour les services d'IA à l'aide de Unity AI Gateway.