Uso de modelo para serviços do Gateway de IA do Unity

Importante

Esse recurso está em Beta. Os administradores de conta podem controlar o acesso a esse recurso na página Visualizações do console da conta. Consulte Gerenciar visualizações do Azure Databricks.

Esta página descreve como monitorar o uso de serviços do Gateway de IA do Unity 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 token e latência. Você pode usar os dados nesta tabela para monitorar usuários, acompanhar custos e obter insights sobre o desempenho e o consumo do serviço de modelo.

O rastreamento de uso também abrange solicitações ai_query aos Serviços de Modelo fornecidos pelo Databricks.

Os administradores de conta e workspace podem exibir uma visão geral consolidada do uso de IA na página de IA no Hub de Governança.

Requirements

  • A prévia em nível de conta do Unity AI Gateway precisa estar habilitada na sua conta. Um administrador de conta habilita essa visualização na página Visualizações do console da conta antes de usar o controle de uso ou o painel de uso interno. Consulte Gerenciar visualizações do Azure Databricks.
  • Um workspace do Azure Databricks em uma região com suporte ao Gateway de IA Unity.
  • Unity Catalog habilitado para seu workspace. Consulte Habilitar um workspace para o Unity Catalog.

Consultar a tabela de uso

O Gateway de IA do Unity registra dados de uso na tabela de sistema system.ai_gateway.usage. Você pode exibir a tabela na interface do usuário ou consultar a tabela no Databricks SQL ou em um notebook.

Observação

Tanto a função de administrador da conta quanto a de administrador do metastore são necessárias para visualizar ou consultar a system.ai_gateway.usage tabela por padrão. Os administradores podem gerenciar o acesso a esse recurso a partir da página de Prévias do console da conta. Consulte Gerenciar visualizações do Azure Databricks.

Para exibir 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 Gerenciador de Catálogos.

Para consultar a tabela do Databricks SQL ou de um notebook:

SELECT * FROM system.ai_gateway.usage;

Dica

O Código do Gênio (modo agente) pode fazer isso por você. 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 uso integrado

Observação

Alguns espaços de trabalho ainda não exibem a lista suspensa Govern. Nesses espaços de trabalho, use os botões independentes Criar painel, Ver painel e Atualizar na página do Unity AI Gateway, em vez disso.

Criar um painel de uso embutido

Os administradores da conta podem criar um painel integrado de uso do Unity AI Gateway para monitorar o uso, acompanhar os custos e obter insights sobre o desempenho e o consumo dos serviços de modelo. Na página gateway de IA do Unity, clique em Controlar no canto superior direito e, em seguida, clique em Criar Painel de Uso. O warehouse que executa as consultas do painel é selecionado automaticamente.

Observação

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

Quando uma versão mais recente do painel de uso integrado estiver disponível, os administradores da conta poderão clicar em Atualizar na linha da versão do painel no menu suspenso Govern na página do Unity AI Gateway.

Você pode usar as seguintes opções de configuração do painel para gerenciar o painel:

  • Escopo: selecione se o escopo do painel deve ser aplicado à conta ou ao espaço de trabalho.
  • Permissões: escolha se as consultas são executadas usando as permissões do proprietário do painel ou as permissões de cada visualizador. Veja o que são permissões de dados compartilhadas?.
  • Atualizações automáticas: quando você habilita essa opção, o painel é atualizado automaticamente sempre que uma versão mais recente fica disponível e um administrador de conta visita a página gateway de IA do Unity.

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

Quando o painel é atualizado para versão 0.3 ou superior, um agendamento é criado automaticamente para atualizar o painel a cada 6 horas. Se necessário, esse agendamento pode ser desabilitado no painel do Lakeview. Confira Criar agendamento.

Exibir painel de uso

Para exibir o painel, clique em Controlar no canto superior direito da página gateway de IA do Unity e clique em Painel de Uso. O painel abre em uma nova guia. O painel integrado oferece visibilidade abrangente sobre o uso, o desempenho e o custo dos serviços de modelo do Unity AI Gateway. Ele inclui várias páginas acompanhando solicitações, consumo de token, métricas de latência, taxas de erro, detalhamentos de custos, tráfego externo do servidor MCP e atividade do agente de codificação.

