Implantar um agente para aplicativo de IA generativa

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 avaliações para interagir com o agente implantado e fornecer feedback que será incorporado 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.

• Instale o databricks-agents SDK.

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

Implantar um agente usando deploy()

A função deploy() faz o seguinte:

• Cria um modelo de CPU que fornece endereços de serviço para o seu agente, podendo ser integrados na sua aplicação para o utilizador.

  • Para reduzir os custos associados a endpoints ociosos (às custas de um aumento do tempo para atender a consultas iniciais), pode ativar o escalar para zero no seu endpoint de serviço passando scale_to_zero_enabled=True para deploy(). Consulte Expectativas de dimensionamento de ponto de extremidade.
  • Permite tabelas de inferência com o AI Gateway no endpoint de disponibilização do modelo. Veja como monitorizar modelos servidos usando tabelas de inferência ativadas pelo Gateway AI.

  Nota

  Para os logs de resposta de streaming, apenas os campos e rastreamentos compatíveis com ChatCompletion são agregados.

  • O Databricks fornece automaticamente credenciais de principal de serviço de curta duração para o código do agente em execução no endpoint. As credenciais têm as permissões mínimas para acessar recursos gerenciados pelo Databricks, conforme definido durante o registro em log do modelo. Antes de gerar essas credenciais, o Databricks garante que o proprietário do ponto de extremidade tenha as permissões apropriadas para evitar o escalonamento de privilégios e o acesso não autorizado. Consulte Autenticação para recursos dependentes.
    • Se você tiver dependências de recursos que não são gerenciadas por Databricks, por exemplo, usando o Pinecone, poderá passar variáveis de ambiente com segredos para a API deploy(). Consulte Configurar o acesso a recursos a partir dos endpoints de fornecimento de modelos.

• Habilita a Aplicação de Avaliações para o seu agente. O Aplicativo de Revisão permite que as partes interessadas conversem com o agente e deem feedback usando a interface do usuário do Aplicativo de Revisão.

• Registra todas as solicitações no aplicativo de revisão ou na API REST em uma tabela de inferência. Os dados registrados incluem solicitações de consulta, respostas e dados de rastreamento intermediários do MLflow Tracing.

• Cria um modelo de feedback com o mesmo catálogo e esquema do agente que você está tentando implantar. Esse modelo de feedback é o mecanismo que torna possível aceitar comentários do aplicativo Review e registrá-los em uma tabela de inferência. Esse modelo é servido no mesmo modelo de CPU que serve o ponto de extremidade do seu agente implantado. Como este endpoint de serviço tem tabelas de inferência habilitadas, é possível registar feedback da aplicação de revisão em uma tabela de inferência.

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.

from databricks.agents import deploy
from mlflow.utils import databricks_utils as du

deployment = deploy(model_fqn, uc_model_info.version)

# query_endpoint is the URL that can be used to make queries to the app
deployment.query_endpoint

# Copy deployment.rag_app_url to browser and start interacting with your RAG application.
deployment.rag_app_url

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 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 automática de autenticação

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

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

Veja Monitorizar agentes implantados com tabelas de inferência.

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

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 DLT"
                      }
                  ],
                  "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

• O que é o Mosaic AI Agent Evaluation?
• Use o aplicativo de revisão para avaliações humanas de um aplicativo de IA de geração