Para governar chamadas de IA no Databricks, comece identificando qual experiência seu ambiente utiliza. A documentação atual apresenta o Unity Gateway, construído sobre o Unity Catalog, e mantém uma seção separada para a configuração legada do AI Gateway em endpoints de Model Serving. Misturar essas duas experiências leva a instruções erradas sobre permissões, tabelas e contingência.
Este guia ajuda a revisar uma implantação conhecida como Mosaic AI Gateway e planejar seu uso com critérios verificáveis. O objetivo é controlar acesso, observar consumo e testar rotas alternativas. Um gateway pode reduzir a dispersão de configuração, mas não elimina falhas, vazamentos ou diferenças de comportamento entre modelos.
Resumo rápido
- Identifique a experiência atual ou legada antes de copiar configurações.
- Separe permissão para consultar de permissão para alterar o serviço.
- Distribuição de tráfego e fallback resolvem problemas diferentes.
- Valide respostas, tempo total e consumo durante a contingência.
- Registros operacionais também precisam de controle de acesso.
Do Mosaic AI Gateway ao Unity Gateway: qual guia seguir
A visão geral oficial descreve o Unity Gateway como uma camada de governança para interações entre modelos, agentes e ferramentas. Os serviços são controlados por objetos do Unity Catalog. Já o procedimento legado configura recursos diretamente em endpoints de Model Serving e usa permissões desse endpoint. Essas instruções não devem ser tratadas como intercambiáveis.
Faça um inventário com nome do serviço, URL usada pela aplicação, responsável, ambiente e documento de configuração correspondente. Registre também o provedor de nuvem do workspace. As referências deste texto são da documentação para AWS; elas não comprovam que qualquer funcionalidade esteja habilitada em toda região ou em todo ambiente brasileiro.
Uma revisão útil começa pela chamada real. Descubra de onde sai a requisição, qual identidade a assina e qual endereço recebe o conteúdo. Em seguida, confira o objeto administrado no console. Essa sequência evita deduzir a arquitetura a partir de um nome antigo salvo em um diagrama. Guarde a configuração anterior antes de experimentar alterações.
Para organizações que já operam o legado, a tarefa imediata pode ser documentar e reduzir riscos, sem migrar tudo no mesmo dia. Para novas decisões, consulte a experiência atual e confirme os requisitos do workspace. O nome comercial sozinho não informa quais controles estão disponíveis na sua implantação.
Acesso, responsabilidades e limites de confiança
Defina três responsabilidades separadas: quem desenvolve a aplicação, quem aprova os destinos e quem acompanha o consumo. Em uma equipe pequena, a mesma pessoa pode acumular funções, mas as decisões precisam continuar registradas. Uma mudança de destino pode alterar onde os dados são processados e o formato da resposta.
No legado, a documentação exige CAN MANAGE para operações administrativas e recomenda restringir essa permissão e a criação de endpoints. No Unity Gateway, a governança dos serviços se apoia em privilégios do Unity Catalog. Portanto, não copie uma lista de permissões de endpoint e a apresente como regra universal do catálogo.
Como prática de implantação, mantenha identidades distintas para desenvolvimento e produção. Teste uma credencial autorizada a consultar e outra que deveria ser recusada. Confirme também que a primeira não consegue trocar destinos ou alterar políticas. Um teste positivo demonstra funcionamento; o teste negativo demonstra que a restrição pretendida realmente existe.
Evite colocar segredos em exemplos de código, conversas de suporte e registros de erro. Centralizar chamadas não torna uma chave impossível de vazar. O que muda é a possibilidade de administrar pontos de acesso com mais consistência. Para estruturar a discussão interna sobre dados, consulte o guia de segurança na implantação de IA.
Também estabeleça quem pode autorizar um novo fornecedor. Uma contingência tecnicamente funcional ainda pode ser inadequada para determinado documento. A lista de destinos permitidos deve refletir as decisões da empresa sobre uso dos dados, e não apenas quais APIs respondem mais rápido durante um teste.
Como testar roteamento e fallback sem promessas irreais
Na experiência atual, a configuração de roteamento separa o destino inicial das tentativas de contingência. Os percentuais distribuem as primeiras chamadas. Os fallbacks seguem uma ordem definida quando a primeira tentativa falha, por exemplo com erros 429 ou 5xx. O registro de roteamento permite conferir os destinos tentados.
Trate isso como mecanismo de recuperação, não como garantia de resposta. Se todos os destinos falharem, a aplicação ainda precisa apresentar um erro compreensível ou encaminhar a tarefa para uma fila. Uma nova tentativa também consome tempo. Não prometa contingência imperceptível ou latência de poucos milissegundos sem medição no seu ambiente.
| Decisão | Função | Como verificar |
|---|---|---|
| Distribuir tráfego | Escolher o destino inicial | Comparar a distribuição observada com a configuração |
| Configurar fallback | Tentar outro destino após falha | Provocar uma falha controlada e examinar a sequência |
| Validar a saída | Verificar utilidade para o processo | Aplicar o mesmo conjunto de casos a todos os destinos |
| Limitar consumo | Controlar a utilização permitida | Enviar carga autorizada e conferir a recusa esperada |
No legado, há restrições específicas: o procedimento documenta fallback para modelos externos, com até dois destinos de contingência. Não transforme essa regra em uma cadeia genérica que mistura qualquer modelo hospedado e qualquer API. A configuração atual tem documentação própria e deve ser validada separadamente.
Prepare perguntas curtas, documentos longos e solicitações que exijam uma estrutura de saída. Execute os casos em cada destino antes de ativar a troca automática. Se a aplicação espera campos obrigatórios, valide esses campos fora do modelo. Uma resposta HTTP bem-sucedida pode continuar sendo inútil para o sistema que a recebe.
Quando houver ferramentas que alteram dados, separe geração de texto da execução da ação. Uma tentativa repetida não deve criar dois pedidos ou enviar duas mensagens. Esse cuidado pertence ao desenho da aplicação; a presença do gateway não substitui o controle de duplicidade no processo de negócio.
Observabilidade, custos e critérios de entrada em produção
A documentação de monitoramento de uso identifica system.ai_gateway.usage como tabela da experiência atual. Ela inclui informações como solicitante, tokens, latência e roteamento. O acesso depende de permissões administrativas ou concessões apropriadas. A mesma página informa que o acompanhamento de uso é um recurso cobrado, sem que isso autorize estimar uma tarifa universal.
Antes de elaborar um painel, escolha perguntas operacionais. Qual aplicação está falhando? Quanto tempo uma resposta demora quando precisa de contingência? Que destino recebeu a chamada? Há consumo sem responsável identificado? Um painel cheio de gráficos, mas incapaz de responder essas perguntas, não ajuda a equipe a
agir.
Separe métricas de conteúdo. Para investigar uma falha de rede, talvez baste o identificador da requisição e o status. Para avaliar uma resposta, pode ser necessário analisar um exemplo previamente autorizado. Não use a conveniência da depuração como justificativa para copiar todos os documentos de produção para qualquer tabela.
Combine esse acompanhamento com rastreamento das chamadas de modelos na aplicação. Registre o identificador que permite ligar a reclamação do usuário à execução correspondente. Evite incluir dados pessoais nesse identificador. Estabeleça quem investiga incidentes e como o acesso temporário aos registros será encerrado.
Para avaliar custo, considere o caminho completo: modelo, tentativas adicionais, observabilidade e operação. Compare o consumo medido com as condições comerciais contratadas. Tokens ajudam a explicar utilização, mas não são uma fatura por si só. Se faltar informação de cobrança, apresente o resultado como estimativa e documente a lacuna.
Use critérios explícitos de liberação: acesso recusado quando esperado, saída válida nos casos selecionados, tratamento de indisponibilidade e capacidade de voltar à configuração anterior. Faça uma liberação limitada e acompanhe os primeiros usos. Se o destino alternativo alterar a qualidade da resposta, corrija a rota antes de ampliar a exposição.
Exemplo: distribuidora em Belo Horizonte organiza a triagem interna
Considere uma distribuidora de peças em Belo Horizonte que quer resumir solicitações recebidas pela equipe comercial. Este é um cenário ilustrativo, sem resultados medidos. O assistente prepara uma classificação e um rascunho para revisão humana; não confirma preço, crédito ou disponibilidade de estoque sozinho.
A equipe identifica duas aplicações: um ambiente de testes e o assistente usado pelos vendedores. Define responsáveis separados e escolhe documentos sintéticos para a homologação. O conjunto inclui pedidos incompletos, referências ambíguas de produtos e uma solicitação que não pertence ao catálogo.
Antes de habilitar contingência, os técnicos executam os mesmos casos no destino principal e no alternativo. Comparam se ambos preservam os códigos de produto e admitem quando falta informação. Uma resposta elegante que inventa uma peça é classificada como falha, mesmo quando chega rapidamente.
Em seguida, a equipe simula uma indisponibilidade controlada. Confere a sequência de tentativas nos registros e observa a mensagem apresentada ao vendedor. Se nenhum destino responde, o pedido permanece disponível para tratamento manual. A aplicação não informa que a triagem foi concluída quando houve apenas uma tentativa.
Na revisão operacional, o gestor recebe contagens por aplicação e uma lista de problemas recorrentes, sem acesso indiscriminado ao conteúdo dos clientes. A decisão de ampliar o uso depende desses testes. O benefício esperado é tornar o processo verificável; nenhuma redução de custo ou eliminação de incidentes é presumida.
Erros comuns
- Misturar gerações do produto: confirme se está configurando um endpoint legado ou um serviço do Unity Gateway antes de aplicar permissões e consultar tabelas.
- Confundir fallback com seleção por qualidade: trocar de destino após erro não demonstra que a resposta alternativa cumpre os critérios do negócio.
- Ignorar chamadas fora do caminho aprovado: inventarie acessos diretos antes de afirmar que toda utilização está sob a mesma política.
- Registrar conteúdo sem necessidade: escolha o mínimo de evidências que permita investigar cada classe de problema.
- Testar apenas sucesso: exercite identidade sem acesso, falha no destino principal, falha total e saída inválida.
Um erro menos visível é deixar a documentação interna parada após uma mudança. Toda alteração de rota precisa atualizar o responsável, o motivo, o conjunto de testes e o procedimento de retorno. Isso reduz o tempo gasto tentando descobrir por que uma resposta mudou sem mudança aparente no código.
Perguntas frequentes
Unity Gateway e o AI Gateway legado usam o mesmo procedimento?
Não. A documentação os separa. Identifique o recurso que existe no workspace e siga a referência correspondente, especialmente para autorização e registros. Nomes semelhantes não comprovam equivalência operacional.
Um erro 429 sempre será resolvido pela contingência?
Não. O destino seguinte também pode falhar ou não ter capacidade disponível. A aplicação precisa tratar a falha final e informar o estado da tarefa sem prometer conclusão.
Posso trocar o modelo sem testar a aplicação?
Não é uma prática adequada. Preserve um conjunto de exemplos representativos e confira formato, conteúdo, recusas e tempo de resposta. A compatibilidade de transporte não prova equivalência dos resultados.
O gateway substitui a revisão de segurança?
Não. Ele participa da arquitetura. Identidades, destinos permitidos, tratamento dos documentos, registros e ações executadas pela aplicação continuam exigindo decisões e testes próprios.
Como começar com uma equipe pequena?
Escolha uma aplicação e um responsável, documente sua chamada atual e use dados sintéticos para testar acesso e falhas. Amplie somente depois de conseguir explicar o caminho de uma requisição do início ao fim.
