Crie e anexe uma política de serviço
Beta
Este recurso está em Beta. Administradores da account podem controlar o acesso a este recurso na página Previews do console da account. Consulte Gerenciar prévias do Databricks.
Para uma visão geral das políticas de serviço, consulte Políticas de serviço para recursos protegíveis de AI.
Você cria uma política de serviço e a anexa a um MCP Serviço, Model Serviço ou Model Provider Serviço por meio da interface do usuário do Unity Gateway . A política rege cada interação em dois pontos de avaliação:
- A fase de entrada (ON CALL) antes de o Databricks invocar o serviço.
- A fase de saída (ON RESULT) após a resposta do serviço.
Escolha um tipo de política
Tipo de política | Use-o para | O que você fornece |
|---|---|---|
Riscos comuns, como conteúdo inseguro, tentativas de jailbreak, alucinações e dados confidenciais. | Nada. Você seleciona o guardrail e o anexa. | |
Regras semânticas que você pode descrever em linguagem simples, como manter um assistente no assunto. | Um prompt que descreve o que sinalizar. | |
Regras determinísticas, como verificações de nomes de ferramentas, argumentos de ferramentas ou a identidade do chamador, e retenção de uma chamada para aprovação humana ( | Uma função definida pelo usuário (UDF) SQL registrada no Unity Catalog. | |
Como impor as decisões de um fornecedor de guardrail terceirizado que você já utiliza. | Uma conexão HTTP do Unity Catalog com o Endpoint do fornecedor. |
Comece com um guardrail integrado quando ele cobrir o seu risco. Para uma regra que nenhuma opção integrada cubra, use uma política de LLM-como-juiz personalizada ou uma função SQL quando a regra precisar ser determinística ou depender de quem está chamando.
Você pode anexar mais de uma política a um serviço. Cada anexo tem uma prioridade (classificação), e uma DENY em uma classificação interrompe a avaliação de todas as classificações posteriores. Na fase de entrada, as classificações são avaliadas em ordem crescente (da menor para a maior). Na fase de saída, elas são avaliadas na ordem inversa. Políticas na mesma classificação podem todas ter execução mesmo após uma delas negar o acesso. Consulte Ordem de avaliação.
Pré-requisitos
- Um administrador de account deve habilitar a versão beta para sua account na página Prévias no console da account.
- Para anexar qualquer política a um serviço:
MANAGEno securitizável do serviço de destino. - Para uma barreira de segurança integrada ou uma política personalizada de LLM como juiz com um avaliador diferente do default:
EXECUTEno serviço de modelo de avaliador escolhido, além deUSE CATALOGeUSE SCHEMAem seu catálogo e esquema. Consulte Conceder acesso a um serviço de modelo. - Para uma política SQL personalizada: privilégio
CREATE FUNCTIONno esquema de destino para criar a função de política eEXECUTEna função de política para anexá-la. - Para uma política de serviço externo:
USE CONNECTIONna conexão HTTP do Unity Catalog. Consulte Antes de começar.
If a rótulo differs from these os passos, follow the in-produto rótulos. A policy applies to all account users on the serviço, so leave Applied to set to All account users .
Attach an integrada policy
O Databricks fornece políticas de serviço integradas sob o namespace system.ai, como system.ai.block_unsafe_content para bloquear conteúdo inseguro ou prejudicial. Eles cobrem riscos comuns sem nenhum código. Para ver a lista completa de políticas integradas e uma observação sobre como elas aparecem no Unity Catalog, consulte Políticas de serviço integradas.
Os passos seguintes associam a barreira de proteção Unsafe Content a um serviço:
- Na barra lateral do workspace, clique em AI Gateway .
- Selecione o serviço a governar: um serviço de modelo na tab Models , um serviço de provedor de modelos na tab Providers , ou um serviço MCP na tab MCPs .
- Abra a tab Políticas , então clique em Nova política .
- Insira um Nome para a política, como
block_unsafe_content. - Em Guardrail type , selecione uma barreira de proteção integrada, como Unsafe Content ou Jailbreak .
- Defina a **Classificação** para controlar a ordem de avaliação. A menor classificação tem a execução primeiro na solicitação e por último na resposta.
- Em Fase , selecione onde a política é executada: Barreiras de segurança de entrada (ON CALL, antes de o serviço ser invocado), Barreiras de segurança de saída (ON RESULT, após a resposta) ou ambas. Algumas barreiras de segurança integradas estão em execução em apenas uma fase, como a detecção de quebra de restrições na entrada e a detecção de alucinação na saída.
- (Opcional) Em um serviço de modelo ou serviço de provedor de modelos, defina a Janela de conversa : quantas interações recentes da conversa o juiz avalia na solicitação. Por default, são 10 turnos. Defina como 1 para avaliar somente a mensagem mais recente ou selecione Avaliar a conversa inteira .
- (Opcional) Expanda Opções avançadas . O Serviço de modelo de avaliador que execução a verificação (o juiz de LLM) está pré-selecionado. Para usar um diferente, selecione-o aqui. Você precisa de
EXECUTEno serviço de modelo escolhido, além deUSE CATALOGeUSE SCHEMAem seu catálogo e esquema. Para registrar veredictos sem bloquear, defina Mode como Log . - Clique em Criar política .
A política aparece na tab Policies do serviço. Aguarde alguns instantes para que a alteração seja propagada antes de testar.
As barreiras de proteção integradas não aceitam nenhuma configuração específica de política. Você define apenas os campos standard Phase , Rank , Evaluator model serviço e Mode . A barreira de proteção determinística Sensitive Data Detection é a exceção: ela também aceita tags de classificação e uma ação. Consulte Detectar dados confidenciais com uma política de serviço.
Criar uma política de LLM-como-juiz
Uma política personalizada de LLM como juiz usa um modelo avaliador para classificar uma solicitação ou resposta em relação aos critérios descritos em linguagem natural. Use-o para verificações semânticas que uma regra determinística não pode expressar, como se uma mensagem está no tópico ou se uma resposta permanece profissional. Você escreve os critérios como um prompt, não como código.
Os passos seguintes anexam uma política que mantém um assistente de suporte focado no assunto:
-
Na barra lateral do workspace, clique em AI Gateway .
-
Selecione o serviço a governar: um serviço de modelo na tab Models , um serviço de provedor de modelos na tab Providers , ou um serviço MCP na tab MCPs .
-
Abra a tab Políticas , então clique em Nova política .
-
Insira um Nome para a política, como
keep_on_topic. -
Em Guardrail type , selecione Custom .
-
Defina a **Classificação** para controlar a ordem de avaliação. A menor classificação tem a execução primeiro na solicitação e por último na resposta.
-
Em Implementation , selecione LLM-as-a-judge .
-
Em Phase , selecione onde ocorre a execução da política: Input guardrails (ON CALL, antes de o serviço ser invocado), Output guardrails (ON RESULT, após a resposta) ou ambos. Uma verificação de aderência a tópicos como esta é uma execução na entrada.
-
Selecione um serviço de modelo do Avaliador . Você precisa de
EXECUTEno serviço de modelo escolhido, além deUSE CATALOGeUSE SCHEMAno catálogo e no esquema dele. -
Em Prompt , descreva o que o avaliador deve sinalizar e o que deve ignorar. Por exemplo:
You are reviewing messages sent to a customer-support assistant that may only help with the company's produtos, orders, billing, and account support. Sinalize a mensagem se ela solicitar algo fora desse escopo, como ajuda geral com código, redação de ensaios, curiosidades irrelevantes ou uso do assistente como um chatbot de uso geral. Não sinalize uma dúvida legítima sobre o produto ou suporte.
Não grave
ALLOWouDENYno prompt e não especifique um formato de saída. O Databricks adiciona um contrato de saída estruturada ao seu prompt, para que o avaliador retorne um veredicto em JSON. Quando o avaliador sinaliza o conteúdo, o Databricks bloqueia a interação. -
(Opcional) Em um serviço de modelo ou serviço de provedor de modelos, defina a janela de conversa : quantos turnos recentes da conversa o juiz avalia na solicitação. O valor default é 10 turnos. Defina como 1 para avaliar somente a mensagem mais recente ou selecione Avaliar a conversa inteira . A janela se aplica somente à avaliação da entrada.
-
(Opcional) Expanda Opções avançadas e defina Mode como Log para registrar veredictos sem bloquear enquanto você ajusta o prompt.
-
Clique em Criar política .
A política aparece na tab Policies do serviço. Aguarde alguns instantes para que a alteração seja propagada antes de testar.
O avaliador é um modelo, portanto, seus veredictos são não determinísticos. O Databricks recomenda começar no modo Log e revisar os possíveis veredictos na tabela de rastreamento unificada. Consulte Não determinismo e testes de simulação. Para obter mais prompts, práticas recomendadas para escrevê-los e exemplos de turnos múltiplos, consulte LLM-as-a-judge policy examples.
Crie uma política SQL
Uma política SQL personalizada é uma função SQL que retorna uma decisão. Use-o quando a regra deve ser determinística, quando depende do nome ou dos argumentos de uma ferramenta ou de quem está chamando, ou quando deve reter uma chamada para aprovação humana (ASK).
O passo 1: escrever a função de política
Uma função de política de serviço é uma UDF SQL registrada no Unity Catalog. Ele recebe um único parâmetro VARIANT, event (os dados e o contexto de interação), e retorna um resultado VARIANT:
CREATE OR REPLACE FUNCTION <catalog>.<schema>.<function_name>(
event VARIANT
)
RETURNS VARIANT
LANGUAGE SQL
RETURN <expression>;
A função é executada em ambos os pontos de avaliação; faça branch em event:type::string ('request' para a fase de entrada, 'response' para a fase de saída) para atuar em uma única fase. Para os campos event completos, o valor de retorno e o subconjunto SQL compatível, consulte Referência da função de política de serviço.
A função retorna uma decisão: um VARIANT com um campo result de ALLOW, DENY ou ASK e um reason opcional. Compile o resultado com named_struct e envolva-o em to_variant_object para que a função retorne um VARIANT, mantendo result e reason como campos de nível superior.
O valor result determina o que acontece (não diferencia maiúsculas de minúsculas):
ALLOW: a interação prossegue.DENY: O Databricks bloqueia a interação. Em vez de um erro, o chamador recebe uma resposta bem-sucedida (HTTP 200) cujo turno do assistente relata o bloqueio, com oreasonem um objetodatabricks_service_policyde nível superior.ASK: em um serviço MCP, a solicitação entra em pausa para aprovação do usuário antes da execução da ferramenta. Se uma política personalizada do SQL ou do Python retornarASKpara um Model serviço ou Model Provider serviço, o Databricks bloqueará a solicitação ou a resposta, pois esses serviços não podem solicitar a aprovação do usuário.
Exemplo: negar um push no GitHub quando um agente age em nome de um usuário
Para remover uma ferramenta para todos os chamadores, use a seleção de ferramentas em vez de uma política de serviço. Uma política de serviço é útil quando a decisão depende de quem está fazendo a chamada. Esta política permite que as pessoas chamem a ferramenta push_files diretamente, mas a nega quando um agente ou aplicativo a chama em nome do usuário (on-behalf-of ou OBO), conforme relatado por event:context.actor.context.is_on_behalf_of:
CREATE OR REPLACE FUNCTION main.governance.block_agent_github_push(
event VARIANT
)
RETURNS VARIANT
LANGUAGE SQL
RETURN
CASE
WHEN event:type::string = 'request'
AND event:context.tool.name::string = 'push_files'
AND event:context.actor.context.is_on_behalf_of::boolean = true
THEN to_variant_object(named_struct('result', 'DENY', 'reason', 'Agents cannot push to GitHub on behalf of a user. Push the change yourself.'))
ELSE to_variant_object(named_struct('result', 'ALLOW', 'reason', ''))
END;
Para permitir agentes específicos em vez de bloquear todos eles, verifique o ID do cliente OAuth do agente. Consulte Restringir uma ferramenta sensível a agentes aprovados. Para ver a lista completa de campos de ator, consulte Referência da função de política de serviço.
Exemplo: exigir aprovação humana antes da execução de uma ferramenta destrutiva
Esta política pausa qualquer chamada à ferramenta delete_repository para aprovação humana e permite todas as outras interações.
CREATE OR REPLACE FUNCTION main.governance.ask_before_repo_delete(
event VARIANT
)
RETURNS VARIANT
LANGUAGE SQL
RETURN
CASE
WHEN event:context.tool.name::string = 'delete_repository'
THEN to_variant_object(named_struct('result', 'ASK', 'reason', 'Deleting a repository requires human approval.'))
ELSE to_variant_object(named_struct('result', 'ALLOW', 'reason', ''))
END;
Quando esta política retorna PEDIR, o Databricks pausa a chamada para aprovação humana antes da execução.
Para agentes externos que chamam os serviços MCP, a Databricks entrega a decisão de aprovação usando a eliciação de modo de URL MCP: o usuário abre a URL fornecida para aprovar ou recusar a chamada. O agente externo deve tentar a chamada novamente após a aprovação. Para usar o ASK com um agente externo, o cliente MCP do agente deve suportar a versão 2025-11-25 do protocolo MCP ou posterior.
Para Serviços MCP, aprovar uma chamada de ferramenta armazena a aprovação em cache por uma hora, para que uma chamada idêntica não seja solicitada novamente dentro dessa janela de tempo.
ASK a aprovação está disponível apenas para serviços MCP durante a fase de entrada. Se uma política personalizada de SQL ou Python retornar ASK para um serviço de modelo ou serviço de provedor de modelo, o Databricks bloqueará a solicitação ou a resposta porque esses serviços não podem solicitar aprovação ao usuário.
Para obter mais políticas personalizadas, incluindo listas de permissões de ferramentas, blocos de palavras-chave e tópicos, limites de comprimento de prompt e verificações de resposta, consulte Exemplos de políticas de serviço.
o passo 2: Anexar a função a um serviço
- Na barra lateral do workspace, clique em AI Gateway .
- Selecione o serviço a governar: um serviço de modelo na tab Models , um serviço de provedor de modelos na tab Providers , ou um serviço MCP na tab MCPs .
- Abra a tab Políticas , então clique em Nova política .
- Insira um Nome para a política.
- Em Guardrail type , selecione Custom .
- Defina a **Classificação** para controlar a ordem de avaliação. A menor classificação tem a execução primeiro na solicitação e por último na resposta.
- Em Implementation , selecione Custom function , clique em Select function e selecione a função SQL que você escreveu no passo 1.
- Clique em Criar política .
Uma função SQL personalizada não tem configuração de Phase : ela tem execução em ambas as fases, portanto, Branch em event:type no corpo da função para definir o escopo de seu comportamento (consulte o passo 1). A política aparece na tab Policies do serviço. Aguarde um pouco para que ele se propague antes de testar.
Anexar uma política de serviço externo
Uma política de serviço externo envia o conteúdo sob avaliação para um fornecedor de barreira de proteção de terceiros e aplica o veredito ALLOW ou DENY do fornecedor. Para usar uma, abra a Policies tab do serviço e clique em New policy , depois escolha External em Guardrail type e selecione ou crie a conexão HTTP do Unity Catalog com o endpoint do seu fornecedor. Defina os campos Phase , Rank , Policy configuration (opcional) e Mode como faria para qualquer política.
Você precisa de MANAGE no serviço de destino e de USE CONNECTION na conexão. Você não precisa de uma função de política. Para a configuração completa, incluindo os campos de conexão, o conteúdo enviado ao fornecedor e o comportamento de falha fechada (fail-closed), consulte Impor um guardrail de parceiro com uma política de serviço externa.
Verificar a política
Depois de anexar uma política, verifique se ela está ativa e produzindo os resultados esperados.
Após anexar ou alterar uma política, aguarde um pouco para que a alteração entre em vigor antes de testar. As alterações de política normalmente levam um ou dois minutos para se propagar.
Confirmar anexo
No Unity Gateway, abra o serviço de destino e visualize as políticas anexadas a ele. A política que você criou aparece na lista.
Observar resultados de política
É possível confirmar que uma política está entrando em vigor:
- Do chamador : quando a política retorna
DENY, o chamador recebe uma resposta bem-sucedida (HTTP 200) em vez de um erro. O turno do assistente relata que o conteúdo foi bloqueado, e um objetodatabricks_service_policyde nível superior carrega oreasonque você especificou.ASKpausa a chamada para aprovação humana. - Na tabela de rastreamento unificada : a tabela de rastreamento unificada registra todas as solicitações em seus serviços do Unity Gateway, com um evento
policy_evaluatedpara cada política e fase em execução, incluindo a ação tomada. Consulte Eventos de avaliação de política. - Nas tabelas do sistema : a atividade de modelo e MCP é registrada nas tabelas de uso e, para um serviço com uma tabela de inferência, as cargas úteis completas de solicitação e resposta na sua tabela de inferência.
Depurar e auditar uma decisão de política
Quando uma política bloqueia uma interação, o bloco reason no objeto databricks_service_policy nomeia a política e fornece uma breve explicação. Consulte Observar resultados de política.
To find which policies ran on a request and what each decided, começar with the unified trace table. A metastore admin sets it up one time for all Unity Gateway serviços, and each request's span carries a policy_evaluated event for every policy and phase that ran, with the policy's name, type, and action. For a policy in Log mode, the event also records the would-be verdict in policy.dry_run_action and policy.dry_run_reason. See Policy evaluation events.
O rastreamento registra a ação de cada política de LLM como juiz, mas não o raciocínio do avaliador. Para ver o raciocínio completo por trás de uma decisão de LLM-as-a-judge integrada ou personalizada, incluindo a confiança do avaliador e o conteúdo exato avaliado, analise a tabela de inferência do serviço de modelo avaliador.
Uma política de LLM-como-juiz executa seu prompt em um serviço de modelo avaliador separado (o juiz). O veredito do juiz não é registrado na tabela de inferência do serviço protegido, que Logs apenas a solicitação e a resposta do próprio serviço protegido. A entrada e o veredito do juiz são capturados apenas quando uma tabela de inferência é habilitada no serviço de modelo avaliador .
Capturar os vereditos do avaliador
Habilite uma tabela de inferência no serviço de modelo que executa a verificação. Você tem duas opções:
- Habilite uma tabela de inferência diretamente no avaliador que a barreira de proteção já utiliza. O avaliador default é um serviço de modelo
system.ai, e você pode habilitar uma tabela de inferência nele. - Em Opções avançadas , ao anexar a política, aponte a barreira de segurança para um serviço de modelo de avaliador que você possui (não precisa ser um modelo
system.ai), então habilite uma tabela de inferência nesse serviço.
Para habilitar uma tabela de inferência, consulte Fazer log de solicitações e respostas em tabelas de inferência. Habilite-o antes das interações que deseja auditar: apenas as avaliações executadas após a habilitação do log são capturadas, e as linhas podem levar alguns minutos para aparecer.
Ler um veredito
Cada avaliação grava uma linha por política por fase na tabela de inferência do avaliador:
requesté o prompt do juiz montado: os critérios da política, o contrato de saída JSON e o conteúdo sob avaliação envolvido em marcadores<ContentToEvaluate>. Para uma política de entrada de vários turnos (janela de conversa), o conteúdo avaliado são os turnos recentes mais a entrada mais recente; caso contrário, é a mensagem única.responseé a conclusão bruta do avaliador. O veredito é o conteúdo da mensagem do assistente: um objeto JSON comflagged,confidencee, quandoflaggedfortrue,reason.destination_nameidentifica o avaliador, erequest_idvincula a avaliação à interação que a Trigger.
Para localizar as avaliações em que o juiz sinalizou conteúdo, filtre a tabela de inferência do avaliador pelo veredito:
SELECT
event_time,
request_id,
get_json_object(response, '$.choices[0].message.content') AS verdict,
request
FROM <catalog>.<schema>.<evaluator_inference_table>
WHERE get_json_object(response, '$.choices[0].message.content') ILIKE '%"flagged":true%'
ORDER BY event_time DESC;
A coluna verdict mostra a decisão do avaliador, tal como {"flagged":true,"confidence":0.87,"reason":"..."}. Um reason aparece apenas quando flagged for true. Um veredito sinalizado é a decisão do juiz, e não a prova de que a interação foi bloqueada. No modo Log , um possível DENY é registrado aqui, mas não aplicado, e a tabela não registra o modo; portanto, confirme um bloqueio real na resposta databricks_service_policy do chamador (consulte Observar resultados da política). Para rastrear uma interação específica, filtre pelo request_id dela.
Audite os bloqueios da tabela de inferência do avaliador, não do serviço protegido. Quando uma política de fase de entrada nega uma solicitação, o Databricks não invoca o serviço subjacente, portanto, uma interação bloqueada pode não produzir uma linha na tabela de inferência do serviço protegido. Portanto, obter IDs de solicitação da tabela protegida perde interações bloqueadas; filtre a tabela do avaliador pelo veredito.
Restringir a uma interação em uma tabela grande
A tabela de inferência do avaliador não tem uma coluna de nome de política, e o id no corpo da resposta (chatcmpl-...) não é o request_id. Refine para a interação que você está em depuração com estes filtros e limite a verificação por tempo:
request_id(mais preciso): cada avaliação para uma interação a compartilha. Capture-o do cabeçalho de respostadatabricks-request-idda chamada e, em seguida, filtreWHERE request_id = '<id>'. Isso funciona para um bloqueio. Confirme se o valor do cabeçalho corresponde à coluna, pois o campoiddo corpo da resposta é um valor diferente.- Conteúdo da solicitação : o
requestdo juiz contém o conteúdo avaliado, portanto, uma string distinta em seu prompt pin a interação, por exemplo,request ILIKE '%<your marker>%'. - Tempo :
event_time >= current_timestamp() - INTERVAL 30 MINUTESlimita a verificação.
Para saber qual política produziu uma linha, leia seu request. A mensagem do sistema é o critério dessa política, para que você possa filtrar e identificar a política. Por exemplo, request ILIKE '%<distinctive phrase from the policy prompt>%'. O reason no veredito geralmente reafirma o trigger.
SELECT event_time, request_id, invocation_id,
get_json_object(response, '$.choices[0].message.content') AS verdict,
request
FROM <catalog>.<schema>.<evaluator_inference_table>
WHERE event_time >= current_timestamp() - INTERVAL 30 MINUTES
AND request ILIKE '%<your marker or prompt text>%'
AND get_json_object(response, '$.choices[0].message.content') ILIKE '%"flagged":true%'
ORDER BY event_time DESC;
Não determinismo e testes de execução de teste
O avaliador é um modelo, portanto seus vereditos não são determinísticos: a mesma entrada pode retornar vereditos diferentes entre execuções, e a variação é maior entre diferentes modelos de avaliador ou quando o roteamento de solicitação abrange versões de modelo. O reason é um texto livre curto, não dados estruturados por entidade, e pode citar o conteúdo sinalizado. Para uma verificação determinística e repetível, use a política integrada Detecção de dados confidenciais ou uma política SQL personalizada em vez de um juiz de LLM.
O Databricks recomenda anexar uma política de LLM como juiz primeiro no modo Log , que registra o veredito sem bloquear. Analise os possíveis vereditos na tabela de rastreamento unificada e habilite uma tabela de inferência no avaliador se você também precisar da confiança dele e do conteúdo avaliado. Inspecione os vereditos no tráfego real, refine o prompt e a classificação e, em seguida, alterne a política para Impor . A Detecção de dados confidenciais está em execução apenas no modo de imposição.
Direitos de acesso
Os passos acima exigem os seguintes privilégios:
Passo | Acesso necessário |
|---|---|
Anexar a barreira de segurança |
|
Selecionar um avaliador não default |
|
Habilitar uma tabela de inferência no avaliador | Permissão para gerenciar o serviço de modelo do avaliador (por exemplo, você o criou), além de |
Leia a tabela de inferência do avaliador |
|
Limitações
Aplicam-se as seguintes limitações:
- Transformação : políticas de serviço retornam uma decisão (ALLOW, DENY ou ASK) e não transformam o conteúdo da solicitação ou da resposta.
- Linguagem de política : as funções de política personalizada oferecem suporte apenas a
LANGUAGE SQL. - Escopo do anexo : A anexação da política é somente pela IU e restrita a um serviço individual, e a política se aplica a todos os usuários da account. A anexação de políticas em nível de catálogo ou esquema, condições de controle de acesso baseado em atributos (ABAC) e entidades de segurança personalizadas não estão disponíveis.