Embasamento com a Pesquisa Google

O embasamento com a Pesquisa Google conecta um modelo Gemini a conteúdo da Web em tempo real e disponível publicamente. Isso permite que o modelo forneça respostas mais precisas e atualizadas, além de citar fontes verificáveis além do corte de conhecimento.

O embasamento com a Pesquisa Google tem os seguintes benefícios:

• Aumentar a acurácia factual: reduza as alucinações do modelo embasando as respostas em informações do mundo real.
• Acessar informações em tempo real: responda a perguntas sobre eventos e temas recentes.
• Forneça citações: aumente a confiança do usuário ou permita que ele navegue por sites relevantes mostrando as fontes das declarações do modelo.
• Conclua tarefas mais complexas: recupere artefatos e imagens, vídeos ou outras mídias relevantes para ajudar em tarefas de raciocínio.
• Melhorar respostas específicas de região ou idioma: encontre informações específicas de uma região ou ajude a traduzir conteúdo com precisão.

O suporte para embasamento na Pesquisa Google está disponível para iOS+, Android e Web. Ele vai estar disponível para Flutter e Unity nas próximas versões.

Observação para editores da Web:o embasamento com a Pesquisa Google não usa páginas da Web para embasamento que tenham desativado o Google-Extended. Os editores da Web podem gerenciar a inclusão no Google Ampliado com um arquivo robots.txt.

Modelos compatíveis

• gemini-2.5-pro
• gemini-2.5-flash
• gemini-2.5-flash-lite-preview-06-17
• gemini-2.0-flash-001 (e o alias atualizado automaticamente gemini-2.0-flash)
• gemini-2.0-flash-live-preview-04-09

Linguagens com suporte

Consulte os idiomas aceitos para modelos Gemini.

Basear o modelo na Pesquisa Google

Clique no seu provedor de Gemini API para conferir o conteúdo e o código específicos do provedor nesta página. API Gemini Developer API Gemini da Vertex AI

Importante: se uma resposta contiver "Sugestões da Pesquisa Google" (o campo searchEntryPoint no objeto groundingMetadata), essa resposta será um "resultado com embasamento". Portanto, é necessário obedecer aos requisitos de uso de "Embasamento com a Pesquisa Google", incluindo como você exibe o resultado. Saiba como usar e mostrar um resultado embasado mais adiante nesta página.

Ao criar a instância GenerativeModel, forneça GoogleSearch como um tool que o modelo pode usar para gerar a resposta.

Swift

import FirebaseAI

// Initialize the Gemini Developer API backend service
let ai = FirebaseAI.firebaseAI(backend: .googleAI())

// Create a `GenerativeModel` instance with a model that supports your use case
let model = ai.generativeModel(
    modelName: "GEMINI_MODEL_NAME",
    // Provide Google Search as a tool that the model can use to generate its response
    tools: [Tool.googleSearch()]
)

let response = try await model.generateContent("Who won the euro 2024?")
print(response.text ?? "No text in response.")

// Make sure to comply with the "Grounding with Google Search" usage requirements,
// which includes how you use and display the grounded result

Kotlin

// Initialize the Gemini Developer API backend service
// Create a `GenerativeModel` instance with a model that supports your use case
val model = Firebase.ai(backend = GenerativeBackend.googleAI()).generativeModel(
    modelName = "GEMINI_MODEL_NAME",
    // Provide Google Search as a tool that the model can use to generate its response
    tools = listOf(Tool.GoogleSearch())
)

val response = model.generateContent("Who won the euro 2024?")
print(response.text)

// Make sure to comply with the "Grounding with Google Search" usage requirements,
// which includes how you use and display the grounded result

Java

// Initialize the Gemini Developer API backend service
// Create a `GenerativeModel` instance with a model that supports your use case
GenerativeModel ai = FirebaseAI.getInstance(GenerativeBackend.googleAI())
                .generativeModel("GEMINI_MODEL_NAME",
                        null,
                        null,
                        // Provide Google Search as a tool that the model can use to generate its response
                        List.of(Tool.GoogleSearch()));

// Use the GenerativeModelFutures Java compatibility layer which offers
// support for ListenableFuture and Publisher APIs
GenerativeModelFutures model = GenerativeModelFutures.from(ai);

