Nachverfolgen der Modellnutzung

Diese Seite beschreibt, wie man die Nutzung von Unity-Gateway-Diensten anhand der Nutzungsverfolgungssystem-Tabelle überwacht.

Die Nutzungsverfolgungstabelle erfasst Anfrage- und Antwortdetails für Modelldienste, Modellanbieterdienste und MCP-Dienste. Für Modellanfragen zeichnet es Kennzahlen wie Tokennutzung und Latenz auf. Für MCP-Anfragen werden Anruf- und Service-Metadaten erfasst. Nutzen Sie die Tabelle, um Nutzer zu überwachen, Kosten zu verfolgen sowie die Nutzung und Leistung der Dienste zu analysieren.

Die Verwendungsnachverfolgung ai_query erfasst auch Anforderungen an von Databricks bereitgestellte Modelldienste.

Konto- und Arbeitsbereichsadministratoren können eine konsolidierte Übersicht über die KI-Nutzung auf der KI-Seite im Governance Hub anzeigen.

Requirements

Pricing

Die Nutzungsverfolgung ist eine abgerechnete Funktion des Unity-Gateways. Azure Databricks erhebt Gebühren für die Nutzung, die es in der Tabelle system.ai_gateway.usage erfasst. Siehe Unity Gateway Preise.

Nutzungstabelle abfragen

Unity Gateway protokolliert Nutzungsdaten in der system.ai_gateway.usage Systemtabelle. Sie können die Tabelle auf der Benutzeroberfläche anzeigen oder die Tabelle aus Databricks SQL oder einem Notizbuch abfragen.

Hinweis

Sowohl die Konto- als auch die Metastore-Administratorrollen müssen standardmäßig die system.ai_gateway.usage Tabelle anzeigen oder abfragen. Administratoren können den Zugriff auf Systemtabellen verwalten , um Berechtigungen für Benutzer, Gruppen und Service-Principals zu steuern.

Um die Tabelle auf der Benutzeroberfläche anzuzeigen, klicken Sie auf der Modelldienstseite auf den Link "Verwendungsnachverfolgungstabelle", um die Tabelle im Katalog-Explorer zu öffnen.

So fragen Sie die Tabelle aus Databricks SQL oder einem Notizbuch ab:

SELECT * FROM system.ai_gateway.usage;

Tip

Genie Code (Agent-Modus) kann dies für Sie tun. Probieren Sie diese Beispielaufforderung aus:

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.

Integriertes Verwendungsdashboard

Hinweis

Einige Arbeitsbereiche zeigen das Dropdown-Menü Verwalten noch nicht an. In diesen Arbeitsbereichen verwenden Sie stattdessen die eigenständigen Schaltflächen Create Dashboard, View Dashboard und Update auf der Unity-Gateway-Seite.

Eingebautes Nutzungsdashboard erstellen

Kontoadministratoren können ein integriertes Unity Gateway-Nutzungs-Dashboard erstellen, um die Nutzung zu überwachen, Kosten zu verfolgen und Einblicke in die Leistung und den Verbrauch von Modelldiensten zu gewinnen. Auf der Unity-Gateway-Seite klicken Sie oben rechts auf Verwalten und dann auf Nutzungs-Dashboard erstellen. Das Lager, in dem die Dashboardabfragen ausgeführt werden, wird automatisch ausgewählt.

Hinweis

Die Dashboarderstellung ist auf Kontoadministratoren beschränkt, da sie Berechtigungen für die SELECT Tabelle erfordertsystem.ai_gateway.usage. Die Daten des Dashboards unterliegen den Aufbewahrungsrichtlinien der usage Tabelle. Siehe Welche Systemtabellen sind verfügbar?.

Wenn eine neuere Version des integrierten Nutzungs-Dashboards verfügbar ist, können Kontoadministratoren in der Dashboard-Versionszeile im Verwalten-Dropdown auf der Unity-Gateway-Seite auf Aktualisieren klicken.

Sie können die folgenden Dashboardkonfigurationsoptionen verwenden, um das Dashboard zu verwalten:

  • Bereich: Wählen Sie aus, ob das Dashboard auf das Konto oder den Arbeitsbereich ausgerichtet werden soll.
  • Berechtigungen: Wählen Sie aus, ob Abfragen mit den Berechtigungen des Dashboardbesitzers oder den Berechtigungen jedes Viewers ausgeführt werden. Siehe Freigegebene Datenberechtigungen.
  • Automatische Updates: Wenn Sie diese Option aktivieren, aktualisiert sich das Dashboard automatisch, sobald eine neuere Version verfügbar wird und ein Kontoadministrator die Unity-Gateway-Seite besucht.

