Implantar um agente para aplicativo de IA generativa

Artigo
11/14/2024

Importante

Esta funcionalidade está em Pré-visualização Pública.

Este artigo mostra como implantar seu agente de IA usando a deploy() API do databricks.agents .

Requisitos

MLflow 2.13.1 ou superior para implantar agentes usando a deploy() API do databricks.agents.
Registre um agente de IA no Unity Catalog. Consulte Registrar a cadeia no Catálogo Unity.

Instale o databricks-agents SDK.

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

Implantar um agente usando `deploy()`

A deploy() API faz o seguinte:

Cria um modelo de CPU servindo pontos de extremidade para seu agente que podem ser integrados ao seu aplicativo voltado para o usuário.
- Para reduzir o custo de pontos de extremidade ociosos (às custas do aumento do tempo para atender consultas iniciais), você pode habilitar a escala para zero para seu ponto de extremidade de serviço passando scale_to_zero_enabled=True para deploy(). Consulte Expectativas de dimensionamento de endpoint.
- As tabelas de inferência são habilitadas nesses modelos que servem pontos de extremidade. Consulte Tabelas de inferência para monitorar e depurar modelos.
- As credenciais de autenticação são passadas automaticamente para todos os recursos gerenciados pelo Databricks exigidos pelo agente, conforme especificado ao registrar o modelo. O Databricks cria uma entidade de serviço que tem acesso a esses recursos e passa isso automaticamente para o ponto de extremidade. Consulte Autenticação para recursos dependentes.
  - Se você tiver dependências de recursos que não são gerenciadas por Databricks, por exemplo, usando Pinecone, você pode passar variáveis de ambiente com segredos para a deploy() API. Consulte Configurar o acesso a recursos a partir de pontos de extremidade de serviço de modelo.
Habilita o aplicativo Avaliações para seu agente. O aplicativo de revisão permite que as partes interessadas conversem com o agente e deem feedback usando a interface do usuário do aplicativo de avaliação.
Registra todas as solicitações no aplicativo de revisão ou na API REST em uma tabela de inferência. Os dados registrados 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 você está tentando implantar. Esse modelo de feedback é o mecanismo que torna possível aceitar comentários do aplicativo Review e registrá-los em uma tabela de inferência. Esse modelo é servido no mesmo modelo de CPU que serve o ponto de extremidade do seu agente implantado. Como esse ponto de extremidade de serviço tem tabelas de inferência habilitadas, é possível registrar comentários do aplicativo de revisão em uma tabela de inferência.

Nota

As implantações podem levar até 15 minutos para serem concluídas. As cargas úteis JSON brutas levam de 10 a 30 minutos para chegar, e os logs formatados são processados a partir das cargas brutas 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 agente

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

Nota

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

Tabela	Exemplo de nome da tabela do Catálogo Unity	O que há em cada tabela
Payload	`{catalog_name}.{schema_name}.{model_name}_payload`	Cargas úteis brutas de solicitação e resposta JSON
Registos de pedidos de carga útil	`{catalog_name}.{schema_name}.{model_name}_payload_request_logs`	Solicitações e respostas formatadas, rastreamentos MLflow
Logs de avaliação de carga útil	`{catalog_name}.{schema_name}.{model_name}_payload_assessment_logs`	Comentários formatados, conforme fornecidos no aplicativo Avaliações, para cada solicitação

A seguir mostra o esquema para a tabela de logs de solicitação.

Nome da coluna	Tipo	Description
`client_request_id`	String	ID de solicitação do cliente, geralmente `null`.
`databricks_request_id`	String	Databricks solicitar ID.
`date`	Date	Data do pedido.
`timestamp_ms`	Longo	Carimbo de data/hora em milissegundos.
`timestamp`	Carimbo de Data/Hora	Carimbo de data/hora do pedido.
`status_code`	Número inteiro	Código de status do ponto de extremidade.
`execution_time_ms`	Longo	Execução total em milissegundos.
`conversation_id`	String	ID da conversação extraída dos registos de pedidos.
`request`	String	A última consulta do usuário da conversa do usuário. Isto é extraído do pedido RAG.
`response`	String	A última resposta ao usuário. Isto é extraído do pedido 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 traço extraído do `databricks_options` Struct da resposta.
`sampling_fraction`	Duplo	Fração de amostragem.
`request_metadata`	Map[String, String]	Um mapa de metadados relacionados ao modelo que serve o ponto de extremidade associado à solicitação. Este mapa contém o nome do ponto de extremidade, o nome do modelo e a versão do modelo usado para o seu ponto de extremidade.
`schema_version`	String	Inteiro para a versão do esquema.

A seguir está o esquema para a tabela de logs de avaliação.

Nome da coluna	Tipo	Description
`request_id`	String	Databricks solicitar ID.
`step_id`	String	Derivado da avaliação de recuperação.
`source`	Estrutura	Um campo struct contendo as informações sobre quem criou a avaliação.
`timestamp`	Carimbo de Data/Hora	Carimbo de data/hora do pedido.
`text_assessment`	Estrutura	Um campo struct contendo os dados para qualquer feedback sobre as respostas do agente do aplicativo de avaliação.
`retrieval_assessment`	Estrutura	Um campo struct contendo os dados para qualquer feedback 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 o Endpoint
Ponto de extremidade de serviço de modelo	Pode consultar
Função Catálogo Unity	Executar
Espaço Genie	Executar
Índice de pesquisa vetorial	ReadVectorIndex
Tabela do Catálogo Unity	Pode ler

Autenticação para recursos dependentes

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

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

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

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 relação aos recursos suportados.

Caraterística	Versão mínima `mlflow`
Índices de pesquisa vetorial	Requer `mlflow` 2.13.1 ou superior
Ponto de extremidade de serviço de modelo	Requer `mlflow` 2.13.1 ou superior
Armazéns SQL	Requer `mlflow` 2.16.1 ou superior
Funções do catálogo Unity	Requer `mlflow` 2.16.1 ou superior

Autenticação manual

Se você tiver um recurso dependente que não ofereça suporte à passagem de autenticação automática ou se quiser usar credenciais diferentes das do criador da implantação, poderá fornecer credenciais manualmente 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 na autenticação unificada do cliente Databricks.

Obtenha aplicativos implantados

Veja a seguir como obter seus 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 "feedback" dentro do mesmo ponto de extremidade, que você pode consultar para fornecer comentários sobre seu aplicativo de agente. As entradas de feedback aparecem como linhas de solicitação dentro da tabela de inferência associada ao ponto de extremidade 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 desta API incluem:

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

Partilhar via

Implantar um agente para aplicativo de IA generativa

Requisitos

Implantar um agente usando `deploy()`

Tabelas de inferência aprimoradas por agente

Requisitos de permissão para recursos dependentes

Autenticação para recursos dependentes

Passagem de autenticação automática

Autenticação manual

Obtenha aplicativos implantados

Fornecer feedback sobre um agente implantado (experimental)

Recursos adicionais

Comentários

Recursos adicionais

Partilhar via

Implantar um agente para aplicativo de IA generativa

Requisitos

Implantar um agente usando deploy()

Tabelas de inferência aprimoradas por agente

Requisitos de permissão para recursos dependentes

Autenticação para recursos dependentes

Passagem de autenticação automática

Autenticação manual

Obtenha aplicativos implantados

Fornecer feedback sobre um agente implantado (experimental)

Recursos adicionais

Comentários

Recursos adicionais

Implantar um agente usando `deploy()`