Migrar para o Unity Gateway

O Unity Gateway é o plano de controle do Databricks para IA corporativa. Criado com base no Unity Catalog, ele governa APIs de modelos, provedores de modelos externos, servidores MCP, agentes, habilidades e ferramentas em um único local, com os mesmos privilégios, controles de custos, barreiras de proteção e observabilidade que você usa para dados. Os endpoints legados do AI Gateway permanecem vinculados a um único workspace e não fornecem essa governança centralizada.

Use this guia to move existing servindo modelo and legacy AI Gateway workloads to Unity Gateway, and to turn on the Enforce Unity Gateway workspace setting so all generative AI traffic is governed through Unity Catalog.

Requisitos

• Um workspace do Databricks habilitado para o Unity Catalog. Consulte Ativar um workspace para o Unity Catalog.
• Acesso de administrador do workspace para ativar a configuração Aplicar governança do Unity Gateway .
• Acesso do administrador da account para query as tabelas de uso de system.serving ao identificar tráfego legado.

Escolha seu caminho de migração

Escolha o caminho que corresponde à sua situação.

Sua situação	Caminho recomendado
You don't use AI Gateway, use it only casually, or you're setting up a new account or workspace	Comece do zero com o Unity Gateway.
Você tem cargas de trabalho ativas do AI Gateway legado	Migrar cargas de trabalho existentes.
Você se inscreveu na prévia de permissões do Unity Catalog do Foundation Model	Migre cargas de trabalho existentes e analise suas permissões de API de modelo. As permissões definidas em modelos individuais não concedem automaticamente acesso à API de modelo correspondente.

Sua situação	Caminho recomendado
You don't use AI Gateway, use it only casually, or you're setting up a new account or workspace	Comece do zero com o Unity Gateway.
Você tem cargas de trabalho ativas do AI Gateway legado	Migrar cargas de trabalho existentes.
Você se inscreveu na prévia de permissões do Unity Catalog do Foundation Model	Migre cargas de trabalho existentes e analise suas permissões de API de modelo. As permissões definidas em modelos individuais não concedem automaticamente acesso à API de modelo correspondente.

Começar do zero com o Unity Gateway

Se você for novo no Unity Gateway ou estiver configurando uma nova account ou workspace, comece diretamente no Unity Gateway.

Passo 1: Revisar o acesso às APIs de modelo hospedadas pelo Databricks

O Unity Gateway fornece APIs de modelo hospedadas pelo Databricks prontas para uso no esquema system.ai. Revise quem pode acessá-los e restrinja o acesso onde necessário.

Por default, todos os usuários da account têm EXECUTE nas APIs de modelo fornecidas pelo sistema. Cada API de modelo também requer USE CATALOG em system e USE SCHEMA em system.ai. Para aplicar o privilégio mínimo, remova o acesso amplo ao esquema e conceda EXECUTE em APIs de modelo individuais. As permissões do modelo subjacente não concedem acesso à API de modelo.

Ação	Permissões necessárias
Consultar uma API de modelo	EXECUTE na API do modelo, além de USE CATALOG e USE SCHEMA em seu catálogo e esquema.
Criar uma API de modelo	EXECUTE no modelo subjacente, mais CREATE SERVICE, USE CATALOG e USE SCHEMA em que você cria a API do modelo.
Query um provedor de modelo externo	EXECUTE no provedor de modelo externo, além de USE CATALOG e USE SCHEMA em seu catálogo e esquema.
Criar um provedor de modelo externo	CREATE SERVICE, USE CATALOG e USE SCHEMA onde você cria o provedor de modelo externo.

