Implantar um agente para aplicativos generativos de IA

Este artigo mostra como implantar seu agente de IA no Mosaic AI Model Serving usando a função deploy() da API Python do Agent Framework.

A implantação de agentes no Mosaic AI Model Serving oferece os seguintes benefícios:

• O Model Serving gerencia o dimensionamento automático, o registro, o controle de versão e o controle de acesso, permitindo que você se concentre no desenvolvimento de agentes de qualidade.
• Os especialistas no assunto podem usar o aplicativo de revisão para interagir com o agente implantado e fornecer feedback que você pode incorporar ao seu monitoramento e avaliações.
• Você pode monitorizar o agente executando a avaliação no tráfego ao vivo. Embora o tráfego de usuários não inclua a verdade do terreno, os juízes do LLM (e a métrica personalizada que você criou) realizam uma avaliação não supervisionada.

Requisitos

• MLflow 2.13.1 ou superior para implantar agentes usando a deploy() API do databricks.agents.

• Registre um agente de IA no Unity Catalog. Consulte Registrar o agente no Unity Catalog.

• A implementação de agentes fora de um notebook Databricks requer a versão databricks-agents SDK 0.12.0 ou superior.

• O criador do ponto de extremidade (o utilizador que implementa o agente) deve ter as CREATE VOLUME permissões no esquema do Catálogo Unity selecionado para armazenar as tabelas de inferência no momento da implementação. Isso garante que tabelas de avaliação e registro relevantes possam ser criadas no esquema. Consulte Ativar e desativar tabelas de inferência.

• Instale o databricks-agents SDK.

  %pip install databricks-agents
  dbutils.library.restartPython()
  

Implantar um agente usando deploy()

Use deploy() para implantar o seu agente num endpoint de serviço do modelo.

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

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

deploy() ação	Descrição
Criar modelo de CPU servindo pontos de extremidade	Torna o seu agente acessível a aplicativos voltados para o utilizador, servindo-o através de um endpoint de serviço de modelos.
Fornecer credenciais temporárias de entidade de serviço	O Databricks fornece automaticamente credenciais de curta duração com permissões mínimas para acessar os recursos gerenciados pelo Databricks definidos ao registrar seu modelo. O Databricks verifica se o proprietário do ponto de extremidade tem as permissões necessárias antes de emitir as credenciais para evitar o escalonamento de privilégios e o acesso não autorizado. Consulte Autenticação para recursos dependentes. Se o seu agente depender de um recurso não gerido pelo Databricks, poderá passar variáveis de ambiente com segredos para deploy(). Consulte Configurar o acesso a recursos a partir dos endpoints de fornecimento de modelos.
Ativar aplicação de revisão	Permite que as partes interessadas interajam com o agente e forneçam feedback. Consulte Usar o aplicativo de revisão para avaliações humanas de um aplicativo de IA de geração (MLflow 2).
Habilitar tabelas de inferência	Monitore e depure agentes registrando entradas e respostas de solicitações. Para ChatAgent e ChatModel agentes, as tabelas de inferência são habilitadas com o AI Gateway. Para outros esquemas de agente preteridos, tabelas de inferência padrão são usadas. Para logs de resposta de streaming, apenas os campos e rastreamentos compatíveis com ChatAgent e ChatCompletion são agregados.
Registrar solicitações de API REST e revisar comentários sobre aplicativos	Registra solicitações de API e comentários em uma tabela de inferência. Crie um modelo de feedback para aceitar e registrar comentários do aplicativo Avaliações. Este modelo é servido no mesmo endpoint de serviço do modelo de CPU que o seu agente implantado.
Ativar a Monitorização do Lakehouse para Gen AI (beta)	Requer inscrição no Lakehouse Monitoring for Gen AI beta. A monitorização básica é ativada automaticamente para os rastreios de agentes implementados.
Habilite o rastreamento e o monitoramento em tempo real com o MLflow 3 (beta)	Requer inscrição no Lakehouse Monitoring for Gen AI beta e uso do MLflow 3.0 ou superior. Além de registrar rastreamentos de agentes implantados em tabelas de inferência para armazenamento de longo prazo, o Databricks registra rastreamentos de seu agente implantado em um experimento MLflow para visibilidade em tempo real. Isso reduz as latências associadas ao monitoramento e à depuração. Quando você cria um novo ponto de extremidade via agents.deploy(), o monitoramento e o rastreamento são configurados para ler e gravar a partir do experimento MLflow atualmente ativo. Configure o experimento para um ponto de extremidade específico chamando mlflow.set_experiment() antes de invocar agents.deploy() para criar o ponto de extremidade. Rastreamentos de todos os agentes atendidos no ponto de extremidade (incluindo agentes adicionados ao ponto de extremidade por meio de chamadas subsequentes para agents.deploy()) são gravados neste experimento. A monitorização calcula métricas de qualidade em registos neste experimento. Por padrão, apenas métricas básicas de monitoramento são configuradas. Para adicionar juízes LLM e muito mais, consulte Configurar monitoramento.

