Pular para o conteúdo principal
Última atualização em

Model usage for Unity AI Gateway services

info

Beta

Este recurso está em Beta. Administradores de conta podem controlar o acesso a este recurso na página Prévias do console da conta. Consulte Gerenciar prévias do Databricks.

Esta página descreve como monitorar o uso dos serviços do Unity AI Gateway usando a tabela do sistema de acompanhamento de uso.

The usage tracking table automatically captures request and response details for a model service, logging essential metrics like token usage and latency. You can use the data in this table to monitor users, track costs, and gain insights into model service performance and consumption.

O acompanhamento de uso também captura solicitações de ai_query para serviços de modelo fornecidos pelo Databricks.

Requisitos​

Query the usage table​

Unity AI Gateway logs usage data to the system.ai_gateway.usage system table. You can view the table in the UI, or query the table from Databricks SQL or a notebook.

nota

Only account admins have permission to view or query the system.ai_gateway.usage table.

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.

To query the table from Databricks SQL or a notebook:

SQL
SELECT * FROM system.ai_gateway.usage;
prompt

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​

Criar painel de uso integrado​

Administradores de account podem criar uma dashboard de uso integrada do Unity AI Gateway clicando em Criar Painel na página do AI Gateway para monitorar o uso, rastrear custos e obter percepções sobre o desempenho e o consumo do serviço de modelo. Administradores de account também podem atualizar o warehouse usado para a execução de queries do painel, o que se aplica a todas as queries subsequentes.

Botão Criar painel

nota

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 dashboard de uso integrada estiver disponível, os administradores de account podem clicar em Atualizar no menu de ações do dashboard na página do AI Gateway.

Caixa de diálogo de atualização do painel de controle do AI 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 esta opção, o dashboard é atualizado automaticamente sempre que uma versão mais recente fica disponível e um administrador de account visita a página do Gateway de AI.

Opções de atualização do dashboard do Gateway de AI

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 view o painel, clique em View Dashboard na página do AI Gateway. O painel integrado oferece visibilidade abrangente sobre o uso, desempenho e custo do serviço de modelo do Unity AI Gateway. Inclui várias páginas de acompanhamento de solicitações, consumo de tokens, métricas de latência, taxas de erro, detalhamentos de custo, tráfego de servidores MCP externos e atividade de agentes de codificação.

Botão view painel

Painel de uso do gateway de AI

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 : Exibe 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 contagens totais de usuários únicos. Use esta tab para obter um Snapshot rápido da atividade geral do Unity AI 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 Custo : Mostra a discriminação 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 Monitorar o custo do Unity AI 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.
  • Tab Agentes de codificação : rastreia a atividade de agentes de codificação integrados, incluindo Cursor, Claude Code, Gemini CLI e Codex CLI. Esta tab mostra métricas como dias ativos, sessões de codificação, commits e linhas de código adicionadas ou removidas para monitorar o uso de ferramentas do desenvolvedor. Consulte o painel de agentes de codificação para obter mais detalhes.

Esquema da tabela de uso​

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

Nome da coluna

Tipo

Descrição

Exemplo

account_id

String

O ID da account.

11d77e21-5e05-4196-af72-423257f74974

workspace_id

String

O ID do workspace.

1653573648247579

request_id

String

Um identificador exclusivo para a solicitação.

b4a47a30-0e18-4ae3-9a7f-29bcb07e0f00

invocation_id

String

Um identificador exclusivo para cada chamada de inferência individual. Múltiplas invocações podem compartilhar o mesmo request_id, como verificações de guardrail ou chamadas de agente de várias etapas. Use invocation_id para distingui-los.

c0a8012e-9f3b-4d21-8a7e-1b2c3d4e5f60

schema_version

Integer

The schema version of the usage record.

1

endpoint_id

String

O ID exclusivo do serviço de modelo do Unity AI Gateway.

43addf89-d802-3ca2-bd54-fe4d2a60d58a

endpoint_name

String

O nome do serviço de modelo do Unity AI Gateway.

databricks-gpt-5-2

endpoint_tags

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.

{"team": "engineering"}

endpoint_metadata

struct

Metadados do 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

Timestamp

O carimbo de data/hora quando a solicitação foi recebida.

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 para o primeiro byte em milissegundos.

300

destination_type

String

O tipo de destino (por exemplo, modelo externo ou modelo básico).

PAY_PER_TOKEN_FOUNDATION_MODEL

destination_name

String

O nome do modelo ou provedor de destino.

databricks-gpt-5-2

destination_id

String

A ID exclusiva do destino.

507e7456151b3cc89e05ff48161efb87

destination_model

String

O modelo específico utilizado para a solicitação.

GPT-5.2

requester

String

O ID do usuário ou da entidade de serviço que fez a solicitação.

user.name@email.com

requester_type

String

O tipo de solicitante (usuário, entidade de serviço ou grupo de usuários).

USER

ip_address

String

O endereço IP do solicitante.

1.2.3.4

url

String

A URL da solicitação.

https://<workspace-url>/ai-gateway/mlflow/v1/chat/completions

user_agent

String

O agente do usuário do solicitante.

OpenAI/Python 2.13.0

api_type

String

O tipo de chamada de API (por exemplo, chat, conclusões ou incorporações).

mlflow/v1/chat/completions

request_tags

Mapa

Tags fornecidas pelo usuário enviadas com solicitações individuais usando o cabeçalho HTTP Databricks-Ai-Gateway-Request-Tags. Use tags de solicitação para atribuir o uso a projetos, equipes, ambientes ou usuários finais específicos. Consulte solicitações de tag para acompanhamento de uso e solicitações de tag para acompanhamento de uso.

{"project": "chatbot", "team": "ml-platform"}

invocation_metadata

struct

Metadados gerados pelo sistema sobre a chamada de inferência. Contém source, o serviço ou caminho que iniciou a chamada.

{"source": "EXTERNAL_CLIENT"}

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

The total number of tokens (input + output).

200

token_details

struct

Detalhamento de tokens, incluindo cache_read_input_tokens, cache_creation_input_tokens e output_reasoning_tokens.

{"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 fallback. Contém um array attempts com priority, action, destination, destination_id, status_code, error_code, latency_ms, start_time e end_time para cada modelo tentado durante a solicitação.

{"attempts": [{"priority": "1", ...}]}

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:

SQL
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;

Recursos adicionais​

Nesta página