Utilização de modelos para serviços Unity AI Gateway

Importante

Este recurso está em versão Beta. Os administradores de conta podem controlar o acesso a esta funcionalidade a partir da página de Pré-visualizações da consola da conta. Ver Gerir as pré-visualizações de Azure Databricks.

Esta página descreve como monitorizar a utilização dos serviços Unity AI Gateway usando a tabela do sistema de rastreamento de utilização.

A tabela de monitorização de utilização captura automaticamente detalhes de pedidos e respostas para um serviço modelo, registando métricas essenciais como a utilização de tokens e a latência. Pode usar os dados desta tabela para monitorizar utilizadores, acompanhar custos e obter informações sobre o desempenho e consumo de serviços do modelo.

O rastreio da utilização também regista ai_query pedidos para serviços de modelo fornecidos pela Databricks.

Requirements

Consultar a tabela de utilização

O Unity AI Gateway regista os dados de utilização na system.ai_gateway.usage tabela do sistema. Podes ver a tabela na interface, ou consultar a tabela no Databricks SQL ou num caderno.

Note

Só os administradores de conta têm permissão para visualizar ou consultar a system.ai_gateway.usage tabela.

Para visualizar a tabela na interface, clique no link da tabela de rastreamento de utilização na página do serviço modelo para abrir a tabela no Explorador de Catálogos.

Para consultar a tabela a partir do Databricks SQL ou de um caderno:

SELECT * FROM system.ai_gateway.usage;

Tip

O Código Génio (modo Agente) pode fazer isto por ti. 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 utilização incorporado

Criar dashboard de utilização incorporado

Os administradores de contas podem criar um painel de utilização integrado do Unity AI Gateway clicando em Criar Painel na página do AI Gateway para monitorizar a utilização, acompanhar custos e obter informações sobre o desempenho e consumo dos serviços do modelo. Os administradores de contas também podem atualizar o armazém usado para executar consultas de dashboard, o que se aplica a todas as consultas subsequentes.

Botão de criar dashboard

Note

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

Quando uma versão mais recente do painel de utilização incorporado estiver disponível, os administradores de contas podem clicar em Atualizar no menu de ações do painel na página do AI Gateway.

Caixa de diálogo do painel de atualização do ai-gateway

Pode usar as seguintes opções de configuração do painel para gerir o painel:

  • Âmbito: Selecione se quer direcionar o painel para a conta ou espaço de trabalho.
  • Permissões: Escolha se as consultas são executadas usando as permissões do proprietário do painel ou as de cada visualizador. Consulte O que são permissões de dados compartilhados?.
  • Atualizações automáticas: Quando ativa esta opção, o painel atualiza-se automaticamente sempre que uma versão mais recente fica disponível e um administrador de conta visita a página do AI Gateway.

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

Quando o dashboard é atualizado para uma versão 0.3 ou superior, é criado automaticamente um cronograma para atualizar o dashboard a cada 6 horas. Se necessário, este horário pode ser desativado no painel de Lakeview. Consulte Criar uma agenda.

Ver painel de utilização

Para visualizar o painel, clique em Ver Painel a partir da página do AI Gateway. O painel integrado tem uma visibilidade abrangente sobre o uso, desempenho e custo dos serviços do modelo Unity AI Gateway. Inclui múltiplas páginas que acompanham pedidos, consumo de tokens, métricas de latência, taxas de erro, desagregação de custos, tráfego externo de servidores MCP e atividade de agentes de codificação.

Ver botão do painel de instrumentos

Painel de utilização do AI-Gateway

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

  • Separador de visão geral: Mostra métricas de utilização de alto nível, incluindo volume diário de pedidos, tendências de utilização de tokens ao longo do tempo, principais utilizadores por consumo de tokens e contagens únicas totais de utilizadores. Use este separador para obter uma rápida visão geral da atividade geral do Unity AI Gateway e identificar os utilizadores e modelos mais ativos.
  • Aba de desempenho: Acompanha métricas de desempenho chave, incluindo percentis de latência (P50, P90, P95, P99), tempo até o primeiro byte, taxas de erro e distribuições de código de estado HTTP. Use este separador para monitorizar a saúde dos serviços do modelo e identificar gargalos de desempenho ou problemas de fiabilidade.
  • Separador de utilização: Mostra divisões detalhadas de consumo por modelo, serviço, espaço de trabalho e solicitante. Este separador mostra padrões de utilização de tokens, distribuições de pedidos e rácios de acertos na cache.
  • Separador de Observabilidade de Custos: Mostra a divisão de custos por modelo de serviço, modelo-alvo, utilizador, etiquetas de serviço e etiquetas de pedido. Este separador inclui também o custo estimado para modelos externos. Consulte Monitorizar o custo do Gateway Unity AI.
  • Separador do Servidor MCP Externo: Mostra o volume de pedidos, as taxas de erro, os utilizadores e as ligações, bem como as tendências de utilização diária para o tráfego do servidor MCP externo.
  • Guia Agentes de Programação: Acompanha a atividade de agentes de programação integrados, incluindo Cursor, Claude Code, Gemini CLI e Codex CLI. Este separador mostra métricas como dias ativos, sessões de programação, commits e linhas de código adicionadas ou removidas para monitorizar o uso de ferramentas para programadores. Consulte o painel de agentes de codificação para mais detalhes.

