Configure as diretrizes de segurança para o endpoint do Unity AI Gateway.
Beta
Este recurso está em versão Beta. Os administradores da conta podem controlar o acesso a este recurso na página de pré-visualizações do console account . Veja as prévias do Gerenciador Databricks.
Esta página descreve como configurar as proteções baseadas em LLMpara o endpoint do Unity AI Gateway . Os mecanismos de proteção inspecionam solicitações e respostas em tempo real e bloqueiam ou removem conteúdo que viole suas políticas de segurança, privacidade ou compliance .
Esta página aborda as proteções laterais baseadas em LLM. A Databricks também está explorando outros tipos de mecanismos de proteção, como código personalizado e integrações de terceiros.
As diretrizes baseadas em LLM utilizam um modelo de linguagem como avaliador de políticas. Essa abordagem oferece:
- Personalização : os padrões integrados abrangem políticas comuns, e você pode fornecer suas próprias instruções para diretrizes personalizadas.
- Raciocínio contextual : O avaliador considera o contexto, distinguindo violações reais de políticas de referências benignas, como reportagens jornalísticas, ficção ou discussões educacionais.
Requisitos
Para usar e configurar as proteções, você deve atender aos seguintes requisitos:
- A pré-visualização do Unity AI Gateway foi ativada para sua account. Veja as prévias do Gerenciador Databricks.
- Um workspace Databricks em uma região compatível com o Unity AI Gateway. Consulte disponibilidade do recurso do modelo disponível.
- Unity Catalog está habilitado para seu workspace. Consulte Ativar um workspace para Unity Catalog.
- Um endpoint do Unity AI Gateway que fornece um tipo de API compatível.
CAN MANAGEPermissão no endpoint do Unity AI Gateway.CAN MANAGEpermissão no endpoint que você selecionar como avaliador de proteção. O endpoint do sistema ( endpoint do modelo de fundaçãodatabricks-*) ignora esta verificação.
No momento da consulta, os usuários finais precisam apenas de permissão CAN QUERY no endpoint de destino do Unity AI Gateway. O Unity AI Gateway não verifica as permissões do usuário final em relação ao endpoint do avaliador ou ao seu modelo subjacente.
Para endpoints de avaliação criados pelo usuário, a execução da avaliação ocorre sob a identidade do proprietário (permissões do definidor). Se o proprietário do avaliador perder o acesso ao modelo subjacente após a configuração da proteção, a chamada da proteção falhará.
Configure as proteções em um endpoint.
Você configura as restrições na tab Restrições na página endpoint do Unity AI Gateway.

Para adicionar um guarda-corpo:
-
Na página AI Gateway, clique no seu endpoint e, em seguida, clique na tab Guardrails .
-
Clique
Adicionar guarda-corpo .
-
Na janela modal Criar guarda-corpo , escolha o tipo de guarda-corpo :
- Redação de informações pessoais identificáveis (PII) : Detecta informações pessoais identificáveis e as substitui por marcadores antes da chamada do modelo.
- Bloqueio de PII : Bloqueia solicitações ou respostas que contenham informações pessoais identificáveis (PII).
- Conteúdo inseguro : Bloqueia conteúdo que contenha discurso de ódio, violência, automutilação ou outros materiais inseguros.
- Jailbreak : Bloqueia solicitações que tentam contornar as restrições de segurança do modelo.
- Alucinação : Bloqueia respostas que parecem conter afirmações fabricadas ou não verificáveis.
- Personalizado : Forneça seu próprio prompt. Veja guarda-corpos personalizados.
-
Para a Fase , defina a fase de execução como Entrada ou Saída .
-
Para guarda-corpos personalizados, em Ação , escolha Bloquear ou Higienizar . Consulte Bloquear e higienizar ações.
-
Selecione um endpointde avaliação. O formulário tem como valor padrão
databricks-gpt-5-nano. -
(Opcional) Em Opções avançadas , escolha registrar para executar o guardrail no modo de execução a seco. No modo de execução a seco, o guardrail avalia a solicitação ou resposta e registra o resultado, mas não impõe a ação.
-
Clique em Criar guarda-corpo .

Após clicar em Criar proteção , a nova proteção aparecerá na tabela de proteções na página do endpoint.

