Volg het modelgebruik

Deze pagina beschrijft hoe het gebruik van Unity Gateway-diensten te monitoren met behulp van de use tracking system-tabel.

De gebruiksvolgtabel bevat verzoek- en responsgegevens voor modelservices, modelproviderservices en MCP-services. Voor modelverzoeken registreert het metrieken zoals tokengebruik en latentie. Voor MCP-verzoeken registreert het de metadata van oproepen en diensten. Gebruik de tabel om gebruikers te monitoren, kosten bij te houden en het gebruik en de prestaties van diensten te analyseren.

Bij het bijhouden van gebruik worden ook aanvragen vastgelegd ai_query voor door Databricks geleverde modelservices.

Account- en werkruimtebeheerders kunnen een geconsolideerd overzicht bekijken van AI-gebruik op de AI-pagina in Governance Hub.

Requirements

Pricing

Gebruiksregistratie is een betaalde functie van Unity Gateway. Azure Databricks rekent kosten voor het gebruik dat het in de system.ai_gateway.usage tabel registreert. Zie de prijzen van Unity Gateway.

Query's uitvoeren op de gebruikstabel

Unity Gateway registreert gebruiksgegevens in de system.ai_gateway.usage systeemtabel. U kunt de tabel in de gebruikersinterface bekijken of een query uitvoeren op de tabel vanuit Databricks SQL of een notebook.

Note

Zowel account- als metastore-beheerdersrollen zijn standaard vereist om de system.ai_gateway.usage tabel te bekijken of te bevragen. Beheerders kunnen toegang tot systeemtabellen beheren om rechten voor gebruikers, groepen en diensthoofden te beheren.

Als u de tabel in de gebruikersinterface wilt weergeven, klikt u op de koppeling naar de tabel voor het bijhouden van gebruik op de pagina van de modelservice om de tabel te openen in Catalog Explorer.

Een query uitvoeren op de tabel vanuit Databricks SQL of een notebook:

SELECT * FROM system.ai_gateway.usage;

Tip

Genie Code kan dit voor je doen. Probeer dit voorbeeldprompt:

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.

Ingebouwd gebruiksdashboard

Note

Sommige werkruimtes tonen de vervolgkeuzelijst Govern nog niet. Gebruik in die werkruimtes in plaats daarvan de zelfstandige knoppen Create Dashboard, View Dashboard en Update op de Unity Gateway-pagina.

Maak een ingebouwd gebruiksdashboard aan

Accountbeheerders kunnen een ingebouwd Unity Gateway-gebruiksdashboard creëren om het gebruik te monitoren, kosten bij te houden en inzicht te krijgen in de prestaties en het verbruik van modeldiensten. Klik vanaf de Unity Gateway-pagina rechtsboven op Govern en vervolgens op Create Usage Dashboard. Het magazijn waarop de dashboardquery's worden uitgevoerd, wordt automatisch geselecteerd.

Note

Het maken van een dashboard is beperkt tot accountbeheerders omdat hiervoor machtigingen voor de SELECT tabel zijn vereistsystem.ai_gateway.usage. De gegevens van het dashboard zijn onderhevig aan het bewaarbeleid van de usage tabel. Zie Welke systeemtabellen zijn beschikbaar?.

Wanneer een nieuwere versie van het ingebouwde gebruiksdashboard beschikbaar is, kunnen accountbeheerders op Update klikken in de dashboardversie-rij in het Govern-dropdown op de Unity Gateway-pagina.

U kunt de volgende dashboardconfiguratieopties gebruiken om het dashboard te beheren:

  • Reikwijdte: Selecteer of het dashboard betrekking heeft op de account of de werkruimte.
  • Machtigingen: Kies of query's worden uitgevoerd met behulp van de machtigingen van de eigenaar van het dashboard of de machtigingen van elke viewer. Zie Wat zijn gedeelde gegevensmachtigingen?
  • Automatische updates: Wanneer je deze optie inschakelt, wordt het dashboard automatisch bijgewerkt zodra een nieuwere versie beschikbaar komt en een accountbeheerder de Unity Gateway-pagina bezoekt.

Dashboardopties voor het bijwerken van ai-gateway

Wanneer het dashboard wordt bijgewerkt naar versie 0.3 of hoger, wordt er automatisch een schema gemaakt om het dashboard elke 6 uur te vernieuwen. Indien nodig kan dit schema worden uitgeschakeld in het Lakeview-dashboard. Zie Een planning maken.

Gebruiksdashboard weergeven

Om het dashboard te bekijken, klik je rechtsboven op Govern op de Unity Gateway-pagina en klik je vervolgens op Usage Dashboard. Het dashboard opent in een nieuw tabblad. Het ingebouwde dashboard heeft volledig inzicht in het gebruik, de prestaties en de kosten van het Unity Gateway-model. Het omvat meerdere pagina's voor het bijhouden van aanvragen, tokenverbruik, latentiemetingen, foutpercentages, kostenoverzichten, verkeer van externe MCP-servers en de activiteit van codeeragents.

