Utilisation du modèle pour les services Unity AI Gateway

Important

Cette fonctionnalité est en version bêta. Les administrateurs de compte peuvent contrôler l’accès à cette fonctionnalité à partir de la page Aperçus de la console de compte. Consultez Gérer les préversions d’Azure Databricks.

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

La table de suivi de l’utilisation capture automatiquement les détails des demandes et des réponses pour un service de modèle, en journalise les métriques essentielles telles que 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 ai_query requêtes vers les services de modèles fournis par Databricks.

Les administrateurs de compte et d’espace de travail peuvent afficher une vue d’ensemble consolidée de l’utilisation de l’IA sur la page IA du hub de gouvernance.

Requirements

Interroger le tableau d'utilisation

Unity AI Gateway journalise 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

Seuls les administrateurs de compte ont l’autorisation d’afficher ou d’interroger la system.ai_gateway.usage table.

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

Tableau de bord d’utilisation intégré

Remarque

Certains espaces de travail n’affichent pas encore la liste déroulante Govern . Dans ces espaces de travail, utilisez plutôt les boutons Créer un tableau de bord, Afficher le tableau de bord et Mettre à jour autonome sur la page Passerelle AI Unity.

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

Les administrateurs de compte peuvent créer un tableau de bord intégré d’utilisation de la passerelle AI Unity pour surveiller l’utilisation, suivre les coûts et obtenir des insights sur les performances et la consommation du service de modèle. Dans la page Unity AI Gateway, cliquez sur Gouverner en haut à droite, puis cliquez sur Créer un tableau de bord d’utilisation. L’entrepôt qui exécute les requêtes de tableau de bord est sélectionné automatiquement.

Remarque

La création du tableau de bord est réservée aux administrateurs du 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 du tableau usage. Consultez 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 la liste déroulante Gouvernance de la page Unity AI Gateway.

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

  • Étendue : indiquez s’il faut étendre le tableau de bord au compte ou à l’espace de travail.
  • Autorisations : indiquez si les requêtes s’exécutent à l’aide des autorisations du propriétaire du tableau de bord ou des autorisations de chaque visionneuse. Voir Qu’est-ce que les autorisations de données partagées ?.
  • Mises à jour automatiques : lorsque vous activez cette option, le tableau de bord est mis à jour automatiquement chaque fois qu’une version plus récente devient disponible et qu’un administrateur de compte visite la page De passerelle AI Unity.

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

Lorsque le tableau de bord est mis à jour vers la version 0.3 ou une version ultérieure, une programmation est automatiquement créée pour actualiser le tableau de bord toutes les 6 heures. Si nécessaire, cette planification peut être désactivée dans le tableau de bord Lakeview. Consultez Créer une planification.

Afficher le tableau de bord d’utilisation

Pour afficher le tableau de bord, cliquez sur Gouverner en haut à droite de la page Unity AI Gateway, puis cliquez sur Tableau de bord d’utilisation. Le tableau de bord s’ouvre dans un nouvel onglet. Le tableau de bord intégré offre une visibilité complète de l’utilisation, des performances et des coûts du service de modèle d’IA Gateway Unity. Il inclut plusieurs pages qui suivent les demandes, la consommation de jetons, les métriques de latence, les taux d’erreur, les répartitions des coûts, le trafic du serveur MCP externe et l’activité de l’agent de codage.

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

Le tableau de bord fournit l’analytique inter-espaces de travail par défaut. Toutes les pages de tableau de bord peuvent être filtrées par plage de dates et ID d’espace de travail.

  • Onglet Vue d’ensemble : affiche les métriques d’utilisation de haut niveau, notamment le volume de demandes quotidiennes, 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 cet onglet pour obtenir un instantané rapide de l’activité globale de la passerelle AI Unity et identifier les utilisateurs et les modèles les plus actifs.
  • Onglet Performances : effectue le suivi des métriques de performances clés, notamment les centiles de latence (P50, P90, P95, P99), la durée de la première octet, les taux d’erreur et les distributions de code d’état HTTP. Utilisez cet onglet 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é.
  • Onglet Utilisation : affiche les répartitions détaillées de la consommation par service de modèle, espace de travail et demandeur. Cet onglet affiche les modèles d’utilisation des jetons, les distributions de requêtes et les ratios d’accès au cache.
  • Onglet Observation des coûts : affiche les répartitions des coûts par service de modèle, modèle cible, utilisateur, étiquettes de service et balises de requête. Cet onglet inclut également le coût estimé pour les modèles externes. Consultez Surveiller les coûts de Unity AI Gateway.
  • Onglet Serveur MCP externe : affiche le volume de demandes, les taux d’erreur, les utilisateurs et les connexions, ainsi que les tendances d’utilisation quotidienne pour le trafic de serveur MCP externe.
  • Onglet Agents de codage : effectue le suivi de l’activité des agents de codage intégrés, notamment Cursor, Claude Code, Gemini CLI et Codex CLI. Cet onglet affiche des métriques telles que les jours actifs, les sessions de codage, les validations et les lignes de code ajoutées ou supprimées pour surveiller l’utilisation des outils de développement. Pour plus d’informations, consultez le tableau de bord de l’agent de codage .

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
endpoint_id STRING L’identifiant unique du service de modèles Unity AI Gateway. 43addf89-d802-3ca2-bd54-fe4d2a60d58a
endpoint_name STRING Le nom du service de modèle Unity AI Gateway. databricks-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. databricks-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. Consultez les demandes de balise pour le suivi de l’utilisation et les demandes de balise pour le suivi de l’utilisation. {"project": "chatbot", "team": "ml-platform"}
invocation_metadata STRUCT Métadonnées générées par le système concernant l’appel d’inférence. Contient source, le service ou le chemin d’accès qui a lancé l’appel. {"source": "EXTERNAL_CLIENT"}
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 Répartition détaillée des jetons, y compris cache_read_input_tokens, cache_creation_input_tokenset output_reasoning_tokens. {"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", ...}]}

É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 obtenir des exemples montrant comment définir des balises de requête avec l’API REST, openAI SDK et Anthropic SDK, consultez Tag demandes pour le suivi de l’utilisation.

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 AI Gateway ne comptabilise pas l’utilisation des jetons pour les réponses de plus de 1 MiB qui ne sont ni en streaming ni des intégrations vectorielles.

Ressources supplémentaires

  • Last updated on