implantado um agente para aplicativos generativos AI

Esta página demonstra como implantar o seu AI agente Mosaic AI Model Serving em utilizando a deploy() função 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 o senhor pode incorporar ao seu monitoramento e às suas avaliações.
• Você pode monitorar o agente executando uma avaliação do tráfego ao vivo. Embora o tráfego do usuário não inclua a verdade fundamental, os juízes do LLM (e as métricas personalizadas que você criou) realizam uma avaliação não supervisionada.

Requisitos

• MLflow 2.13.1 ou acima para agentes implantados usando o deploy() API 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.

• O criador do endpoint (o usuário que implantou o agente) deve ter permissões CREATE VOLUME no esquema Unity Catalog selecionado para armazenar as tabelas de inferência no momento da implantação. Isso garante que tabelas relevantes de avaliação e registro possam ser criadas no esquema. Consulte Habilitar e desabilitar tabelas de inferência.

• 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:

deploy() Ação	Descrição
Criar o endpoint CPU servindo modelo	Torna o seu agente acessível aos aplicativos voltados para o usuário, servindo-o por meio de um modelo de serviço endpoint.
provisionamento short-lived entidade de serviço credentials	Databricks fornece automaticamente credenciais de curta duração com permissões mínimas para acessar o Databricks-gerenciar recurso definido ao registrar seu modelo. A Databricks verifica se o proprietário do endpoint tem as permissões necessárias antes de emitir as credenciais para evitar o aumento de privilégios e o acesso não autorizado. Consulte Autenticação para recurso dependente. Se o seu agente depende de um recurso nãoDatabricks-gerenciar, o senhor pode passar variável de ambiente com segredos para deploy(). Consulte Configurar o acesso ao recurso a partir do endpoint do modelo de atendimento.
Ativar aplicativo de avaliação	Permite que as partes interessadas interajam com o agente e forneçam feedback. Consulte Usar o aplicativo de avaliação para avaliações humanas de um aplicativo gen AI (MLflow 2).
Habilitar tabelas de inferência	Monitore e depure agentes registrando as entradas e respostas das solicitações. Para ResponsesAgent e ChatModel or ChatAgent as tabelas de inferência são ativadas com o AI Gateway. Para outros esquemas de agentes obsoletos, tabelas de inferência padrão são usadas. For streaming response logs, only fields and traces compatible with ResponsesAgent, ChatAgent and ChatCompletion are aggregated.
Registre REST API solicitações e comentários sobre o aplicativo de revisão	registra as solicitações e o feedback do API em uma tabela de inferência. Crie um modelo de feedback para aceitar e log feedback do aplicativo Review. Esse modelo é servido na mesma CPU servindo modelo endpoint que seu agente implantado.
Habilitar o monitoramento de lagoas para a Geração AI (beta)	É necessário se inscrever no monitoramento do Lakehouse para a versão beta AI do Gen. O monitoramento básico é ativado automaticamente para rastreamentos de agentes implantados.
Habilite o rastreamento e o monitoramento em tempo real com o MLflow 3 (beta)	É necessário se inscrever no monitoramento do Lakehouse para a versão AI beta do Gen e usar o MLflow 3.0 ou superior. Além de registrar traços de agentes implantados em tabelas de inferência para armazenamento de longo prazo, Databricks logs traços de seu agente implantado em um experimento MLflow para visibilidade real do tempo. Isso reduz as latências de monitoramento e depuração. Quando o senhor cria um novo endpoint via agents.deploy()o monitoramento e o rastreamento são configurados para ler e gravar no experimento MLflow ativo no momento. Configure o experimento para um endpoint específico chamando mlflow.set_experiment() antes de invocar agents.deploy() para criar o endpoint. Os rastros de todos os agentes atendidos no endpoint (incluindo agentes adicionados ao endpoint por meio de chamadas subsequentes para agents.deploy()) são gravados nesse experimento. monitoramento computam métricas de qualidade em traços neste experimento. Em default, apenas as métricas básicas de monitoramento são configuradas. Para adicionar juízes do LLM e outros, consulte Configurar monitoramento.

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.

3. 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. Para obter mais informações, consulte Implantação de um agente usando a autenticação no local do usuário.
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 seu agente é posteriormente implantado, ele pode acessar um recurso Databricks em nome do usuário final, mas apenas utilizando os escopos especificados. Para obter mais informações sobre os escopos de API, consulte Autenticação em nome 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.

important

Se o MLflow 3 estiver instalado no seu ambiente de desenvolvimento quando você chamar agents.deploy(), o seu endpoint logs MLflow Traces em tempo real para o MLflow Experimento ativado no momento da chamada agents.deploy(). Você pode chamar mlflow.set_experiment() para alterar o experimento ativo antes da implantação.

Consulte os documentos do MLflow para obter mais detalhes.

Consulte Debug & Observe seu aplicativo com rastreamento.

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

Consulte API Python do Databricks Agents.

Fornecer feedback sobre um agente implantado (experimental)

Quando o agente é implantado com agents.deploy(), a estrutura do agente também cria e implanta um feedback "" versão do modelo dentro do mesmo endpoint, que pode ser consultado para fornecer feedback sobre a aplicação do agente. As entradas de feedback aparecem como linhas de solicitação na tabela de inferência associada ao seu 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.
• A API de feedback requer a transmissão do ID de solicitação de feedback ( request_id ) gerado pelo Databricks da solicitação do endpoint do agente sobre o qual você deseja fornecer feedback. endpointPara obter o documento “ databricks_request_id” (Declaração de Direitos do Consumidor de Informações de Crédito), inclua “ {"databricks_options": {"return_trace": True}} ” (Incluir a declaração de direitos do consumidor de informações de crédito) em sua solicitação original ao agente A resposta do agente endpoint inclui o databricks_request_id associado à solicitação, para que você possa passar esse 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.

A solicitação de exemplo a seguir fornece feedback sobre o agente endpoint chamado "your-agent-endpoint-name" e pressupõe que a variável de ambiente DATABRICKS_TOKEN está definida como um token Databricks REST API .

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 Lakeflow Declarative Pipelines"
                      }
                  ],
                  "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

• Consultar um agente implantado Mosaic AI
• Mosaic AI Avaliação do agente (MLflow 2)
• Use o aplicativo de avaliação para avaliações humanas de um aplicativo do gênero AI (MLflow 2)
• Depurar um agente implantado AI