ai-gateway-gebruiksdashboard

Het dashboard biedt standaard analyse in meerdere werkruimten. Alle dashboardpagina's kunnen worden gefilterd op datumbereik en werkruimte-id.

  • Tabblad Overzicht: Toont metrische gegevens op hoog niveau over gebruik, waaronder dagelijks aanvraagvolume, tokengebruikstrends in de loop van de tijd, belangrijkste gebruikers per tokenverbruik en het totale aantal unieke gebruikers. Gebruik dit tabblad om snel een momentopname te krijgen van de totale Unity Gateway-activiteit en identificeer de meest actieve gebruikers en modellen.
  • Tabblad Prestaties: Houdt belangrijke prestatiegegevens bij, waaronder latentie percentielen (P50, P90, P95, P99), tijd tot eerste byte, foutpercentages en HTTP-statuscodedistributies. Gebruik dit tabblad om de servicestatus van het model te bewaken en prestatieknelpunten of betrouwbaarheidsproblemen te identificeren.
  • Tabblad Gebruik: toont gedetailleerde uitsplitsingen van verbruik per modelservice, werkruimte en aanvrager. Dit tabblad toont gebruikspatronen voor tokens, aanvraagdistributies en verhoudingen voor cachetreffers.
  • Tabblad Waarneembaarheid van kosten: toont kostenanalyses per modelservice, doelmodel, gebruiker, servicetags en aanvraagtags. Dit tabblad bevat ook geschatte kosten voor externe modellen. Zie Analyzeer de kosten van Unity Gateway.
  • Tabblad Externe MCP-server: toont aanvraagvolume, foutpercentages, gebruikers en verbindingen en dagelijkse gebruikstrends voor extern MCP-serververkeer.
  • Coding Agents-tab: Volgt activiteit van geïntegreerde codeeragenten waaronder Claude Code, Codex CLI, Cursor en Gemini CLI. Dit tabblad bevat metrische gegevens, zoals actieve dagen, coderingssessies, doorvoeringen en regels code die zijn toegevoegd of verwijderd om het gebruik van ontwikkelhulpprogramma's te bewaken. Zie het dashboard van de coderingsagent voor meer informatie.

Beschikbaarheid van records

Records zijn meestal binnen een uur beschikbaar. Datalevering voor nieuwe werkruimten kan langer duren dan dit.

Schema van gebruikstabel

De system.ai_gateway.usage tabel heeft het volgende schema:

