Pular para o conteúdo principal
Última atualização em

Implantar um agente para aplicações de IA generativa (Model Serving)

info

Para novos casos de uso, a Databricks recomenda implantar agentes no Databricks Apps para controle total sobre o código do agente, a configuração do servidor e o fluxo de trabalho de implantação. Consulte Crie um agente de AI e o tenha implantado no Databricks Apps. Para migrar um agente existente, consulte Migre um agente do Model Serving para o Databricks Apps.

Implante seu agente de AI no Model Serving usando a função deploy() da API Python de Agentes Personalizados. A implantação cria um endpoint de serviço com escalabilidade integrada, monitoramento e ferramentas de colaboração.

Seu agente implantado integra-se automaticamente com os recursos de avaliação e monitoramento do MLflow 3, incluindo rastreamento em tempo real, o aplicativo de revisão para feedback das partes interessadas e monitoramento.

Requisitos​

  • Obtenha o registro do seu agente no Unity Catalog.
  • Instale o MLflow 3.1.3 ou acima para implantar agentes utilizando a API deploy() de databricks.agents.
  • A implantação de agentes de fora de um Notebook Databricks requer o SDK databricks-agents versão 1.1.0 ou acima.

Instale os pré-requisitos:

Python
# Install prerequisites
%pip install mlflow>=3.1.3 databricks-agents>=1.1.0

# Restart Python to make sure the new packages are picked up
dbutils.library.restartPython()

Implante agentes usando deploy()​

Implantar seu agente em um endpoint servindo modelo:

Python
from databricks import agents

deployment = agents.deploy(uc_model_name, uc_model_info.version)

# Retrieve the query endpoint URL for making API requests
deployment.query_endpoint

Ao chamar implantar(), o Databricks configura automaticamente a infraestrutura de produção e integra seu agente com os recursos de AI generativa do MLflow, fazendo o seguinte:

atenção

Se você estiver implantando um agente de um Notebook armazenado em uma pasta Git do Databricks, o rastreamento em tempo real do MLflow 3 não funcionará por default.

Para habilitar o rastreamento em tempo real, defina o experimento como um experimento não associado ao Git usando mlflow.set_experiment() antes de executar agents.deploy().

A função deploy() executa as seguintes ações default:

  • Cria um endpoint servindo modelo para hospedar seu agente com dimensionamento automático e balanceamento de carga.
  • **Provisionamento de autenticação segura** para seu agente acessar recursos subjacentes
  • Habilita o monitoramento em tempo real através do rastreamento de experimentos do MLflow e avaliação automatizada de qualidade no tráfego de produção.
  • Configura a colaboração das partes interessadas usando o aplicativo de revisão para a coleta de feedback

Para mais informações, consulte Ações de implantação detalhadas.

Personalizar a implantação​

Passe argumentos adicionais para deploy() para personalizar a implantação. Por exemplo, é possível habilitar a escala para zero para endpoints parados, passando scale_to_zero_enabled=True. Isso reduz os custos, mas aumenta o tempo para atender as consultas iniciais.

Para mais parâmetros, consulte API Python dos Agentes Databricks.

Atualizar uma implantação existente​

Quando você chama deploy() com o mesmo nome de modelo do Unity Catalog que uma implantação existente, a nova versão do modelo é adicionada ao endpoint de serviço existente e o tráfego é direcionado para ele depois que estiver pronto. A versão anteriormente implantada continua a atender solicitações durante a implantação, portanto, as atualizações não interrompem o tráfego em andamento.

Para obter implantações com tempo de inatividade zero, não altere nenhuma configuração além da versão do modelo UC (ou seja, endpoint_name e nome do modelo).

Recuperar e excluir implantações de agente​

Recupere ou gerencie implantações de agente existentes. Consulte a API Python de Agentes do Databricks.

Python
from databricks.agents import list_deployments, get_deployments, delete_deployment

# Print all current deployments
deployments = list_deployments()
print(deployments)

# Get the deployment for a specific agent model name and version
agent_model_name = ""    # Set to your Unity Catalog model name
agent_model_version = 1  # Set to your agent model version
deployment = get_deployments(model_name=agent_model_name, model_version=agent_model_version)

# List all deployments
all_deployments = list_deployments()

# Delete an agent deployment
delete_deployment(model_name=agent_model_name, model_version=agent_model_version)

Autenticação para recursos dependentes​

Os agentes geralmente precisam se autenticar em outros recursos para concluir tarefas quando são implantados. Por exemplo, um agente pode precisar acessar um índice de Pesquisa de AI para consultar dados não estruturados.

