Embasamento com a Pesquisa Google

Nesta página, explicamos como embasar as respostas do Gemini usando resultados do mecanismo de pesquisa do Google, que usa dados da Web disponíveis publicamente. Além disso, as sugestões de pesquisa, que estão incluídas nas suas respostas, são explicadas.

Se quiser conectar seu modelo ao conhecimento mundial, a uma ampla variedade de tópicos ou a informações atualizadas na Internet, use o embasamento com a Pesquisa Google.

Para saber mais sobre o embasamento de modelo na Vertex AI, consulte a Visão geral de embasamento.

Modelos compatíveis

Esta seção lista os modelos que oferecem suporte ao embasamento com a Pesquisa.

Idiomas compatíveis

Para uma lista de idiomas disponíveis, consulte Idiomas.

Use as instruções a seguir para embasar um modelo com dados da Web disponíveis publicamente.

Considerações

  • Para usar o embasamento com a Pesquisa Google, ative as Sugestões de pesquisa. Para mais informações, consulte Usar as sugestões da Pesquisa Google.

  • Para resultados ideais, use uma temperatura de 1.0. Para saber mais sobre como definir essa configuração, consulte o Corpo da solicitação da API Gemini na referência do modelo.

  • O embasamento na Pesquisa Google tem um limite de um milhão de consultas por dia. Se precisar de mais consultas, entre em contato com o suporte doGoogle Cloud para receber ajuda.

Os resultados da pesquisa podem ser personalizados para um local geográfico específico do usuário final usando as coordenadas de latitude e longitude. Para mais informações, consulte a API Grounding.

Console

Para usar o Embasamento com a Pesquisa Google no Vertex AI Studio, siga estas etapas:

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

    Acessar o Vertex AI Studio

  2. Clique na guia Formato livre.
  3. No painel lateral, clique no botão Embasar respostas do modelo.
  4. Clique em Personalizar e defina o embasamento com a Pesquisa Google como a origem.
  5. Insira o comando na caixa de texto e clique em Enviar.

Agora, suas respostas aos comandos usam o Embasamento com a Pesquisa Google.

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,
    GoogleSearch,
    HttpOptions,
    Tool,
)

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

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="When is the next total solar eclipse in the United States?",
    config=GenerateContentConfig(
        tools=[
            # Use Google Search Tool
            Tool(
                google_search=GoogleSearch(
                    # Optional: Domains to exclude from results
                    exclude_domains=["domain.com", "domain2.com"]
                )
            )
        ],
    ),
)

print(response.text)
# Example response:
# 'The next total solar eclipse in the United States will occur on ...'

Go

Saiba como instalar ou atualizar o Go.

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
 

import (
	"context"
	"fmt"
	"io"

	genai "google.golang.org/genai"
)

// generateWithGoogleSearch shows how to generate text using Google Search.
func generateWithGoogleSearch(w io.Writer) error {
	ctx := context.Background()

	client, err := genai.NewClient(ctx, &genai.ClientConfig{
		HTTPOptions: genai.HTTPOptions{APIVersion: "v1"},
	})
	if err != nil {
		return fmt.Errorf("failed to create genai client: %w", err)
	}

	modelName := "gemini-2.5-flash"
	contents := []*genai.Content{
		{Parts: []*genai.Part{
			{Text: "When is the next total solar eclipse in the United States?"},
		},
			Role: genai.RoleUser},
	}
	config := &genai.GenerateContentConfig{
		Tools: []*genai.Tool{
			{GoogleSearch: &genai.GoogleSearch{ExcludeDomains: []string{"example.com", "example.org"}}},
		},
	}

	resp, err := client.Models.GenerateContent(ctx, modelName, contents, config)
	if err != nil {
		return fmt.Errorf("failed to generate content: %w", err)
	}

	respText := resp.Text()

	fmt.Fprintln(w, respText)

	// Example response:
	// The next total solar eclipse in the United States will occur on March 30, 2033, but it will only ...

	return nil
}

Java

Saiba como instalar ou atualizar o Java.

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
 


import com.google.genai.Client;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.GoogleSearch;
import com.google.genai.types.HttpOptions;
import com.google.genai.types.Tool;

public class ToolsGoogleSearchWithText {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String modelId = "gemini-2.5-flash";
    generateContent(modelId);
  }

  // Generates content with Google Search tool
  public static String generateContent(String modelId) {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (Client client =
        Client.builder()
            .location("global")
            .vertexAI(true)
            .httpOptions(HttpOptions.builder().apiVersion("v1").build())
            .build()) {

      // Create a GenerateContentConfig and set Google Search tool
      GenerateContentConfig contentConfig =
          GenerateContentConfig.builder()
              .tools(Tool.builder().googleSearch(GoogleSearch.builder().build()).build())
              .build();

      GenerateContentResponse response =
          client.models.generateContent(
              modelId, "When is the next total solar eclipse in the United States?", contentConfig);

      System.out.print(response.text());
      // Example response:
      // The next total solar eclipse in the United States will occur on...
      return response.text();
    }
  }
}

