Pular para o conteúdo principal
Última atualização em

Crie e anexe uma política de serviço

info

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.

Para criar uma política de serviço, você escreve uma função de política SQL e, em seguida, anexa-a a um serviço MCP, serviço de modelo ou serviço de provedor de modelo por meio da interface de 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.

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 criar a função de política: privilégio CREATE FUNCTION no esquema de destino.
  • Para anexar uma política a um serviço: MANAGE no ativo protegível do serviço de destino **e** EXECUTE na função de política.

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:

SQL
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.

Escrever uma política de decisão​

Uma Política de Decisão retorna um VARIANT com um campo result de ALLOW, DENY ou ASK e um reason opcional. Crie 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 o reason em um objeto databricks_service_policy de nível superior.
  • ASK: a interação faz uma pausa para aprovação humana antes de continuar.

Para o subconjunto SQL compatível e as regras para retornar um VARIANT, consulte Referência da Função de Política de Serviço.

Exemplo: negar um push do GitHub de um serviço MCP.

Esta política bloqueia qualquer chamada para a ferramenta push_files e permite todas as outras interações. Como a política está anexada a um serviço MCP específico, a função só precisa verificar o nome da ferramenta:

SQL
CREATE OR REPLACE FUNCTION main.governance.block_github_push(
  event VARIANT
)
RETURNS VARIANT
LANGUAGE SQL
RETURN
  CASE
    WHEN event:type::string = 'request'
      AND event:context.tool.name::string = 'push_files'
    THEN to_variant_object(named_struct('result', 'DENY', 'reason', 'GitHub push operations are not permitted by policy.'))
    ELSE to_variant_object(named_struct('result', 'ALLOW', 'reason', ''))
  END;

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.

SQL
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.

Para mais políticas personalizadas, incluindo listas de permissão de ferramentas, bloqueios de palavras-chave e tópicos, limites de tamanho de prompt, verificações de resposta e classificadores de LLM-as-a-judge, consulte Exemplos de políticas de serviço.

O passo 2: Anexar a política a um serviço​

Durante a versão Beta, você anexa uma política de serviço por meio da interface do Unity Gateway , em um MCP Service, Model Service ou Model Provider Service individual. Você pode anexar mais de uma política a um serviço: cada anexo tem uma prioridade (classificação), e a cadeia para no primeiro DENY. Na fase de entrada, as políticas são avaliadas em ordem crescente de classificação (a mais baixa primeiro); na fase de saída, na ordem inversa.

Para anexar uma política:

  1. Na barra lateral do workspace, clique em AI Gateway .

  2. 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 .

  3. Abra a tab Políticas , então clique em Nova política .

  4. Insira um Nome para a política.

  5. Em Aplicado a , selecione a quais entidades de segurança a política se aplica. O default, Todos os usuários da conta , aplica-o a todos.

  6. Em Tipo de barreira de segurança , selecione a execução da política:

    • Uma barreira de segurança integrada, como Conteúdo inseguro ou Jailbreak . O serviço de modelo do Avaliador que executa a verificação (o juiz de LLM) está pré-selecionado; para usar um diferente, expanda Opções avançadas e selecione-o (você precisa de CAN_QUERY no modelo que escolher).
    • Personalizado : clique em Função personalizada , em seguida, em Selecionar função e selecione a função SQL que você escreveu no o passo 1.

  7. Em Phase , selecione onde a política é executada: Input guardrails (ON CALL, antes de o serviço ser invocado), Output guardrails (ON RESULT, depois que ele responder) ou ambos. A seleção de fases se aplica a guardrails integrados e políticas personalizadas de LLM-as-a-judge . Alguns guardrails integrados são executados em apenas uma fase, como a detecção de jailbreak na entrada e a detecção de alucinação na saída. A custom SQL function não tem configuração de Phase : ela é executada em ambas as fases, portanto, Branch em event:type no corpo da função para delimitar seu comportamento (consulte o o passo 1).

  8. 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.

  9. Clique em Criar política .

