Implantar um agente em um aplicativo de IA generativa

Artigo
02/10/2025

Importante

Esse recurso está em uma versão prévia.

Este artigo mostra como implantar seu agente de IA usando a deploy() função da API Python do Agent Framework.

Requisitos

É necessário ter o MLflow 2.13.1 ou superior para implantar agentes utilizando a API deploy() do databricks.agents.
Registre um agente de IA no Catálogo do Unity. Confira Registrar o agente no Catálogo do Unity.
Implantar agentes de fora de um notebook do Databricks requer databricks-agents SDK versão 0.12.0 ou superior.

Instalar o SDK do databricks-agents

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

Implantar um agente usando `deploy()`

A função deploy() faz o seguinte:

Cria pontos de extremidade de CPU de serviço de modelo para seu agente que podem ser integrados ao seu aplicativo voltado para o usuário.
- Para reduzir o custo de endpoints ociosos (às custas do aumento do tempo para atender às consultas iniciais), você pode habilitar a escala para zero para o endpoint de serviço passando scale_to_zero_enabled=True para deploy(). Consulte Expectativas de escalabilidade de endpoint.
- Habilita tabelas de inferência com o Gateway de IA no ponto de extremidade de serviço do modelo. Confira os Modelos atendidos do Monitor usando tabelas de inferência habilitadas pelo Gateway de IA.
Observação

Para os logs de resposta de streaming, apenas os campos e rastreamentos compatíveis com o ChatCompletion são agregados.
- O Databricks fornece automaticamente credenciais temporárias de entidade de serviço para o código do agente em execução no ponto de extremidade. As credenciais têm as permissões mínimas para acessar Recursos gerenciados pelo Databricks, conforme definido durante o registro do modelo. Antes de gerar essas credenciais, o Databricks garante que o proprietário do ponto de extremidade tenha as permissões apropriadas para evitar o escalonamento de privilégios e o acesso não autorizado. Consulte Autenticação para recursos dependentes.
  - Se você tiver dependências de recursos que não são gerenciadas pelo Databricks, por exemplo, usando o Pinecone, poderá passar variáveis de ambiente com segredos para a API deploy(). Consulte Configurar o acesso aos recursos dos pontos de extremidade de serviço de modelo.
Habilita o Aplicativo de Revisão para o agente. O Aplicativo de Revisão permite que os participantes conversem com o agente e enviem comentários usando a interface do usuário do Aplicativo de Revisão.
Registra todas as solicitações para o Aplicativo de Revisão ou a API REST em uma tabela de inferência. Os dados registrados incluem solicitações de consulta, respostas e dados de rastreamento de intermediários do Rastreamento do MLflow.
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 feedback do aplicativo Review e registrá-lo em uma tabela de inferência. Esse modelo é servido no mesmo ponto de extremidade de atendimento do modelo de CPU que seu agente implementado. Esse modelo é servido no mesmo endpoint de atendimento do modelo de CPU que seu agente implementou.

Observação

As implantações podem levar até 15 minutos para terminar. Os conteúdos JSON brutos demoram de 10 a 30 minutos para chegar, e os logs formatados são processados a partir dos conteúdos brutos aproximadamente 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 pelo agente

O deploy() cria três tabelas de inferência para cada implantação, a fim de registrar solicitações e respostas de e para o ponto de extremidade de serviço do agente. Os usuários podem esperar que os dados estejam nessa tabela do payload dentro de uma hora depois de interagirem com a implantação.

Os logs de solicitação de payload e os logs de avaliação podem levar mais tempo para serem preenchidos, mas são derivados da tabela de payload bruta. É possível extrair logs de solicitação e avaliação da tabela de payload por conta própria. As exclusões e atualizações na tabela de carga não são refletidas nos logs de solicitação de carga ou nos logs de avaliação de carga.

Observação

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

Tabela	Exemplo de nome de tabela do Unity Catalog	O que contém cada tabela
Conteúdo	`{catalog_name}.{schema_name}.{model_name}_payload`	Payloads de solicitação e resposta JSON
Logs de solicitação de conteúdo	`{catalog_name}.{schema_name}.{model_name}_payload_request_logs`	Solicitações e respostas formatadas, rastreamentos do MLflow
Logs de avaliação de conteúdo	`{catalog_name}.{schema_name}.{model_name}_payload_assessment_logs`	Comentários formatados, conforme fornecido no Aplicativo de Revisão, para cada solicitação

A seguir, é apresentado o esquema para a tabela de registros de solicitações.