Dashboardoptionen für ai-gateway-Updates

Wenn das Dashboard auf version 0.3 oder höher aktualisiert wird, wird automatisch ein Zeitplan erstellt, um das Dashboard alle 6 Stunden zu aktualisieren. Bei Bedarf kann dieser Zeitplan im Lakeview-Dashboard deaktiviert werden. Siehe Erstellen eines Zeitplans.

Anzeigen des Verwendungsdashboards

Um das Dashboard anzuzeigen, klicken Sie oben rechts auf der Unity-Gateway-Seite auf Verwalten und dann auf Nutzungs-Dashboard. Das Dashboard öffnet sich in einem neuen Tab. Das integrierte Dashboard bietet umfassende Transparenz in die Servicenutzung, Leistung und Kosten des Unity Gateway-Modells. Sie umfasst mehrere Seiten zur Nachverfolgung von Anfragen, Tokenverbrauch, Latenzmetriken, Fehlerraten, Kostenaufschlüsselungen, dem Datenverkehr externer MCP-Server und den Aktivitäten von Coding-Agenten.

Ai-Gateway-Nutzungsdashboard

Das Dashboard bietet standardmäßig Arbeitsbereichsübergreifende Analysen. Alle Dashboardseiten können nach Datumsbereich und Arbeitsbereichs-ID gefiltert werden.

  • Registerkarte "Übersicht": Zeigt allgemeine Nutzungsmetriken an, einschließlich täglicher Anforderungsvolumen, Tokenverwendungstrends im Laufe der Zeit, top-Benutzer nach Tokenverbrauch und Gesamtzahl eindeutiger Benutzer. Nutzen Sie diesen Tab, um einen schnellen Überblick über die gesamte Unity Gateway-Aktivität zu erhalten und die aktivsten Nutzer und Modelle zu identifizieren.
  • Registerkarte "Leistung": Verfolgt wichtige Leistungsmetriken, einschließlich Latenz-Quantils (P50, P90, P95, P99), Zeit für das erste Byte, Fehlerraten und HTTP-Statuscodeverteilungen. Verwenden Sie diese Registerkarte, um den Modelldienststatus zu überwachen und Leistungsengpässe oder Zuverlässigkeitsprobleme zu identifizieren.
  • Registerkarte "Verwendung": Zeigt detaillierte Verbrauchsaufschlüsselungen nach Modelldienst, Arbeitsbereich und Anforderer an. Auf dieser Registerkarte werden Tokenverwendungsmuster, Anforderungsverteilungen und Cachetrefferverhältnisse angezeigt.
  • Registerkarte „Kostenübersicht“: Zeigt Kostenaufschlüsselungen nach Modellservice, Zielmodell, Benutzer, Service-Tags und Anfrage-Tags an. Diese Registerkarte enthält auch geschätzte Kosten für externe Modelle. Siehe Unity Gateway-Kosten analysieren.
  • Registerkarte "Externer MCP-Server": Zeigt Anforderungsvolumen, Fehlerraten, Benutzer und Verbindungen sowie tägliche Nutzungstrends für externen MCP-Serverdatenverkehr an.
  • Registerkarte „Coding Agents“: Zeigt die Aktivitäten integrierter Codieragenten an, darunter Claude Code, Codex CLI, Cursor und Gemini CLI. Diese Registerkarte zeigt Metriken wie aktive Tage, Codierungssitzungen, Commits und Codezeilen an, die hinzugefügt oder entfernt wurden, um die Verwendung des Entwicklertools zu überwachen. Weitere Details finden Sie im Codierungs-Agent-Dashboard .

Verwendungstabellenschema

Die system.ai_gateway.usage Tabelle weist das folgende Schema auf:

Spaltenname Typ Beschreibung Example
account_id STRING Die Konto-ID. 11d77e21-5e05-4196-af72-423257f74974
workspace_id STRING Die Arbeitsbereichs-ID. 1653573648247579
request_id STRING Ein eindeutiger Bezeichner für die Anforderung. b4a47a30-0e18-4ae3-9a7f-29bcb07e0f00
invocation_id STRING Ein eindeutiger Bezeichner für jeden einzelnen Ableitungsaufruf. Mehrere Aufrufe können dasselbe request_id teilen, z. B. Guardrail-Prüfungen oder Multi-Turn-Agent-Aufrufe. Verwenden Sie invocation_id, um sie zu unterscheiden. c0a8012e-9f3b-4d21-8a7e-1b2c3d4e5f60
schema_version INTEGER Die Schemaversion des Verwendungsdatensatzes. 1
service_type STRING Die Art des Dienstes, der den Nutzungsdatensatz generiert hat. Die Werte sind MODEL_SERVICE, MCP_SERVICE, und MODEL_PROVIDER_SERVICE. MODEL_SERVICE
service_id STRING Die ID des Modelldienstes, MCP-Dienstes oder Modellanbieterdienstes. 43addf89-d802-3ca2-bd54-fe4d2a60d58a
service_name STRING Der vollständig qualifizierte Name des Dienstes im Unity Catalog. main.default.github_tools
service_tags MAP Ressourcen-Tags, die auf den Unity Catalog angewendet werden, sind bei der Erstellung oder Aktualisierung sicher. Sie gelten für alle Anfragen an den Dienst und sind nützlich, um die Nutzung nach Team, Kostenstelle oder Projekt zu kategorisieren. {"team": "engineering"}
endpoint_id STRING Die eindeutige ID des Unity-Gateway-Modelldienstes. 43addf89-d802-3ca2-bd54-fe4d2a60d58a
endpoint_name STRING Der Name des Unity Gateway Modelldienstes. system.ai.gpt-5-2
endpoint_tags MAP Tags, die beim Erstellen oder Aktualisieren auf dem Modelldienst konfiguriert sind. Sie gelten für alle Anforderungen an den Modelldienst und eignen sich für die Kategorisierung von Diensten nach Team, Kostenstelle oder Projekt. {"team": "engineering"}
endpoint_metadata STRUCT Modelldienstmetadaten, einschließlich creator, creation_time, last_updated_time, destinations, inference_tableund fallbacks. {"creator": "user.name@email.com", "creation_time": "2026-01-06T12:00:00.000Z", ...}
event_time TIMESTAMP Der Zeitstempel, zu dem die Anforderung empfangen wurde. 2026-01-20T19:48:08.000+00:00
latency_ms LONG Die Gesamtlatenz in Millisekunden. 300
time_to_first_byte_ms LONG Die Zeit für das erste Byte in Millisekunden. 300
destination_type STRING Der Zieltyp (z. B. externes Modell oder Foundation-Modell). PAY_PER_TOKEN_FOUNDATION_MODEL
destination_name STRING Der Name des Zielmodells oder Anbieters. system.ai.gpt-5-2
destination_id STRING Die eindeutige ID des Ziels. 507e7456151b3cc89e05ff48161efb87
destination_model STRING Das für die Anforderung verwendete spezifische Modell. GPT-5.2
requester STRING Die ID des Benutzers oder Dienstprinzipals, der die Anforderung gestellt hat. user.name@email.com
requester_type STRING Der Typ des Anforderers (Benutzer, Dienstprinzipal oder Benutzergruppe). USER
ip_address STRING Die IP-Adresse des Anforderers. 1.2.3.4
url STRING Die URL der Anforderung. https://<workspace-url>/ai-gateway/mlflow/v1/chat/completions
user_agent STRING Der Benutzer-Agent des Anforderers. OpenAI/Python 2.13.0
api_type STRING Der Typ des API-Aufrufs (z. B. Chat, Fertigstellungen oder Einbettungen). mlflow/v1/chat/completions
request_tags MAP Vom Benutzer bereitgestellte Tags, die mit einzelnen Anfragen über den HTTP-Header Databricks-Ai-Gateway-Request-Tags gesendet werden. Verwenden Sie Anforderungstags, um die Verwendung bestimmten Projekten, Teams, Umgebungen oder Endbenutzern zuzuordnen. Siehe Tag-Anfragen für Nutzungsverfolgung und Anfrage-Tagging. {"project": "chatbot", "team": "ml-platform"}
invocation_metadata STRUCT Informationen darüber, woher die Anfrage stammt, welche Dienststufe vom Modellanbieter gemeldet wird und ob die Anfrage ein Claude-Abonnement verwendet. {"source": "EXTERNAL_CLIENT", "service_tier": "priority", "relayed": false}
input_tokens LONG Die Anzahl der Eingabetoken. 100
output_tokens LONG Die Anzahl der Ausgabetoken. 100
total_tokens LONG Die Gesamtzahl der Token (Eingabe + Ausgabe). 200
token_details STRUCT Detaillierte Aufschlüsselung der Token- und Werkzeugnutzung, einschließlich cache_read_input_tokens, cache_creation_5m_input_tokens, output_reasoning_tokens, cache_creation_1h_input_tokens, file_search_count, num_web_search_queries und cache_creation_input_tokens. {"cache_read_input_tokens": 100, ...}
response_content_type STRING Der Inhaltstyp der Antwort. application/json
status_code INT Der HTTP-Statuscode der Antwort. 200
routing_information STRUCT Routeninformationen für Fallback-Versuche. Enthält ein attempts Array mit priority, action, destinationdestination_idstatus_codeerror_code, latency_msund start_timeend_time für jedes Modell, das während der Anforderung versucht wurde. {"attempts": [{"priority": "1", ...}]}
mcp_metadata STRUCT Details einer Anfrage an einen MCP-Service, einschließlich des aufgerufenen Tools, des Servertyps und der JSON-RPC Operation. Gefüllt für MCP_SERVICE Zeilen. {"tool_name": "echo", "server_type": "EXTERNAL", "json_rpc_method": "tools/call"}
session_metadata STRUCT Sitzungs- und Clientkontext, einschließlich Session- und Subagenten-IDs, Name und Version des Codieragenten, Client-Interface, Argumentationsaufwand und Smart-Routing-Rezept. Verwenden Sie diese Felder, um verwandte Anfragen zu gruppieren und die Nutzung nach Agent oder Sitzung zu analysieren. {"coding_agent": "claude-code", "agent_version": "2.1.282", "reasoning_effort": "high", ...}
auth_mode STRING Der Databricks-Zugangstyp, der zur Authentifizierung der Anfrage verwendet wird: ein persönliches Zugriffstoken (PAT) oder ein OAuth-Token (OAUTH). OAUTH

