Aplicar um guardrail de parceiro com uma política de serviço externo
Beta
Esse recurso está em Beta. Os administradores do account podem controlar o acesso a esse recurso na página Pré-visualizações do console do account. Consulte Gerenciar prévias do Databricks.
Uma política de serviço externo impõe as decisões de um fornecedor de guardrail que você já usa, como um serviço de segurança de AI ou de prevenção contra perda de dados, no tráfego pelo Unity Gateway. Em cada chamada governada, o Databricks envia o conteúdo sob avaliação para o endpoint do seu fornecedor. O fornecedor retorna permitir ou negar, e o Databricks aplica essa decisão, sem alterações em seus aplicativos.
You attach an external política de serviço to a Model Serviço , Model Provider Serviço , or MCP Serviço , the same way you attach any política de serviço.
Como funcionam as políticas de serviço externo
Uma política de serviço externo tem três partes:
- Uma conexão HTTP do Unity Catalog armazena a URL do endpoint do seu fornecedor e suas credenciais de OAuth. Várias políticas podem compartilhar uma conexão.
- A política de serviço externa está anexada a um serviço. Ela nomeia a conexão e define a fase, a classificação (rank), o modo e uma configuração de política opcional. O Databricks realiza a execução em cada solicitação e aplica o resultado.
- A barreira de segurança do seu fornecedor inspeciona o conteúdo e retorna um veredito:
ALLOWouDENY, com um motivo opcional.
Seu fornecedor deve implementar a API de política externa do Databricks, que define a solicitação que o Databricks envia e o veredito esperado. Pergunte ao seu fornecedor se eles oferecem suporte e solicite os detalhes do Endpoint. O Databricks não cria nem mantém integrações para fornecedores individuais.
Antes de começar
Você precisa de:
- Um endpoint do seu fornecedor de guardrail que implementa a API de política externa do Databricks.
- Credenciais do OAuth machine-to-machine (M2M) para esse Endpoint: um ID de cliente, um segredo de cliente e a URL do Endpoint de tokens do fornecedor. O OAuth M2M é o único método de autenticação compatível. Chaves de API, autenticação básica e OAuth user-to-machine não são compatíveis.
- Permissões para criar a conexão : o privilégio
CREATE CONNECTION, além deUSE CATALOGeUSE SCHEMAno catálogo e no esquema onde a conexão está armazenada. - Permissões para anexar a política :
MANAGEno serviço que você deseja governar,USE CONNECTIONna conexão eUSE CATALOGeUSE SCHEMAno catálogo e no esquema da conexão.
Os dois conjuntos de permissões podem pertencer a pessoas diferentes. Se a pessoa que anexar a política não tiver CREATE CONNECTION, a pessoa que gerencia as credenciais do fornecedor poderá criar a conexão antecipadamente e conceder USE CONNECTION a ela.
O passo 1: Create a connection to your vendor
A conexão é um objeto do Unity Catalog que armazena o endpoint e as credenciais do seu fornecedor. Você pode criá-lo de duas maneiras:
- Ao anexar a política : no formulário de política, selecione Criar nova conexão . Esta é a opção mais rápida para um único guardrail.
- Ahead of time : create an HTTP connection with OAuth machine-to-machine authentication in Catalog Explorer or with
CREATE CONNECTION, then select Use existing connection in the policy form. Use this option when several policies share one endpoint, or when a different team gerencia the vendor credentials. See Create a connection to the external serviço.
Quando você criar a conexão a partir do formulário de política, insira o seguinte:
campo | Descrição |
|---|---|
Nome da conexão | Um nome para a conexão do Unity Catalog, por exemplo, |
Catálogo e Esquema | Onde a conexão é armazenada no Unity Catalog. |
Host | O host do fornecedor, incluindo o esquema, por exemplo |
Caminho da API (opcional) | Um caminho nesse host, por exemplo |
Tipo de autenticação | Sempre OAuth M2M . Este campo não pode ser alterado. |
Client ID e Client secret | As credenciais da account de serviço emitidas pelo fornecedor. |
Endpoint de token | O URL do token OAuth do seu fornecedor, por exemplo, |
Escopo OAuth (opcional) | Escopos separados por espaço, se exigidos pelo seu fornecedor, por exemplo, |
Geralmente, os fornecedores atendem a muitas políticas a partir de um único endpoint e as diferenciam com a configuração de política definida no o passo 2. Em geral, você cria uma conexão por endpoint de fornecedor, e não uma por política.
O passo 2: Anexar a política de serviço externo
-
Na barra lateral do workspace, clique em AI Gateway .
-
Selecione o serviço para governar: a model serviço on the Models tab, a model provider serviço on the Providers tab, or an MCP serviço on the MCPs tab.
-
Abra a Políticas tab e clique em Nova política .
-
Insira um Nome para a política.
-
Em Guardrail type , selecione External .
-
Defina a Classificação para controlar a ordem de avaliação em relação a outras políticas no serviço. A menor classificação entra em execução primeiro na solicitação e por último na resposta, e um
DENYinterrompe todas as classificações posteriores. Na mesma classificação, apenas umDENYde uma política de LLM-como-juiz bloqueadora ignora a chamada para o seu fornecedor. UmDENYde uma política SQL personalizada ou de outra política sequencial na mesma classificação não faz isso, portanto, o seu fornecedor ainda recebe o conteúdo. Para ignorar a chamada do fornecedor quando essa política negar, coloque-a em uma classificação que seja avaliada antes da classificação da política de serviço externo. Consulte Ordem de avaliação. -
Under Phase , select Input guardrails (before the serviço is called), Output guardrails (after it responds), or both. Choose input only if your vendor inspects only requests. Each phase is a separate call to your vendor, so selecting both phases roughly doubles the number of calls.
-
Selecione a conexão. Escolha Use existing connection e selecione-a na lista, ou escolha Create new connection e preencha os campos de o passo 1.
-
(Opcional) em Configuração da política , insira um objeto JSON, por exemplo
{"profile": "strict"}. O Databricks não lê esse valor. Ele transmite o texto ao seu fornecedor em cada solicitação, exatamente como você o inseriu. A documentação do seu fornecedor lista as key que ele aceita. Deixe-o vazio se o seu fornecedor não precisar de um. -
Expanda Advanced options e selecione um Mode :
- Enforce aplica a decisão do fornecedor. Um
DENYbloqueia a chamada. - O Log avalia a política e registra o possível veredito sem bloquear nada. Revise os resultados na tabela unificada de rastreios, onde cada avaliação é um evento
policy_evaluatedcom o possível veredito empolicy.dry_run_actionepolicy.dry_run_reason. Consulte Eventos de avaliação de política. Se o serviço tiver uma tabela de inferência, os resultados também serão registrados nela.
- Enforce aplica a decisão do fornecedor. Um
-
Clique em Criar política .
O Databricks recomenda começar no modo Logs . Permita que o tráfego real flua pela política, analise o que ela teria bloqueado e, em seguida, mude para Aplicar .
O modo de log não bloqueia chamadas, mas cada avaliação ainda chama seu fornecedor e usa qualquer cota ou cobrança por chamada incluída no seu contrato com o fornecedor. Configure a tabela de rastreamento unificada ou uma tabela de inferência no serviço antes de começar para poder revisar as avaliações pelas quais você paga.
o passo 3: testar a política
Depois de anexar ou alterar uma política, aguarde o tempo necessário para que a alteração seja propagada antes de realizar os testes. A propagação normalmente leva de 60 a 90 segundos.
Em seguida, envie uma solicitação que o guardrail do seu fornecedor deva capturar. No modo Enforce , o Databricks bloqueia a chamada e retorna uma resposta bem-sucedida (HTTP 200) com um objeto databricks_service_policy, como em qualquer política de serviço de bloqueio. Consulte Decisões de política. O bloco reason é a explicação do seu fornecedor. Se o seu fornecedor não retornar nenhum, o chamador verá o motivo default:
Acesso negado: esta solicitação não é permitida por uma política neste serviço.
O que o Databricks envia para o seu fornecedor
Em cada avaliação, o Databricks envia ao seu fornecedor o conteúdo em avaliação, o nome do serviço regido e a configuração de política definida. O conteúdo depende do serviço e da fase:
Serviço | Fase | Conteúdo enviado |
|---|---|---|
Serviço MCP | Entrada | O nome da ferramenta e seus argumentos. |
Serviço MCP | Saída | O resultado da ferramenta, junto com a chamada de ferramenta de origem. |
Serviço de modelo ou Serviço de provedor de modelos | Entrada | O corpo da solicitação completa do modelo, como as mensagens. |
Serviço de modelo ou Serviço de provedor de modelos | Saída | O corpo completo da resposta do modelo, juntamente com a solicitação de origem. |
Os corpos de solicitação e resposta do modelo são enviados no formato de API que o chamador usou, como OpenAI Chat Completions, OpenAI Responses, Anthropic Messages ou Gemini. O Databricks não os converte para um formato comum.
O Databricks envia apenas o conteúdo do seu fornecedor, não a identidade do chamador. Quando a solicitação tiver um rastreamento, o Databricks também enviará o ID de rastreamento correspondente, para que você possa associar uma avaliação nos logs do seu fornecedor à solicitação.
Revise a saída de rede antes de anexar uma política
Uma política de serviço externo envia o conteúdo sob avaliação, que pode incluir solicitações e respostas de modelo brutas ou argumentos e resultados de ferramentas MCP, para um serviço de terceiros. Antes de anexar a política, reveja as práticas de tratamento de dados do seu fornecedor e confirme o destino da conexão.
Uma conexão do Unity Catalog rege as credenciais e a configuração de conexão. Isso não restringe quais destinos de rede podem ser alcançados. As políticas de serviço externo não exigem uma política de rede restrita; portanto, se o seu workspace não tiver uma, o acesso de saída será irrestrito e uma política poderá enviar conteúdo avaliado para qualquer endpoint acessível por meio de uma conexão configurada.
A Databricks recomenda aplicar uma política de rede de acesso restrito que permita apenas destinos de serviço de política aprovados. Consulte Conexões e políticas de rede e Gerenciar políticas de rede para controle de saída serverless.
Comportamento de falha fechada
As políticas de serviço externo falham fechadas. Se o endpoint do seu fornecedor atingir o tempo limite, retornar um erro, retornar uma resposta que o Databricks não puder analisar ou retornar um veredito diferente de ALLOW ou DENY, o Databricks negará a chamada. Não é possível configurar uma política de serviço externo para permitir a passagem de tráfego quando o fornecedor estiver indisponível.
No modo Enforce , isso coloca a disponibilidade e a latência do seu fornecedor no caminho crítico de todas as chamadas governadas:
- Confirm your vendor's latency and availability before you enforce the policy. Databricks waits about 5 seconds for a response. Slower responses are denied.
- O modo de log não oculta problemas do endpoint. Um endpoint com falha ainda registra resultados de
DENY, portanto, muitas negações inesperadas no modo de log são um sinal para corrigir o endpoint antes de mudar para o modo de imposição (Enforce).
Limitações
Aplicam-se as seguintes limitações:
- Allow and deny only : as políticas de serviço externo retornam
ALLOWouDENY. Elas não podem reter uma chamada para aprovação humana (ASK) e não podem redigir ou reescrever conteúdo. - Um serviço por vez : você anexa uma política a um único serviço. Não é possível anexar uma política a vários serviços de uma só vez.
- Somente IU : você anexa políticas de serviço externas por meio da IU do Unity Gateway. A anexação por meio da API REST ou do Terraform não está disponível.
- Somente OAuth M2M : a conexão deve usar autenticação OAuth machine-to-machine.
- Suporte do fornecedor obrigatório : seu fornecedor deve implementar a API de política externa do Databricks. O Databricks não fornece adaptadores por fornecedor.
Solução de problemas
Sintoma | Causa provável |
|---|---|
A política não tem efeito logo após você anexá-la. | Você testou dentro da janela de propagação, o que normalmente leva de 60 a 90 segundos. Aguarde e tente novamente. |
Todas as chamadas são negadas. | The endpoint is unreachable, returns errors, or times out, so the policy fails closed. Check the host, path, and credentials on the connection, then check the endpoint's health with your vendor. |
Cada chamada é negada, e o motivo indica que o resultado não é reconhecido. | O seu fornecedor retornou um veredito diferente de |
Denied calls show the default reason instead of your vendor's. | O fornecedor não retornou um motivo, portanto, o Databricks exibe o texto default. |
O modo de log não mostra resultados. | Nem a tabela de rastreamento unificada nem uma tabela de inferência no serviço estão configuradas, portanto, os resultados do modo de log não são registrados em nenhum local que você possa query. A política ainda chama seu fornecedor. |
A conexão é salva, mas as chamadas falham. | The credentials or token endpoint are wrong. Confirme o ID do cliente, o segredo do cliente, o endpoint de token e quaisquer escopos necessários com o seu fornecedor. |