Implantar um agente para aplicativo de IA generativa

Prévia

Esse recurso está em Pré-lançamento público.

Este artigo mostra como implantar seu agenteAI usando o deploy() API de databricks.agents.

Requisitos

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

• registrar um agente AI para Unity Catalog. Veja o registro da corrente em Unity Catalog.

• Instale o SDK do databricks-agents.

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

Implante um agente com deploy()

A API deploy() faz o seguinte:

• Cria endpoint de serviço do modelo de CPU para o seu agente que podem ser integrados ao seu aplicativo voltado para o usuário.

  • As tabelas de inferência estão ativadas nesses endpoints de modelo de serviço. Consulte Tabelas de inferência para monitoramento e depuração de modelos.

    • As credenciais de autenticação são passadas automaticamente para todos os Databricks-gerenciar recurso exigidos pelo agente, conforme especificado no registro do modelo. Databricks cria uma entidade de serviço que tem acesso a esses recursos e automaticamente passa isso para o site endpoint. Consulte Autenticação para recurso dependente.

    • Se você tiver dependências de recursos não gerenciadas pelo Databricks, por exemplo, com o Pinecone, poderá passar variáveis de ambiente com segredos para a API deploy(). Consulte Configurar o acesso aos recursos de endpoints de serviço de modelo.

• Ativa o aplicativo de avaliação para seu agente. O Review App permite que suas partes interessadas conversem com o agente e forneçam feedback usando a interface do Review App.

• registra todas as solicitações no Review App ou REST API em uma tabela de inferência. Os registros de dados 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 o senhor está tentando implantar. Esse modelo de feedback é o mecanismo que torna possível aceitar o feedback do aplicativo Review e log para uma tabela de inferência. Esse modelo é servido na mesma CPU servindo modelo endpoint que seu agente implantado. Como este serviço endpoint tem tabelas de inferência ativadas, é possível log feedback do Review App para uma tabela de inferência.

Observação

As implementações podem levar até 15 minutos para serem concluídas. Os payloads de JSON brutos levam de 10 a 30 minutos para chegar e os registros formatados são processados a partir dos payloads brutos 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 agentes

O deploy() cria três tabelas de inferência para cada implantação para log solicitações e respostas de e para o agente que atende endpoint. Os usuários podem esperar que os dados estejam na tabela de carga útil dentro de uma hora após a interação com a 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 útil bruta. O senhor mesmo pode extrair os 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.

Tabela	Exemplo de nome da tabela do Unity Catalog	O que há em cada tabela
Payload	{catalog_name}.{schema_name}.{model_name}_payload	Cargas de solicitação e resposta JSON brutas
Logs de solicitação de payload	{catalog_name}.{schema_name}.{model_name}_payload_request_logs	Solicitação e respostas formatadas, rastreamentos do MLflow
Logs de avaliação de payload	{catalog_name}.{schema_name}.{model_name}_payload_assessment_logs	Feedback formatado, conforme apresentado no aplicativo de avaliação, para cada solicitação

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

Nome da coluna	Tipo	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	Long	Carimbo de data/hora em milissegundos.
timestamp	Carimbo de data/hora	Carimbo de data/hora da solicitação.
status_code	Integer	Código de status de endpoint.
execution_time_ms	Long	Execução total em milissegundos.
conversation_id	String	ID da conversa extraído da solicitação logs.
request	String	A última consulta do usuário na conversa do usuário. Isso é extraído da solicitação RAG.
response	String	A última resposta ao usuário. Isso é extraído da solicitação RAG.
request_raw	String	representação de strings da solicitação.
response_raw	String	representação em strings da resposta.
trace	String	representação de strings do traço extraído do site databricks_options das estruturas de resposta.
sampling_fraction	Double	Fração de amostragem.
request_metadata	Map[strings, strings]	Um mapa de metadados relacionados ao modelo de serviço endpoint associado à solicitação. Esse mapa contém o nome endpoint, o nome do modelo e a versão do modelo usados para o seu endpoint.
schema_version	String	Número inteiro para a versão do esquema.

A seguir, o esquema da tabela de logs de avaliação.

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

Autenticação para recurso dependente

Ao criar o modelo de serviço endpoint para a implantação do agente, o Databricks verifica se o criador do endpoint tem permissões para acessar todos os recursos dos quais o agente depende.

Para agentes com o endereçoLangChain , os recursos dependentes são inferidos automaticamente durante a criação e o registro de agentes. Esses recursos são registrados no arquivo resources.yaml no artefato de modelos registrados. Durante a implementação, databricks.agents.deploy cria automaticamente o M2M OAuth tokens necessário para acessar e se comunicar com essas dependências de recursos inferidas.

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

Passagem automática de autenticação

A tabela a seguir lista os recursos que suportam a passagem automática de autenticação. A passagem automática de autenticação usa as credenciais do criador da implementação para autenticar automaticamente o recurso compatível.

Recurso	Versão mínima mlflow
Índices de pesquisa vetorial	Requer mlflow 2.13.1 ou acima
servindo modelo endpoint	Requer mlflow 2.13.1 ou acima
SQL warehouses	Requer mlflow 2.16.1 ou acima
Funções do Unity Catalog	Requer mlflow 2.16.1 ou acima

Autenticação manual

Se o senhor tiver um recurso dependente que não ofereça suporte à passagem automática de autenticação ou se quiser usar credenciais diferentes das do criador da implementação, poderá fornecer credenciais manualmente usando a variável de ambiente baseada em segredos. Por exemplo, se estiver usando o Databricks SDK em seu agente para acessar outros tipos de recurso dependente, o senhor pode definir a variável de ambiente descrita em Databricks autenticação unificada de cliente.

Receba aplicativos implantados

A seguir, mostramos como fazer seus agentes serem 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 o agente é implantado com agents.deploy(), a estrutura do agente também cria e implanta uma versão do modelo de "feedback" no mesmo endpoint, que pode ser consultado para fornecer feedback sobre o aplicativo do agente. As entradas de feedback aparecem como linhas de solicitação na tabela de inferência associada ao endpoint de atendimento do agente.

Observe que esse comportamento é experimental: A Databricks pode fornecer uma API de primeira classe para fornecer feedback 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 feedback não tem validação de entrada - ela sempre responde com êxito, mesmo se for passada uma entrada inválida.

• O feedback API requer a passagem do Databricks-generated request_id da solicitação do agente endpoint sobre a qual o senhor deseja fornecer feedback. 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 agente endpoint incluirá então o databricks_request_id associado à solicitação, para que o senhor possa passar essa ID de solicitação de volta para o feedback API ao fornecer feedback sobre a resposta do agente.

• O feedback é coletado usando tabelas de inferência. Veja as limitações da tabela de inferência.

O exemplo de solicitação a seguir fornece feedback sobre o agente endpoint denominado "your-agent-endpoint-name" e pressupõe que a variável DATABRICKS_TOKEN de ambiente esteja definida como Databricks REST API tokens.

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

O senhor pode passar par key-value adicionais ou diferentes nos campos text_assessments.ratings e retrieval_assessments.ratings para fornecer diferentes tipos de feedback. 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 baseada no contexto obtido por uma ferramenta de recuperação.

Outros recursos

• O que é o Mosaic AI Agent Evaluation?

• Receba feedback sobre a qualidade de um aplicativo de agente