Embasamento com a Pesquisa do agente

Nesta página, explicamos como fundamentar respostas usando seus dados da Pesquisa do agente.

Embasar o Gemini com seus dados

Se quiser fazer a geração aumentada por recuperação (RAG), conecte seu modelo aos dados do site ou aos conjuntos de documentos e use o Embasamento com a Pesquisa do agente.

O embasamento nos seus dados é compatível com um máximo de 10 fontes de dados da Pesquisa do agente 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.

Pré-requisitos

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

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

    Acessar IAM

    Para receber as permissões necessárias para usar o embasamento com a Pesquisa do agente, 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 da Pesquisa por agente: Editor do Discovery Engine (roles/discoveryengine.editor).

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

  2. Ative o AI Applications e a API.

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

    Para mais informações, consulte a Introdução à Pesquisa do agente.

Ativar aplicativos de IA

Para usar a Pesquisa do agente e fundamentar suas respostas, ative o serviço seguindo estas etapas:

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

    Acesse os Aplicativos de IA

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

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

Criar um repositório de dados no AI Applications

Para criar um repositório de dados nos Aplicativos de IA, é possível embasar com dados de sites ou documentos.

Site

  1. Abra a página Criar um data store no console do Google Cloud .

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

  3. Se a Indexação avançada de sites não estiver marcada, selecione a caixa de seleção Indexação avançada de sites para ativar.
    O painel 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 um data store no console do Google Cloud .

  2. Na caixa Cloud Storage, clique em Selecionar.
    O painel Importar dados do Cloud Storage vai aparecer.

  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 em Selecione uma pasta ou um arquivo para importar e insira o caminho no campo.

  6. Clique em Continuar.O painel
    Configurar seu repositório de dados vai aparecer.

  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 em partes dos 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. É possível usar no máximo 10 repositórios de dados.

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

  1. No console Google Cloud , 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 Gemini Enterprise Agent Platform Studio no consoleGoogle Cloud , siga estas etapas:

  1. No console Google Cloud , acesse a página Gemini Enterprise Agent Platform Studio.

    Acesse o Gemini Enterprise Agent Platform Studio

  2. Para ativar o embasamento, siga estas etapas:
    1. Clique em + Novo e Chat no menu de navegação.
    2. Abra o painel Configurações do modelo e selecione seu modelo.
    3. Opcional: se a opção Saída estruturada ou Fundamentação: Google estiver ativada, desative-a.
    4. Clique na opção Embasamento: seus dados. O painel Personalizar embasamento aparece.
      1. Selecione uma opção de fonte de embasamento na tabela a seguir:
        2. Opção de embasamento Descrição Entrada
        Vertex AI RAG Engine Embasamento com seus dados e componentes faça você mesmo. Se você não tiver um corpus, crie um. Caso contrário, insira seu corpus.
        Pesquisa de agentes Faz embasamento usando seus dados com um mecanismo de pesquisa gerenciado pelo Google. Insira seu caminho no campo Caminho do repositório de dados da plataforma de agentes do Gemini Enterprise.
        Elasticsearch Embasamento usando o Elasticsearch. Digite as seguintes informações:
        1. Insira um valor no campo Endpoint do Elasticsearch.
        2. Insira um valor no campo Chave de 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. Suas respostas aos comandos são baseadas em aplicativos de IA.

Python

Instalar

pip install --upgrade google-genai

Para saber mais, 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_VERTEXAI=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 as substituições a seguir:

  • LOCATION: a região para processar a solicitação. Para usar o endpoint global, 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 das duas APIs inclui o texto gerado pelo LLM, que é chamado de candidato. Se o comando do modelo embasar corretamente com sua 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:

  • Função: indica o remetente da resposta embasada. Como a resposta sempre contém texto embasado, a função é sempre model.
  • Texto: a resposta embasada gerada pelo LLM.
  • Metadados de embasamento: informações sobre a fonte de embasamento, que contém os seguintes elementos:
    • Trechos de embasamento: uma lista de resultados do seu índice que apoiam a resposta.
    • O embasamento oferece suporte a: informações sobre uma declaração específica na resposta que podem ser usadas para mostrar citações:
    • Segmento: a parte da resposta do modelo que é fundamentada por um trecho de embasamento.
    • Índice do trecho de embasamento: o índice dos trechos de embasamento na lista de trechos de embasamento que corresponde a esta declaração.
    • Níveis de confiança: um número de 0 a 1 que indica o nível de embasamento da declaração no conjunto de partes de embasamento fornecido. Não disponível para Gemini 2.5 e versões mais recentes.

A seguir