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

Implante 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 implante-o 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 se integra automaticamente aos 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​

  • Registre seu agente no Unity Catalog.
  • Instalar o MLflow 3.1.3 ou superior 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 superior.

Instalar 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()

Implantar agentes utilizando deploy()​

Implante seu agente em um endpoint de 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 deploy(), a Databricks configura automaticamente a infraestrutura de produção e integra seu agente com os recursos de AI generativa do MLflow da seguinte forma:

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 por default:

  • **Cria um Endpoint de servindo modelo** para hospedar seu agente com escalonamento automático e balanceamento de carga.
  • Provê autenticação segura para seu agente acessar recursos subjacentes
  • Permite o monitoramento em tempo real por meio do rastreamento de experimentos MLflow e avaliação automatizada de qualidade no tráfego de produção
  • Configura a colaboração das partes interessadas usando o Review App para coleta de feedback.

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

Personalize a implantação​

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

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

Atualizar uma Implantação Existente​

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

Para obter implantações sem tempo de inatividade, não altere nenhuma configuração além da versão do modelo no UC (ou seja, endpoint_name e o 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 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 agente​

Se o seu Workspace utiliza o Private Service Connect ou políticas de rede de saída restrita, você deve configurar o acesso à rede para que as implantações do agente sejam bem-sucedidas. Os endpoints de serviço de modelos exigem acesso externo para download de dependências durante o processo de construção do contêiner. Os agentes também podem precisar acessar APIs externas em Runtime.

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

Para agentes implantados em Model Serving, verifique o seguinte:

  • Dependências em tempo de build: Sua política de rede deve permitir acesso a repository de pacotes exigidos pelo ambiente do seu agente, como pypi.org ou files.pythonhosted.org para pacotes Python. Databricks registra falhas de build 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 Private Service Connect, verifique se o seu agente consegue resolver os hostnames de quaisquer serviços Databricks dos quais ele dependa, como o AI Search ou endpoints de SQL Warehouse.

Ações detalhadas de implantação​

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

deploy() Ação

Descrição

Criar endpoint de servindo modelo

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

Provisionar autenticação segura

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

A Databricks verifica que o proprietário do Endpoint tem as permissões necessárias antes de emitir 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 a recursos de endpoints de servindo modelo.

Habilitar Aplicativo de Revisão

Fornece uma interface web onde as partes interessadas podem interagir com seu agente e fornecer feedback. Consulte Coletar feedback e expectativas rotulando rastreamentos existentes.

Habilitar rastreamento em tempo real

Logs 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 rastreamentos
  • Rastreamentos também são gravados em tabelas de inferência para armazenamento de longo prazo.

Habilitar monitoramento de produção (beta)

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

Habilitar tabelas de inferência

Cria tabelas que log entradas de solicitação e respostas para auditoria e análise.

Aviso: os logs de solicitação e os logs de avaliação foram descontinuados e serão removidos em uma versão futura. Em vez disso, use o rastreamento em tempo real do MLflow 3. Consulte descontinuação de logs de solicitação e logs de avaliação para orientação sobre migração.

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

Logs REST API requests e feedback do aplicativo de revisão

Logs 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.

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

deploy() Ação

Descrição

Criar endpoint de servindo modelo

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

Provisionar autenticação segura

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

A Databricks verifica que o proprietário do Endpoint tem as permissões necessárias antes de emitir 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 a recursos de endpoints de servindo modelo.

Habilitar Aplicativo de Revisão

Fornece uma interface web onde as partes interessadas podem interagir com seu agente e fornecer feedback. Consulte Coletar feedback e expectativas rotulando rastreamentos existentes.

Habilitar rastreamento em tempo real

Logs 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 rastreamentos
  • Rastreamentos também são gravados em tabelas de inferência para armazenamento de longo prazo.

Habilitar monitoramento de produção (beta)

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

Habilitar tabelas de inferência

Cria tabelas que log entradas de solicitação e respostas para auditoria e análise.

Aviso: os logs de solicitação e os logs de avaliação foram descontinuados e serão removidos em uma versão futura. Em vez disso, use o rastreamento em tempo real do MLflow 3. Consulte descontinuação de logs de solicitação e logs de avaliação para orientação sobre migração.

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

Logs REST API requests e feedback do aplicativo de revisão

Logs 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.

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

Outros recursos​

Nesta página