Nota

As implantações podem levar até 15 minutos para serem concluídas. Os dados JSON brutos levam de 10 a 30 minutos para chegar, e os logs formatados são processados a partir desses dados aproximadamente a cada hora.

Personalizar a implantação

Para personalizar a implantação, você pode passar argumentos adicionais para deploy(). Por exemplo, você pode habilitar o redimensionamento para zero para endpoints ociosos passando scale_to_zero_enabled=True. Isso reduz os custos, mas aumenta o tempo para atender às consultas iniciais.

Para obter mais parâmetros, consulte Databricks Agents Python API.

Recuperar e apagar implantações de agente

Recupere ou gerencie implantações de agentes existentes:

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)

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

Autenticação para recursos dependentes

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

O seu agente pode usar um dos seguintes métodos para autenticação aos recursos dependentes quando o coloca atrás de um endpoint de Servição de Modelos:

1. Passagem automática de autenticação: Declare as dependências de recursos do Databricks para o seu agente durante o processo de registo. O Databricks pode provisionar, alternar e gerir automaticamente credenciais de curta duração quando o agente é implantado para aceder a recursos de forma segura. O Databricks recomenda o uso de passagem de autenticação automática sempre que possível.
2. Autenticação em nome do usuário: Permite usar credenciais de usuário final do agente para acessar APIs e recursos REST do Databricks
3. Autenticação Manual: Especificar manualmente as credenciais de longa duração durante a implantação do agente. Use a autenticação manual para recursos do Databricks que não suportam passagem de autenticação automática ou para acesso externo à API.

Passagem de autenticação automática

O Model Serving suporta passagem de autenticação automática para os tipos mais comuns de recursos do Databricks usados pelos agentes.

Para habilitar a passagem de autenticação automática, deve-se especificar dependências durante o registo do agente.

Em seguida, quando se atende o agente por trás de um endpoint, o Databricks executa as seguintes etapas:

1. Verificação de permissão: O Databricks verifica se o criador do endpoint pode aceder a todas as dependências especificadas durante o registo do agente.

2. Criação e concessões do principal de serviço: Um principal de serviço é criado para a versão do modelo do agente e recebe automaticamente acesso de leitura aos recursos do agente.

   Nota

   A entidade de serviço gerada pelo sistema não aparece nas listas da API nem na UI. Se a versão do modelo do agente for removida do endpoint, a entidade de serviço também será excluída.

3. Provisionamento e rotação de credenciais: credenciais de curta duração (um token M2M OAuth ) são injetadas no endpoint para um service principal, permitindo que o código do agente aceda aos recursos do Databricks. O Databricks também alterna as credenciais, garantindo que seu agente tenha acesso contínuo e seguro aos recursos dependentes.

Esse comportamento de autenticação é semelhante ao comportamento "Executar como proprietário" para painéis do Databricks – recursos downstream, como tabelas do Unity Catalog, são acessados usando as credenciais de um principal de serviço com acesso de privilégios mínimos aos recursos dependentes.

A tabela a seguir lista os recursos do Databricks que oferecem suporte à passagem de autenticação automática e as permissões que o criador do ponto de extremidade deve ter ao implantar o agente.

Nota

Os recursos do Catálogo Unity também exigem USE SCHEMA no esquema pai e USE CATALOG no catálogo pai.

Tipo de recurso	Permissão
Armazém SQL	Usar o Endpoint
Endpoint de serviço do modelo	Pode efetuar consultas
Função do Unity Catalog	EXECUTAR
Espaço Genie	Pode Executar
Índice de pesquisa vetorial	Pode usar
Tabela do Catálogo Unity	SELECT

Autenticação em nome do usuário

A autenticação em nome do usuário permite que os desenvolvedores do agente acessem recursos confidenciais do Databricks usando as credenciais de usuário final do agente. Para habilitar o acesso em nome do usuário aos recursos, há duas etapas:

1. No código do agente, verifique se um recurso databricks está sendo acessado com um cliente que tenha a autenticação em nome do usuário habilitada. Consulte Implantar um agente usando a autenticação em nome do usuário para obter mais informações.
2. No momento de registo do agente, especifique os escopos da API REST do utilizador final (por exemplo, vectorsearch.vector-search-endpoints) exigidos pelo agente. Quando seu agente é implantado posteriormente, ele pode acessar recursos do Databricks em nome do usuário final, mas apenas usando os escopos especificados. Para obter mais informações sobre escopos de API, consulte Autenticação em nome do usuário.

Autenticação manual

Você também pode fornecer credenciais manualmente usando variáveis de ambiente baseadas em segredos. A autenticação manual pode ser útil nos seguintes cenários:

• O recurso dependente não suporta passagem de autenticação automática.
• O agente está acessando um recurso externo ou API.
• O agente precisa usar credenciais diferentes das do responsável pela implementação do agente.

Por exemplo, para usar o SDK do Databricks no seu agente para aceder a outros recursos dependentes, pode definir as variáveis de ambiente descritas em Autenticação Unificada do Cliente Databricks.

Monitorizar agentes implantados

Depois que um agente é implantado no Databricks Model Serving, você pode usar tabelas de inferência do AI Gateway para monitorar o agente implantado. As tabelas de inferência contêm logs detalhados de solicitações, respostas, rastreamentos de agentes e comentários de agentes do aplicativo de revisão. Essas informações permitem depurar problemas, monitorar o desempenho e criar um conjunto de dados dourado para avaliação offline.

Importante

Se o MLflow 3 estiver instalado no seu ambiente de desenvolvimento quando chamar agents.deploy(), o seu endpoint irá registar os Rastros MLflow em tempo real no Experimento MLflow ativado no momento da chamada agents.deploy(). Você pode ligar mlflow.set_experiment() para alterar o experimento ativo antes da implantação.

Consulte os documentos do MLflow para obter mais detalhes.

Consulte Depure e Observe a sua aplicação com rastreamento.

Obtenha aplicações implantadas

O seguinte mostra como obter os seus agentes em operação.

from databricks.agents import list_deployments, get_deployments

# Get the deployment for specific model_fqn and version
deployment = get_deployments(model_name=model_fqn, model_version=model_version.version)

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

Consulte Databricks Agents Python API.

Fornecer feedback sobre um agente implantado (experimental)

Quando implanta o seu agente com agents.deploy(), a estrutura do agente também cria e implanta uma versão de modelo de "feedback" no mesmo endpoint, a qual pode consultar para fornecer feedback sobre a sua aplicação do agente. As entradas de feedback aparecem como linhas de pedidos na tabela de inferência associada ao endpoint de serviço do seu agente.

Observe que esse comportamento é experimental: o Databricks pode fornecer uma API de primeira classe para fornecer comentários sobre um agente implantado no futuro, e a funcionalidade futura pode exigir a migração para essa API.

As limitações desta API incluem:

• A API de feedback não tem validação de entrada - ela sempre responde com êxito, mesmo se a entrada inválida for aprovada.
• A API de feedback requer a inserção do identificador gerado pelo Databricks request_id do pedido à endpoint do agente para o qual deseja fornecer feedback. Para obter o databricks_request_id, inclua {"databricks_options": {"return_trace": True}} na sua solicitação original ao agente responsável pelo endpoint. A resposta do endpoint do agente incluirá o databricks_request_id associado à solicitação para que possas passar esse ID de solicitação de volta para a API de feedback ao fornecer feedback sobre a resposta do agente.
• O feedback é coletado usando tabelas de inferência. Consulte as limitações da tabela de inferência, ,.

A seguinte solicitação de exemplo fornece feedback sobre o ponto final do agente chamado "your-agent-endpoint-name" e assume que a variável de ambiente DATABRICKS_TOKEN está definida como um token da API REST do Databricks.

curl \
  -u token:$DATABRICKS_TOKEN \
  -X POST \
  -H "Content-Type: application/json" \
  -d '
      {
          "dataframe_records": [
              {
                  "source": {
                      "id": "user@company.com",
                      "type": "human"
                  },
                  "request_id": "573d4a61-4adb-41bd-96db-0ec8cebc3744",
                  "text_assessments": [
                      {
                          "ratings": {
                              "answer_correct": {
                                  "value": "positive"
                              },
                              "accurate": {
                                  "value": "positive"
                              }
                          },
                          "free_text_comment": "The answer used the provided context to talk about Lakeflow Declarative Pipelines"
                      }
                  ],
                  "retrieval_assessments": [
                      {
                          "ratings": {
                              "groundedness": {
                                  "value": "positive"
                              }
                          }
                      }
                  ]
              }
          ]
      }' \
https://<workspace-host>.databricks.com/serving-endpoints/<your-agent-endpoint-name>/served-models/feedback/invocations

Você pode passar pares chave-valor adicionais ou diferentes nos campos text_assessments.ratings e retrieval_assessments.ratings para fornecer outros tipos de feedback. No exemplo, a carga útil de feedback indica que a resposta do agente à solicitação com ID 573d4a61-4adb-41bd-96db-0ec8cebc3744 foi correta, precisa e fundamentada no contexto buscado por uma ferramenta retriever.

Recursos adicionais

• Consultar um agente Mosaic AI implantado
• Avaliação do Agente de IA em Mosaico (MLflow 2)
• Use o aplicativo de revisão para avaliações humanas de um aplicativo de IA de geração (MLflow 2)
• Depurar um agente de IA implantado