Implantar um agente para aplicativo de IA generativa

Importante

Esta funcionalidade está em Pré-visualização Pública.

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

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. Veja Registe o agente no Unity Catalog.

• A implantação de agentes de fora de um bloco de anotações Databricks requer databricks-agents SDK versão 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 servindo pontos de extremidade para seu agente que podem ser integrados ao seu aplicativo voltado para o usuário.
  • Para reduzir o custo de pontos de extremidade ociosos (às custas do aumento do tempo para atender consultas iniciais), você pode habilitar a escala para zero para seu ponto de extremidade de serviço passando scale_to_zero_enabled=True para deploy(). Consulte Expectativas de dimensionamento de endpoint.
  • As tabelas de inferência estão ativadas nestes pontos de extremidade de serviço de modelo. Consulte Tabelas de inferência para monitorar e depurar modelos.
  • O Databricks fornece automaticamente credenciais temporárias de entidade de serviço para o código do agente que está a correr no ponto de extremidade. As credenciais têm as permissões mínimas para aceder recursos geridos pelo Databricks, conforme definido durante o registo 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 de pontos de extremidade de serviço de modelo.
• Habilita o aplicativo Avaliações para 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 esse ponto de extremidade de serviço tem tabelas de inferência habilitadas, é possível registrar comentários do aplicativo de revisão em uma tabela de inferência.

Nota

As implantações podem levar até 15 minutos para serem concluídas. As cargas úteis JSON brutas levam de 10 a 30 minutos para chegar, e os logs formatados são processados a partir das cargas brutas 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

Tabelas de inferência aprimoradas por agente

O deploy() cria três tabelas de inferência para cada implantação para registrar solicitações e respostas de e para o agente que serve o ponto de extremidade. Os usuários podem esperar que os dados estejam na tabela de carga útil dentro de uma hora após a interação com sua implantação.

Os logs de solicitação de carga útil e os logs de avaliação podem levar mais tempo para serem preenchidos, mas, em última análise, são derivados da tabela de carga bruta. Você mesmo pode extrair logs de solicitação e avaliação da tabela de carga útil. As exclusões e atualizações da tabela de carga útil não são refletidas nos logs de solicitação de carga útil ou nos logs de avaliação de carga útil.

Nota

Se você tiver o Firewall de Armazenamento do Azure habilitado, entre em contato com sua equipe de conta do Databricks para habilitar tabelas de inferência para seus pontos de extremidade.

Tabela	Exemplo de nome da tabela do Catálogo Unity	O que há em cada tabela
Payload	{catalog_name}.{schema_name}.{model_name}_payload	Cargas úteis brutas de solicitação e resposta JSON
Registos de pedidos de carga útil	{catalog_name}.{schema_name}.{model_name}_payload_request_logs	Solicitações e respostas formatadas, rastreamentos MLflow
Logs de avaliação de carga útil	{catalog_name}.{schema_name}.{model_name}_payload_assessment_logs	Comentários formatados, conforme fornecidos no aplicativo Avaliações, para cada solicitação

A seguir mostra o esquema para a tabela de logs de solicitação.

Nome da coluna	Tipo	Description
client_request_id	String	ID de solicitação do cliente, geralmente null.
databricks_request_id	String	Databricks solicitar ID.
date	Date	Data do pedido.
timestamp_ms	Longo	Carimbo de data/hora em milissegundos.
timestamp	Carimbo de Data/Hora	Carimbo de data/hora do pedido.
status_code	Número inteiro	Código de status do ponto de extremidade.
execution_time_ms	Longo	Execução total em milissegundos.
conversation_id	String	ID da conversação extraída dos registos de pedidos.
request	String	A última consulta do usuário da conversa do usuário. Isto é extraído do pedido RAG.
response	String	A última resposta ao usuário. Isto é extraído do pedido RAG.
request_raw	String	Representação de cadeia de caracteres da solicitação.
response_raw	String	Representação de cadeia de caracteres da resposta.
trace	String	Representação de cadeia de caracteres do traço extraído do databricks_options Struct da resposta.
sampling_fraction	Duplo	Fração de amostragem.
request_metadata	Map[String, String]	Um mapa de metadados relacionados ao modelo que serve o ponto de extremidade associado à solicitação. Este mapa contém o nome do ponto de extremidade, o nome do modelo e a versão do modelo usado para o seu ponto de extremidade.
schema_version	String	Inteiro para a versão do esquema.

