Configurar o AI Gateway no endpoint modelo servindo

Neste artigo, o senhor aprenderá a configurar o Mosaic AI Gateway em um modelo de serviço endpoint.

Requisitos

• Um Databricks workspace em uma região onde o servindo modelo é suportado. Veja a disponibilidade do modelo de recurso servindo.
• A servindo o modelo endpoint. O senhor pode usar um dos endpoints pré-configurados de pay-per-tokens em seu site workspace ou fazer o seguinte:
  • Para criar um endpoint para modelos externos, conclua as etapas 1 e 2 de Criar um modelo de serviço externo endpoint.
  • Para criar um endpoint para provisionamento Taxa de transferência, consulte provisionamento Taxa de transferência Foundation Model APIs.
  • Para criar um endpoint para um modelo personalizado, consulte Criar um endpoint.

Configurar o AI Gateway usando a UI

Na seção AI Gateway da página de criação endpoint, é possível configurar individualmente o recurso AI Gateway. Consulte Recurso suportado para saber quais recursos estão disponíveis no endpoint de modelo de serviço externo e no endpoint de taxa de transferência de provisionamento.

A tabela a seguir resume como configurar o AI Gateway durante a criação do endpoint usando a UI de serviço. Se o senhor preferir fazer isso de forma programática, consulte o exemplo do Notebook.