Node.js

Instalar

npm install @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
 

const {GoogleGenAI} = require('@google/genai');

const GOOGLE_CLOUD_PROJECT = process.env.GOOGLE_CLOUD_PROJECT;
const GOOGLE_CLOUD_LOCATION = process.env.GOOGLE_CLOUD_LOCATION || 'global';

async function generateGoogleSearch(
  projectId = GOOGLE_CLOUD_PROJECT,
  location = GOOGLE_CLOUD_LOCATION
) {
  const client = new GoogleGenAI({
    vertexai: true,
    project: projectId,
    location: location,
  });

  const response = await client.models.generateContent({
    model: 'gemini-2.5-flash',
    contents: 'When is the next total solar eclipse in the United States?',
    config: {
      tools: [
        {
          googleSearch: {},
        },
      ],
    },
  });

  console.log(response.text);

  // Example response:
  //    'The next total solar eclipse in United States will occur on ...'

  return response.text;
}

REST

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.
  • TEXT: as instruções de texto a serem incluídas no comando.
  • EXCLUDE_DOMAINS: opcional. Lista de domínios que não podem ser usados para embasamento.
  • LATITUDE: opcional, é a latitude do local do usuário final. Por exemplo, uma latitude de 37.7749 representa São Francisco. Você pode usar serviços como o Google Maps ou outras ferramentas de geocodificação para obter coordenadas de latitude e longitude.
  • LONGITUDE: opcional, a longitude do local do usuário final. Por exemplo, uma longitude de -122.4194 representa São Francisco.

Método HTTP e URL: 

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

Corpo JSON da solicitação:

{
  "contents": [{
    "role": "user",
    "parts": [{
      "text": "TEXT"
    }]
  }],
  "tools": [{
    "googleSearch": {
      "exclude_domains": [ "domain.com", "domain2.com" ]
    }
  }],
  "toolConfig": {
    "retrievalConfig": {
      "latLng": {
        "latitude": LATITUDE,
        "longitude": LONGITUDE
      }
    }
  },
  "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": "The weather in Chicago this weekend, will be partly cloudy. The temperature will be between 49°F (9°C) and 55°F (13°C) on Saturday and between 51°F (11°C) and 56°F (13°C) on Sunday. There is a slight chance of rain on both days.\n"
          }
        ]
      },
      "finishReason": "STOP",
      "groundingMetadata": {
        "webSearchQueries": [
          "weather in Chicago this weekend"
        ],
        "searchEntryPoint": {
          "renderedContent": "..."
        },
        "groundingChunks": [
          {
            "web": {
              "uri": "https://www.google.com/search?q=weather+in+Chicago,+IL",
              "title": "Weather information for locality: Chicago, administrative_area: IL",
              "domain": "google.com"
            }
          },
          {
            "web": {
              "uri": "...",
              "title": "weatherbug.com",
              "domain": "weatherbug.com"
            }
          }
        ],
        "groundingSupports": [
          {
            "segment": {
              "startIndex": 85,
              "endIndex": 214,
              "text": "The temperature will be between 49°F (9°C) and 55°F (13°C) on Saturday and between 51°F (11°C) and 56°F (13°C) on Sunday."
            },
            "groundingChunkIndices": [
              0
            ],
            "confidenceScores": [
              0.8662828
            ]
          },
          {
            "segment": {
              "startIndex": 215,
              "endIndex": 261,
              "text": "There is a slight chance of rain on both days."
            },
            "groundingChunkIndices": [
              1,
              0
            ],
            "confidenceScores": [
              0.62836814,
              0.6488607
            ]
          }
        ],
        "retrievalMetadata": {}
      }
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 10,
    "candidatesTokenCount": 98,
    "totalTokenCount": 108,
    "trafficType": "ON_DEMAND",
    "promptTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 10
      }
    ],
    "candidatesTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 98
      }
    ]
  },
  "modelVersion": "gemini-2.0-flash",
  "createTime": "2025-05-19T14:42:55.000643Z",
  "responseId": "b0MraIMFoqnf-Q-D66G4BQ"
}

Entender a resposta

Se o comando do modelo usar corretamente o embasamento com a Pesquisa Google pelo Vertex AI Studio ou pela API, as respostas vão incluir metadados com links de origem (URLs da Web). 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.

Suporte de embasamento

É necessário mostrar o suporte de embasamento porque ele ajuda você a validar as respostas dos editores e oferece caminhos para mais aprendizado.

O suporte de embasamento para respostas de fontes da Web precisa ser mostrado inline e de forma agregada. Confira a imagem abaixo como uma sugestão de como fazer isso.

Exemplos de suporte de embasamento

Uso de opções alternativas de mecanismo de pesquisa

Ao usar o Embasamento com a Pesquisa Google, um aplicativo do cliente pode:

  • Oferecer opções alternativas de mecanismo de pesquisa
  • Definir outros mecanismos de pesquisa como padrão
  • Mostrar sugestões ou resultados de pesquisa próprios ou de terceiros, desde que: os resultados que não são do Google sejam exibidos separadamente dos resultados embasados e das sugestões de pesquisa do Google, e mostrados de uma forma que não confunda os usuários nem sugira que são do Google.