Ação	Permissões necessárias
Consultar uma API de modelo	EXECUTE na API do modelo, além de USE CATALOG e USE SCHEMA em seu catálogo e esquema.
Criar uma API de modelo	EXECUTE no modelo subjacente, mais CREATE SERVICE, USE CATALOG e USE SCHEMA em que você cria a API do modelo.
Query um provedor de modelo externo	EXECUTE no provedor de modelo externo, além de USE CATALOG e USE SCHEMA em seu catálogo e esquema.
Criar um provedor de modelo externo	CREATE SERVICE, USE CATALOG e USE SCHEMA onde você cria o provedor de modelo externo.

Para acesso baseado em tag controlada e em atributos, consulte as políticas GRANT.

nota

Se você estava inscrito na preview do Unity Catalog Permissions do Foundation Model, as permissões definidas em modelos individuais não se aplicam automaticamente às APIs de modelo correspondentes. Revise e reaplique suas concessões de privilégio mínimo nas APIs de modelo.

Passo 2: Ativar Enforce Unity Gateway

Ative a configuração do workspace Aplicar Unity Gateway para desabilitar experiências legadas do AI Gateway, de modo que todo o tráfego de IA generativa seja governado por meio do Unity Catalog. Se você não ativar essa opção, suas configurações legadas existentes permanecerão inalteradas.

Quando você ativa a imposição, cada superfície de produto se comporta da seguinte maneira:

Superfície	Comportamento quando a aplicação está ativada
Modelos Pay-per-token Foundation	Todo o tráfego pay-per-token deve ser roteado por meio de uma API de modelo. Os endpoints de serviço pay-per-token fornecidos pelo Databricks (os modelos databricks-) estão desativados.
Provisioned Throughput Foundation Models	Não é mais possível criar endpoints de serviço de throughput provisionado sem o Unity Gateway. Os endpoints existentes permanecem intactos e disponíveis para consulta.
Modelos externos	Não é mais possível criar endpoints de servindo modelo externo sem o Unity Gateway. Os endpoints existentes permanecem intactos e continuam permitindo queries.

Superfície	Comportamento quando a aplicação está ativada
Modelos Pay-per-token Foundation	Todo o tráfego pay-per-token deve ser roteado por meio de uma API de modelo. Os endpoints de serviço pay-per-token fornecidos pelo Databricks (os modelos databricks-) estão desativados.
Provisioned Throughput Foundation Models	Não é mais possível criar endpoints de serviço de throughput provisionado sem o Unity Gateway. Os endpoints existentes permanecem intactos e disponíveis para consulta.
Modelos externos	Não é mais possível criar endpoints de servindo modelo externo sem o Unity Gateway. Os endpoints existentes permanecem intactos e continuam permitindo queries.

Para ativar a configuração:

1. Faça log in no seu workspace Databricks como administrador do workspace.
2. Acesse Configurações > Avançado .
3. Ative Aplicar Unity Gateway .

Após a ativação, as solicitações para Endpoints de disponibilização de pagamento por tokens desativados retornam um erro PERMISSION_DENIED:

JSON

{
  "error_code": "PERMISSION_DENIED",
  "message": "Querying pay-per-token foundation model endpoint 'databricks-gpt-5' is disabled for this workspace. Please use Unity Gateway."
}

atenção

Enabling enforcement stops traffic to active legacy endpoints. If your workspace runs legacy workloads, complete Migrate existing workloads and validate that traffic has moved before you turn on the setting.

The Enforce Unity Gateway setting is available in Workspaces that have legacy AI Gateway Endpoints. It stays available after their traffic drops to zero, so you can turn it on at the end of your migration. New workspaces have enforcement on by default and don't show the setting. If the setting isn't available in your workspace, contact your Databricks account team after you complete and validate your migration.

Quando a imposição está ativada, as seguintes limitações se aplicam porque nem todos os produtos que dependiam de Endpoint de serviço legados migraram para o Unity Gateway:

• AI Search: Creating AI Search endpoints through Unity Gateway is not yet supported. Knowledge Assistant and Multi-Agent Supervisor agents that depend on AI Search endpoints don't work.
• ai_query: ai_query oferece suporte a APIs de modelo fornecidas pelo Databricks apenas em system.ai, não a serviços de modelo criados por você.
• Databricks Apps: Apps configurados com o recurso de Endpoint de servindo modelo (um Service Principal com acesso a modelos system.ai) param de funcionar. Conceda o EXECUTE ao Service Principal nas APIs de modelo system.ai correspondentes e atualize o aplicativo para query as APIs de modelo.

Migrar cargas de trabalho existentes

Se você tiver cargas de trabalho ativas do AI Gateway legado, siga estes passos antes de habilitar a aplicação.

O passo 1: Identificar o uso legado ativo

Encontre quais endpoints legados ainda recebem tráfego, em quais workspaces e quem os chama.

1. Ative o acompanhamento de uso nos seus endpoints legados. A ativação é idempotente, portanto, é seguro executá-la novamente.
2. Consulte as tabelas do sistema system.serving.endpoint_usage e system.serving.served_entities para ver solicitações recentes, chamadores e horários da última solicitação. Somente administradores de conta podem consultar essas tabelas.

Etapa 2: Configurar APIs e provedores de modelo

A governança configurada em um endpoint legado não é transferida. A configuração existente permanece no endpoint legado. Crie ou identifique a API de modelo ou o provedor de modelo externo necessário e, em seguida, recrie as configurações das quais você depende, como permissões, limites de taxa, orçamentos, políticas de serviço, acompanhamento de uso, tabelas de inferência e roteamento de tráfego e fallbacks. Atualize também todos os fluxos de trabalho de CI/CD ou de Infrastructure-as-Code para usar as APIs do Unity Gateway.

Migre cada tipo de carga de trabalho para o seguinte destino:

Carga de trabalho existente	Destino de migração
Modelo de pagamento por token hospedado pelo Databricks	Use a API de modelo correspondente em system.ai, anal ise suas permissões e recrie as configurações necessárias. Consulte Descobrir e governar o acesso a APIs de modelo (serviços de modelo).
Throughput provisionado hospedado pela Databricks	Mantenha o endpoint de serving de throughput provisionado existente e crie uma API de modelo que faça referência a ele. Conceda aos chamadores EXECUTE na API de modelo.
Provedor externo	Crie um external model provider com seu provedor existente, suas credenciais, seus modelos expostos e seus chamadores. Faça a query diretamente ou crie uma API de modelo para governança específica do modelo; nesse caso, as configurações da API de modelo têm precedência.

Carga de trabalho existente	Destino de migração
Modelo de pagamento por token hospedado pelo Databricks	Use a API de modelo correspondente em system.ai, anal ise suas permissões e recrie as configurações necessárias. Consulte Descobrir e governar o acesso a APIs de modelo (serviços de modelo).
Throughput provisionado hospedado pela Databricks	Mantenha o endpoint de serving de throughput provisionado existente e crie uma API de modelo que faça referência a ele. Conceda aos chamadores EXECUTE na API de modelo.
Provedor externo	Crie um external model provider com seu provedor existente, suas credenciais, seus modelos expostos e seus chamadores. Faça a query diretamente ou crie uma API de modelo para governança específica do modelo; nesse caso, as configurações da API de modelo têm precedência.

O passo 3: Atualizar seus clientes

Depois de configurar a API de modelo ou o provedor de modelo externo, mova cada carga de trabalho para o Unity Gateway. Migre o URL do gateway e o escopo do access token pessoal (PAT) juntos.

API and SDK clients : For Databricks-hosted models, change the base URL from /serving-endpoints to /ai-gateway/mlflow/v1 and change the model from the endpoint name to the fully qualified model API name.

Python

from openai import OpenAI

client = OpenAI(
    api_key=token,
    base_url="https://<workspace-url>/ai-gateway/mlflow/v1",
)

response = client.chat.completions.create(
    model="<catalog>.<schema>.<model-service>",
    messages=[...],
)