Recurso	Como habilitar	Detalhes
Uso acompanhamento	Selecione Ativar acompanhamento de uso para ativar o acompanhamento e o monitoramento do uso de dados métricos.	É necessário que o Unity Catalog esteja habilitado. Os administradores da conta devem habilitar o esquema da tabela do sistema de serviço antes de utilizar as tabelas do sistema: system.serving.endpoint_usage, que captura a contagem de tokens para cada solicitação ao endpoint. system.serving.served_entities, que armazena metadados para cada modelo de base. Não compatível com o endpoint de pagamento por token. Consulte os esquemas da tabela de acompanhamento de uso. Apenas os administradores d account têm permissão para acessar view ou consultar a tabela served_entities ou endpoint_usage, mesmo que o usuário que gerencia endpoint tenha habilitado o uso de acompanhamento. Consulte Conceder acesso às tabelas do sistema. A contagem de tokens de entrada e saída é estimada como (text_length+1)/4 se a contagem de tokens não for retornada pelo modelo.
Registro de carga útil	Selecione Enable inference tables (Ativar tabelas de inferência ) para automaticamente log solicitações e respostas de seu endpoint em Delta tabelas gerenciadas por Unity Catalog.	CREATE TABLE É necessário que o Unity Catalog esteja habilitado e que você tenha acesso como administrador no esquema de catálogo especificado. As tabelas de inferência habilitadas pelo AI Gateway possuem um esquema específico. Os dados de registro de carga útil preenchem essas tabelas em menos de uma hora após a consulta ao endpoint. Consulte Limitações para obter informações sobre as expectativas de latência para o endpoint de modelo de serviço personalizado. Cargas úteis maiores que 1 MiB não são registros. A carga útil da resposta agrega a resposta de todos os fragmentos retornados. A transmissão é suportada. Em cenários de transmissão, a carga útil da resposta agrega a resposta dos blocos retornados. As tabelas de inferência para o endpoint servindo modelo otimizado para rota estão em pré-visualização pública.
AI Guarda-corpos	Consulte Configurar AI Guardrails na interface do usuário.	As grades de proteção evitam que o modelo interaja com conteúdo inseguro e prejudicial que é detectado nas entradas e saídas do modelo. As proteções de saída não são compatíveis com modelos incorporados ou com transmissão.
Limites de taxa	Selecione Limites de taxa para gerenciar e especificar o número de consultas por minuto (QPM) ou tokens por minuto (TPM) que seu endpoint pode suportar. Os limites de taxa aplicam-se apenas aos usuários que possuem permissão para consultar o endpoint. É possível definir limites de taxa baseados em consultas e em tokens em diferentes níveis: Utilize o campo “ponto final ” para especificar o QPM ou TPM máximo que todo o “ endpoint ” pode suportar. Esse limite se aplica a todo o tráfego, independentemente do usuário. Utilize o campo “Usuário (padrão) ” para definir um limite de taxa por usuário para default que se aplica a todos os usuários de endpoint, a menos que um limite de taxa personalizado mais específico seja definido. Você pode especificar limites de taxa personalizados para: Usuários individuais ou entidade de serviço . Eles têm prioridade sobre os limites de taxa personalizados do grupo de usuários. Grupos de usuários . Esse limite é um limite de taxa compartilhado para todos os membros do grupo.	Os limites de taxa de TPM não podem ser aplicados a pontos finais de serviço que atendem modelos ou agentes personalizados. Por default, não há limites de taxa configurados para usuários ou para endpoint. É possível especificar no máximo 20 limites de taxa e até 5 limites de taxa específicos para cada grupo em um arquivo de configuração de grupo ( endpoint). O limite de taxa do endpoint é um máximo global. Se esse limite for excedido, todas as solicitações para endpoint serão bloqueadas, independentemente de quaisquer limites de taxa específicos do usuário ou do grupo. Se um endpoint, usuário ou entidade de serviço tiver um limite de taxa baseado em consulta e um limite de taxa baseado em tokens especificados, o limite de taxa mais restritivo será aplicado. Os limites de taxa personalizados substituem o limite de taxa do usuário (padrão). Se um usuário pertencer a um limite específico do usuário e a um limite específico do grupo, o limite específico do usuário será aplicado. Se um usuário pertencer a vários grupos de usuários com limites de taxa de QPM e TPM diferentes, o usuário terá uma taxa limitada se exceder todos os limites de taxa de QPM ou todos os limites de taxa de TPM de seus grupos de usuários.
Divisão de tráfego	Na seção Entidades atendidas , especifique a porcentagem do tráfego que você deseja que seja roteado para modelos específicos. Para configurar a divisão de tráfego em seu endpoint de forma programática, consulte Servir vários modelos externos a um endpoint.	Para direcionar todo o tráfego para um modelo específico, defina-o como 100%. Caso deseje especificar um modelo apenas para fallback, adicione esse modelo ao endpoint e defina sua porcentagem de tráfego como 0. Por exemplo:%. Para equilibrar o tráfego entre os modelos e configurar o fallback, é possível esperar o seguinte comportamento: As solicitações são divididas aleatoriamente entre as entidades com base nas porcentagens de tráfego atribuídas. Se a solicitação atingir a primeira entidade e falhar, ela retornará para a próxima entidade na ordem em que as entidades atendidas foram listadas durante a criação do endpoint ou na atualização mais recente do endpoint. A divisão do tráfego não influencia a ordem das tentativas de fallback.
recuo	Selecione Enable fallback (Ativar fallback ) na seção AI Gateway para enviar sua solicitação a outros modelos atendidos no endpoint como um fallback.	Se a solicitação inicial encaminhada para uma determinada entidade retornar um erro 429 ou 5XX, a solicitação será redirecionada para a próxima entidade listada no endpoint. A ordem em que as solicitações são redirecionadas para entidades de fallback é baseada na ordem em que os modelos são listados durante a criação do endpoint ou na atualização mais recente do endpoint. A porcentagem de tráfego não influencia a ordem das tentativas de fallback enviadas às entidades atendidas. O recurso de fallback é suportado apenas para modelos externos. É necessário atribuir porcentagens de tráfego a outros modelos veiculados no endpoint antes de habilitar o fallback para modelos externos. Qualquer modelo externo atribuído a 0 (% ) funciona exclusivamente como um modelo interno ( fallback ). É possível ter no máximo dois fallbacks. Cada entidade é testada uma vez em ordem sequencial até que a solicitação seja bem-sucedida. Se todas as entidades listadas tiverem sido testadas sem sucesso, a solicitação falhará. A primeira tentativa bem-sucedida ou a última tentativa mal sucedida e a resposta são registradas nas tabelas de acompanhamento de uso e registro de carga útil.

O diagrama a seguir mostra um exemplo de fallback em que o senhor é o único a ter acesso,

• Três entidades atendidas são atendidas em um modelo de atendimento endpoint.
• A solicitação foi originalmente roteada para a entidade servida 3 .
• Se a solicitação retornar uma resposta 200, a solicitação foi bem-sucedida na entidade Served 3 e a solicitação e sua resposta serão registradas nas tabelas de acompanhamento de uso e de registro de carga útil do site endpoint.
• Se a solicitação retornar um erro 429 ou 5xx na entidade atendida 3 , a solicitação voltará para a próxima entidade atendida no site endpoint, entidade atendida 1 .
  • Se a solicitação retornar um erro 429 ou 5xx na entidade atendida 1 , a solicitação voltará para a próxima entidade atendida no site endpoint, entidade atendida 2 .
  • Se a solicitação retornar um erro 429 ou 5xx na entidade servida 2 , a solicitação falhará, pois esse é o número máximo de entidades de retorno. A solicitação com falha e o erro de resposta são registrados nas tabelas de acompanhamento de uso e de registro de carga útil.

Configurar AI Guardrails na interface do usuário

info

Visualização

Esse recurso está em Public Preview.

A tabela a seguir mostra como configurar os guardrails suportados.