Vantagens

As seguintes solicitações e fluxos de trabalho complexos que exigem planejamento, raciocínio e pensamento podem ser feitos ao usar o embasamento com a Pesquisa Google como uma ferramenta:

  • Você pode usar o embasamento para garantir que as respostas sejam baseadas nas informações mais recentes e precisas.
  • Você pode recuperar artefatos da Web para fazer análises.
  • Você pode encontrar imagens, vídeos ou outras mídias relevantes para ajudar no raciocínio multimodal ou na geração de tarefas.
  • Você pode realizar programação, solução de problemas técnicos e outras tarefas especializadas.
  • Você pode encontrar informações específicas da região ou ajudar a traduzir conteúdo com precisão.
  • Você pode encontrar sites relevantes para navegar.

Usar as Sugestões da Pesquisa Google

Ao usar o embasamento com a Pesquisa Google e receber sugestões de pesquisa na sua resposta, você precisa mostrar as sugestões de pesquisa na produção e nos seus aplicativos.

Especificamente, você precisa mostrar as consultas de pesquisa incluídas nos metadados da resposta embasada. A resposta inclui:

  • "content": resposta gerada por LLM.
  • "webSearchQueries": as consultas a serem usadas para sugestões de pesquisa.

Por exemplo, no snippet de código a seguir, o Gemini responde a um comando baseado na Pesquisa que pergunta sobre um tipo de planta tropical.

"predictions": [
  {
    "content": "Monstera is a type of vine that thrives in bright indirect light…",
    "groundingMetadata": {
      "webSearchQueries": ["What's a monstera?"],
    }
  }
]

Use as sugestões da Pesquisa para mostrar essa saída.

Requisitos para sugestões de pesquisa

Os seguintes requisitos são necessários para as sugestões de pesquisa:

Requisito Descrição
O que fazer
  • Em conformidade com os requisitos de exibição, a sugestão de pesquisa é mostrada exatamente como fornecida, sem alterações.
  • Quando você interage com a sugestão de pesquisa, é direcionado diretamente para a página de resultados da Pesquisa (SRP).
O que não fazer
  • Inclua telas ou etapas adicionais entre o toque do usuário e a exibição do SRP.
  • Mostre outros resultados ou sugestões da pesquisa ao lado da Sugestão de Pesquisa ou da resposta do LLM fundamentada associada.

Requisitos de exibição

Confira os requisitos de exibição:

  • Mostre a sugestão de pesquisa exatamente como ela foi fornecida e não faça modificações nas cores, fontes ou aparência. Confira se a sugestão de pesquisa é renderizada conforme especificado nas simulações a seguir, como os modos claro e escuro:

  • Sempre que uma resposta fundamentada for exibida, a sugestão de pesquisa correspondente deverá permanecer visível.
  • Para branding, siga rigorosamente as diretrizes do Google para uso de características da marca do Google por terceiros na Central de recursos da marca.
  • Quando você usa o embasamento com a Pesquisa, os ícones de sugestão de pesquisa aparecem. O campo que contém os chips de sugestões de pesquisa precisa ter a mesma largura da resposta embasada do LLM.

Comportamento ao tocar

Quando um usuário toca no ícone, ele é direcionado para uma página de resultados da Pesquisa (SRP) com o termo de pesquisa exibido no ícone. O SRP pode ser aberto no navegador do aplicativo ou em um aplicativo de navegador separado. É importante não minimizar, remover ou obstruir a exibição do SRP de maneira alguma. O modelo animado a seguir ilustra a interação do toque para o SRP.

exemplo de app/desktop

Código para implementar uma sugestão de pesquisa

Quando você usa a API para fundamentar uma resposta para a pesquisa, a resposta do modelo fornece estilo HTML e CSS compatível no campo renderedContent, que você implementa para mostrar sugestões de pesquisa no seu aplicativo.

Além disso, as Sugestões de pesquisa eram chamadas de Pontos de entrada de pesquisa. Embora você possa encontrar referências a "Pontos de entrada de pesquisa" em alguns campos da API, os dois termos se referem às sugestões de pesquisa atuais que você recebe na resposta da API.

Mudanças no faturamento com o Gemini 3

Ao usar o Embasamento com a Pesquisa Google nos modelos do Gemini 3, o faturamento ocorre para cada consulta de pesquisa gerada pelo Gemini e enviada à Pesquisa. Um único comando pode levar a uma ou mais consultas de pesquisa.

Exemplo

Este exemplo mostra um comando do usuário e consultas de pesquisa que podem ser cobradas.

  • Comando do usuário: Conte-me sobre a vida de Albert Einstein.
  • O Gemini pode gerar estas consultas de pesquisa:
    • Nascimento e educação de Albert Einstein
    • Teoria da relatividade de Albert Einstein
    • A vida de Albert Einstein nos EUA

Neste exemplo, essas três consultas de pesquisa são cobradas.

A seguir