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 detalhes de solicitações e respostas para serviços de modelo, serviços de provedor de modelos e serviços MCP. Para solicitações de modelo, grava métricas como uso de tokens e latência. Para solicitações MCP, registra metadados de chamadas e serviços. Use a tabela para monitorar usuários, acompanhar custos e analisar o uso e o desempenho do serviço.
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 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 origem. 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.