Acompanhe o uso do modelo

Esta página descreve como monitorizar a utilização dos serviços Unity Gateway usando a tabela do sistema de rastreio de uso.

A tabela de rastreio de utilização capta detalhes de pedidos e respostas para serviços modelo, serviços de fornecedores modelo e serviços MCP. Para pedidos de modelo, regista métricas como utilização de tokens e latência. Para pedidos MCP, regista metadados de chamadas e serviços. Use a tabela para monitorizar os utilizadores, acompanhar custos e analisar o uso e o desempenho dos serviços.

O rastreio da utilização também regista ai_query pedidos para serviços de modelo fornecidos pela Databricks.

Os administradores de contas e espaços de trabalho podem consultar uma visão geral consolidada do uso de IA na página de IA no Governance Hub.

Requirements

Pricing

O acompanhamento de utilização é uma funcionalidade faturada do Unity Gateway. O Azure Databricks cobra pelo uso que regista na system.ai_gateway.usage tabela. Veja preços do Unity Gateway.

Consultar a tabela de utilização

O Unity Gateway regista os dados de utilização na system.ai_gateway.usage tabela do sistema. Podes ver a tabela na interface, ou consultar a tabela no Databricks SQL ou num caderno.

Note

São necessárias as funções de administrador da conta e de administrador do metastore para visualizar ou consultar a tabela system.ai_gateway.usage por predefinição. Os administradores podem gerir o acesso às tabelas do sistema para controlar permissões para utilizadores, grupos e principais de serviço.

Para visualizar a tabela na interface, clique no link da tabela de rastreamento de utilização na página do serviço modelo para abrir a tabela no Explorador de Catálogos.

Para consultar a tabela a partir do Databricks SQL ou de um caderno:

SELECT * FROM system.ai_gateway.usage;

Tip

O Código Génio (modo Agente) pode fazer isto por ti. Experimente este prompt de exemplo:

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.

Painel de utilização incorporado

Note

Alguns espaços de trabalho ainda não mostram o menu pendente Govern. Nesses espaços de trabalho, utilize, em vez disso, os botões autónomos Criar Dashboard, Ver Dashboard e Atualizar na página do Unity Gateway.

Criar dashboard de utilização incorporado

Os administradores de conta podem criar um painel de utilização integrado do Unity Gateway para monitorizar a utilização, acompanhar custos e obter informações sobre o desempenho e consumo dos serviços do modelo. Na página do Unity Gateway, clique em Governar no canto superior direito e depois clique em Criar Painel de Utilização. O armazém que executa as consultas do painel é selecionado automaticamente.

Note

A criação de painéis está restrita aos administradores da conta porque requer as permissões SELECT na tabela system.ai_gateway.usage. Os dados do painel estão sujeitos às usage políticas de retenção da tabela. Consulte Quais tabelas do sistema estão disponíveis?.

Quando uma versão mais recente do painel de utilização incorporado estiver disponível, os administradores de conta podem clicar em Atualizar na linha da versão do painel no menu suspenso Governar na página do Unity Gateway.

Pode usar as seguintes opções de configuração do painel para gerir o painel:

  • Âmbito: Selecione se quer direcionar o painel para a conta ou espaço de trabalho.
  • Permissões: Escolha se as consultas são executadas usando as permissões do proprietário do painel ou as de cada visualizador. Consulte O que são permissões de dados compartilhados?.
  • Atualizações automáticas: Quando ativa esta opção, o painel atualiza-se automaticamente sempre que uma versão mais recente fica disponível e um administrador de conta visita a página do Unity Gateway.

opções do painel de atualização do ai-gateway

Quando o dashboard é atualizado para uma versão 0.3 ou superior, é criado automaticamente um cronograma para atualizar o dashboard a cada 6 horas. Se necessário, este horário pode ser desativado no painel de Lakeview. Consulte Criar uma agenda.

Ver painel de utilização

Para ver o painel, clique em Governar no canto superior direito da página do Unity Gateway e depois clique em Painel de Uso. O painel abre num novo separador. O painel incorporado tem uma visibilidade abrangente sobre o uso dos serviços, desempenho e custo do modelo Unity Gateway. Inclui múltiplas páginas que acompanham pedidos, consumo de tokens, métricas de latência, taxas de erro, desagregação de custos, tráfego externo de servidores MCP e atividade de agentes de codificação.

