Usar a Pesquisa de agentes como um back-end de recuperação com o mecanismo RAG

Os controles de segurança do VPC-SC e a CMEK são compatíveis com o mecanismo RAG na Gemini Enterprise Agent Platform. Os controles de segurança de residência de dados e AXT não são compatíveis.

Para conferir um exemplo de uso do mecanismo RAG na Gemini Enterprise Agent Platform com a Pesquisa de Agentes, execute o notebook "Mecanismo RAG com Pesquisa de Agentes" em um dos seguintes ambientes:

Abrir no Colab | Abrir no Colab Enterprise | Abrir no Workbench da plataforma de agentes | Ver no GitHub

Nesta página, apresentamos a integração da Pesquisa de Agentes com o RAG Engine.

A Pesquisa de Agentes oferece uma solução para recuperar e gerenciar dados nos aplicativos RAG da Gemini Enterprise Agent Platform. Ao usar a Pesquisa de Agentes como back-end de recuperação, é possível melhorar o desempenho, a escalonabilidade e a facilidade de integração.

• Melhor desempenho e escalonabilidade: a Pesquisa de Agente foi projetada para processar grandes volumes de dados com latência excepcionalmente baixa. Isso se traduz em tempos de resposta mais rápidos e melhor desempenho para seus aplicativos RAG, especialmente ao lidar com bases de conhecimento complexas ou extensas.

• Gerenciamento de dados simplificado: importe dados de várias fontes, como sites, conjuntos de dados do BigQuery e buckets do Cloud Storage, que podem simplificar o processo de ingestão de dados.

• Integração perfeita: a Agent Platform oferece integração integrada com o Agent Search, que permite selecionar o Agent Search como o back-end do corpus para seu aplicativo RAG. Isso simplifica o processo de integração e ajuda a garantir a compatibilidade ideal entre os componentes.

• Melhoria da qualidade da saída do LLM: ao usar os recursos de recuperação da Pesquisa de Agente, você pode garantir que seu aplicativo RAG recupere as informações mais relevantes do seu corpus, o que leva a saídas geradas pelo LLM mais precisas e informativas.

Agent Search

A Pesquisa de Agentes reúne a recuperação profunda de informações, o processamento de linguagem natural e os recursos mais recentes em processamento de modelos de linguagem grandes (LLMs), o que ajuda a entender a intenção do usuário e retornar os resultados mais relevantes para ele.

Com a Pesquisa de Agentes, é possível criar um aplicativo de pesquisa com a qualidade do Google usando dados que você controla.

Configurar a Pesquisa do Agente

Para configurar uma Pesquisa de Agente, faça o seguinte:

1. Crie um repositório de dados de pesquisa.

2. Crie um aplicativo de pesquisa.

Usar a Pesquisa de Agentes como um back-end de recuperação para o mecanismo RAG

Depois de configurar a Pesquisa de Agentes, siga estas etapas para defini-la como o back-end de recuperação do aplicativo RAG.

Definir a Pesquisa de Agentes como o back-end de recuperação para criar um corpus RAG

Estes exemplos de código mostram como configurar a Pesquisa de Agente como o back-end de recuperação de um corpus RAG.

REST

Para usar a linha de comando para criar um corpus de RAG, faça o seguinte:

1. Criar um corpus RAG

   Substitua as seguintes variáveis usadas no exemplo de código:

   • PROJECT_ID: o ID do projeto do Google Cloud .
   • LOCATION: a região para processar a solicitação.
   • DISPLAY_NAME: o nome de exibição do corpus de RAG que você quer criar.
   • ENGINE_NAME: o nome completo do recurso do mecanismo de pesquisa do agente ou do repositório de dados da pesquisa do agente. Por exemplo,

     projects/PROJECT_NUMBER/locations/LOCATION/collections/default_collection/engines/ENGINE_NAME/servingConfigs/default_search

   curl -X POST \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/ragCorpora" \
   -d '{
     "display_name" : "DISPLAY_NAME",
     "vertex_ai_search_config" : {
       "serving_config": "ENGINE_NAME/servingConfigs/default_search"
     }
   }'
   

2. Monitorar o progresso

   Substitua as seguintes variáveis usadas no exemplo de código:

   • PROJECT_ID: o ID do projeto do Google Cloud .
   • LOCATION: a região para processar a solicitação.
   • OPERATION_ID: o ID da operação de criação do corpus da RAG.

   curl -X GET \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID"
   

Python

Antes de testar este exemplo, siga as instruções de configuração do Python no Guia de início rápido da plataforma de agentes: como usar bibliotecas de cliente.

Para autenticar na plataforma de agentes, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

import agentplatform
from agentplatform import types

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# vertex_ai_search_engine_name = "projects/{PROJECT_ID}/locations/{LOCATION}/collections/default_collection/engines/{ENGINE_ID}"
# display_name = "test_corpus"
# description = "Corpus Description"

# Initialize Agent Platform client once per session.
# See https://docs.cloud.google.com/gemini-enterprise-agent-platform/build/rag-engine/rag-overview#supported-regions
client = agentplatform.Client(project=PROJECT_ID, location="us-east5")

# Configure Search
vertex_ai_search_config = types.VertexAiSearchConfig(
    serving_config=f"{vertex_ai_search_engine_name}/servingConfigs/default_search",
)

corpus = client.rag.create_corpus(
    rag_corpus=types.RagCorpus(
        display_name=display_name,
        description=description,
        vertex_ai_search_config=vertex_ai_search_config,
    ),
)
print(corpus)
# Example response:
# RagCorpus(name='projects/1234567890/locations/us-central1/ragCorpora/1234567890',
# display_name='test_corpus', description='Corpus Description'.
# ...