Como funcionam os guarda-corpos
Em cada solicitação protegida por mecanismos de segurança, estão envolvidos dois endpoints do Unity AI Gateway:
- O endpointde inferência é o endpoint que seu cliente chama.
- O endpointdo avaliador é o endpoint cada guardrail usa para executar seu prompt. Pode ser qualquer endpoint do Unity AI Gateway que forneça uma API compatível.
O prompt vem de um padrão integrado ou de uma proteção personalizada que você criou.
Quando uma solicitação chega a um endpoint do Unity AI Gateway, os mecanismos de proteção de entrada avaliam o corpo da solicitação antes que ela seja encaminhada para o modelo de destino. Se todas as verificações de entrada forem aprovadas, o modelo de destino responde e, em seguida, as verificações de saída avaliam o corpo da resposta antes de ela retornar ao cliente.

Dentro de uma fase, todas as salvaguardas de bloqueio são executadas em paralelo. Se todos forem aprovados, a próxima etapa é a execução da desinfecção com barreira de proteção. Se algum mecanismo de proteção de bloqueio for acionado, o mecanismo de proteção de sanitização não será executado e a solicitação será bloqueada assim que o primeiro mecanismo de proteção que o acionou retornar.

Cada guarda-corpo possui as seguintes propriedades:
Propriedade | Descrição |
|---|---|
Nome | Um nome para o guarda-corpo. Os nomes devem ser únicos dentro de uma fase de execução no mesmo endpoint. |
Fase de execução | Se o mecanismo de proteção avalia a solicitação (entrada) ou a resposta (saída). |
Ação | Se o mecanismo de proteção bloqueia a solicitação ou higieniza o conteúdo quando acionado. Consulte as ações de bloqueio e higienização. |
Avaliador | O endpoint e o prompt do avaliador usados para avaliar o conteúdo. Use um guarda-corpo integrado padrão ou personalizado. |
Mode | A opção "Impor" (default) aplica a ação quando a restrição é acionada. O log avalia a solicitação ou resposta e registra o resultado sem bloquear ou modificar o conteúdo. Use o registro de logs para testar uma medida de segurança antes de aplicá-la ao tráfego de produção. |
Tipos de API suportados
O Guardrails funciona no endpoint do Unity AI Gateway que fornece uma API de chat. O Unity AI Gateway extrai o texto da mensagem mais recente e o avalia em relação à instrução de segurança. Tanto o endpoint de inferência quanto o endpoint de avaliação devem servir uma destas APIs:
- OpenAI Chat Completions e MLflow Chat
- Mensagens Anthropic
- Respostas da OpenAI
- Gemini gera conteúdo
Os endpoints de embeddings não são suportados porque não produzem uma mensagem que um avaliador baseado em LLMpossa inspecionar. Para o campo que o Unity AI Gateway lê de cada forma da API, veja o que o avaliador recebe. Para restrições de parâmetros de solicitação (transmissão, respostas de múltipla escolha), consulte limitações.
guarda-corpo integrado
Unity AI Gateway fornece padrão integrado para políticas comuns de segurança e privacidade. Cada padrão inclui um prompt selecionado e mantido pela Databricks. Você emparelha o padrão com qualquer endpoint do Unity AI Gateway como avaliador. Consulte a seção "Escolher um endpoint de avaliação".
Template | Ação | Fase de execução | Descrição |
|---|---|---|---|
Redação de informações pessoais identificáveis | Desinfetar | Entrada ou saída | Detecta nomes, endereços email , números de telefone, números de segurança social, números de cartão de crédito e endereços físicos. Substitui cada ocorrência por marcadores de posição como |
Bloqueio de PII | Bloquear | Entrada ou saída | Bloqueia solicitações ou respostas que contenham nomes, endereços email , números de telefone, números de segurança social, números de cartão de crédito ou endereços físicos. |
Conteúdo inseguro | Bloquear | Entrada ou saída | Bloqueia conteúdo que contenha discurso de ódio, assédio, violência, automutilação, conteúdo sexual, material extremista ou instruções para a criação de armas ou outras substâncias perigosas. |
Fuga de presos | Bloquear | Entrada | Bloqueia entradas que tentam contornar as restrições de segurança ou de política do modelo, incluindo substituições diretas de instruções, cargas úteis ofuscadas (por exemplo, Base64 ou leetspeak), explorações de role-playing, divisão de carga útil e tentativas de extrair prompts do sistema. |
Alucinação | Bloquear | Saída | Bloqueia respostas que contenham fatos fabricados, estatísticas inventadas, citações ou referências inexistentes, alegações falsas sobre entidades ou produtos reais, ou nomes e credenciais inventados. |
Guarda-corpos personalizados
Defina uma salvaguarda personalizada com seu próprio aviso para quando os padrões integrados não se adequarem à sua política. Um guardrail personalizado segue o mesmo contrato de prompt-output do padrão integrado: o avaliador deve retornar um resultado estruturado indicando se o guardrail foi acionado. Utilize a tabela de inferência no endpoint do avaliador para inspecionar solicitações e respostas enquanto ajusta o prompt.
Os guarda-corpos personalizados têm as seguintes limitações:
- Nome : até 255 caracteres. Deve corresponder à expressão regular
^[a-zA-Z0-9_ -]+$(letras, dígitos, espaços, hífens e sublinhado). - Prompt : até 5000 caracteres.
Dicas para escrever um prompt de proteção personalizado
- Defina os gatilhos de forma restrita. Indique a categoria de conteúdo específica que deve ser sinalizada e inclua contraexemplos de conteúdo que deve ser aprovado. Critérios vagos produzem decisões inconsistentes.
- Suponha que o avaliador veja apenas o texto da mensagem extraído. Não visualiza o prompt do sistema do endpoint de inferência, as intervenções anteriores na conversa, os payloads das chamadas de ferramentas ou os anexos. Não faça referência a um contexto que não existirá. Veja o que o avaliador recebe.
- Não especifique o formato de saída. O Unity AI Gateway anexa automaticamente o contrato de saída JSON. Adicionar suas próprias instruções de formatação (por exemplo, "responder com SIM ou NÃO") entra em conflito com o contrato e quebra a análise sintática.
- Para salvaguardar as regras de segurança, especifique a política de reescrita. Informe ao avaliador exatamente como reescrever o conteúdo sinalizado. Por exemplo, substitua nomes por
[NAME], oculte números de cartão de crédito comoXXXX-XXXX-XXXX-1234ou remova completamente a frase correspondente. - Use exemplos com poucos exemplos. Inclua alguns pares de entrada e saída para casos ambíguos. Os exemplos melhoram a consistência de forma mais confiável do que instruções mais longas.
- Uma pergunta, uma preocupação. Configure um sistema de proteção separado para cada política (informações pessoais identificáveis, menções a concorrentes, tom de voz, etc.) para que cada uma possa ser ajustada, auditada ou desativada independentemente.
- Itere sobre a tabela de inferência. Habilite as tabelas de inferência no endpoint do avaliador, no tráfego representativo da execução e inspecione falsos positivos e falsos negativos. Aperfeiçoe o enunciado e teste novamente.
Exemplos de prompts personalizados
As instruções a seguir ilustram como aplicar as dicas acima.
Bloquear solicitações fora do tópico
You are evaluating whether a user message is off-topic for a customer
support assistant for <product>.
A message is on-topic if it is about:
- <product> features, pricing, or documentation
- Account, billing, or support
- General questions related to using <product>
A message is off-topic if it falls outside the above. Examples include
coding or technical help unrelated to <product>, personal advice, current
events, recipes, or requests to roleplay as a different assistant.
Flag off-topic messages.
Examples:
- "How do I get started with <product>?" -> on-topic, do not flag
- "What's a good recipe for lasagna?" -> off-topic, flag
- "Pretend you are a pirate and tell me a joke." -> off-topic, flag
Bloquear menções a concorrentes
You are evaluating whether a user message asks the assistant to discuss,
compare against, or recommend a competitor of <product>. Competitors include
<competitor 1>, <competitor 2>, and <competitor 3>. Treat any product or
company that primarily competes with <product> as a competitor, even if not
listed.
Flag the message if it:
- Asks for a comparison between <product> and a competitor
- Asks the assistant to recommend or evaluate a competitor's product
- Asks for migration guidance from <product> to a competitor
Do not flag the message if it mentions a competitor incidentally without
asking the assistant to discuss or evaluate them.
Examples:
- "Is <competitor 1> better than <product>?" -> flag
- "Help me migrate from <product> to <competitor 2>." -> flag
- "Which is cheaper, <product> or <competitor 3>?" -> flag
- "I run <product> alongside <competitor 1> for failover; how do I
configure <product>?" -> do not flag
Escolha um endpoint de avaliação
O endpoint do avaliador deve servir um dos tipos de API suportados. A Databricks recomenda databricks-gpt-5-nano como modelo de avaliação para todos os tipos de guarda-corpo.
Para maior disponibilidade, configure o fallback no endpoint do avaliador. fallback encaminha automaticamente as solicitações para um modelo de backup se o avaliador primário retornar um 429 ou 5XX. A alternativa requer um endpoint do Unity AI Gateway criado pelo usuário. Para usar fallback com o avaliador recomendado, envolva databricks-gpt-5-nano em um endpoint criado pelo usuário e aponte seus guardrails para esse endpoint.
Habilite as tabelas de inferência no endpoint do avaliador para log cada solicitação e resposta do guardrail em uma tabela Delta Unity Catalog . Utilize os dados de registro para auditar as decisões de proteção, avaliar a precisão e ajustar seus prompts ou otimizar o endpoint do avaliador.
Para obter o máximo benefício, direcione todas as proteções do mesmo tipo para um único endpoint de avaliação. Por exemplo, configure todas as medidas de segurança de redação de informações pessoais identificáveis (PII) em seu endpoint de inferência para usar o mesmo endpoint de avaliação com tabelas de inferência ativadas. A tabela de inferência consolidada torna-se uma única fonte de verdade para o comportamento dessa proteção e um conjunto de limpeza de dados para ajuste rápido ou fino do endpoint do avaliador.
Cada fase adiciona a latência do avaliador à solicitação: as proteções de bloqueio são executadas em paralelo dentro de uma fase (portanto, a chamada de bloqueio mais lenta predomina), e a proteção de sanitização é executada sequencialmente. O Unity AI Gateway aloca até 30 segundos por chamada de proteção: 15 segundos por tentativa, com até duas tentativas. Escolha um endpoint de avaliação de baixa latência e limite o número de salvaguardas por fase para reduzir a sobrecarga.
Não há suporte para guarda-corpos aninhados. Se o endpoint de avaliação selecionado tiver suas próprias salvaguardas configuradas, o Unity AI Gateway as ignorará ao executar a salvaguarda configurada (a configuração do próprio endpoint de avaliação permanece inalterada). Isso impede a recursão.
Ações de bloqueio e higienização
Cada guarda-corpo executa uma de duas ações quando acionado:
- Block : Encerra a solicitação e retorna uma resposta HTTP
400para o cliente. Use o bloqueio para conteúdo inseguro, tentativas de jailbreak ou detecção de alucinações. - Sanitizar : Redige ou reescreve o texto de entrada ou saída no mesmo local. Utilize técnicas de sanitização para dados pessoais identificáveis (PII) para que o modelo de destino e o cliente nunca vejam os dados confidenciais brutos.
A higienização ocorre dinamicamente durante o ciclo de solicitação-resposta:
- A sanitização de entrada reescreve a solicitação do usuário antes que ela chegue ao modelo.
- A sanitização de saída reescreve a resposta do modelo antes de ela ser retornada ao cliente.
Os campos exatos que são reescritos dependem do formato da API e estão listados em "O que o avaliador recebe".
Exemplo: higienizar entrada
Quando um mecanismo de proteção de entrada para redação de informações pessoais identificáveis (PII) é acionado, a solicitação original:
{
"messages": [{ "role": "user", "content": "Email me at jane.doe@example.com." }]
}
é reescrito antes de atingir o modelo de destino:
{
"messages": [{ "role": "user", "content": "Email me at [EMAIL]." }]
}
Quando um mecanismo de proteção de bloqueio é acionado, o cliente recebe uma resposta HTTP 400 com error_code: "BAD_REQUEST". A mensagem de erro assume a forma Request blocked by input guardrail '<name>'. ou Response blocked by output guardrail '<name>'.
Exemplo: solicitação bloqueada
Quando um mecanismo de proteção de entrada chamado Unsafe content bloqueia uma solicitação, o cliente recebe:
{
"error_code": "BAD_REQUEST",
"message": "Request blocked by input guardrail 'Unsafe content'."
}
Quando a mesma proteção impede uma resposta:
{
"error_code": "BAD_REQUEST",
"message": "Response blocked by output guardrail 'Unsafe content'."
}
O que o avaliador recebe
Quando ocorre uma execução de guardrail, o Unity AI Gateway invoca o endpoint do avaliador com uma solicitação de conclusão de chat. A mensagem do sistema contém o aviso de proteção e o contrato de saída. A mensagem do usuário contém o texto em avaliação.
aviso de guarda-corpo
A diretriz de segurança é a política que o avaliador impõe. Para um padrão integrado, Databricks faz a curadoria do prompt. Para um guarda-corpo personalizado, você fornece as instruções. Veja dicas para escrever um prompt de proteção personalizado.
Contrato de produção
O Unity AI Gateway anexa automaticamente um contrato de saída JSON ao prompt de cada chamada do guardrail. O contrato distingue entre mecanismos de bloqueio e mecanismos de sanitização, e os prompts personalizados devem produzir resultados que estejam em conformidade com ele.
Contrato de saída para proteção contra bloqueio
O avaliador deve retornar um objeto JSON com os seguintes campos:
flagged(Booleano):truese o conteúdo violar os critérios de segurança.confidence(float,0.0a1.0): A confiança do avaliador na decisão.1.0significa uma violação certa,0.0significa certamente nenhuma violação e os valores intermediários refletem certeza parcial. Se o campo for omitido, o Unity AI Gateway assume1.0.
Qualquer resposta flagged: true aciona a ação de bloqueio, independentemente da confiança.
Contrato de fornecimento para higienização de guarda-corpos
O avaliador deve retornar um objeto JSON com os seguintes campos:
flagged(Booleano):truese o conteúdo corresponder aos critérios de segurança.sanitized_text(strings): O texto com o conteúdo correspondente substituído ou higienizado. Obrigatório quandoflaggedétrue. Quandoflaggedéfalse, a solicitação ou resposta passa sem alterações.
A resposta JSON do avaliador pode incluir texto ou código Markdown delimitando o conteúdo; o Unity AI Gateway extrai o objeto JSON de forma segura. Se a resposta não puder ser analisada, o mecanismo de proteção falha (consulte avaliação de falha fechada).
Mensagem do usuário
A mensagem do usuário contém o texto de uma única mensagem da solicitação ou resposta original, e não o histórico completo da conversa. Para garantir a segurança da entrada de dados, o Unity AI Gateway extrai o texto da última mensagem do usuário na solicitação. Para um limite de saída, ele extrai a resposta do assistente. O prompt do sistema do endpoint de inferência, as intervenções anteriores na conversa, os payloads de chamadas de ferramentas, os bytes de imagem e áudio e os blocos de raciocínio ou pensamento não são encaminhados.
Extração de campos por API
Os campos que o Unity AI Gateway lê dependem da API nativa do endpoint de inferência. Para matrizes de conteúdo multimodal, apenas os blocos do tipo texto são extraídos.
API | Input (last user message) | Output (assistant response) |
|---|---|---|
OpenAI Chat Completions, MLflow Chat |
|
|
Anthropic Messages |
|
|
OpenAI Responses |
|
|
Gemini generateContent |
|
|
Ao escrever um prompt personalizado, considere que o avaliador vê apenas o texto extraído, e não a conversa ao redor, o prompt do sistema ou o contexto da ferramenta.
Juntando tudo
A solicitação completa de conclusão do chat para o avaliador tem a seguinte aparência:
{
"model": "<evaluator endpoint>",
"stream": false,
"messages": [
{ "role": "system", "content": "<guardrail prompt>\n\n<output contract>" },
{ "role": "user", "content": "<extracted message text>" }
]
}
O aviso de segurança e o conteúdo em avaliação são passados como funções distintas, não concatenados. Isso mantém as instruções do avaliador separadas do conteúdo que está sendo avaliado.
Cada chamada de proteção consome tokens no endpoint do avaliador. A carga útil da solicitação (aviso de segurança, contrato de saída JSON e texto da mensagem extraído) e a resposta do avaliador contam para o uso do endpoint do avaliador e são cobradas na mesma unidade do modelo.
Atividade de proteção de auditoria
Habilite o acompanhamento de uso e as tabelas de inferência tanto no endpoint de inferência quanto no endpoint do avaliador para capturar dados de auditoria.
No endpoint de inferência, o acompanhamento de uso registra uma linha por solicitação, incluindo as bloqueadas. As solicitações aprovadas e sanitizadas registram o uso real de tokens com status 200. As solicitações bloqueadas por entrada registram o status 400 com 0 tokens de entrada e saída. As solicitações bloqueadas na saída registram o status 400 com as contagens reais de tokens do modelo de destino.
A tabela de inferência do endpoint de inferência registra uma linha por solicitação que alcançou o modelo de destino. Portanto, as solicitações bloqueadas por entrada estão ausentes da tabela de inferência (audite-as por meio do comando usage). As solicitações bloqueadas na saída aparecem na tabela de inferência com o corpo da resposta upstream bruta e o código de status substituído por 400.
No endpoint do avaliador, a tabela de inferência registra uma linha por chamada de proteção, com o corpo da solicitação descrito em "o que o avaliador recebe ", a resposta JSON bruta do avaliador, a latência, o código de status e o carimbo de data/hora. O acompanhamento de uso não inclui registros de chamadas do guardrail no endpoint do avaliador.
A tabela de inferência do endpoint de inferência e a tabela de inferência do endpoint de avaliação compartilham o mesmo request_id. Utilize este campo para rastrear uma decisão de proteção até a chamada original do cliente.
Avaliação de falha fechada
Os guardrails são do tipo "falha fechada". Se uma chamada de proteção falhar, expirar ou retornar uma resposta que o Unity AI Gateway não consiga analisar, a solicitação será bloqueada. Isso garante que as políticas de segurança e privacidade não possam ser contornadas por falhas transitórias do avaliador.
O erro do cliente reflete o modo de falha. Os tempos limite retornam DEADLINE_EXCEEDED. Quando o avaliador retorna um erro HTTP, o Unity AI Gateway propaga o código de erro correspondente, por exemplo PERMISSION_DENIED para 403. Outras falhas retornam INTERNAL_ERROR. Em todos os casos, o nome da proteção lateral com defeito é incluído na mensagem de erro.
Para testar uma nova proteção sem afetar o tráfego de produção, defina o modo da proteção para registro em Opções avançadas . No modo de registro (log mode), o guardrail avalia a solicitação ou resposta e registra o resultado, mas não bloqueia nem modifica o conteúdo. Um mecanismo de proteção no modo de registro que falha ou expira também é repassado silenciosamente, em vez de bloquear a solicitação. A tabela de proteções marca as proteções do modo logcom um ícone de proteção desativada ao lado da tag de ação.
Limitações
Os guarda-corpos apresentam as seguintes limitações:
- Capacidade por fase : Você pode configurar até três mecanismos de bloqueio, além de um mecanismo de sanitização, por fase de execução.
- Transmissão com restrições de saída : O Unity AI Gateway não suporta respostas de transmissão em endpoints que tenham restrições de saída configuradas. As solicitações com
stream=true(ou a variante streamGenerateContent Gemini) nesses endpoints são rejeitadas comINVALID_PARAMETER_VALUE: "Streaming responses with output guardrails are not supported. Disable streaming (stream=false) or remove the output guardrail."A transmissão com proteções somente de entrada é suportada. - Respostas de múltipla escolha com proteções de saída : o Unity AI Gateway não suporta solicitações com
n > 1(OpenAI Chat Completions, MLflow Chat) ougenerationConfig.candidateCount > 1(Gemini) no endpoint que tenha proteções de saída configuradas. Essas solicitações são rejeitadas comINVALID_PARAMETER_VALUE: "Multi-choice responses (n > 1 or candidateCount > 1) with output guardrails are not supported. Set n=1 (or candidateCount=1) or remove the output guardrail."Mensagens Anthropic e a API de Respostas OpenAI não possui parâmetro multi-alternativo e não é afetada. - Avaliação de mensagem única : Cada mecanismo de proteção avalia uma única mensagem por vez. Como o avaliador não agrega o contexto de múltiplas interações, ele não consegue detectar padrões que abrangem várias mensagens, como ataques de escalada gradual ou de manipulação de contexto. Este projeto garante que as entradas do avaliador permaneçam limitadas e com bom desempenho. Veja o que o avaliador recebe.