Rastrear o uso do modelo
Monitore o uso de serviços do Unity Gateway com a tabela do sistema system.ai_gateway.usage. Ele captura solicitações de serviços de modelo, serviços de provedor de modelo e serviços MCP de várias fontes, incluindo AI Query, agentes de codificação, Databricks Apps, AI Playground e outros aplicativos.
Os registros de uso incluem detalhes do solicitante e do serviço, status da resposta, uso de tokens do modelo e latência, metadados de chamada MCP e metadados de sessão do agente de codificação. Faça uma query na tabela para análises personalizadas ou use o dashboard de uso integrado para monitorar o uso, o gasto, a adoção e o desempenho.
Os administradores de account e Workspace também podem view uma visão geral consolidada do uso de AI na página de AI no Governance Hub.
Requisitos
- Um workspace do Databricks em uma região com suporte ao Unity Gateway.
- Unity Catalog habilitado para seu workspace. Consulte Ativar um workspace para o Unity Catalog.
- Ambas as funções de administrador de account e de metastore são necessárias para view ou query a tabela
system.ai_gateway.usagepor default. Os administradores podem gerenciar o acesso às tabelas do sistema para controlar as permissões de usuários, grupos e Service Principal.
Consultar a tabela de uso
O Unity Gateway Logs dados de uso na tabela do sistema system.ai_gateway.usage. Você pode ver a tabela na interface de usuário, ou consultar a tabela a partir do Databricks SQL ou de um Notebook.
Os registros geralmente estão disponíveis em até uma hora. A entrega de dados para novos Workspace pode demorar mais do que isso.
Para view a tabela na interface do usuário, clique no link da tabela de acompanhamento de uso na página do serviço de modelo para abrir a tabela no Explorador de Catálogos.
Para consultar a tabela do Databricks SQL ou de um Notebook:
SELECT * FROM system.ai_gateway.usage;
O Genie Code pode fazer isso por você. Experimente este exemplo 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.
preços
O acompanhamento de uso é um recurso faturável do Unity Gateway. O Databricks cobra pelo uso que registra na tabela system.ai_gateway.usage. Consulte preços do Unity Gateway.
Dashboard de uso integrada
O painel de uso do Unity Gateway integrada fornece uma view consolidada do uso, gastos, adoção e desempenho em modelos, serviços MCP, agentes de codificação e habilidades.
Criar dashboard
Os account admins podem criar o dashboard na página do Unity Gateway:
-
Clique em Governar > Criar dashboard de uso .
-
Escolha Uso da account para analisar o uso em workspaces, ou Uso do workspace para restringir a análise ao workspace atual.
-
Configurar permissões de dados :
- Permissão de compartilhamento de dados : os espectadores fazem execução de queries de dashboard usando suas permissões de dados.
- Permissão de dados individual : cada espectador faz a execução de queries de dashboard usando suas próprias permissões de dados.
-
Escolha se deseja habilitar Atualizações automáticas e Refresh de dados agendado .
-
Clique em Configurar e publicar .
O SQL warehouse default é selecionado automaticamente. A identidade que executa as queries do dashboard precisa de acesso às tabelas do sistema subjacentes. Consulte Conceder acesso às tabelas do sistema e Permissões de dados do dashboard.
Em Workspace sem o dropdown Govern , use os botões independentes Create Dashboard , View Dashboard e Update na página do Unity Gateway.
Explorar o painel
Clique em Govern > Usage Dashboard para abrir o dashboard em uma nova tab.
Tab | Análise |
|---|---|
Visão geral | Revise o uso, tokens, usuários ativos e sessões de agente de codificação. Compare modelos e usuários por gastos, tendências de gastos e gastos por tokens ou solicitação. |
Gasto | Analise os gastos por modelo e usuário, compare o consumo e o cache de tokens e atribua os gastos por meio de tags de serviço e solicitação. |
Agentes de programação | Compare a adoção de agentes, o uso de harness, sessões, consumo de tokens e subagentes. Investigue as sessões individuais classificadas por gasto estimado. |
MCPs | Acompanhe chamadas de ferramentas e usuários ativos, identifique serviços e ferramentas usados com frequência e compare fontes de uso. |
Habilidades | Acompanhe os downloads e carregamentos de habilidades, compare a adoção de habilidades e analise a atividade por usuário. |
Desempenho | Compare a latência do modelo e do MCP, o tempo de transmissão para o primeiro byte, tokens de saída/seg, taxas de acerto de cache, erros e chamadas com limite de taxa. |
README | Revise os recursos do painel, as alterações recentes e os links para as fontes de dados subjacentes. |
Selecione um intervalo de datas para focar a análise, ou selecione uma serviço tag key e uma ou mais entradas de serviço tag Value para reduzir o uso e os gastos a equipes ou projetos específicos. Dashboards de escopo de account também incluem um filtro Workspace ID . Os filtros de tag de serviço não se aplicam à tab Skills.
Atualizar o dashboard
Quando uma versão de dashboard mais recente estiver disponível, um administrador account pode clicar em Update na linha da versão do dashboard no dropdown Govern . Com Automatic updates habilitado, um padrão mais recente é aplicado quando um administrador account visita a página do Unity Gateway.
A atualização substitui o conteúdo do painel pelo padrão mais recente e pode sobrescrever personalizações. Salve uma cópia antes de atualizar se quiser preservar suas alterações.
refresh dados do painel
Refresh de dados agendado faz refresh nos resultados de query a cada seis horas.
Gerenciar o programar de refresh no dashboard. Veja Criar programar.
Esquema da tabela de uso
A tabela system.ai_gateway.usage tem o seguinte esquema:
Nome da coluna | Tipo | Descrição | Exemplo |
|---|---|---|---|
| String | O ID da account. |
|
| String | O ID do workspace. |
|
| String | Um identificador exclusivo para a solicitação. |
|
| String | Um identificador exclusivo para cada chamada de inferência individual. Múltiplas invocações podem compartilhar o mesmo |
|
| Integer | A versão do esquema do registro de uso. |
|
| String | O tipo de serviço que gerou o registro de uso. Os valores são |
|
| String | O ID do Model Service, do serviço MCP ou do serviço de provedor de modelos. |
|
| String | O nome totalmente qualificado do serviço no Unity Catalog. |
|
| Mapa | Tags de recurso aplicadas ao objeto protegível do Unity Catalog no momento da criação ou atualização. Eles se aplicam a todas as solicitações ao serviço e são úteis para categorizar o uso por equipe, centro de custos ou projeto. |
|
| String | O ID exclusivo do serviço de modelo do Unity Gateway. |
|
| String | O nome do serviço de modelo do Unity Gateway. |
|
| Mapa | Tags configuradas no serviço de modelo no momento da criação ou atualização. Eles se aplicam a todas as solicitações para o serviço de modelo e são úteis para categorizar serviços por equipe, centro de custo ou projeto. |
|
| struct | Metadados do serviço de modelo, incluindo |
|
| Timestamp | O carimbo de data/hora quando a solicitação foi recebida. |
|
| Long | A latência total em milissegundos. |
|
| Long | O tempo para o primeiro byte em milissegundos. |
|
| String | O tipo de destino (por exemplo, modelo externo ou modelo básico). |
|
| String | O nome do modelo ou provedor de destino. |
|
| String | A ID exclusiva do destino. |
|
| String | O modelo específico utilizado para a solicitação. |
|
| String | O ID do usuário ou da entidade de serviço que fez a solicitação. |
|
| String | O tipo de solicitante (usuário, entidade de serviço ou grupo de usuários). |
|
| String | O endereço IP do solicitante. |
|
| String | A URL da solicitação. |
|
| String | O agente do usuário do solicitante. |
|
| String | O tipo de chamada de API (por exemplo, chat, conclusões ou incorporações). |
|
| Mapa | Tags fornecidas pelo usuário enviadas com solicitações individuais usando o cabeçalho HTTP |
|
| struct | Informação sobre onde a solicitação se originou, o nível de serviço relatado pelo provedor do modelo e se a solicitação usou uma inscrição do Claude. |
|
| Long | O número de tokens de entrada. |
|
| Long | O número de tokens de saída. |
|
| Long | O número total de tokens (entrada + saída). |
|
| struct | Detalhamento do uso de tokens e ferramentas, incluindo |
|
| String | O tipo de conteúdo da resposta. |
|
| INT | O código de status HTTP da resposta. |
|
| struct | Detalhes de roteamento para tentativas de fallback. Contém um array |
|
| struct | Detalhes de uma solicitação para um serviço MCP, incluindo a ferramenta invocada, o tipo de servidor e a operação JSON-RPC. Preenchido para |
|
| struct | Contexto de sessão e cliente, incluindo IDs de sessão e subagente, nome e versão do agente de codificação, interface do cliente, esforço de raciocínio e receita de roteamento inteligente. Use estes campos para agrupar solicitações relacionadas e analisar o uso por agente ou sessão. |
|
| String | O tipo de credencial do Databricks usado para autenticar a solicitação: um access token pessoal ( |
|
Schemas de colunas aninhadas
As tabelas a seguir descrevem os campos em colunas aninhadas de STRUCT. A disponibilidade dos campos depende do serviço, modelo e cliente usados para a solicitação.
Metadados de invocação e token
Caminho do campo | Tipo | Descrição |
|---|---|---|
| String | O aplicativo, serviço ou API que iniciou a solicitação. Use este campo para atribuir o uso à sua fonte. Os valores incluem |
| String | A camada de serviço relatada pelo provedor do modelo na resposta de inferência, como |
| Booleana | Se a solicitação foi encaminhada para a Anthropic usando a inscrição do Claude do chamador. |
| Long | O número de tokens lidos do cache de prompts. |
| Long | O número de tokens gravados no cache de prompts. |
| Long | O número de tokens de raciocínio na saída. |
| Long | O número de tokens de entrada gravados no cache de prompts com um tempo de vida de 5 minutos. |
| Long | O número de tokens de entrada gravados no cache do prompt com um tempo de vida de 1 hora. |
| Long | O número de chamadas da ferramenta de pesquisa de arquivos feitas como parte da solicitação. |
| Long | O número de web search queries cobráveis feitas como parte da requisição. |
MCP service metadata
Esses campos são preenchidos em mcp_metadata para MCP_SERVICE linhas.
Caminho do campo | Tipo | Descrição |
|---|---|---|
| String | O nome da ferramenta invocada por uma solicitação MCP |
| String | The category of MCP server handling the request, such as |
| String | A operação JSON-RPC solicitada pelo cliente, como |
Metadados da sessão
Os campos session_metadata ajudam a correlacionar solicitações em uma sessão e a distinguir agentes de codificação, interfaces de cliente e configurações de solicitação. Cada campo é preenchido quando a informação correspondente está disponível no cliente ou na solicitação.
Caminho do campo | Tipo | Descrição |
|---|---|---|
| String | O ID da sessão fornecido pelo cliente. Use-o para agrupar solicitações feitas durante a mesma conversa ou sessão de agente de programação. |
| String | O ID do subagente fornecido pelo cliente. Use-o com |
| String | The normalized name of the coding agent that sent the request, such as |
| String | A versão relatada do agente de programação. Use-o com |
| String | A interface do cliente da qual o agente de codificação enviou a solicitação, como uma interface de linha de comando, IDE ou aplicativo de desktop. |
| String | O esforço de raciocínio especificado na solicitação, como |
| String | The name of the smart-routing recipe selected by the client. Use it to group usage by routing recipe. |
Solicitações de tag para acompanhamento de uso
Tags de solicitação são pares key-value personalizados que o chamador anexa a solicitações individuais. Use tags de solicitação para atribuir o uso por projeto, equipe, ambiente, usuário final ou qualquer outra dimensão relevante para sua organização. Tags de solicitação são registradas na tabela system.ai_gateway.usage e podem ser usadas para filtrar, agregar e analisar dados de uso.
Para adicionar tag a solicitações individuais, inclua o cabeçalho HTTP Databricks-Ai-Gateway-Request-Tags com um objeto JSON que mapeia key de strings para valores de strings. As tags de solicitação são registradas na coluna request_tags na tabela de uso e em tabelas de inferência.
Para obter exemplos que mostram como definir tags de solicitação com a API REST, o SDK da OpenAI e o SDK da Anthropic, consulte Marcação de tag.
Por exemplo, pode agregar o uso por projeto usando tags de solicitação:
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;
Limitações
- O Unity Gateway não rastreia o uso de tokens para respostas que não sejam de transmissão ou de embedding maiores que 1 MiB.
- O uso de AI Functions específicas de tarefa, como
ai_parse_documenteai_extract, conta para os orçamentos do Unity Gateway, mas não é registrado na tabelasystem.ai_gateway.usage. Para view o uso faturado, consulte view custos de cargas de trabalho de AI com funções.