Recuperar contextos usando a API RAG

Após a criação do corpus de RAG, os contextos relevantes podem ser recuperados da Pesquisa de Agente usando a API RetrieveContexts.

REST

Este exemplo de código demonstra como recuperar contextos usando REST.

Substitua as seguintes variáveis usadas no exemplo de código:

• PROJECT_ID: o ID do projeto do Google Cloud .
• LOCATION: a região para processar a solicitação.
• RAG_CORPUS_RESOURCE: o nome do recurso de corpus RAG.

  Formato: projects/{project}/locations/{location}/ragCorpora/{rag_corpus}.

• TEXT: o texto da consulta para receber contextos relevantes.

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:retrieveContexts" \
  -d '{
    "vertex_rag_store": {
      "rag_resources": {
        "rag_corpus": "RAG_CORPUS_RESOURCE"
      }
    },
    "query": {
      "text": "TEXT"
    }
  }'

Python

Para saber como instalar o SDK da Vertex AI para Python, consulte Instalar o SDK da Vertex AI para Python. Para mais informações, consulte a documentação de referência da API Python.

import agentplatform

from agentplatform import types
from google.genai import types as genai_types

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# corpus_name = "projects/[PROJECT_ID]/locations/us-east5/ragCorpora/[rag_corpus_id]"

# Initialize Agent Platform client once per session.
# See https://docs.cloud.google.com/gemini-enterprise-agent-platform/build/rag-engine/rag-overview#supported-regions
client = agentplatform.Client(project=PROJECT_ID, location="us-east5")

response = client.rag.retrieve_contexts(
    vertex_rag_store=genai_types.VertexRagStore(
        rag_resources=[
            genai_types.VertexRagStoreRagResource(
                rag_corpus=corpus_name,
                # Optional: supply IDs from `rag.list_files()`.
                # rag_file_ids=["rag-file-1", "rag-file-2", ...],
            )
        ],
    ),
    query=types.RagQuery(
        text="Hello World!",
        rag_retrieval_config=genai_types.RagRetrievalConfig(
            top_k=10,
            filter=genai_types.RagRetrievalConfigFilter(
                vector_distance_threshold=0.5
            ),
        ),
    )
)
print(response)
# Example response:
# contexts {
#   contexts {
#     source_uri: "gs://your-bucket-name/file.txt"
#     text: "....
#   ....

Gerar conteúdo usando a API Gemini da Agent Platform

REST

Para gerar conteúdo usando modelos do Gemini, faça uma chamada para a API GenerateContent da Agent Platform. Ao especificar o RAG_CORPUS_RESOURCE na solicitação, ele recupera automaticamente os dados da Pesquisa de Agente.

Substitua as seguintes variáveis usadas no exemplo de código:

• PROJECT_ID: o ID do projeto do Google Cloud .

• LOCATION: a região para processar a solicitação.

• MODEL_ID: modelo LLM para geração de conteúdo. Por exemplo, gemini-3.8-flash.

• GENERATION_METHOD: método LLM para geração de conteúdo. Exemplo: generateContent, streamGenerateContent.

• INPUT_PROMPT: o texto enviado ao LLM para geração de conteúdo. Tente usar um comando relevante para os documentos na Pesquisa de Agente.

• RAG_CORPUS_RESOURCE: o nome do recurso do corpus RAG. Formato: projects/{project}/locations/{location}/ragCorpora/{rag_corpus}.

• SIMILARITY_TOP_K (opcional): o número dos principais contextos a serem recuperados.

  curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATION_METHOD" \
  -d '{
    "contents": {
      "role": "user",
      "parts": {
        "text": "INPUT_PROMPT"
      }
    },
    "tools": {
      "retrieval": {
        "disable_attribution": false,
        "vertex_rag_store": {
          "rag_resources": {
              "rag_corpus": "RAG_CORPUS_RESOURCE"
            },
          "similarity_top_k": SIMILARITY_TOP_K
        }
      }
    }
  }'
  

Python

Para saber como instalar o SDK da Vertex AI para Python, consulte Instalar o SDK da Vertex AI para Python. Para mais informações, consulte a documentação de referência da API Python.

from google import genai
from google.genai import types as genai_types

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# corpus_name = "projects/{PROJECT_ID}/locations/us-east5/ragCorpora/{rag_corpus_id}"

rag_retrieval_tool = genai_types.Tool(
    retrieval=genai_types.Retrieval(
        vertex_rag_store=genai_types.VertexRagStore(
            rag_resources=[
                genai_types.VertexRagStoreRagResource(
                    rag_corpus=corpus_name
                )
            ],
            rag_retrieval_config=genai_types.RagRetrievalConfig(
                top_k=10,
                filter=genai_types.RagRetrievalConfigFilter(
                    vector_distance_threshold=0.5
                ),
            ),
        ),
    )
)

# Create a GenAI SDK client to make a generate_content request
genai_client = genai.Client(vertexai=True, project=PROJECT_ID, location="global")

response = genai_client.models.generate_content(
    model="gemini-3.8-flash",
    contents="Why is the sky blue?",
    config=genai_types.GenerateContentConfig(
        tools=[rag_retrieval_tool]
    ),
)
print(response.text)
# Example response:
#   The sky appears blue due to a phenomenon called Rayleigh scattering.
#   Sunlight, which contains all colors of the rainbow, is scattered
#   by the tiny particles in the Earth's atmosphere....
#   ...

A seguir

• Recuperação e classificação