Embasamento com a Pesquisa do agente

Nesta página, explicamos como embasar respostas usando seus dados do Agent Search.

Embasar o Gemini com seus dados

Se você quiser fazer a geração aumentada por recuperação (RAG, na sigla em inglês), conecte seu modelo aos dados do site ou aos conjuntos de documentos e use o embasamento com o Agent Search.

O embasamento com seus dados oferece suporte a um máximo de 10 fontes de dados do Agent Search e pode ser combinado com o embasamento com a Pesquisa Google.

Modelos compatíveis

Esta seção lista os modelos que oferecem suporte ao embasamento com seus dados.

Clique para expandir os modelos compatíveis

Pré-requisitos

Antes de embasar a saída do modelo com seus dados, faça o seguinte:

  1. No Google Cloud console, acesse a página IAM e pesquise a discoveryengine.servingConfigs.search permissão, que é necessária para que o serviço de embasamento funcione.

    Acessar IAM

    Para receber as permissões necessárias para usar o embasamento com o Agent Search, peça ao administrador para conceder a você os seguintes papéis do IAM:

    • Para ler todos os recursos do Discovery Engine: Leitor do Discovery Engine (roles/discoveryengine.viewer).

    • Para ler e gravar todos os recursos do Discovery Engine e criar uma instância do Agent Search: Editor do Discovery Engine (roles/discoveryengine.editor).

    Para mais informações sobre o IAM, consulte Papéis e permissões do IAM.

  2. Ative os Aplicativos de IA e a API.

  3. Crie uma fonte de dados dos Aplicativos de IA e aplicativo.

    Para mais informações, consulte Introdução ao Agent Search.

Ativar aplicativos de IA

Para usar o Agent Search para embasar suas respostas, ative o serviço seguindo estas etapas:

  1. No Google Cloud console, acesse a página Aplicativos de IA.

    Acessar os Aplicativos de IA

  2. Opcional: revise os termos de uso de dados.

Os Aplicativos de IA estão disponíveis no local global ou na multirregião eu e us. Para saber mais, consulte Locais dos Aplicativos de IA.

Criar um repositório de dados nos Aplicativos de IA

Para criar um repositório de dados nos Aplicativos de IA, você pode escolher embasar com dados ou documentos do site.

Site

  1. Abra a página Criar repositório de dados no Google Cloud console.

  2. Na caixa Conteúdo do site, clique em Selecionar.
    O painel Especificar os sites do repositório de dados é exibido.

  3. Se a opção Indexação avançada de sites não estiver marcada, selecione a caixa de seleção Indexação avançada de sites para ativá-la.
    Configurar seu repositório de dados é exibido.

  4. Na seção Especificar padrões de URL para indexar, faça o seguinte:

    • Adicione URLs para Sites a serem incluídos.
    • Opcional: adicione URLs para Sites a serem excluídos.

  5. Clique em Continuar.

  6. No painel Configurar seu repositório de dados,

    1. Selecione um valor na lista Local do repositório de dados.
    2. Insira um nome no campo Nome do repositório de dados. O ID é gerado. Use esse ID ao gerar respostas embasadas com seu repositório de dados. Para mais informações, consulte Gerar respostas embasadas com seu repositório de dados.
    3. Clique em Criar.

Documentos

  1. Abra a página Criar repositório de dados no Google Cloud console.

  2. Na caixa Cloud Storage, clique em Selecionar.
    O painel Importar dados do Cloud Storage é exibido.

  3. Na seção Documentos não estruturados (PDF, HTML, TXT e mais), selecione Documentos não estruturados (PDF, HTML, TXT e mais).

  4. Selecione uma opção de Frequência de sincronização.

  5. Selecione uma opção Selecione uma pasta ou um arquivo para importar e insira o caminho no campo.

  6. Clique em Continuar.
    Configurar seu repositório de dados painel é exibido.

  7. No painel Configurar seu repositório de dados,

    1. Selecione um valor na lista Local do repositório de dados.
    2. Insira um nome no campo Nome do repositório de dados. O ID é gerado.
    3. Para selecionar opções de análise e divisão para seus documentos, expanda a seção Opções de processamento de documentos. Para mais informações sobre diferentes analisadores, consulte Analisar documentos.
    4. Clique em Criar.

  8. Clique em Criar.

Gerar respostas embasadas com seu repositório de dados

Use as instruções a seguir para embasar um modelo com seus dados. Um máximo de 10 repositórios de dados é compatível.

Se você não souber o ID do repositório de dados, siga estas etapas:

  1. No Google Cloud console, acesse a página Aplicativos de IA e no menu de navegação, clique em Repositórios de dados.

    Acesse a página Repositório de dados

  2. Clique no nome do seu repositório de dados.

  3. Na página Dados do seu repositório de dados, encontre o ID do repositório.

Console