nota

Após 30 de maio de 2025, a moderação de tópicos e a filtragem de palavras-chave AI guardrails não serão mais suportadas. Se esses recursos forem necessários para o seu fluxo de trabalho, entre em contato com a equipe Databricks account para participar do Custom guardrails Private Preview.

Guardrail	Como habilitar
Segurança	Selecione Segurança para ativar salvaguardas para impedir que seu modelo interaja com conteúdo inseguro e prejudicial.
Detecção de informações de identificação pessoal (PII)	Selecione para bloquear ou mascarar dados de PII, como nomes, endereços, números de cartão de crédito, se essas informações forem detectadas nas solicitações e respostas do site endpoint. Caso contrário, selecione Nenhum para que nenhuma detecção de PII ocorra.

Uso de esquemas de tabelas de acompanhamento

As seções a seguir resumem os esquemas de tabela de acompanhamento de uso para as tabelas de sistema system.serving.served_entities e system.serving.endpoint_usage.

system.serving.served_entities uso acompanhamento esquema de tabela

nota

A tabela do sistema de acompanhamento de uso system.serving.served_entities atualmente não é compatível com o ponto de extremidade pay-per-tokens.

A tabela do sistema de acompanhamento de uso system.serving.served_entities tem o seguinte esquema:

Nome da coluna	Descrição	Tipo
served_entity_id	O ID exclusivo da entidade atendida.	String
account_id	O cliente account ID para Delta Sharing.	String
workspace_id	O cliente workspace ID do serviço endpoint.	String
created_by	O ID do criador.	String
endpoint_name	O nome do endpoint de serviço.	String
endpoint_id	A ID exclusiva do endpoint de atendimento.	String
served_entity_name	O nome da entidade atendida.	String
entity_type	Tipo da entidade que é atendida. Pode ser FEATURE_SPEC, EXTERNAL_MODEL, FOUNDATION_MODEL ou CUSTOM_MODEL	String
entity_name	O nome subjacente da entidade. Diferente do served_entity_name, que é um nome fornecido pelo usuário. Por exemplo, entity_name é o nome do modelo do Unity Catalog.	String
entity_version	A versão da entidade servida.	String
endpoint_config_version	A versão da configuração do site endpoint.	INT
task	O tipo de tarefa. Pode ser llm/v1/chat, llm/v1/completions ou llm/v1/embeddings.	String
external_model_config	Configurações para modelos externos. Por exemplo, {Provider: OpenAI}	struct
foundation_model_config	Configurações para modelos de fundação. Por exemplo,{min_provisioned_throughput: 2200, max_provisioned_throughput: 4400}	struct
custom_model_config	Configurações para modelos personalizados. Por exemplo,{ min_concurrency: 0, max_concurrency: 4, compute_type: CPU }	struct
feature_spec_config	Configurações para especificações de recurso. Por exemplo, { min_concurrency: 0, max_concurrency: 4, compute_type: CPU }	struct
change_time	Carimbo de data e hora da mudança para a entidade atendida.	Timestamp
endpoint_delete_time	Carimbo de data e hora da exclusão da entidade. O endpoint é o contêiner da entidade atendida. Depois que o endpoint é excluído, a entidade servida também é excluída.	Timestamp

system.serving.endpoint_usage uso acompanhamento esquema de tabela

A tabela do sistema de acompanhamento de uso system.serving.endpoint_usage tem o seguinte esquema:

Nome da coluna	Descrição	Tipo
account_id	O cliente account ID.	String
workspace_id	O cliente workspace id do serviço endpoint.	String
client_request_id	O identificador de solicitação fornecido pelo usuário que pode ser especificado no corpo da solicitação do modelo de serviço. Para o endpoint de modelo personalizado, não há suporte para solicitações maiores que 4 MiB.	String
databricks_request_id	Um identificador de solicitação gerado pelo site Databricks anexado a todas as solicitações de servindo modelo.	String
requester	O ID do usuário ou da entidade de serviço cujas permissões são usadas para a solicitação de invocação do serviço endpoint.	String
status_code	O código de status HTTP que foi retornado do modelo.	Integer
request_time	A data e hora em que a solicitação é recebida.	Timestamp
input_token_count	A contagem de tokens da entrada. Isso será 0 para solicitações de modelos personalizados.	Long
output_token_count	A contagem de tokens da saída. Isso será 0 para solicitações de modelos personalizados.	Long
input_character_count	A contagem de caracteres das strings de entrada ou prompt. Isso será 0 para solicitações de modelos personalizados.	Long
output_character_count	A contagem de caracteres das strings de saída da resposta. Isso será 0 para solicitações de modelos personalizados.	Long
usage_context	O mapa fornecido pelo usuário contendo identificadores do usuário final ou do aplicativo do cliente que faz a chamada para o endpoint. Consulte Definir melhor o uso com usage_context. Para o endpoint de modelo personalizado, não há suporte para solicitações maiores que 4 MiB.	Mapa
request_streaming	Se a solicitação está no modo de transmissão.	Booleana
served_entity_id	O ID exclusivo usado para join com a tabela de dimensão system.serving.served_entities para procurar informações sobre a entidade endpoint e servida.	String