Esquema da tabela de utilização

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

Nome da coluna Tipo Description Example
account_id STRING O ID da conta. 11d77e21-5e05-4196-af72-423257f74974
workspace_id STRING O ID 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 único para cada chamada de inferência individual. Múltiplas invocações podem partilhar o mesmo request_id, como verificações de proteção ou chamadas a agentes com múltiplos turnos. Use invocation_id para os distinguir. c0a8012e-9f3b-4d21-8a7e-1b2c3d4e5f60
schema_version INTEIRO A versão esquemática do registo de utilização. 1
endpoint_id STRING O ID único do serviço modelo Unity AI Gateway. 43addf89-d802-3ca2-bd54-fe4d2a60d58a
endpoint_name STRING O nome do serviço modelo Unity AI Gateway. databricks-gpt-5-2
endpoint_tags MAP Etiquetas configuradas no serviço modelo no momento da criação ou atualização. Aplicam-se a todos os pedidos ao serviço modelo e são úteis para categorizar serviços por equipa, centro de custos ou projeto. {"team": "engineering"}
endpoint_metadata STRUCT Metadados de 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 DATA E HORA A data e hora em que o pedido foi recebido. 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é ao primeiro byte em milissegundos. 300
destination_type STRING O tipo de destino (por exemplo, modelo externo ou modelo de fundação). PAY_PER_TOKEN_FOUNDATION_MODEL
destination_name STRING O nome do modelo de destino ou fornecedor. databricks-gpt-5-2
destination_id STRING O ID único do destino. 507e7456151b3cc89e05ff48161efb87
destination_model STRING O modelo específico usado para o pedido. GPT-5.2
requester STRING O ID do utilizador ou principal do serviço que fez o pedido. user.name@email.com
requester_type STRING O tipo de requerente (utilizador, principal de serviço ou grupo de utilizadores). USER
ip_address STRING O endereço IP do requerente. 1.2.3.4
url STRING O URL do pedido. https://<workspace-url>/ai-gateway/mlflow/v1/chat/completions
user_agent STRING O agente de utilizador do solicitante. OpenAI/Python 2.13.0
api_type STRING O tipo de chamada de API (por exemplo, chat, completamentos ou embeddings). mlflow/v1/chat/completions
request_tags MAP Etiquetas fornecidas pelo utilizador enviadas com pedidos individuais usando o Databricks-Ai-Gateway-Request-Tags cabeçalho HTTP. Use etiquetas de pedido para atribuir a utilização a projetos, equipas, ambientes ou utilizadores finais específicos. Consulte pedidos de etiquetas para rastreamento de utilização e pedidos de etiquetas para rastreio de utilização. {"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 O número total de tokens (entrada + saída). 200
token_details STRUCT Divisão detalhada dos 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 recurso . Contém um attempts array com priority, action, destination, destination_id, status_code, error_code, latency_ms, start_time e end_time para cada modelo tentado durante o pedido. {"attempts": [{"priority": "1", ...}]}

Pedidos de etiquetas para monitorização de utilização

As etiquetas de pedido são pares chave-valor personalizados que o chamador associa a pedidos individuais. Use etiquetas de pedido para atribuir o uso por projeto, equipa, ambiente, utilizador final ou qualquer outra dimensão relevante para a sua organização. As etiquetas de pedido são registadas na system.ai_gateway.usage tabela e podem ser usadas para filtrar, agregar e analisar dados de utilização.

Para identificar pedidos individuais, inclua o cabeçalho HTTP Databricks-Ai-Gateway-Request-Tags com um objeto JSON que associa chaves de texto a valores de texto. As etiquetas de pedido são registadas na request_tags coluna da tabela de utilização e nas tabelas de inferência.

Para ver exemplos de como configurar etiquetas de pedidos com a API REST, o SDK da OpenAI e o SDK da Anthropic, consulte Marcar pedidos para controlo de utilização.

Por exemplo, pode agregar o uso por projeto usando etiquetas de pedido:

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

  • Last updated on