painel de uso do ai-gateway

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

  • Guia Visão geral: mostra métricas de uso de alto nível, incluindo volume de solicitação diária, tendências de uso de token ao longo do tempo, principais usuários por consumo de token e contagens totais de usuários exclusivos. Use essa guia para obter um instantâneo rápido da atividade geral do Gateway de IA do Unity e identificar os usuários e modelos mais ativos.
  • Guia Desempenho: controla as principais métricas de desempenho, incluindo percentis de latência (P50, P90, P95, P99), tempo para primeiro byte, taxas de erro e distribuições de código de status HTTP. Use esta guia para monitorar a saúde do serviço do modelo e identificar gargalos de desempenho ou problemas de confiabilidade.
  • Guia Uso: mostra detalhamentos de consumo por Serviço de Modelo, workspace e solicitante. Esta aba mostra padrões de uso de tokens, distribuição de solicitações e taxas de acerto de cache.
  • Guia Observabilidade de Custo: mostra divisões de custo por Serviço de Modelo, modelo de destino, usuário, marcações de serviço e marcas de solicitação. Essa guia também inclui o custo estimado para modelos externos. Consulte Monitoramento do custo do Unity AI Gateway.
  • Guia Servidor MCP externo: mostra volume de solicitação, taxas de erro, usuários e conexões e tendências de uso diário para o tráfego externo do servidor MCP.
  • Guia Agentes de Codificação: acompanha a atividade de agentes de codificação integrados, incluindo Cursor, Claude Code, CLI do Gemini e CLI do Codex. Essa guia mostra métricas como dias ativos, sessões de codificação, confirmações e linhas de código adicionadas ou removidas para monitorar o uso da ferramenta de desenvolvedor. Consulte o painel do agente de codificação para obter mais detalhes.

Esquema de Tabela de Utilização

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

Nome da Coluna Tipo Descrição Example
account_id STRING O ID da conta. 11d77e21-5e05-4196-af72-423257f74974
workspace_id STRING O identificador 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 exclusivo para cada chamada de inferência individual. Várias invocações podem compartilhar o mesmo request_id, como verificações de proteção ou chamadas de agente de várias rodadas. Use invocation_id para distingui-los. c0a8012e-9f3b-4d21-8a7e-1b2c3d4e5f60
schema_version INTEGER A versão do esquema do registro de uso. 1
endpoint_id STRING O ID exclusivo do serviço de modelos do Gateway de IA do Unity. 43addf89-d802-3ca2-bd54-fe4d2a60d58a
endpoint_name STRING O nome do serviço de modelo do Gateway de IA do Unity. databricks-gpt-5-2
endpoint_tags MAP Tags configuradas no serviço de modelo no momento da criação ou da atualização. Elas se aplicam a todas as solicitações ao 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 registro 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 até o primeiro byte em milissegundos. 300
destination_type STRING O tipo de destino (por exemplo, modelo externo ou modelo de base). 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 usado para a solicitação. GPT-5.2
requester STRING A 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 de usuário do solicitante. OpenAI/Python 2.13.0
api_type STRING O tipo de chamada à API (por exemplo, chat, conclusões ou inserções). mlflow/v1/chat/completions
request_tags MAP Etiquetas fornecidas pelo usuário enviadas com solicitações individuais usando o cabeçalho HTTP Databricks-Ai-Gateway-Request-Tags. Use marcas de solicitação para atribuir o uso a projetos, equipes, ambientes ou usuários finais específicos. Consulte Solicitações de marcação para acompanhamento de uso e Solicitações de marcação para acompanhamento de uso. {"project": "chatbot", "team": "ml-platform"}
invocation_metadata STRUCT Metadados gerados pelo sistema sobre a chamada de inferência. Contém sourceo serviço ou o 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 O número total de tokens (entrada + saída). 200
token_details STRUCT Detalhamento de token, 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 uma attempts matriz com priority, action, , destination, destination_idstatus_code, , error_code, latency_ms, e start_timeend_time para cada modelo tentado durante a solicitação. {"attempts": [{"priority": "1", ...}]}

Solicitações de marcação para acompanhamento de uso

As tags de solicitação são pares de chave-valor personalizados que quem faz a chamada anexa a cada solicitação. Use marcas de solicitação para atribuir o uso por projeto, equipe, ambiente, usuário final ou qualquer outra dimensão relevante para sua organização. As marcas de solicitação são registradas na system.ai_gateway.usage tabela e podem ser usadas para filtrar, agregar e analisar dados de uso.

Para identificar solicitações individuais, inclua o cabeçalho HTTP Databricks-Ai-Gateway-Request-Tags com um objeto JSON que mapeia chaves de string para valores de string. As tags de solicitação são registradas na coluna request_tags na tabela de uso e nas tabelas de inferência.

Para ver exemplos de como definir tags de solicitação com a API REST, o SDK da OpenAI e o SDK da Anthropic, consulte Marcar solicitações para rastreamento de uso.

Por exemplo, você pode agregar o uso por projeto usando marcas 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;

Limitations

  • O Gateway de IA do Unity não controla o uso de token para respostas não streaming e não inseridas maiores que 1 MiB.

Recursos adicionais

  • Last updated on