Para embasar a saída do modelo com os Aplicativos de IA usando o Vertex AI Studio no Google Cloud console, siga estas etapas:

  1. No Google Cloud console, acesse a página Vertex AI Studio.

    Acessar Vertex AI Studio

  2. Para ativar o embasamento, siga estas etapas:
    1. Clique em + Novo e Chat no menu de navegação.
    2. Expanda o painel Configurações do modelo e selecione o modelo.
    3. Opcional: se a opção Saída estruturada ou Embasamento: Google estiver ativada, desative-a.
    4. Clique na opção Embasamento: seus dados. O painel Personalizar embasamento aparece.
      1. Selecione uma opção de origem de embasamento na tabela a seguir:
        2. Opção de embasamento Descrição Entrada
        Mecanismo RAG Embasamento usando seus dados e componentes do tipo "faça você mesmo". Se você não tiver um corpus, crie um. Caso contrário, insira o corpus.
        Agent Search Embasamento usando seus dados com um Googlemecanismo de pesquisa gerenciado. Insira o caminho no campo Caminho do repositório de dados da Gemini Enterprise Agent Platform.
        Elasticsearch Embasamento usando o Elasticsearch. Insira as seguintes informações:
        1. Insira um valor no campo Endpoint do Elasticsearch.
        2. Insira um valor no campo Chave da API do Elasticsearch.
        3. Insira um valor no campo Índice do Elasticsearch.
        4. Insira um valor no campo Modelo de pesquisa do Elasticsearch.
      2. Clique em Salvar.
  3. Insira o comando na caixa de texto e clique em Enviar. As respostas aos comandos são embasadas nos Aplicativos de IA.

Python

Instalar

pip install --upgrade google-genai

Para mais informações, consulte a documentação de referência do SDK.

Defina variáveis de ambiente para usar o SDK de IA generativa com a Vertex AI: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True
 

from google import genai
from google.genai.types import (
    GenerateContentConfig,
    VertexAISearch,
    Retrieval,
    Tool,
    HttpOptions,
)

client = genai.Client(http_options=HttpOptions(api_version="v1"))

# Replace with your Agent Search data store details
DATASTORE_PATH = "projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATASTORE_ID"

tool = Tool(
    retrieval=Retrieval(
        vertex_ai_search=VertexAISearch(
            datastore=DATASTORE_PATH
        )
    )
)

response = client.models.generate_content(
    model="gemini-2.5-flash",  # Or another supported model
    contents="What information can you find about topic X in the provided documents?", # Your query
    config=GenerateContentConfig(
        tools=[tool],
    ),
)

print(response.text)

REST

Para testar um comando de texto usando a API Agent Platform, envie uma solicitação POST para o endpoint do modelo do editor.

Antes de usar os dados da solicitação abaixo, faça estas substituições:

  • LOCATION: a região para processar a solicitação. Para usar o global endpoint, exclua o local do nome do endpoint e configure o local do recurso como global.
  • PROJECT_ID: seu [ID do projeto](/resource-manager/docs/creating-managing-projects#identifiers). .
  • MODEL_ID: o ID do modelo multimodal.
  • PROMPT: o comando a ser enviado para o modelo.

Método HTTP e URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent

Corpo JSON da solicitação: 

{
  "contents": [{
    "role": "user",
    "parts": [{
      "text": "PROMPT"
    }]
  }],
  "tools": [{
    "retrieval": {
      "vertexAiSearch": {
        "datastore": projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATASTORE_ID
      }
    }
  }],
  "model": "projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID"
}

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "You can make an appointment on the website https://dmv.gov/"
          }
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": [
        "..."
      ],
      "groundingMetadata": {
        "retrievalQueries": [
          "How to make appointment to renew driving license?"
        ],
        "groundingChunks": [
          {
            "retrievedContext": {
              "uri": "https://vertexaisearch.cloud.google.com/grounding-api-redirect/AXiHM.....QTN92V5ePQ==",
              "title": "dmv"
            }
          }
        ],
        "groundingSupport": [
          {
            "segment": {
              "startIndex": 25,
              "endIndex": 147
            },
            "segment_text": "ipsum lorem ...",
            "supportChunkIndices": [1, 2],
            "confidenceScore": [0.9541752, 0.97726375]
          },
          {
            "segment": {
              "startIndex": 294,
              "endIndex": 439
            },
            "segment_text": "ipsum lorem ...",
            "supportChunkIndices": [1],
            "confidenceScore": [0.9541752, 0.9325467]
          }
        ]
      }
    }
  ],
  "usageMetadata": {
    "..."
  }
}

Entender a resposta

A resposta de ambas as APIs inclui o texto gerado pelo LLM, que é chamado de candidato. Se o comando do modelo for embasado com sucesso na fonte de dados, as respostas vão incluir metadados de embasamento, que identificam as partes da resposta derivadas dos seus dados. No entanto, há vários motivos para esses metadados não serem fornecidos e a resposta ao comando não ser embasada. Esses motivos incluem baixa relevância de fonte ou informações incompletas na resposta do modelo.

Confira a seguir um detalhamento dos dados de saída:

  • Papel: indica o remetente da resposta embasada. Como a resposta sempre contém texto embasado, o papel é sempre model.
  • Texto: a resposta embasada gerada pelo LLM.
  • Metadados de embasamento: informações sobre a origem do embasamento, que contém os seguintes elementos:
    • Blocos de embasamento: uma lista de resultados do seu índice que oferecem suporte à resposta.
    • Suportes de embasamento: informações sobre uma declaração específica na resposta que pode ser usada para mostrar citações:
    • Segmento: a parte da resposta do modelo que é comprovada por um bloco de embasamento.
    • Índice de blocos de embasamento: o índice dos blocos de embasamento na lista de blocos de embasamento que corresponde a essa declaração.
    • Pontuações de confiança: um número de 0 a 1 que indica o quão embasada a declaração está no conjunto de blocos de embasamento fornecido. Não disponível para o Gemini 2.5 e versões mais recentes.

A seguir