Tutorial: Controla o acesso ao modelo de um agente de codificação com o Unity Gateway

Neste tutorial, liga um agente de programação externo, como Claude Code, Codex, Cursor ou Gemini CLI, a grandes modelos de linguagem (LLMs) governados pelo Unity Gateway. Depois controlas quem pode aceder a esses modelos e quanto o agente pode consumir e gastar. Em vez de cada programador colar uma chave API de fornecedor na sua ferramenta, cada pedido passa por um serviço modelo Unity Gateway. O Unity Catalog controla quem pode usar quais modelos, e o Unity Gateway impõe limites, regista o uso e o custo.

No final deste tutorial, terá:

  • Um agente de programação que envia todos os pedidos de modelo através do Unity Gateway usando as suas credenciais Azure Databricks, sem uma chave API de fornecedor na máquina do programador.
  • Registos centrais do uso e custo do agente, sujeitos aos limites de tarifa e permissões que definir no serviço modelo.

Prerequisites

Passo 1: Ligue o seu agente de codificação

Pode ligar o agente de uma de duas formas:

  • Unity Gateway CLI (recomendado): Um launcher open-source que gere o OAuth e escreve o ficheiro de configuração de cada agente, incluindo a URL da base do serviço modelo e o modelo. Não geres as chaves de API ou os endpoints manualmente.
  • Configuração manual: Defina a URL da base de serviço do modelo e modele você próprio nas definições integradas da ferramenta (Claude Code, Codex, Cursor ou Gemini CLI). Ver Agentes de codificação suportados.

Esta secção utiliza a CLI do Gateway Unity. Instale-o e depois execute o agente que quiser:

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

Código Claude

ug claude

Codex

ug codex

Para correr em modo não interativo, passe a própria flag do agente através da CLI do Unity Gateway:

ug codex --full-auto

Gemini CLI

ug gemini

OpenCode

ug opencode

Copilot

ug copilot

Na primeira execução, a CLI do Unity Gateway pede o URL do seu espaço de trabalho e autentica-o; nas execuções seguintes, segue diretamente para o agente.

Passo 2: Gerir o acesso ao modelo do agente

Pode gerir um serviço de modelo como qualquer outro objeto protegível do Unity Catalog: conceda EXECUTE para controlar quem o pode utilizar e use o Unity Gateway para limitar o volume de pedidos e os custos. Configure qualquer um dos seguintes:

  • Gerir quem pode aceder ao modelo: No Explorador de Catálogo, abra o serviço de modelos e conceda EXECUTE a utilizadores ou grupos no separador Permissões .
  • Limitar o volume de pedidos: No Explorador de Catálogo, no separador Visão Geral do serviço de modelo, clique em Configurar em Limites de taxa. Defina um limite de pedidos por minuto (QPM) ou de tokens por minuto (TPM) para todos os pedidos do endpoint ou por utilizador.
  • Defina um orçamento de despesas: Um administrador de contas pode criar um orçamento com o âmbito de todos os endpoints do Unity Gateway. O orçamento agrega os gastos em todos os seus serviços-modelo; Defina um limiar de alerta para ser notificado, ou para bloquear o uso, antes que os custos o ultrapassem.

Passo 3: Verificar se o tráfego é governado

Confirme que os pedidos do agente passam pelo Unity Gateway e são registados:

  • Do agente: Envie um prompt. O agente responde usando o modelo que configuraste, sem a chave API do fornecedor na tua máquina.

  • Na tabela do sistema de utilização: Consulte o registo de utilização para confirmar que o seu serviço de modelo regista os pedidos:

    SELECT service_name, requester, status_code, COUNT(*) AS calls
FROM system.ai_gateway.usage
WHERE service_type = 'MODEL_SERVICE'
GROUP BY service_name, requester, status_code
ORDER BY calls DESC;

Para analisar os gastos com mais detalhe, veja Analisar o custo do Unity Gateway.

Passos seguintes

  • Última atualização a