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 de agentes.

O embasamento com seus dados aceita no máximo 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 abrir os modelos compatíveis

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 do 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. Criar uma fonte de dados de aplicativos de IA e um aplicativo.

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

Ativar aplicativos de IA

Para usar a Agent Search para embasar 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 repositório de dados 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 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.
    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 repositório de dados 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 as opções de análise e agrupamento dos seus documentos, abra 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 ter 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 Agent Studio no console doGoogle Cloud , siga estas etapas:

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

    Acessar o Agent Studio

  2. Para ativar o embasamento, siga estas etapas:
    1. No painel lateral, em Configurações do modelo, selecione seu modelo.
    2. Acesse a seção Embasamento e ative a opção Seus dados. O painel de configuração aparece.
      1. Selecione uma opção de fonte de embasamento na tabela a seguir:
        2. Opção de embasamento Descrição Entrada
        Mecanismo RAG Embasamento com seus dados e componentes aprenda a fazer. Se você não tiver um corpus, crie um. Caso contrário, insira seu corpus.
        Agent Search Embase usando seus dados com um mecanismo de pesquisa gerenciado pelo Google. Insira seu 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 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. As respostas aos seus comandos são embasadas em 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 do Google 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 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: o ID do projeto. .
  • 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 corretamente na fonte de dados, as respostas incluirão metadados de embasamento, que identificam as partes da resposta derivadas dos 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 fonte de embasamento, que contém os seguintes elementos:
    • Trechos de embasamento: uma lista de resultados do seu índice que apoiam a resposta.
    • Suportes de embasamento: 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 de fragmentos de embasamento: o índice dos fragmentos de embasamento na lista de fragmentos de embasamento que corresponde a essa declaração.
    • Pontuações de confiança: um número de 0 a 1 que indica o nível de embasamento da declaração no conjunto de trechos de embasamento fornecido. Não disponível para o Gemini 2.5 e versões mais recentes.

A seguir