A seguir está o esquema para a tabela de logs de avaliação.

Nome da coluna	Tipo	Description
request_id	String	Databricks solicitar ID.
step_id	String	Derivado da avaliação de recuperação.
source	Estrutura	Um campo struct contendo as informações sobre quem criou a avaliação.
timestamp	Carimbo de Data/Hora	Carimbo de data/hora do pedido.
text_assessment	Estrutura	Um campo struct contendo os dados para qualquer feedback sobre as respostas do agente do aplicativo de avaliação.
retrieval_assessment	Estrutura	Um campo struct contendo os dados para qualquer feedback sobre os documentos recuperados para uma resposta.

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 autenticar aos recursos dependentes quando o disponibiliza atrás de um endpoint de serviço de modelo:

1. Passagem automática de autenticação: Declare as dependências de recursos do Databricks para o seu agente durante o registo. O Databricks pode provisionar, alternar e administrar automaticamente credenciais de curta duração quando suas agentes são implantados para acessar recursos de forma segura. O Databricks recomenda o uso de passagem de autenticação automática sempre que possível.
2. Autenticação manual: Especifique manualmente credenciais de longa duração durante a implementaçã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 de logs do agente.

Em seguida, quando você atende o agente por trás de um ponto de extremidade, o Databricks executa as seguintes etapas:

1. Verificação de permissão: Databricks verifica se o criador do ponto final 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 privilégios de leitura aos recursos do agente.

   Nota

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

3. Provisionamento e rotação de credenciais: As credenciais de curta duração, como um token M2M OAuth , para o principal de serviço são injetadas no ponto de extremidade, 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 a jusante, 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
Serviço de endpoint do modelo	Pode consultar
Função Catálogo Unity	EXECUTAR
Espaço Genie	Pode Executar
Índice de pesquisa vetorial	Pode usar
Tabela do Catálogo Unity	SELECIONAR

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 daquelas do implantador 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 na autenticação unificada do cliente Databricks .

Obtenha aplicativos implantados

Veja a seguir como obter seus agentes implantados.

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 você implanta seu agente com agents.deploy()o , a estrutura do agente também cria e implanta uma versão do modelo de "feedback" dentro do mesmo ponto de extremidade, que você pode consultar para fornecer comentários sobre seu aplicativo de agente. As entradas de feedback aparecem como linhas de solicitação dentro da tabela de inferência associada ao ponto de extremidade de serviço do 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 passagem do Databricks gerado request_id da solicitação de ponto de extremidade do agente sobre a qual você deseja fornecer feedback. Para obter o databricks_request_id, inclua {"databricks_options": {"return_trace": True}} em sua solicitação original para o agente que serve o ponto de extremidade. A resposta do ponto de extremidade do agente incluirá o databricks_request_id associado à solicitação para que você possa passar esse ID de solicitação de volta para a API de feedback ao fornecer comentários sobre a resposta do agente.
• O feedback é coletado usando tabelas de inferência. Consulte as limitações da tabela de inferência.

A solicitação de exemplo a seguir fornece comentários sobre o ponto de extremidade do agente chamado "your-agent-endpoint-name" e pressupõe que a DATABRICKS_TOKEN variável de ambiente esteja definida como um token de 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 Delta Live Tables"
                      }
                  ],
                  "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 text_assessments.ratings campos e retrieval_assessments.ratings para fornecer diferentes 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?
• Obter feedback sobre a qualidade de um aplicativo agentic