Nome da coluna	Type	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`	Longo	Carimbo de data/hora em milissegundos.
`timestamp`	Timestamp	Carimbo de hora da solicitação.
`status_code`	Inteiro	Código de status do ponto de extremidade.
`execution_time_ms`	Longo	Total de milissegundos de execução.
`conversation_id`	String	ID de conversa extraída dos logs de solicitação.
`request`	String	A última consulta de usuário da conversa do usuário. Isso é extraído da solicitação RAG.
`response`	String	A última resposta para o usuário. Isso é extraído da solicitação 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 rastreamento extraído do `databricks_options` do struct de resposta.
`sampling_fraction`	Double	Fração de amostragem.
`request_metadata`	Map[String, String]	Um mapa de metadados relacionados ao ponto de extremidade de serviço de modelo associado à solicitação. Este mapa contém o nome do ponto de extremidade, o nome do modelo e a versão do modelo usados para o ponto de extremidade.
`schema_version`	String	Inteiro para a versão do esquema.

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

Nome da coluna	Type	Descrição
`request_id`	String	ID da solicitação do Databricks.
`step_id`	String	Derivado da avaliação de recuperação.
`source`	Estrutura	Um campo de struct que contém as informações sobre quem criou a avaliação.
`timestamp`	Timestamp	Carimbo de data/hora da solicitação.
`text_assessment`	Estrutura	Um campo de struct que contém os dados de qualquer comentário sobre as respostas do agente do aplicativo de revisão.
`retrieval_assessment`	Estrutura	Um campo de struct que contém os dados de qualquer comentário sobre os documentos recuperados para uma resposta.

Autenticação para recursos dependentes

Os agentes de IA geralmente precisam se autenticar em outros recursos para concluir tarefas. Por exemplo, um agente pode precisar acessar um índice de Pesquisa de Vetor para consultar dados não estruturados.

Seu agente pode usar um dos seguintes métodos para se autenticar em recursos dependentes quando ele é atendido por trás de um ponto de extremidade do Serviço de Modelo:

Passagem de autenticação automática: declare dependências de recursos do Databricks para seu agente durante o registro em log. O Databricks pode provisionar, alternar e gerenciar credenciais de curta duração automaticamente quando seu agente é implantado para acessar recursos de maneira segura. O Databricks recomenda usar a passagem de autenticação automática sempre que possível.
Autenticação manual: especifique manualmente as credenciais de longa duração durante a implantação do agente. Use a autenticação manual para recursos do Databricks que não dão suporte à passagem de autenticação automática ou para acesso à API externa.

Passagem de autenticação automática

O Serviço de Modelo dá suporte à passagem de autenticação automática para os tipos mais comuns de recursos do Databricks usados pelos agentes.

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

Em seguida, quando você atende o agente por trás de um ponto de extremidade, o Databricks executa as seguintes etapas:

Verificação de permissão: o Databricks verifica se o criador do ponto de extremidade pode acessar todas as dependências especificadas durante o registro em log do agente.
Criação e concessão de entidade de serviço: uma entidade de serviço é criada para a versão do modelo do agente e é automaticamente recebe acesso de leitura aos recursos do agente.

Observação

A entidade de serviço gerada pelo sistema não aparece em listagens de API ou interface do usuário. Se a versão do modelo do agente for removida do ponto de extremidade, a entidade de serviço também será excluída.
Provisionamento e rotação de credenciais: credenciais de curta duração (um token M2M OAuth) para a entidade de serviço são injetadas no ponto de extremidade, permitindo que o código do agente acesse os recursos do Databricks. O Databricks também gira as credenciais, garantindo que o agente tenha acesso seguro e contínuo aos recursos dependentes.

Esse comportamento de autenticação é semelhante a "Executar como proprietário" para painéis do Databricks. Recursos downstream, como tabelas do Unity Catalog, são acessados usando as credenciais de uma entidade de serviço com acesso de privilégio mínimo a recursos dependentes.

A tabela a seguir lista os recursos do Databricks que dão suporte à passagem de autenticação automática e as permissões que o criador do ponto de extremidade deve ter ao implantar o agente.

Observação

Os recursos do Unity Catalog também exigem USE SCHEMA no esquema pai e USE CATALOG no catálogo pai.

Tipo de recurso	Permissão
SQL Warehouse	Usar ponto de extremidade
Ponto de extremidade do serviço de modelo	Pode consultar
Função de catálogo do Unity	Execute
Espaço do gênio	Pode executar
Índice de Pesquisa Vetorial	Pode usar
Tabela de catálogo do Unity	SELECT

Autenticação manual

Você também pode fornecer credenciais manualmente usando variáveis de ambiente baseadas em segredos. A autenticação manual pode ser útil nos seguintes cenários:

O recurso dependente não dá suporte à passagem de autenticação automática.
O agente está acessando um recurso externo ou uma API.
O agente precisa usar credenciais diferentes das do agente de implantação.

Por exemplo, para usar o SDK do Databricks em seu agente para acessar outros recursos dependentes, você pode definir as variáveis de ambiente descritas em Autenticação Unificada do Cliente do Databricks.

Obter os aplicativos implantados

O exemplo a seguir mostra como obter os 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 "comentários" no mesmo ponto de extremidade, que você pode consultar para fornecer comentários sobre o aplicativo do agente. As entradas de feedback aparecem como linhas de solicitação na tabela de inferência associada ao endpoint 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 dessa API incluem:

A API de comentários não tem validação de entrada - ela sempre responde com êxito, mesmo se for passada uma entrada inválida.
A API de comentários requer a passagem da solicitação de ponto de extremidade do agente gerada request_id pelo Databricks sobre a qual você deseja fornecer comentários. 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 ponto de extremidade do agente incluirá o databricks_request_id associado à solicitação, de modo que você pode passar essa ID de solicitação novamente para a API de feedback ao dar feedback sobre a resposta do agente.
O feedback é coletado usando tabelas de inferência. Consulte 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 de chave-valor adicionais ou diferentes nos text_assessments.ratings campos e retrieval_assessments.ratings para fornecer diferentes tipos de comentários. 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 fundamentada no contexto buscado por uma ferramenta de recuperação.

Compartilhar via

Implantar um agente em um aplicativo de IA generativa

Requisitos

Implantar um agente usando `deploy()`

Tabelas de inferência aprimoradas pelo agente

Autenticação para recursos dependentes

Passagem de autenticação automática

Autenticação manual

Obter os aplicativos implantados

Fornecer feedback sobre um agente implantado (experimental)

Recursos adicionais

Comentários

Recursos adicionais

Compartilhar via

Implantar um agente em um aplicativo de IA generativa

Requisitos

Implantar um agente usando deploy()

Tabelas de inferência aprimoradas pelo agente

Autenticação para recursos dependentes

Passagem de autenticação automática

Autenticação manual

Obter os aplicativos implantados

Fornecer feedback sobre um agente implantado (experimental)

Recursos adicionais

Comentários

Recursos adicionais

Implantar um agente usando `deploy()`