Compartilhar via

Implantar um agente em um aplicativo de IA generativa

  • Artigo

Importante

Esse recurso está em uma versão prévia.

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

Requisitos

  • É necessário ter o MLflow 2.13.1 ou superior para implantar agentes utilizando a API deploy() do databricks.agents.

  • Registre um agente de IA no Catálogo do Unity. Confira Registre a cadeia no Catálogo do Unity.

  • Instalar o SDK do databricks-agents

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

Implantar um agente usando deploy()

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

  • Cria pontos de extremidade de CPU de serviço de modelo para seu agente que podem ser integrados ao seu aplicativo voltado para o usuário.
    • Para reduzir o custo de endpoints ociosos (às custas do aumento do tempo para atender às consultas iniciais), você pode habilitar a escala para zero para o endpoint de serviço passando scale_to_zero_enabled=True para deploy(). Consulte Expectativas de escalabilidade de endpoint.
    • As tabelas de inferência são habilitadas nesses pontos de extremidade de serviço de modelo. Consulte Tabelas de inferência para modelos de monitoramento e depuração.
    • As credenciais de autenticação são fornecidas automaticamente para todos os recursos gerenciados pelo Databricks exigidos pelo agente, como especificado ao registrar o modelo em log. O Databricks cria uma entidade de serviço que tem acesso a esses recursos e a passa automaticamente para o ponto de extremidade. Consulte Autenticação para recursos dependentes.
  • Habilita o Aplicativo de Revisão para o agente. O Aplicativo de Revisão permite que os stakeholders conversem com o agente e forneçam comentários usando a interface do usuário do Aplicativo de Revisão.
  • Registra todas as solicitações para o Aplicativo de Revisão ou a API REST em uma tabela de inferência. Os dados registrados incluem solicitações de consulta, respostas e dados de rastreamento de intermediários do Rastreamento do MLflow.
  • 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 feedback do aplicativo Review e registrá-lo em uma tabela de inferência. Esse modelo é servido no mesmo ponto de extremidade de atendimento do modelo de CPU que seu agente implementado. Esse modelo é servido no mesmo endpoint de atendimento do modelo de CPU que seu agente implementou.

Observação

As implantações podem levar até 15 minutos para terminar. Os conteúdos JSON brutos demoram de 10 a 30 minutos para chegar, e os logs formatados são processados a partir dos conteúdos brutos 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

Tabelas de inferência aprimoradas pelo agente

O deploy() cria três tabelas de inferência para cada implantação, a fim de registrar solicitações e respostas de e para o ponto de extremidade de serviço do agente. Os usuários podem esperar que os dados estejam nessa tabela do payload dentro de uma hora depois de interagirem com a implantação.

Os logs de solicitação de payload e os logs de avaliação podem levar mais tempo para serem preenchidos, mas são derivados da tabela de payload bruta. É possível extrair logs de solicitação e avaliação da tabela de payload por conta própria. As exclusões e atualizações na tabela de carga não são refletidas nos logs de solicitação de carga ou nos logs de avaliação de carga.

Observação

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

Tabela Exemplo de nome de tabela do Unity Catalog O que contém cada tabela
Conteúdo {catalog_name}.{schema_name}.{model_name}_payload Payloads de solicitação e resposta JSON
Logs de solicitação de conteúdo {catalog_name}.{schema_name}.{model_name}_payload_request_logs Solicitações e respostas formatadas, rastreamentos do MLflow
Logs de avaliação de conteúdo {catalog_name}.{schema_name}.{model_name}_payload_assessment_logs Comentários formatados, conforme fornecido no Aplicativo de Revisão, para cada solicitação

A seguir, é apresentado o esquema para a tabela de registros de solicitações.

Nome da coluna Type Descrição
client_request_id String ID da solicitação do cliente, geralmente null.
databricks_request_id String ID da solicitação do Databricks.
date Data Data da solicitação.
timestamp_ms Longo Carimbo de data/hora em milissegundos.
timestamp Timestamp Carimbo de hora da solicitação.
status_code Inteiro Código de status do ponto de extremidade.
execution_time_ms Longo Total de milissegundos de execução.
conversation_id String ID de conversa extraída dos logs de solicitação.
request String A última consulta de usuário da conversa do usuário. Isso é extraído da solicitação RAG.
response String A última resposta para o usuário. Isso é extraído da solicitação 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 rastreamento extraído do databricks_options do struct de resposta.
sampling_fraction Double Fração de amostragem.
request_metadata Map[String, String] Um mapa de metadados relacionados ao ponto de extremidade de serviço de modelo associado à solicitação. Este mapa contém o nome do ponto de extremidade, o nome do modelo e a versão do modelo usados para o ponto de extremidade.
schema_version String Inteiro para a versão do esquema.