ListenableFuture response = model.generateContent("Who won the euro 2024?");
  Futures.addCallback(response, new FutureCallback() {
      @Override
      public void onSuccess(GenerateContentResponse result) {
          String resultText = result.getText();
          System.out.println(resultText);
      }

      @Override
      public void onFailure(Throwable t) {
          t.printStackTrace();
      }
  }, executor);

// Make sure to comply with the "Grounding with Google Search" usage requirements,
// which includes how you use and display the grounded result

Web

import { initializeApp } from "firebase/app";
import { getAI, getGenerativeModel, GoogleAIBackend } from "firebase/ai";

// TODO(developer) Replace the following with your app's Firebase configuration
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize FirebaseApp
const firebaseApp = initializeApp(firebaseConfig);

// Initialize the Gemini Developer API backend service
const ai = getAI(firebaseApp, { backend: new GoogleAIBackend() });

// Create a `GenerativeModel` instance with a model that supports your use case
const model = getGenerativeModel(
  ai,
  {
    model: "GEMINI_MODEL_NAME",
    // Provide Google Search as a tool that the model can use to generate its response
    tools: [{ googleSearch: {} }]
  }
);

const result = await model.generateContent("Who won the euro 2024?");

console.log(result.response.text());

// Make sure to comply with the "Grounding with Google Search" usage requirements,
// which includes how you use and display the grounded result

Dart

O suporte para Flutter será disponibilizado na próxima versão.

Unity

O suporte ao Unity será disponibilizado na próxima versão.

Saiba como escolher um modelo adequado para seu caso de uso e app.

Para resultados ideais, use uma temperatura de 1.0, que é o padrão para todos os modelos 2.5. Saiba como definir a temperatura na configuração do modelo.

Como funciona o embasamento com a Pesquisa Google

Quando você usa a ferramenta GoogleSearch, o modelo processa todo o fluxo de trabalho de pesquisa, tratamento e citação de informações automaticamente.

Este é o fluxo de trabalho do modelo:

1. Receber comando: seu app envia um comando ao modelo Gemini com a ferramenta GoogleSearch ativada.
2. Analisar o comando: o modelo analisa o comando e determina se a Pesquisa Google pode melhorar a resposta.
3. Enviar consultas para a Pesquisa Google: se necessário, o modelo gera e executa automaticamente uma ou várias consultas de pesquisa.
4. Processar os resultados da pesquisa: o modelo processa os resultados da Pesquisa Google e formula uma resposta ao comando original.
5. Retornar um "resultado embasado": o modelo retorna uma resposta final e fácil de usar embasada nos resultados da pesquisa do Google. Essa resposta inclui a resposta de texto do modelo e groundingMetadata com as consultas de pesquisa, os resultados da Web e as citações.

Fornecer a Pesquisa Google como uma ferramenta para o modelo não exige que ele sempre use essa ferramenta para gerar a resposta. Nesses casos, a resposta não vai conter um objeto groundingMetadata e, portanto, não é um "resultado embasado".

Entender o resultado embasado

Se o modelo embasar a resposta nos resultados da Pesquisa Google, ela vai incluir um objeto groundingMetadata com dados estruturados essenciais para verificar declarações e criar uma experiência de citação avançada no seu aplicativo.

Importante: se uma resposta contiver "Sugestões da Pesquisa Google" (o campo searchEntryPoint no objeto groundingMetadata), essa resposta será um "resultado com embasamento". Portanto, é necessário obedecer aos requisitos de uso de "Embasamento com a Pesquisa Google", incluindo como você exibe o resultado. Saiba como usar e mostrar um resultado embasado mais adiante nesta página.

O objeto groundingMetadata em um "resultado embasado" contém as seguintes informações:

• webSearchQueries: uma matriz das consultas de pesquisa enviadas à Pesquisa Google. Essas informações são úteis para depurar e entender o processo de raciocínio do modelo.

• searchEntryPoint: contém o HTML e o CSS para renderizar as "Sugestões da Pesquisa Google" necessárias. Você precisa obedecer aos requisitos de uso de "Embasamento com a Pesquisa Google" para o provedor de API escolhido: Gemini Developer API ou Vertex AI Gemini API. Consulte a seção Termos de serviço nos Termos específicos de serviço. Saiba como usar e mostrar um resultado embasado mais adiante nesta página.

• groundingChunks: uma matriz de objetos que contém as fontes da Web (uri e title).