A política aparece na tab Políticas do serviço. Durante a versão Beta, aguarde um curto período para que ela seja propagada antes de testar.

nota

Durante a fase Beta, a IU da política pode mudar. Se um rótulo diferir destes os passos, siga os rótulos no produto.

Usar uma política integrada​

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. Para usar uma, siga o Passo 2, mas escolha a barreira de proteção integrada em Guardrail type em vez de Custom . As barreiras de proteção integradas não exigem nenhuma configuração específica de política. Você define os campos padrão Phase , Rank , Evaluator model service e Mode ao anexá-las.

Para obter 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.

É necessário ter o privilégio EXECUTE na função de política integrada e MANAGE no serviço de destino.

Verificar a política​

Depois de anexar uma política, verifique se ela está ativa e produzindo os resultados esperados.

nota

Depois de anexar ou alterar uma política, aguarde um curto período para que a alteração entre em vigor antes de testar. Durante o beta, as alterações de política podem levar um ou dois minutos para serem propagadas.

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 objeto databricks_service_policy de nível superior carrega o reason que você especificou. ASK pausa a chamada para aprovação humana.
  • Em tabelas do sistema : a atividade do modelo e do MCP é registrada nas tabelas de uso, e cargas úteis de solicitação e resposta completas nas tabelas 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.

Para ver o raciocínio completo por trás de uma decisão de LLM-como-juiz integrada ou personalizada, incluindo a confiança do avaliador e o conteúdo exato que ele julgou, revise a tabela de inferência do serviço de modelo do 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 com flagged, confidence e, quando flagged for true, reason.
  • destination_name identifica o avaliador, e request_id vincula 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:

SQL
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.

nota

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 resposta databricks-request-id da chamada e, em seguida, filtre WHERE request_id = '<id>'. Isso funciona para um bloqueio. Confirme se o valor do cabeçalho corresponde à coluna, pois o campo id do corpo da resposta é um valor diferente.
  • Conteúdo da solicitação : o request do 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 MINUTES limita 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.

SQL
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, com uma tabela de inferência habilitada em seu avaliador. Inspecione os vereditos no tráfego real, refine o prompt e a classificação e, em seguida, alterne a política para Aplicar . A Detecção de dados confidenciais é executada apenas no modo de aplicação.

Direitos de acesso​

Os passos acima exigem os seguintes privilégios:

Passo

Acesso necessário

Anexar a barreira de segurança

MANAGE no serviço de destino (protegido) e EXECUTE na função de política que você anexa. Consulte a Etapa 2.

Selecionar um avaliador não default

CAN_QUERY no serviço de modelo de avaliador que você escolher.

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 USE CATALOG, USE SCHEMA e CREATE TABLE no catálogo e no esquema onde a tabela está armazenada. Consulte os pré-requisitos da tabela de inferência.

Leia a tabela de inferência do avaliador

SELECT na tabela, além de USE CATALOG e USE SCHEMA no catálogo e esquema correspondentes. O criador do serviço do modelo é o proprietário da tabela e concede acesso a outros usuários.

Passo

Acesso necessário

Anexar a barreira de segurança

MANAGE no serviço de destino (protegido) e EXECUTE na função de política que você anexa. Consulte a Etapa 2.

Selecionar um avaliador não default

CAN_QUERY no serviço de modelo de avaliador que você escolher.

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 USE CATALOG, USE SCHEMA e CREATE TABLE no catálogo e no esquema onde a tabela está armazenada. Consulte os pré-requisitos da tabela de inferência.

Leia a tabela de inferência do avaliador

SELECT na tabela, além de USE CATALOG e USE SCHEMA no catálogo e esquema correspondentes. O criador do serviço do modelo é o proprietário da tabela e concede acesso a outros usuários.

Limitações​

As seguintes limitações se aplicam durante a versão beta:

  • Transformação : As políticas de serviço retornam uma decisão (PERMITIR, DENY ou PERGUNTAR); elas não transformam o conteúdo da solicitação ou da resposta durante a versão beta.
  • 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.
Nesta página