Para modelos externos, faça uma query no serviço de provedor de modelos passando seu nome em um cabeçalho de solicitação.

Python

from openai import OpenAI

client = OpenAI(
    api_key=token,
    base_url="https://<workspace-url>/ai-gateway/openai/v1",
    default_headers={
        &quot;Databricks-Model-Provider-Service&quot;: &quot;&lt;catalog&gt;.&lt;schema&gt;.&lt;model-provider-service&gt;&quot;
    },
)

response = client.chat.completions.create(
    model="<provider-model-name>",
    messages=[...],
)

Para ver mais opções de query, consulte Query model APIs (model serviços) e Query external model providers (model provider serviços).

Autenticação : o Unity Gateway oferece suporte à autenticação OAuth e PAT. O escopo de PAT de que você precisa depende do URL:

• Rota do workspace /ai-gateway/ : use o escopo ai-gateway recomendado e de privilégio mínimo.
• Host regional legado do *.ai-gateway.* : use o escopo mais abrangente do all-apis.

Chamar o URL regional legado com um PAT com escopo para ai-gatewayretorna 403: required scopes: all-apis. Mova o cliente para o URL do workspace /ai-gateway/, use um PAT com escopo para ai-gatewaye tente novamente.

ai_query : Substitua o nome do endpoint legado pela API de modelo correspondente fornecida pelo Databricks em system.ai. O chamador precisa de EXECUTE nessa API de modelo.

SQL

-- Legacy
SELECT ai_query('<legacy-endpoint-name>', 'Summarize: ' || text)
FROM my_table;

SQL

-- Unity Gateway
SELECT ai_query('system.ai.<model-name>', 'Summarize: ' || text)
FROM my_table;

ai_query supports Databricks-provided model APIs, not model serviços that you create. Only usage acompanhamento applies. Service policies, inference tables, rate limits, and fallbacks don't apply to ai_query calls. See ai_query function.

Coding agents : Configure um agente de codificação compatível para ser roteado pelo Unity Gateway em vez de se conectar diretamente ao provedor de modelo. O Databricks fornece a CLI do Unity Gateway (ug) para esta configuração. A instalação requer o Python 3.12 ou posterior e uv.

Bash

uv tool install git+https://github.com/databricks/unity-gateway

Inicie um agente de codificação compatível por meio do Unity Gateway:

Bash

ug claude
ug codex
ug gemini
ug opencode
ug copilot

Se você usar suas próprias credenciais de provedor, primeiro crie um provedor de modelo externo e, em seguida, aponte o agente de codificação para ele. A opção --provider é suportada para ug claude e ug codex.

Bash

ug claude --provider <catalog>.<schema>.<provider-service>

Consulte Introdução a agentes de programação e Configurar capacidade do modelo.

Etapa 4: Validar o tráfego migrado

Confirme se o tráfego legado parou antes de habilitar a aplicação. Faça uma query na tabela system.serving.endpoint_usage para cada endpoint legado e verifique se a contagem de solicitações caiu para zero e se o horário da última solicitação é anterior à sua migração.

Etapa 5: (Opcional) Limitar a taxa de Endpoint legados durante uma migração faseada

Para migrar gradualmente, defina o limite de taxa de um endpoint legado individual para 0 para interromper o novo tráfego para ele, mantendo outros endpoints legados ativos. Repita os passos 2 a 5 para cada carga de trabalho restante.

O passo 6: Ativar Enforce Unity Gateway

Após a migração bem-sucedida de todo o tráfego necessário, ative a configuração Aplicar Unity Gateway para desativar os Endpoint legados para o Workspace. Consulte Passo 2: Ativar Aplicar Unity Gateway para ver quais alterações ocorrem, como ativar a configuração e suas limitações.

Outros recursos

• Governança de AI com o Unity Gateway
• Guia de governança de AI
• Criar e gerenciar APIs de modelo (serviços de modelo)
• Governar provedores de modelos externos (serviços de provedor de modelos)