Configurar o AI Gateway no endpoint modelo servindo

info

Visualização

O Mosaic AI Gateway está em Public Preview e é compatível com as seguintes regiões:

• asia-south1
• asia-southeast1
• europe-west2
• us-east4
• us-west1
• us-east1
• us-central1

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. Consulte a disponibilidade regional do modelo 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.	O senhor deve ter o Unity Catalog ativado. - Os administradores de conta devem ativar o esquema de tabela do sistema de serviço antes de usar as tabelas do sistema: system.serving.endpoint_usage, que captura a contagem de tokens de cada solicitação para o site endpoint, e system.serving.served_entities, que armazena metadados para cada modelo de fundação. - Ver Uso de esquemas de tabelas de acompanhamento - Somente os administradores do account têm permissão para view ou consultar a tabela served_entities ou endpoint_usage, embora o usuário que gerenciar o endpoint deva habilitar o acompanhamento do uso. 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. - No momento, a tabela do sistema system.serving.served_entities não é compatível com o ponto de extremidade pay-per-tokens.
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.	O senhor deve ter o Unity Catalog ativado e o acesso CREATE_TABLE no esquema de catálogo especificado. - As tabelas de inferência habilitadas pelo AI Gateway têm um esquema específico. - Os dados de registro de carga útil preenchem essas tabelas menos de uma hora após a consulta do endpoint. Consulte Limitações para expectativas de latência para o endpoint de modelo de serviço personalizado. - As 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 pedaços retornados.
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 detectado nas entradas e saídas do modelo. - Os guardrails de saída não são compatíveis com os modelos de incorporação ou de transmissão.
Limites de taxa	O senhor pode impor limites de taxa de solicitação para gerenciar o tráfego do seu endpoint por usuário e por endpoint	Os limites de taxa são definidos em consultas por minuto (QPM). - O default é No limit tanto por usuário quanto por endpoint.
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%. - Se o senhor quiser especificar um modelo somente de fallback, adicione esse modelo ao endpoint e defina sua porcentagem de tráfego como 0%. - Para equilibrar a carga do tráfego entre os modelos e configurar o fallback, o senhor pode 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 voltará 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 a uma determinada entidade retornar um erro 429 ou 5XX, a solicitação voltará para a próxima entidade listada no endpoint. - A ordem em que as solicitações são redirecionadas para as entidades atendidas pelo site fallback baseia-se na ordem em que os modelos são listados durante a criação do site endpoint ou na atualização mais recente do site endpoint. A porcentagem de tráfego não influencia a ordem das tentativas de fallback enviadas às entidades atendidas. - são suportados apenas para modelos externos. - O senhor deve atribuir porcentagens de tráfego a outros modelos atendidos no site endpoint antes de ativar o fallback para modelos externos. - Qualquer modelo externo atribuído a 0% de tráfego funciona exclusivamente como um modelo de fallback. - O senhor pode ter no máximo dois fallback. - 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 de solicitação bem-sucedida ou a última tentativa de solicitação com falha e a resposta são registradas nas tabelas de acompanhamento de uso e de registro de carga útil.

O diagrama a seguir mostra um exemplo em que,

• 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

A tabela a seguir mostra como configurar os guardrails suportados.

nota

A moderação de tópicos e a filtragem de palavras-chave estão obsoletas. Após 30 de maio de 2025, esses recursos não terão mais suporte nem estarão disponíveis. Se essas funções forem necessárias para o seu fluxo de trabalho, entre em contato com a equipe do Databricks account para participar do Custom guardrails Private Preview.

Guardrail	Como habilitar	Detalhes
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.
Tópicos válidos (descontinuados)	Você pode digitar tópicos diretamente nesse campo. Se você tiver várias entradas, certifique-se de pressionar enter após cada tópico. Como alternativa, o senhor pode acessar upload um arquivo .csv ou .txt.	Um máximo de 50 tópicos válidos podem ser especificados. Cada tópico não pode exceder 100 caracteres
Palavras-chave inválidas (descontinuadas)	Você pode digitar tópicos diretamente nesse campo. Se você tiver várias entradas, certifique-se de pressionar enter após cada tópico. Como alternativa, o senhor pode acessar upload um arquivo .csv ou .txt.	É possível especificar no máximo 50 palavras-chave inválidas. Cada palavra-chave não pode exceder 100 caracteres.

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.	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.	Long
output_token_count	A contagem de tokens da saída.	Long
input_character_count	A contagem de caracteres das cadeias de caracteres de entrada ou do prompt.	Long
output_character_count	A contagem de caracteres das strings de saída da resposta.	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.	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.