Aplicar um guardrail de parceiro com uma política de serviço externo
Beta
Este recurso está em Beta. Os administradores do workspace podem controlar o acesso a esse recurso na página Prévias optando pela prévia de Políticas de Serviço do Unity Gateway . Consulte Gerenciar prévias no nível do workspace.
Uma política de serviço externo aplica as decisões de um provedor 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 controlada, o Databricks envia o conteúdo em avaliação para o endpoint do seu provedor. O provedor retorna um veredito e o Databricks o aplica, 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.
- O guardrail do seu fornecedor inspeciona o conteúdo e retorna um veredito:
ALLOWouDENY, com um motivo opcional. Em uma chamada de ferramenta MCP, ele também pode retornarASKpara manter a chamada para aprovação do usuário.
Seu fornecedor deve implementar a API de política externa do Databricks, que define a solicitação que o Databricks envia e o veredito que espera receber. Compartilhe a referência da API de política de serviço externo com seu fornecedor e pergunte se eles são compatíveis com ela 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 provedor de guardrail que implementa a API de política externa do Databricks.
- Credenciais de máquina para máquina (M2M) OAuth para esse endpoint: um ID de cliente, um segredo de cliente e a URL do endpoint de token do fornecedor. OAuth M2M é o único método de autenticação compatível. Chaves de API, autenticação básica e OAuth de usuário para máquina não são suportados.
- 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.
Os provedores podem encontrar o formato completo de solicitação e resposta na Referência da API de política de serviço externo.
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 de forma fechada. Se o endpoint do seu provedor falhar ou retornar uma resposta que o Databricks não pode usar, o Databricks nega a chamada. Para cada caso, consulte Como o Databricks trata cada resposta. Você não pode configurar uma política de serviço externo para permitir o tráfego quando o provedor não estiver disponível.
No modo Enforce , isso coloca a disponibilidade e a latência do seu fornecedor no caminho crítico de todas as chamadas governadas:
- Confirme a latência e a disponibilidade do seu fornecedor antes de aplicar a política. O Databricks nega a chamada quando o seu fornecedor não responde a tempo.
- 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:
- Vereditos : Políticas de serviço externo retornam
ALLOWouDENYe, em uma chamada de ferramenta MCP, elas podem retornarASKpara manter a chamada aguardando a aprovação do usuário. Eles não podem editar ou reescrever o conteúdo. - Um serviço de cada vez : Você anexa uma política a um único serviço. Não é possível anexar uma política a vários serviços em um único o passo.
- 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. | Seu fornecedor retornou um veredicto 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. |
Próximos os passos
- Políticas de serviço para elementos protegidos de AI
- Criar e anexar uma política de serviço
- Connect to external HTTP serviços
- Monitore toda a atividade de AI usando a tabela de rastreamento unificada
- Referência da API de política de serviço externo: Referência para fornecedores que criam o endpoint.