Veja a seguir o esquema da tabela de logs da avaliação.

Nome da coluna Type Descrição
request_id String ID da solicitação do Databricks.
step_id String Derivado da avaliação de recuperação.
source Estrutura Um campo de struct que contém as informações sobre quem criou a avaliação.
timestamp Timestamp Carimbo de data/hora da solicitação.
text_assessment Estrutura Um campo de struct que contém os dados de qualquer comentário sobre as respostas do agente do aplicativo de revisão.
retrieval_assessment Estrutura Um campo de struct que contém os dados de qualquer comentário sobre os documentos recuperados para uma resposta.

Requisitos de permissão para recursos dependentes

Ao implantar um modelo com recursos dependentes, o criador do ponto de extremidade deve ter as seguintes permissões, dependendo do tipo de recurso:

Tipo de recurso Permissão
Armazém SQL Usar ponto de extremidade
Ponto de extremidade de serviço do modelo Pode consultar
Função de catálogo do Unity Executar
Espaço do gênio Executar
Índice de pesquisa vetorial ReadVectorIndex
Tabela de catálogo do Unity Pode ler

Autenticação para recursos dependentes

Ao criar o ponto de extremidade de serviço do modelo para implantação do agente, o Databricks verifica se o criador do endpoint possui as permissões para acessar todos os recursos dos quais o agente é dependente.

Para agentes LangChain, os recursos dependentes são automaticamente inferidos durante a criação e o registro do agente. Esses recursos estão registrados no arquivo resources.yaml no artefato de modelo registrado. Durante a implantação, databricks.agents.deploy cria automaticamente os tokens OAuth M2M necessários para acessar e se comunicar com essas dependências de recursos inferidas.

Para agentes do tipo PyFunc, você deve especificar manualmente quaisquer dependências de recursos durante o registro do agente implantado no parâmetro resources. Consulte Especificar recursos para o agente PyFunc ou LangChain. Durante a implantação, databricks.agents.deploy cria um token OAuth M2M com acesso aos recursos especificados no parâmetro resources e o implanta no agente implantado.

Passagem de autenticação automática

A tabela a seguir lista os recursos que oferecem suporte à passagem de autenticação automática. A passagem de autenticação automática usa as credenciais do criador da implantação para autenticar automaticamente em recursos com suporte.

Recurso Versão mlflow mínima
Índices de busca em vetores Requer o mlflow 2.13.1 ou superior
Ponto de extremidade do serviço de modelo Requer o mlflow 2.13.1 ou superior
SQL warehouses Requer o mlflow 2.16.1 ou superior
Funções do Catálogo do Unity Requer o mlflow 2.16.1 ou superior

Autenticação manual

Se você tiver um recurso dependente que não oferece suporte à passagem de autenticação automática ou se quiser usar credenciais diferentes das do criador da implementação, poderá fornecer manualmente as credenciais usando variáveis de ambiente baseadas em segredos. Por exemplo, se estiver usando o SDK do Databricks em seu agente para acessar outros tipos de recursos dependentes, você poderá definir as variáveis de ambiente descritas em Autenticação unificada do cliente do Databricks.

Obter os aplicativos implantados

O exemplo a seguir mostra como obter os 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 "comentários" no mesmo ponto de extremidade, que você pode consultar para fornecer comentários sobre o aplicativo do agente. As entradas de feedback aparecem como linhas de solicitação na tabela de inferência associada ao endpoint 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 dessa API incluem:

  • A API de comentários não tem validação de entrada - ela sempre responde com êxito, mesmo se for passada uma entrada inválida.
  • A API de comentários requer a passagem da solicitação de ponto de extremidade do agente gerada request_id pelo Databricks sobre a qual você deseja fornecer comentários. Para obter o databricks_request_id, inclua {"databricks_options": {"return_trace": True}} em sua solicitação original para o endpoint de atendimento do agente. A resposta do endpoint do agente incluirá a databricks_request_id associada à solicitação, para que você possa passar essa ID de solicitação de volta para a API de comentários ao fornecer comentários sobre a resposta do agente.
  • O feedback é coletado usando tabelas de inferência. Consulte 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 de chave-valor adicionais ou diferentes nos text_assessments.ratings campos e retrieval_assessments.ratings para fornecer diferentes tipos de comentários. No exemplo, a carga 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 de recuperação.

Recursos adicionais