Pular para o conteúdo principal

implantado um agente para aplicativos generativos AI

Este artigo mostra como implantar seu agenteAI em Mosaic AI Model Serving usando a função deploy() do Agent Framework Python API .

Os agentes implantados no site Mosaic AI Model Serving oferecem os seguintes benefícios:

  • servindo modelo gerenciar autoscale, logging, controle de versão e controle de acesso, permitindo que o senhor se concentre no desenvolvimento de agentes de qualidade.
  • Os especialistas no assunto podem usar o Review App para interagir com o agente implantado e fornecer feedback que será incorporado ao monitoramento e às avaliações.
  • Você pode monitorar o agente executando uma avaliação do tráfego ao vivo. Embora o tráfego de usuários não inclua a verdade básica, os juízes do LLM (e as métricas personalizadas que o senhor criou) realizam uma avaliação não supervisionada.

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 do agente em Unity Catalog.

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

  • Instale o SDK do databricks-agents.

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

implantado um agente usando deploy()​

Use implantado() para implantar seu agente em um modelo de serviço endpoint.

Python
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 função deploy() executa as seguintes ações em default:

  • Cria um endpoint de modelo de serviço de CPU para integrar seu agente a aplicativos voltados para o usuário.

  • Permite que as tabelas de inferência monitorem e depurem agentes registrando as entradas e respostas das solicitações.

    • Para os agentes ChatAgent e ChatModel, as tabelas de inferência são ativadas com o AI Gateway.
    • Para a resposta de transmissão logs, somente os campos e traços compatíveis com ChatAgent e ChatCompletion são agregados.

  • Fornecimento de credenciais de entidade de serviço de curta duração para o código do agente em execução no site endpoint.

  • Habilita o Review App , permitindo que as partes interessadas interajam com o agente e forneçam feedback. Consulte Usar o aplicativo de avaliação para obter avaliações humanas de um aplicativo do gênero AI.

  • registra as solicitações do REST API e o feedback do Review App em uma tabela de inferência.

    • Cria um modelo de feedback para aceitar 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.
nota

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.

Personalize a implantação​

Para personalizar a implantação, você pode passar argumentos adicionais para deploy(). Por exemplo, o senhor pode ativar a escala para zero para o endpoint parado 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 excluir implantações de agentes​

Recuperar ou gerenciar implantações de agentes existentes:

Python
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 recurso dependente​

AI Os agentes geralmente precisam se autenticar em outro recurso para concluir a tarefa. Por exemplo, um agente pode precisar acessar um índice de pesquisa vetorial para consultar dados não estruturados.

Seu agente pode usar um dos métodos a seguir para se autenticar no recurso dependente quando o senhor o atende por meio de um modelo de atendimento endpoint:

  1. Passagem automática de autenticação: Declare as dependências do recurso Databricks para o seu agente durante o registro. Databricks pode provisionar, girar e gerenciar automaticamente credenciais de curta duração quando seu agente é implantado para acessar recursos com segurança. A Databricks recomenda o uso de passagem automática de autenticação sempre que possível.
  2. Autenticação na metade do usuário: Permite usar as credenciais do usuário final do agente para acessar Databricks REST APIs e recurso
  3. Autenticação manual: especifique manualmente credenciais de longa duração durante a implantação do agente. Use a autenticação manual para Databricks recurso que não seja compatível com a passagem automática de autenticação ou para acesso externo a API.

Passagem automática de autenticação​

O modelo de serviço oferece suporte à passagem automática de autenticação para os tipos mais comuns de Databricks recurso usados pelos agentes.

Para ativar a passagem automática de autenticação, você deve especificar dependências durante o registro do agente.

Então, quando o senhor serve o agente por trás de um endpoint, o Databricks executa as seguintes etapas:

  1. Verificação de permissão: A Databricks verifica se o criador do endpoint pode acessar todas as dependências especificadas durante o registro em log do agente.

  2. criação e concessões da entidade de serviço : Uma entidade de serviço é criada para a versão do modelo do agente e recebe automaticamente acesso de leitura ao recurso do agente.

nota

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

  1. Provisionamento e rotação de credenciais : Credenciais de curta duração ( tokens M2M OAuth) para a entidade de serviço são injetadas no site endpoint, permitindo que o código do agente acesse o recurso Databricks. Databricks também faz a rotação das credenciais, garantindo que seu agente tenha acesso contínuo e seguro ao recurso dependente.

Esse comportamento de autenticação é semelhante ao comportamento de "execução como proprietário" dos painéis do site Databricks - recursos downstream, como as tabelas do site Unity Catalog, são acessados usando as credenciais de uma entidade de serviço com acesso de menor privilégio ao recurso dependente.

A tabela a seguir lista o recurso Databricks que suporta a passagem automática de autenticação e as permissões que o criador do endpoint deve ter ao implantar o agente.

nota

Unity Catalog O recurso também requer USE SCHEMA no esquema pai e USE CATALOG no catálogo pai.

Tipo de recurso

Permissão

SQL Warehouse

Usar endpoint

Modelo de ponto de extremidade de serviço

Pode consultar

Unity Catalog Função

EXECUTAR

Espaço Genie

Pode executar

Índice de pesquisa vetorial

Pode usar

Unity Catalog Tabela

SELECIONAR

Autenticação em nome do usuário​

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

  1. No código do agente, certifique-se de que um recurso do databricks esteja sendo acessado com um cliente que tenha a autenticação no meio do usuário ativada. Consulte Autenticação no local do usuário para obter mais informações.
  2. No momento do registro do agente, especifique os escopos da API REST do usuário final (por exemplo, vectorsearch.vector-search-endpoints) exigidos pelo seu agente. Quando o agente for implantado posteriormente, ele poderá acessar Databricks recurso em nome do usuário final, mas somente usando os escopos especificados. Para obter mais informações sobre os escopos do API, consulte Autenticação no local do usuário.

Autenticação manual​

O senhor também pode fornecer credenciais manualmente usando a variável de ambiente baseada em segredos. A autenticação manual pode ser útil nos seguintes cenários:

  • O recurso dependente não é compatível com a passagem automática de autenticação.
  • O agente está acessando um recurso externo ou uma API.
  • O agente precisa usar credenciais diferentes das do implantador do agente.

Por exemplo, para usar o Databricks SDK em seu agente para acessar outro recurso dependente, o senhor pode definir a variável de ambiente descrita em Databricks autenticação unificada de cliente.

Monitorar agentes implantados​

Depois que um agente é implantado no Databricks servindo modelo, o senhor pode usar as tabelas de inferência do AI Gateway para monitorar o agente implantado. As tabelas de inferência contêm detalhes logs de solicitações, respostas, rastreamentos de agentes e feedback de agentes do aplicativo de análise. Essas informações permitem que o senhor depure problemas, monitore o desempenho e crie um golden dataset para avaliação off-line.

Consulte Monitorar agentes implantados com tabelas de inferência.

Obter aplicativos implantados​

A seguir, mostramos como fazer seus agentes serem implantados.

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

Bash
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

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.

Recurso adicional​

Última atualização em