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 a função deploy() do Agent Framework Python API .

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.

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

Implante um agente com `deploy()`

A função implantado() 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.
- Para reduzir o custo do endpoint parado (às custas do aumento do tempo para atender às consultas iniciais), o senhor pode ativar a escala para zero para o seu serviço endpoint passando scale_to_zero_enabled=True para deploy(). Consulte as expectativas de escalonamento de endpoints.
- As tabelas de inferência estão ativadas nesses endpoints de modelo de serviço. Consulte Tabelas de inferência para modelos de monitoramento e depuração.
- Databricks fornece automaticamente credenciais de entidade de serviço de curta duração para o código do agente em execução no site endpoint. As credenciais têm as permissões mínimas para Databricksacessar -gerenciar recurso conforme definido durante o registro do modelo. Antes de gerar essas credenciais, a Databricks garante que o proprietário do endpoint tenha as permissões adequadas para evitar o aumento de privilégios e o acesso não autorizado. Consulte Autenticação para recurso dependente.
  - Se o senhor tiver dependências de recurso que não sejam Databricks-gerenciar, por exemplo, usando o Pinecone, poderá passar a variável de ambiente com segredos para o deploy() API. Consulte Configurar o acesso ao recurso a partir do endpoint do modelo de atendimento.
Ativa o aplicativo de avaliação para seu agente. O Review App permite que as partes interessadas conversem com o agente e forneçam feedback usando a interface do usuário 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

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:

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

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

Observação

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.
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 alterna as 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.

Observação

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

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.