Verschachtelte Spaltenschemata

Die folgenden Tabellen beschreiben Felder innerhalb verschachtelter Spalten STRUCT . Die Feldverfügbarkeit hängt vom für die Anfrage verwendeten Dienst, Modell und Client ab.

Aufruf und Token-Metadaten

Feldpfad Typ Beschreibung
invocation_metadata.source STRING Die Anwendung, der Dienst oder die API, die die Anfrage initiiert hat. Verwenden Sie dieses Feld, um die Nutzung seiner Quelle zuzuordnen. Werte umfassen AI_PLAYGROUND, EXTERNAL_CLIENT, , AI_QUERY, GUARDRAILund MANAGED_AGENT.
invocation_metadata.service_tier STRING Die vom Modellanbieter in der Inferenzantwort gemeldete Service-Schicht, wie default oder priority. Nutzen Sie dieses Feld, um die Nutzung zwischen den Preisstufen der Anbieter zu vergleichen.
invocation_metadata.relayed BOOLEAN Ob die Anfrage über das Claude-Abonnement des Anrufers an Anthropic weitergeleitet wurde.
token_details.cache_read_input_tokens LONG Die Anzahl der Token, die aus dem Prompt-Cache gelesen werden.
token_details.cache_creation_input_tokens LONG Die Anzahl der Token, die in den Prompt-Cache geschrieben werden.
token_details.output_reasoning_tokens LONG Die Anzahl der Argumentationstoken im Output.
token_details.cache_creation_5m_input_tokens LONG Die Anzahl der in den Prompt-Cache geschriebenen Eingabetoken mit einer Lebensdauer von 5 Minuten.
token_details.cache_creation_1h_input_tokens LONG Die Anzahl der in den Prompt-Cache geschriebenen Eingabetoken mit einer Lebensdauer von 1 Stunde.
token_details.file_search_count LONG Die Anzahl der Dateisuch-Toolaufrufe, die im Rahmen der Anfrage durchgeführt werden.
token_details.num_web_search_queries LONG Die Anzahl der abrechenbaren Websuchanfragen, die im Rahmen der Anfrage ausgeführt wurden.