Painel de utilização do AI-Gateway

O painel fornece análises entre espaços de trabalho como padrão. Todas as páginas do dashboard podem ser filtradas por intervalo de datas e ID do espaço de trabalho.

  • Separador de visão geral: Mostra métricas de utilização de alto nível, incluindo volume diário de pedidos, tendências de utilização de tokens ao longo do tempo, principais utilizadores por consumo de tokens e contagens únicas totais de utilizadores. Use este separador para obter uma rápida visão geral da atividade geral do Unity Gateway e identificar os utilizadores e modelos mais ativos.
  • Aba de desempenho: Acompanha métricas de desempenho chave, incluindo percentis de latência (P50, P90, P95, P99), tempo até o primeiro byte, taxas de erro e distribuições de código de estado HTTP. Use este separador para monitorizar a saúde dos serviços do modelo e identificar gargalos de desempenho ou problemas de fiabilidade.
  • Separador de utilização: Mostra divisões detalhadas de consumo por modelo, serviço, espaço de trabalho e solicitante. Este separador mostra padrões de utilização de tokens, distribuições de pedidos e rácios de acertos na cache.
  • Separador de Observabilidade de Custos: Mostra a divisão de custos por modelo de serviço, modelo-alvo, utilizador, etiquetas de serviço e etiquetas de pedido. Este separador inclui também o custo estimado para modelos externos. Veja Analisar o custo do Unity Gateway.
  • Separador do Servidor MCP Externo: Mostra o volume de pedidos, as taxas de erro, os utilizadores e as ligações, bem como as tendências de utilização diária para o tráfego do servidor MCP externo.
  • Separador de Agentes de Programação: Acompanha a atividade de agentes de codificação integrados, incluindo Claude Code, Codex CLI, Cursor e Gemini CLI. Este separador mostra métricas como dias ativos, sessões de programação, commits e linhas de código adicionadas ou removidas para monitorizar o uso de ferramentas para programadores. Consulte o painel de agentes de codificação para mais detalhes.

Esquema da tabela de utilização

A system.ai_gateway.usage tabela apresenta o seguinte esquema:

Nome da coluna Tipo Description Example
account_id STRING O ID da conta. 11d77e21-5e05-4196-af72-423257f74974
workspace_id STRING O ID do espaço de trabalho. 1653573648247579
request_id STRING Um identificador exclusivo para a solicitação. b4a47a30-0e18-4ae3-9a7f-29bcb07e0f00
invocation_id STRING Um identificador único para cada chamada de inferência individual. Múltiplas invocações podem partilhar o mesmo request_id, como verificações de proteção ou chamadas a agentes com múltiplos turnos. Use invocation_id para os distinguir. c0a8012e-9f3b-4d21-8a7e-1b2c3d4e5f60
schema_version INTEIRO A versão esquemática do registo de utilização. 1
service_type STRING O tipo de serviço que gerava o registo de utilização. Os valores são MODEL_SERVICE, MCP_SERVICE, e MODEL_PROVIDER_SERVICE. MODEL_SERVICE
service_id STRING O ID do Serviço Modelo, Serviço MCP ou Serviço de Fornecedor Modelo. 43addf89-d802-3ca2-bd54-fe4d2a60d58a
service_name STRING O Unity Catalog qualificava totalmente o nome do serviço. main.default.github_tools
service_tags MAP Etiquetas de recurso aplicadas ao Catálogo Unity são seguras na altura da criação ou atualização. Aplicam-se a todos os pedidos ao serviço e são úteis para categorizar o uso por equipa, centro de custos ou projeto. {"team": "engineering"}
endpoint_id STRING O ID único do serviço modelo Unity Gateway. 43addf89-d802-3ca2-bd54-fe4d2a60d58a
endpoint_name STRING O nome do serviço modelo Unity Gateway. system.ai.gpt-5-2
endpoint_tags MAP Etiquetas configuradas no serviço modelo no momento da criação ou atualização. Aplicam-se a todos os pedidos ao serviço modelo e são úteis para categorizar serviços por equipa, centro de custos ou projeto. {"team": "engineering"}
endpoint_metadata STRUCT Metadados de serviço de modelo incluindo creator, creation_time, last_updated_time, destinations, inference_table, e fallbacks. {"creator": "user.name@email.com", "creation_time": "2026-01-06T12:00:00.000Z", ...}
event_time DATA E HORA A data e hora em que o pedido foi recebido. 2026-01-20T19:48:08.000+00:00
latency_ms LONG A latência total em milissegundos. 300
time_to_first_byte_ms LONG O tempo até ao primeiro byte em milissegundos. 300
destination_type STRING O tipo de destino (por exemplo, modelo externo ou modelo de fundação). PAY_PER_TOKEN_FOUNDATION_MODEL
destination_name STRING O nome do modelo de destino ou fornecedor. system.ai.gpt-5-2
destination_id STRING O ID único do destino. 507e7456151b3cc89e05ff48161efb87
destination_model STRING O modelo específico usado para o pedido. GPT-5.2
requester STRING O ID do utilizador ou principal do serviço que fez o pedido. user.name@email.com
requester_type STRING O tipo de requerente (utilizador, principal de serviço ou grupo de utilizadores). USER
ip_address STRING O endereço IP do requerente. 1.2.3.4
url STRING O URL do pedido. https://<workspace-url>/ai-gateway/mlflow/v1/chat/completions
user_agent STRING O agente de utilizador do solicitante. OpenAI/Python 2.13.0
api_type STRING O tipo de chamada de API (por exemplo, chat, completamentos ou embeddings). mlflow/v1/chat/completions
request_tags MAP Etiquetas fornecidas pelo utilizador enviadas com pedidos individuais usando o Databricks-Ai-Gateway-Request-Tags cabeçalho HTTP. Use etiquetas de pedido para atribuir a utilização a projetos, equipas, ambientes ou utilizadores finais específicos. Consulte Etiquetar pedidos para monitorização da utilização e Etiquetagem de pedidos. {"project": "chatbot", "team": "ml-platform"}
invocation_metadata STRUCT Informação sobre a origem do pedido, o nível de serviço reportado pelo fornecedor do modelo e se o pedido utilizou uma subscrição Claude. {"source": "EXTERNAL_CLIENT", "service_tier": "priority", "relayed": false}
input_tokens LONG O número de tokens de entrada. 100
output_tokens LONG O número de tokens de saída. 100
total_tokens LONG O número total de tokens (entrada + saída). 200
token_details STRUCT Divisão detalhada da utilização de tokens e ferramentas, incluindo cache_read_input_tokens, cache_creation_input_tokens, output_reasoning_tokens, cache_creation_5m_input_tokens, cache_creation_1h_input_tokens, file_search_count, , e num_web_search_queries. {"cache_read_input_tokens": 100, ...}
response_content_type STRING O tipo de conteúdo da resposta. application/json
status_code INT O código de status HTTP da resposta. 200
routing_information STRUCT Detalhes de roteamento para tentativas de recurso . Contém um attempts array com priority, action, destination, destination_id, status_code, error_code, latency_ms, start_time e end_time para cada modelo tentado durante o pedido. {"attempts": [{"priority": "1", ...}]}
mcp_metadata STRUCT Detalhes de um pedido a um serviço MCP, incluindo a ferramenta invocada, o tipo de servidor e a operação JSON-RPC. Preenchido para MCP_SERVICE linhas. {"tool_name": "echo", "server_type": "EXTERNAL", "json_rpc_method": "tools/call"}
session_metadata STRUCT Contexto da sessão e do cliente, incluindo IDs de sessão e subagentes, nome e versão do agente de codificação, interface do cliente, esforço de raciocínio e receita de encaminhamento inteligente. Use estes campos para agrupar pedidos relacionados e analisar a utilização por agente ou sessão. {"coding_agent": "claude-code", "agent_version": "2.1.282", "reasoning_effort": "high", ...}
auth_mode STRING O tipo de credencial Databricks usado para autenticar o pedido: um token de acesso pessoal (PAT) ou um token OAuth (OAUTH). OAUTH

Esquemas de colunas aninhadas

As tabelas seguintes descrevem campos dentro de colunas aninhadas STRUCT . A disponibilidade de campo depende do serviço, modelo e cliente utilizado para o pedido.

Metadados de invocação e do token