• groundingSupports: uma matriz de partes para conectar a resposta do modelo text às fontes em groundingChunks. Cada trecho vincula um texto segment (definido por startIndex e endIndex) a um ou mais groundingChunkIndices. Esse campo ajuda você a criar citações inline. Saiba como usar e mostrar um resultado embasado mais adiante nesta página.

Confira um exemplo de resposta que inclui um objeto groundingMetadata:

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "Spain won Euro 2024, defeating England 2-1 in the final. This victory marks Spain's record fourth European Championship title."
          }
        ],
        "role": "model"
      },
      "groundingMetadata": {
        "webSearchQueries": [
          "UEFA Euro 2024 winner",
          "who won euro 2024"
        ],
        "searchEntryPoint": {
          "renderedContent": "<!-- HTML and CSS for the search widget -->"
        },
        "groundingChunks": [
          {"web": {"uri": "https://vertexaisearch.cloud.google.com.....", "title": "aljazeera.com"}},
          {"web": {"uri": "https://vertexaisearch.cloud.google.com.....", "title": "uefa.com"}}
        ],
        "groundingSupports": [
          {
            "segment": {"startIndex": 0, "endIndex": 85, "text": "Spain won Euro 2024, defeatin..."},
            "groundingChunkIndices": [0]
          },
          {
            "segment": {"startIndex": 86, "endIndex": 210, "text": "This victory marks Spain's..."},
            "groundingChunkIndices": [0, 1]
          }
        ]
      }
    }
  ]
}

Usar e mostrar um resultado embasado

Se o modelo usar a ferramenta Pesquisa Google para gerar uma resposta, ele vai fornecer um groundingMetadata objeto na resposta.

É obrigatório mostrar sugestões da Pesquisa Google e recomendado mostrar citações.

Além de obedecer aos requisitos de uso da ferramenta Pesquisa Google, mostrar essas informações ajuda você e seus usuários finais a validar respostas e oferece caminhos para mais aprendizado.

Importante: esta seção descreve orientações básicas e um padrão geral de como usar e mostrar um resultado embasado. Analise e obedeça aos requisitos de uso e exibição do Gemini APIprovedor escolhido: Gemini Developer API ou Vertex AI Gemini API. Consulte a seção Termos de serviço nos Termos específicos de serviço.

(Obrigatório) Mostrar sugestões da Pesquisa Google

Se uma resposta contiver "Sugestões da Pesquisa Google", você precisará cumprir os requisitos de uso do "Embasamento com a Pesquisa Google", que incluem como exibir as sugestões da Pesquisa Google.

O objeto groundingMetadata contém "Sugestões da Pesquisa Google", especificamente o campo searchEntryPoint, que tem um campo renderedContent que fornece estilo HTML e CSS compatível, que você precisa implementar para mostrar sugestões da Pesquisa no seu app.

Consulte as informações detalhadas sobre os requisitos de exibição e comportamento para sugestões da Pesquisa Google na documentação do Google Cloud. Embora essa orientação detalhada esteja na documentação do Vertex AI Gemini API, ela também se aplica ao provedor Gemini Developer API.

Confira exemplos de código mais adiante nesta seção.

Observação: o HTML e o CSS fornecidos na resposta se adaptam automaticamente às configurações do dispositivo, sendo exibidos no modo claro ou escuro com base na preferência indicada por @media(prefers-color-scheme).

(Recomendado) Citações de display

O objeto groundingMetadata contém dados de citação estruturados, especificamente os campos groundingSupports e groundingChunks. Use essas informações para vincular as declarações do modelo diretamente às fontes na sua interface (inline e agregadas).

Confira exemplos de código mais adiante nesta seção.

Exemplos de código

Essas amostras de código fornecem padrões generalizados para usar e mostrar o resultado embasado. No entanto, é sua responsabilidade garantir que sua implementação específica esteja alinhada aos requisitos de compliance.

Swift

// ...

// Get the model's response
let text = response.text

// Get the grounding metadata
if let candidate = response.candidates.first,
   let groundingMetadata = candidate.groundingMetadata {
  // REQUIRED - display Google Search suggestions
  // (renderedContent contains HTML and CSS for the search widget)
  if let renderedContent = groundingMetadata.searchEntryPoint?.renderedContent {
    // TODO(developer): Display Google Search suggestions using a WebView
  }

  // RECOMMENDED - display citations
  let groundingChunks = groundingMetadata.groundingChunks
  for chunk in groundingMetadata.groundingChunks {
    if let web = chunk.web {
      let title = web.title  // for example, "uefa.com"
      let uri = web.uri  // for example, "https://vertexaisearch.cloud.google.com..."
      // TODO(developer): show citation in the UI
    }
  }
}