MCP-Servicemetadaten

Diese Felder werden in mcp_metadata für MCP_SERVICE Zeilen ausgefüllt.

Feldpfad Typ Beschreibung
mcp_metadata.tool_name STRING Der Name des von einer MCP-Anfrage tools/call aufgerufenen Werkzeugs. Nutzen Sie dieses Feld, um die Nutzung einzelner Tools auf einem Server zu analysieren.
mcp_metadata.server_type STRING Die Kategorie des MCP-Servers, der die Anfrage behandelt, wie EXTERNAL oder SYSTEM.
mcp_metadata.json_rpc_method STRING Die JSON-RPC Operation, die vom Client angefordert wird, wie tools/call zum Beispiel ein Werkzeug aufzurufen, tools/list Werkzeuge zu entdecken oder initialize eine Sitzung zu starten.

Sitzungsmetadaten

Die Felder session_metadata helfen dabei, Anfragen innerhalb einer Sitzung zu korrelieren und unterscheiden Codierungsagenten, Client-Oberflächen und Anfrageeinstellungen. Jedes Feld wird ausgefüllt, wenn die entsprechenden Informationen vom Client oder der Anfrage verfügbar sind.

Feldpfad Typ Beschreibung
session_metadata.client_session_id STRING Die vom Client bereitgestellte Session-ID. Nutze es, um Anfragen zu gruppieren, die während derselben Gesprächs- oder Coding-Agent-Sitzung gestellt werden.
session_metadata.client_subagent_id STRING Die vom Client bereitgestellte Subagent-ID. Nutzen Sie es mit client_session_id, um Anfragen von Subagenten innerhalb einer übergeordneten Sitzung zu unterscheiden.
session_metadata.coding_agent STRING Der normalisierte Name des Coding-Agenten, der die Anfrage gesendet hat, wie claude-code oder codex.
session_metadata.agent_version STRING Die vom Codier-Agenten gemeldete Version. Verwende es mit coding_agent, um die Nutzung über Agent-Releases hinweg zu vergleichen.
session_metadata.surface STRING Die Client-Schnittstelle, von der der Coding-Agent die Anfrage gesendet hat, wie zum Beispiel eine Kommandozeilen-Schnittstelle, IDE oder Desktop-Anwendung.
session_metadata.reasoning_effort STRING Der in der Anfrage angegebene Argumentationsaufwand, wie low, medium, oder high. Verfügbare Werte hängen vom Modell und der API ab.
session_metadata.smart_router_name STRING Der Name des vom Client ausgewählten Smart-Routing-Rezepts. Nutze es, um die Nutzung nach Routing-Rezept zu gruppieren.

Tag-Anforderungen für die Verwendungsnachverfolgung

Anforderungstags sind benutzerdefinierte Schlüssel-Wert-Paare, die der Aufrufer an einzelne Anforderungen anfügt. Verwenden Sie Anforderungstags, um die Verwendung nach Projekt, Team, Umgebung, Endbenutzer oder einer anderen Dimension zu attributieren, die für Ihre Organisation relevant ist. Anforderungstags werden in der system.ai_gateway.usage Tabelle protokolliert und können verwendet werden, um Nutzungsdaten zu filtern, zu aggregieren und zu analysieren.

Um einzelne Anfragen zu kennzeichnen, fügen Sie den Databricks-Ai-Gateway-Request-Tags HTTP-Header mit einem JSON-Objekt hinzu, das Zeichenfolgenschlüssel Zeichenfolgenwerten zuordnet. Anfrage-Tags werden in der request_tags Spalte der Nutzungstabelle und in Inferenztabellen protokolliert.

Beispiele, die zeigen, wie man Anfrage-Tags mit der REST API, dem OpenAI SDK und dem Anthropic SDK einsetzt, siehe Anfrage-Tagging.

Beispielsweise können Sie die Nutzung nach Projekt mithilfe von Anforderungstags aggregieren:

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;

Einschränkungen

  • Unity Gateway verfolgt die Tokennutzung nicht für nicht gestreamte Antworten ohne Einbettungen, die größer als 1 MiB sind.

Weitere Ressourcen

  • Zuletzt aktualisiert um