Percurso de campo Tipo Description
invocation_metadata.source STRING A aplicação, serviço ou API que iniciou o pedido. Use este campo para atribuir o uso à sua origem. Os valores incluem AI_PLAYGROUND, EXTERNAL_CLIENT, AI_QUERY, GUARDRAIL, e MANAGED_AGENT.
invocation_metadata.service_tier STRING O nível de serviço reportado pelo fornecedor do modelo na resposta de inferência, como default ou priority. Use este campo para comparar a utilização entre os escalões de preços dos fornecedores.
invocation_metadata.relayed BOOLEAN Se a solicitação foi encaminhada para a Anthropic através da subscrição do Claude do autor da chamada.
token_details.cache_read_input_tokens LONG O número de tokens lidos da memória cache de comandos.
token_details.cache_creation_input_tokens LONG O número de tokens escritos na cache do prompt.
token_details.output_reasoning_tokens LONG O número de tokens de raciocínio na saída.
token_details.cache_creation_5m_input_tokens LONG O número de tokens de entrada escritos na cache do prompt com uma validade de 5 minutos.
token_details.cache_creation_1h_input_tokens LONG O número de tokens de entrada escritos na cache do prompt com um tempo de vida de 1 hora.
token_details.file_search_count LONG O número de chamadas à ferramenta de pesquisa de ficheiros efetuadas no âmbito do pedido.
token_details.num_web_search_queries LONG O número de consultas de pesquisa na Web faturáveis efetuadas como parte da solicitação.

Metadados do serviço MCP

Estes campos são preenchidos em mcp_metadata para MCP_SERVICE linhas.

Percurso de campo Tipo Description
mcp_metadata.tool_name STRING O nome da ferramenta invocada por um pedido MCP tools/call . Use este campo para analisar a utilização de ferramentas individuais num servidor.
mcp_metadata.server_type STRING A categoria de servidor MCP que trata o pedido, como EXTERNAL ou SYSTEM.
mcp_metadata.json_rpc_method STRING A operação JSON-RPC solicitada pelo cliente, como tools/call para invocar uma ferramenta, tools/list para descobrir ferramentas, ou initialize para iniciar uma sessão.

Metadados da sessão

Os session_metadata campos ajudam a correlacionar pedidos dentro de uma sessão e a distinguir agentes de codificação, interfaces de cliente e definições de pedidos. Cada campo é preenchido quando a informação correspondente está disponível junto do cliente ou pedido.

Percurso de campo Tipo Description
session_metadata.client_session_id STRING O ID da sessão fornecido pelo cliente. Use-o para agrupar pedidos feitos durante a mesma conversa ou sessão do agente de codificação.
session_metadata.client_subagent_id STRING O ID do subagente fornecido pelo cliente. Utiliza-o com client_session_id para distinguir solicitações de subagentes numa sessão principal.
session_metadata.coding_agent STRING O nome normalizado do agente de codificação que enviou o pedido, como claude-code ou codex.
session_metadata.agent_version STRING A versão reportada pelo agente de codificação. Utilize-o com coding_agent para comparar a utilização entre versões do agente.
session_metadata.surface STRING A interface cliente a partir da qual o agente de codificação enviou o pedido, como uma interface de linha de comandos, IDE ou aplicação de ambiente de trabalho.
session_metadata.reasoning_effort STRING O esforço de raciocínio especificado no pedido, como low, medium, ou high. Os valores disponíveis dependem do modelo e da API.
session_metadata.smart_router_name STRING O nome da receita de encaminhamento inteligente selecionada pelo cliente. Utilize-o para agrupar a utilização por receita de encaminhamento.

Pedidos de etiquetas para monitorização de utilização

As etiquetas de pedido são pares chave-valor personalizados que o chamador associa a pedidos individuais. Use etiquetas de pedido para atribuir o uso por projeto, equipa, ambiente, utilizador final ou qualquer outra dimensão relevante para a sua organização. As etiquetas de pedido são registadas na system.ai_gateway.usage tabela e podem ser usadas para filtrar, agregar e analisar dados de utilização.

Para identificar pedidos individuais, inclua o cabeçalho HTTP Databricks-Ai-Gateway-Request-Tags com um objeto JSON que associa chaves de texto a valores de texto. As etiquetas de pedido são registadas na request_tags coluna da tabela de utilização e nas tabelas de inferência.

Para exemplos que mostram como definir etiquetas de pedido com API REST, SDK OpenAI e Anthropic SDK, veja Marcagem de Pedidos.

Por exemplo, pode agregar o uso por projeto usando etiquetas de pedido:

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

  • O Unity Gateway não acompanha o uso de tokens para respostas não streaming e não embedding superiores a 1 MiB.

Recursos adicionais

  • Última atualização a