Kolomnaam Type Beschrijving Example
account_id STRING De account-id. 11d77e21-5e05-4196-af72-423257f74974
workspace_id STRING De werkruimte-ID. 1653573648247579
request_id STRING Een unieke id voor de aanvraag. b4a47a30-0e18-4ae3-9a7f-29bcb07e0f00
invocation_id STRING Een unieke id voor elke afzonderlijke deductieoproep. Meerdere aanroepen kunnen hetzelfde request_id delen, zoals guardrailcontroles of agentoproepen met meerdere beurten. Gebruik invocation_id dit om ze te onderscheiden. c0a8012e-9f3b-4d21-8a7e-1b2c3d4e5f60
schema_version GEHEEL GETAL De schemaversie van het gebruikslog. 1
service_type STRING Het type dienst dat het gebruiksrecord heeft gegenereerd. Waarden zijn MODEL_SERVICE, MCP_SERVICE, en MODEL_PROVIDER_SERVICE. MODEL_SERVICE
service_id STRING Het ID van de Model Service, MCP Service of Model Provider Service. 43addf89-d802-3ca2-bd54-fe4d2a60d58a
service_name STRING De volledig gekwalificeerde naam van de service in Unity Catalog. main.default.github_tools
service_tags MAP Resourcetags toegepast op de Unity-catalogus kunnen worden gesecureerd bij aanmaak of update. Ze zijn van toepassing op alle verzoeken aan de dienst en zijn nuttig om gebruik te categoriseren per team, kostencentrum of project. {"team": "engineering"}
endpoint_id STRING De unieke ID van de Unity Gateway-modelservice. 43addf89-d802-3ca2-bd54-fe4d2a60d58a
endpoint_name STRING De naam van de modelservice van Unity Gateway. system.ai.gpt-5-2
endpoint_tags MAP Tags die bij het maken of bijwerken op de modelservice zijn ingesteld. Ze zijn van toepassing op alle aanvragen voor de modelservice en zijn handig voor het categoriseren van services per team, kostenplaats of project. {"team": "engineering"}
endpoint_metadata STRUCT Metagegevens van de modelservice, inclusief creator, creation_time, last_updated_time, destinations, inference_table en fallbacks. {"creator": "user.name@email.com", "creation_time": "2026-01-06T12:00:00.000Z", ...}
event_time TIMESTAMP De tijdstempel waarop de aanvraag is ontvangen. 2026-01-20T19:48:08.000+00:00
latency_ms LONG De totale latentie in milliseconden. 300
time_to_first_byte_ms LONG De tijd tot eerste byte in milliseconden. 300
destination_type STRING Het type bestemming (bijvoorbeeld extern model of basismodel). PAY_PER_TOKEN_FOUNDATION_MODEL
destination_name STRING De naam van het doelmodel of de doelprovider. system.ai.gpt-5-2
destination_id STRING De unieke ID van de bestemming. 507e7456151b3cc89e05ff48161efb87
destination_model STRING Het specifieke model dat wordt gebruikt voor de aanvraag. GPT-5.2
requester STRING De id van de gebruiker of service-principal die de aanvraag heeft ingediend. user.name@email.com
requester_type STRING Het type aanvrager (gebruiker, service-principal of gebruikersgroep). USER
ip_address STRING Het IP-adres van de aanvrager. 1.2.3.4
url STRING De URL van de aanvraag. https://<workspace-url>/ai-gateway/mlflow/v1/chat/completions
user_agent STRING De gebruikersagent van de aanvrager. OpenAI/Python 2.13.0
api_type STRING Het type API-aanroep (bijvoorbeeld chatten, voltooiingen of insluiten). mlflow/v1/chat/completions
request_tags MAP Door de gebruiker verstrekte tags die worden verzonden met afzonderlijke aanvragen met behulp van de Databricks-Ai-Gateway-Request-Tags HTTP-header. Gebruik aanvraagtags om gebruik toe te passen aan specifieke projecten, teams, omgevingen of eindgebruikers. Zie Tagverzoeken voor gebruikstracking en Request tagging. {"project": "chatbot", "team": "ml-platform"}
invocation_metadata STRUCT Informatie over waar het verzoek vandaan kwam, de servicelaag die door de modelaanbieder is gerapporteerd, en of het verzoek een Claude-abonnement gebruikte. {"source": "EXTERNAL_CLIENT", "service_tier": "priority", "relayed": false}
input_tokens LONG Het aantal invoertokens. 100
output_tokens LONG Het aantal uitvoertokens. 100
total_tokens LONG Het totale aantal tokens (invoer en uitvoer). 200
token_details STRUCT Gedetailleerde uitleg van token- en toolgebruik, inclusief cache_read_input_tokens, cache_creation_input_tokens, output_reasoning_tokens, , cache_creation_1h_input_tokenscache_creation_5m_input_tokens, , file_search_count, en num_web_search_queries. {"cache_read_input_tokens": 100, ...}
response_content_type STRING Het inhoudstype van het antwoord. application/json
status_code INT De HTTP-statuscode van het antwoord. 200
routing_information STRUCT Routeringsdetails voor terugvalpogingen . Bevat een attempts matrix met priority, action, destination, destination_id, , status_code, error_code, latency_msen start_timeend_time voor elk model dat tijdens de aanvraag is geprobeerd. {"attempts": [{"priority": "1", ...}]}
mcp_metadata STRUCT Details van een verzoek aan een MCP-service, inclusief het aangeroepen tool, het servertype en de JSON-RPC operatie. Ingevuld voor MCP_SERVICE rijen. {"tool_name": "echo", "server_type": "EXTERNAL", "json_rpc_method": "tools/call"}
session_metadata STRUCT Sessie- en clientcontext, inclusief sessie- en subagent-ID's, naam en versie van de codeeragent, clientinterface, redeneerwerk en slim-routeringsrecept. Gebruik deze velden om gerelateerde verzoeken te groeperen en het gebruik per agent of sessie te analyseren. {"coding_agent": "claude-code", "agent_version": "2.1.282", "reasoning_effort": "high", ...}
auth_mode STRING Het type Databricks-credential dat wordt gebruikt om het verzoek te authenticeren: een persoonlijk toegangstoken (PAT) of een OAuth-token (OAUTH). OAUTH

Geneste kolomschema's

De volgende tabellen beschrijven velden binnen geneste STRUCT kolommen. De beschikbaarheid van het veld hangt af van de dienst, het model en de client die voor het verzoek worden gebruikt.

Aanroepen en tokenmetadata