Para obter informações sobre métodos de autenticação, incluindo quando usá-los e como configurá-los, consulte Autenticação para agentes de AI (Model Serving).

Rede para implantações de agentes​

Se o seu workspace usa Private Service Connect ou políticas de rede de egresso restrito, você deve configurar o acesso à rede para que as implantações de agente sejam bem-sucedidas. Endpoints servindo modelo exigem acesso de saída para realizar downloads de dependências durante o processo de compilação do contêiner. Os agentes também podem precisar acessar APIs externas em tempo de execução.

Para agentes implantados no Databricks Apps, consulte Implantar aplicativos em ambientes Private Service Connect para orientação detalhada sobre como configurar políticas de DNS ou egresso.

Para agentes implantados no Model Serving, verifique o seguinte:

  • **Dependências de tempo de compilação:** Sua política de rede deve permitir acesso a repositórios de pacotes necessários pelo ambiente do seu agente, como pypi.org ou files.pythonhosted.org para pacotes Python. Databricks log falhas de compilação causadas por acesso de rede bloqueado com network_source_type: ML Build na tabela do sistema system.access.outbound_network. Consulte Validar com servindo modelo.
  • Dependências do Runtime: Se seu agente chamar APIs ou serviços externos durante a inferência, adicione esses domínios à lista de permissões da sua política de rede.
  • Resolução de DNS: Em ambientes do Private Service Connect, verifique se o seu agente pode resolver os hostnames de quaisquer serviços Databricks dos quais ele depende, como AI Search ou endpoints de SQL warehouse.

Ações detalhadas de implantação​

A tabela a seguir lista as ações detalhadas de implantação que resultam de uma chamada deploy(). As implantações podem levar até 15 minutos para serem concluídas.

deploy() Ação

Descrição

Criar endpoint servindo modelo

Cria um endpoint de API REST escalável que serve seu agente para aplicativos voltados ao usuário com balanceamento de carga automático.

Provisionamento de autenticação segura

Fornece automaticamente credenciais de curta duração que permitem ao seu agente acessar recursos gerenciados pelo Databricks (índices de pesquisa de AI, funções do Unity Catalog, etc.) com as permissões mínimas necessárias.

O Databricks verifica que o proprietário do endpoint tem as permissões necessárias antes de emitir as credenciais, evitando acesso não autorizado.

Para recursos que não são do Databricks, passe variáveis de ambiente com segredos para deploy(). Consulte Configurar o acesso ao recurso de endpoints servindo modelo.

Habilitar Aplicativo de Revisão

Fornece uma interface web onde as partes interessadas podem interagir com seu agente e fornecer feedback. Veja Coletar feedback e expectativas aplicando rótulos a rastreamentos existentes.

Habilitar rastreamento em tempo real

Registra todas as interações do agente em um experimento do MLflow em tempo real, fornecendo visibilidade imediata para monitoramento e depuração.

  • Rastreamentos do seu endpoint são gravados no experimento MLflow atualmente ativo (definido com mlflow.set_experiment())
  • Todos os agentes no endpoint compartilham o mesmo experimento para armazenamento de rastreamento.
  • Os rastreamentos também gravam em tabelas de inferência para armazenamento de longo prazo.

Habilitar monitoramento de produção (em fase beta)

Configura a avaliação automatizada de qualidade que faz a execução de avaliadores no tráfego de produção. Consulte monitoramento de produção.

Habilitar tabelas de inferência

Cria tabelas que fazem log de entradas e respostas de solicitações para auditoria e análise.

Aviso: Os logs de solicitação e os logs de avaliação estão obsoletos e serão removidos em uma versão futura. Use o rastreamento em tempo real do MLflow 3 em vez disso. Consulte depreciação de log de solicitação e log de avaliação para obter orientação sobre a migração.

  • Todos os agentes usam tabelas de inferência do AI Gateway para fins de registro.
  • Respostas de transmissão registram apenas campos compatíveis com os esquemas ResponsesAgent, ChatAgent e ChatCompletion.

Log solicitações da API REST e feedback do Review App

Registra solicitações de API e feedback em uma tabela de inferência.

Aviso: O modelo de feedback foi descontinuado e será removido em uma versão futura. Atualize para o MLflow 3 e use a API log_feedback em vez disso. Consulte Coletar feedback do usuário.

  • Criar um modelo de feedback para aceitar e log feedback do aplicativo de revisão.
  • Este modelo é servido no mesmo endpoint de servindo modelo de CPU que seu agente implantado.

Recursos adicionais​

Nesta página