Rastrear o uso do modelo
Esta página descreve como monitorar o uso de serviços do Unity Gateway usando a tabela do sistema de acompanhamento de uso.
A tabela de acompanhamento de uso captura automaticamente os detalhes de solicitação e resposta de um serviço de modelo, registrando métricas essenciais como uso de tokens e latência. É possível usar os dados nesta tabela para monitorar usuários, acompanhar custos e obter percepções sobre o desempenho e o consumo do serviço de modelo.
O acompanhamento de uso também captura solicitações de ai_query para serviços de modelo fornecidos pelo Databricks.
Os administradores de conta e de Workspace podem visualizar 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.
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.
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.
Ambas as funções de administrador de account e de metastore são necessárias para view ou query a tabela system.ai_gateway.usage por default. Os administradores podem gerenciar o acesso às tabelas do sistema para controlar as permissões de usuários, grupos e Service Principal.
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;
Genie Code (modo Agente) 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.
Dashboard de uso integrada
Alguns workspaces ainda não exibem o dropdown Govern . Nesses workspaces, use os botões independentes Create Dashboard , View Dashboard e Update na página do Unity Gateway.
Criar painel de uso integrado
Os administradores da account podem criar um painel de uso integrado do Unity Gateway para monitorar o uso, rastrear custos e obter percepções sobre o desempenho e o consumo do serviço de modelo. Na página do Unity Gateway, clique em Governar no canto superior direito e, em seguida, clique em Criar Painel de Uso . O warehouse que executa as queries do painel é selecionado automaticamente.
A criação de dashboards é restrita a administradores de account porque requer permissões SELECT na tabela system.ai_gateway.usage. Os dados do dashboard estão sujeitos às políticas de retenção da tabela usage. Consulte Quais tabelas do sistema estão disponíveis?.
Quando uma versão mais recente do painel de uso integrado estiver disponível, os administradores da account podem clicar em Atualizar na linha da versão do painel no menu suspenso Govern na página do Unity Gateway.
É possível usar as seguintes opções de configuração do painel para gerenciar o painel:
- Escopo: Selecione se deseja definir o escopo do painel na account ou no workspace.
- Permissões : Escolha se as consultas serão de execução com base nas permissões do proprietário do painel ou nas permissões de cada visualizador. Consulte O que são permissões de dados compartilhados?.
- Atualizações automáticas : Quando você habilita essa opção, o dashboard é atualizado automaticamente sempre que uma versão mais recente estiver disponível e um administrador da account visitar a página do Unity Gateway.
Quando o painel é atualizado para a versão 0.3 ou superior, uma programação é criada automaticamente para refresh o painel a cada 6 horas. Se necessário, este programar pode ser desativado no painel Lakeview. Consulte Criar um programar.
view painel de uso
Para ver o dashboard, clique em Govern no canto superior direito da página do Unity Gateway e, em seguida, clique em Usage Dashboard . O dashboard abre em uma nova tab. O painel integrado tem visibilidade abrangente sobre o uso, desempenho e custo do serviço de modelo do Unity Gateway. Ele inclui várias páginas de acompanhamento de requisições, consumo de tokens, métricas de latência, taxas de erro, detalhamento de custos, tráfego de servidor MCP externo e atividade de agente de codificação.
O dashboard fornece analítica entre workspaces por default. Todas as páginas do dashboard podem ser filtradas por intervalo de datas e ID do workspace.
- Tab Visão geral : mostra métricas de uso de alto nível, incluindo volume diário de solicitações, tendências de uso de tokens ao longo do tempo, principais usuários por consumo de tokens e contagem total de usuários únicos. Use esta tab para obter um Snapshot rápido da atividade geral do Unity Gateway e identificar os usuários e modelos mais ativos.
- Tab de desempenho : Acompanha as key métricas de desempenho, incluindo percentis de latência (P50, P90, P95, P99), tempo até o primeiro byte, taxas de erro e distribuições de código de status HTTP. Use esta tab para monitorar a integridade do serviço de modelo e identificar gargalos de desempenho ou problemas de confiabilidade.
- Tab Uso : Mostra detalhamentos de consumo detalhados por serviço de modelo, workspace e solicitante. Esta tab mostra padrões de uso de tokens, distribuições de solicitações e taxas de acerto de cache.
- Tab de observabilidade de custos : mostra detalhamentos de custos por serviço de modelo, modelo de destino, usuário, tags de serviço e tags de solicitação. Esta tab também inclui o custo estimado para modelos externos. Consulte Analisar custo do Unity Gateway.
- Tab do Servidor MCP Externo : mostra o volume de solicitações, taxas de erro, usuários e conexões, e tendências de uso diário para o tráfego do servidor MCP externo.
- Coding Agents tab : Tracks activity from integrated coding agents including Claude Code, Codex CLI, Cursor, and Gemini CLI. This tab shows métricas like active days, coding sessions, commits, and lines of code added or removed to monitor developer tool usage. See Coding agent dashboard for more details.
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 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 | Metadados gerados pelo sistema sobre a chamada de inferência. Contém |
|
| 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 de tokens, 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 |
|
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 exemplos que mostram como definir tags de solicitação com a API REST, OpenAI SDK e Anthropic SDK, consulte Tag de solicitações para acompanhamento de uso.
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.