Defina ainda mais o uso com usage_context

Ao consultar um modelo externo com o acompanhamento de uso ativado, o senhor pode fornecer o parâmetro usage_context com o tipo Map[String, String]. O mapeamento do contexto de uso aparece na tabela de acompanhamento de uso na coluna usage_context. O tamanho do mapa usage_context não pode exceder 10 KiB.

Bash

{
  "messages": [
    {
      "role": "user",
      "content": "What is Databricks?"
    }
  ],
  "max_tokens": 128,
  "usage_context":
    {
      "use_case": "external",
      "project": "project1",
      "priority": "high",
      "end_user_to_charge": "abcde12345",
      "a_b_test_group": "group_a"
    }
}

Se estiver usando o cliente OpenAI Python, o senhor pode especificar o endereço usage_context incluindo-o no parâmetro extra_body.

Python

from openai import OpenAI

client = OpenAI(
    api_key="dapi-your-databricks-token",
    base_url="https://example.staging.cloud.databricks.com/serving-endpoints"
)

response = client.chat.completions.create(
    model="databricks-claude-3-7-sonnet",
    messages=[{"role": "user", "content": "What is Databricks?"}],
    temperature=0,
    extra_body={"usage_context": {"project": "project1"}},
)
answer = response.choices[0].message.content
print("Answer:", answer)

Os administradores de conta podem agregar diferentes linhas com base no contexto de uso para obter percepções e podem join essas informações com as informações na tabela de registro de carga útil. Por exemplo, o senhor pode adicionar end_user_to_charge ao usage_context para acompanhar a atribuição de custos para os usuários finais.

Monitorar o uso do endpoint

Para monitorar o uso do endpoint, o senhor pode join as tabelas do sistema e as tabelas de inferência do seu endpoint.

unir tabelas do sistema

Este exemplo se aplica apenas ao modelo externo e ao ponto de extremidade da Taxa de transferência de provisionamento. A tabela do sistema served_entities não é compatível com o ponto de extremidade pay-per-tokens, mas o senhor pode unir as tabelas de inferência e uso para obter detalhes semelhantes.

Para join as tabelas de sistema endpoint_usage e served_entities, use o seguinte SQL:

SQL

SELECT * FROM system.serving.endpoint_usage as eu
JOIN system.serving.served_entities as se
ON eu.served_entity_id = se.served_entity_id
WHERE created_by = "\<user_email\>";

unir tabelas de inferência e uso

A seguir, junte a tabela do sistema endpoint_usage e a tabela de inferência para um pay-per-tokens endpoint. As tabelas de inferência e o acompanhamento do uso devem estar ativados no site endpoint para join essas tabelas.

SQL

SELECT * FROM system.serving.endpoint_usage AS endpoint_usage
JOIN
  (SELECT DISTINCT(served_entity_id) AS fmapi_served_entity_id
  FROM <inference table name>) fmapi_id
ON fmapi_id.fmapi_served_entity_id = endpoint_usage.served_entity_id;

Atualizar AI Recurso do gateway no endpoint

O senhor pode atualizar o AI Gateway recurso on servindo modelo de endpoint que os tinha ativado anteriormente e o endpoint que não os tinha. As atualizações das configurações do AI Gateway levam cerca de 20 a 40 segundos para serem aplicadas, mas as atualizações de limitação de taxa podem levar até 60 segundos.

A seguir, mostramos como atualizar o recurso do gateway AI em um modelo de serviço endpoint usando a Serving UI.

Na seção Gateway da página endpoint, é possível ver quais recursos estão ativados. Para atualizar esses recursos, clique em Edit AI Gateway .

Notebook exemplo

O Notebook a seguir mostra como ativar e usar programaticamente o recurso Databricks Mosaic AI Gateway para gerenciar e administrar modelos de provedores. Veja o PUT /api/2.0/serving-endpoint/{{name}/AI-gateway para obter detalhes da API REST.

Habilitar Databricks Mosaic AI Gateway recurso Notebook

Open notebook in new tab

Recurso adicional

• Introdução ao Mosaic AI Gateway.
• Monitorar modelos atendidos usando tabelas de inferência habilitadas para AI Gateway.