Kotlin

// ...

// Get the model's response
val text = response.text

// Get the grounding metadata
val groundingMetadata = response.candidates.firstOrNull()?.groundingMetadata

// REQUIRED - display Google Search suggestions
// (renderedContent contains HTML and CSS for the search widget)
val renderedContent = groundingMetadata?.searchEntryPoint?.renderedContent
if (renderedContent != null) {
    // TODO(developer): Display Google Search suggestions using a WebView
}

// RECOMMENDED - display citations
val groundingChunks = groundingMetadata?.groundingChunks
groundingChunks?.let { chunks ->
  for (chunk in chunks) {
  	val title = chunk.web?.title  // for example, "uefa.com"
	val uri = chunk.web?.uri  // for example, "https://vertexaisearch.cloud.google.com..."
// TODO(developer): show citation in the UI
  }
}

Java

// ...

Futures.addCallback(response, new FutureCallback() {
  @Override
  public void onSuccess(GenerateContentResponse result) {
  // Get the model's response
  String text = result.getText();

  // Get the grounding metadata
  GroundingMetadata groundingMetadata =
  result.getCandidates()[0].getGroundingMetadata();

  if (groundingMetadata != null) {
    // REQUIRED - display Google Search suggestions
  // (renderedContent contains HTML and CSS for the search widget)
    String renderedContent =
  groundingMetadata.getSearchEntryPoint().getRenderedContent();
    if (renderedContent != null) {
      // TODO(developer): Display Google Search suggestions using a WebView
    }

    // RECOMMENDED - display citations
    List chunks = groundingMetadata.getGroundingChunks();
    if (chunks != null) {
      for(GroundingChunk chunk : chunks) {
        WebGroundingChunk web = chunk.getWeb();
        if (web != null) {
          String title = web.getTitle();  // for example, "uefa.com"
          String uri = web.getUri();  // for example, "https://vertexaisearch.cloud.google.com..."
          // TODO(developer): show citation in the UI
        }
      }
    }
  }
  }

  @Override
  public void onFailure(Throwable t) {
  t.printStackTrace();
  }
  }, executor);

Web

// ...

// Get the model's text response
const text = result.response.text();

// Get the grounding metadata
const groundingMetadata = result.response.candidates?.[0]?.groundingMetadata;

// REQUIRED - display Google Search suggestions
// (renderedContent contains HTML and CSS for the search widget)
const renderedContent = groundingMetadata?.searchEntryPoint?.renderedContent;
if (renderedContent) {
  // TODO(developer): render this HTML and CSS in the UI
}

// RECOMMENDED - display citations
const groundingChunks = groundingMetadata?.groundingChunks;
if (groundingChunks) {
  for (const chunk of groundingChunks) {
    const title = chunk.web?.title;  // for example, "uefa.com"
    const uri = chunk.web?.uri;  // for example, "https://vertexaisearch.cloud.google.com..."
    // TODO(developer): show citation in the UI
  }
}

Dart

O suporte para Flutter será disponibilizado na próxima versão.

Unity

O suporte ao Unity será disponibilizado na próxima versão.

Resultados embasados e monitoramento de IA no console do Firebase

Se você ativou o monitoramento de IA no console do Firebase, as respostas são armazenadas no Cloud Logging. Por padrão, esses dados têm um período de retenção de 30 dias.

É sua responsabilidade garantir que esse período de retenção ou qualquer período personalizado definido por você esteja totalmente alinhado ao seu caso de uso específico e a outros requisitos de compliance do provedor de Gemini API escolhido: Gemini Developer API ou Vertex AI Gemini API (consulte a seção Termos de Serviço nos Termos Específicos do Serviço). Talvez seja necessário ajustar o período de retenção em Cloud Logging para atender a esses requisitos.

Preços e limites

Revise os preços, a disponibilidade de modelos e os limites do embasamento com a Pesquisa Google na documentação do provedor Gemini API escolhido: Gemini Developer API | Vertex AI Gemini API.