Veldpad Type Beschrijving
invocation_metadata.source STRING De applicatie, service of API die het verzoek heeft gestart. Gebruik dit veld om het gebruik toe te schrijven aan de bron. Waarden zijn onder meer GUARDRAIL, MANAGED_AGENT, AI_QUERY, EXTERNAL_CLIENT en AI_PLAYGROUND.
invocation_metadata.service_tier STRING De servicelaag die door de modelaanbieder wordt gerapporteerd in de inferentierespons, zoals default of priority. Gebruik dit veld om het gebruik tussen de prijsklassen van aanbieders te vergelijken.
invocation_metadata.relayed BOOLEAN Of het verzoek via het Claude-abonnement van de beller aan Anthropic is doorgegeven.
token_details.cache_read_input_tokens LONG Het aantal tokens dat uit de promptcache wordt gelezen.
token_details.cache_creation_input_tokens LONG Het aantal tokens dat naar de promptcache wordt geschreven.
token_details.output_reasoning_tokens LONG Het aantal redeneringstokens in de output.
token_details.cache_creation_5m_input_tokens LONG Het aantal invoertokens dat naar de promptcache wordt geschreven met een levensduur van 5 minuten.
token_details.cache_creation_1h_input_tokens LONG Het aantal invoertokens dat naar de promptcache wordt geschreven met een levensduur van 1 uur.
token_details.file_search_count LONG Het aantal aanroepen van de bestandszoektool dat als onderdeel van het verzoek wordt uitgevoerd.
token_details.num_web_search_queries LONG Het aantal factureerbare webzoekopdrachten dat als onderdeel van het verzoek wordt gedaan.

MCP-servicemetadata

Deze velden worden ingevuld in mcp_metadata voor MCP_SERVICE rijen.

Veldpad Type Beschrijving
mcp_metadata.tool_name STRING De naam van het hulpmiddel dat door een MCP-verzoek tools/call wordt aangeroepen. Gebruik dit veld om het gebruik van individuele tools op een server te analyseren.
mcp_metadata.server_type STRING De categorie van MCP-server die het verzoek afhandelt, zoals EXTERNAL of SYSTEM.
mcp_metadata.json_rpc_method STRING De JSON-RPC bewerking die door de client wordt gevraagd, zoals tools/call het aanroepen van een tool, tools/list het ontdekken van tools of initialize het starten van een sessie.

Sessiemetadata

De velden session_metadata helpen verzoeken binnen een sessie te correleren en onderscheiden codeeragenten, clientinterfaces en verzoekinstellingen. Elk veld wordt ingevuld wanneer de bijbehorende informatie beschikbaar is van de client of het verzoek.

Veldpad Type Beschrijving
session_metadata.client_session_id STRING De sessie-ID die door de client wordt verstrekt. Gebruik het om verzoeken te groeperen die tijdens hetzelfde gesprek of dezelfde codeer-agent-sessie worden gedaan.
session_metadata.client_subagent_id STRING De subagent-ID die door de klant is verstrekt. Gebruik het met client_session_id om verzoeken van subagenten binnen een oudersessie te onderscheiden.
session_metadata.coding_agent STRING De genormaliseerde naam van de codeeragent die het verzoek verstuurde, zoals claude-code of codex.
session_metadata.agent_version STRING De gerapporteerde versie van de codeeragent. Gebruik het met coding_agent om het gebruik tussen agentreleases te vergelijken.
session_metadata.surface STRING De clientinterface van waaruit de codeeragent het verzoek verstuurde, zoals een commandoregelinterface, IDE of desktopapplicatie.
session_metadata.reasoning_effort STRING De redeneerinspanning die in het verzoek is gespecificeerd, zoals low, medium, , of high. Beschikbare waarden hangen af van het model en de API.
session_metadata.smart_router_name STRING De naam van de slimme-routeringsconfiguratie die de klant heeft geselecteerd. Gebruik dit om gebruik per routeringsrecept te groeperen.

Tagaanvragen voor het bijhouden van gebruik

Aanvraagtags zijn aangepaste sleutel-waardeparen die de aanroeper koppelt aan afzonderlijke aanvragen. Gebruik aanvraagtags om gebruik toe te passen op project, team, omgeving, eindgebruiker of een andere dimensie die relevant is voor uw organisatie. Aanvraagtags worden vastgelegd in de system.ai_gateway.usage tabel en kunnen worden gebruikt voor het filteren, aggregeren en analyseren van gebruiksgegevens.

Als u afzonderlijke verzoeken wilt taggen, neemt u de Databricks-Ai-Gateway-Request-Tags HTTP-header op in een JSON-object dat tekenreekssleutels toewijst aan tekenreekswaarden. Aanvraagtags worden geregistreerd in de kolom request_tags in de gebruikstabel en in inferentietabellen.

Voor voorbeelden die laten zien hoe je request-tags kunt instellen met REST API, OpenAI SDK en Anthropic SDK, zie Request tagging.

U kunt bijvoorbeeld het gebruik per project aggregeren met behulp van aanvraagtags:

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 houdt geen tokengebruik bij voor niet-streamende antwoorden zonder embeddings die groter zijn dan 1 MiB.

Aanvullende informatiebronnen

  • Laatst bijgewerkt om