O embasamento com a Pesquisa Google conecta o modelo Gemini a conteúdo da Web em tempo real e funciona com todos os idiomas disponíveis. Isso permite que o Gemini dê respostas mais precisas e cite fontes verificáveis além do corte de conhecimento.
O embasamento ajuda você a criar aplicativos que podem:
- Aumentar a acurácia factual:reduza as alucinações do modelo com base 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 mostrando as fontes das declarações do modelo.
Python
from google import genai
from google.genai import types
client = genai.Client()
grounding_tool = types.Tool(
google_search=types.GoogleSearch()
)
config = types.GenerateContentConfig(
tools=[grounding_tool]
)
response = client.models.generate_content(
model="gemini-2.5-flash",
contents="Who won the euro 2024?",
config=config,
)
print(response.text)
JavaScript
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({});
const groundingTool = {
googleSearch: {},
};
const config = {
tools: [groundingTool],
};
const response = await ai.models.generateContent({
model: "gemini-2.5-flash",
contents: "Who won the euro 2024?",
config,
});
console.log(response.text);
REST
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"contents": [
{
"parts": [
{"text": "Who won the euro 2024?"}
]
}
],
"tools": [
{
"google_search": {}
}
]
}'
Saiba mais testando o notebook da ferramenta de pesquisa.
Como funciona o embasamento com a Pesquisa Google
Quando você ativa a ferramenta google_search, o modelo processa todo o fluxo de trabalho de pesquisa, tratamento e citação de informações automaticamente.

- Comando do usuário:seu aplicativo envia um comando do usuário para a API Gemini
com a ferramenta
google_searchativada. - Análise do comando:o modelo analisa o comando e determina se uma Pesquisa Google pode melhorar a resposta.
- Pesquisa Google:se necessário, o modelo gera e executa automaticamente uma ou várias consultas de pesquisa.
- Processamento dos resultados da pesquisa:o modelo processa os resultados da pesquisa, sintetiza as informações e formula uma resposta.
- Resposta embasada:a API retorna uma resposta final e fácil de usar que
é baseada nos resultados da pesquisa. Essa resposta inclui a resposta de texto do modelo e
groundingMetadatacom as consultas de pesquisa, os resultados da Web e as citações.
Entender a resposta de embasamento
Quando uma resposta é fundamentada com sucesso, ela inclui um campo groundingMetadata. Esses dados estruturados são essenciais para verificar declarações e criar uma experiência de citação avançada no seu aplicativo.
{
"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]
}
]
}
}
]
}
A API Gemini retorna as seguintes informações com o groundingMetadata:
webSearchQueries: matriz das consultas de pesquisa usadas. Isso é útil para depurar e entender o processo de raciocínio do modelo.searchEntryPoint: contém o HTML e o CSS para renderizar as sugestões de pesquisa necessárias. Os requisitos de uso completos estão detalhados nos Termos de Serviço.groundingChunks: matriz de objetos que contém as fontes da Web (urietitle).groundingSupports: matriz de partes para conectar a resposta do modelotextàs fontes emgroundingChunks. Cada parte vincula um textosegment(definido porstartIndexeendIndex) a um ou maisgroundingChunkIndices. Essa é a chave para criar citações inline.
A embasamento com a Pesquisa Google também pode ser usado em combinação com a ferramenta de contexto de URL para embasar respostas em dados da Web públicos e nos URLs específicos que você fornece.
Como atribuir fontes com citações diretas
A API retorna dados de citação estruturados, a você controle total sobre como exibir fontes na interface do usuário. Você pode usar os campos groundingSupports e groundingChunks para vincular as declarações do modelo diretamente às fontes. Confira um padrão comum para processar os metadados e criar uma resposta com citações inline clicáveis.
Python
def add_citations(response):
text = response.text
supports = response.candidates[0].grounding_metadata.grounding_supports
chunks = response.candidates[0].grounding_metadata.grounding_chunks
# Sort supports by end_index in descending order to avoid shifting issues when inserting.
sorted_supports = sorted(supports, key=lambda s: s.segment.end_index, reverse=True)
for support in sorted_supports:
end_index = support.segment.end_index
if support.grounding_chunk_indices:
# Create citation string like [1](link1)[2](link2)
citation_links = []
for i in support.grounding_chunk_indices:
if i < len(chunks):
uri = chunks[i].web.uri
citation_links.append(f"[{i + 1}]({uri})")
citation_string = ", ".join(citation_links)
text = text[:end_index] + citation_string + text[end_index:]
return text
# Assuming response with grounding metadata
text_with_citations = add_citations(response)
print(text_with_citations)
JavaScript
function addCitations(response) {
let text = response.text;
const supports = response.candidates[0]?.groundingMetadata?.groundingSupports;
const chunks = response.candidates[0]?.groundingMetadata?.groundingChunks;
// Sort supports by end_index in descending order to avoid shifting issues when inserting.
const sortedSupports = [...supports].sort(
(a, b) => (b.segment?.endIndex ?? 0) - (a.segment?.endIndex ?? 0),
);
for (const support of sortedSupports) {
const endIndex = support.segment?.endIndex;
if (endIndex === undefined || !support.groundingChunkIndices?.length) {
continue;
}
const citationLinks = support.groundingChunkIndices
.map(i => {
const uri = chunks[i]?.web?.uri;
if (uri) {
return `[${i + 1}](${uri})`;
}
return null;
})
.filter(Boolean);
if (citationLinks.length > 0) {
const citationString = citationLinks.join(", ");
text = text.slice(0, endIndex) + citationString + text.slice(endIndex);
}
}
return text;
}
const textWithCitations = addCitations(response);
console.log(textWithCitations);
A nova resposta com citações inline vai ficar assim:
Spain won Euro 2024, defeating England 2-1 in the final.[1](https:/...), [2](https:/...), [4](https:/...), [5](https:/...) This victory marks Spain's record-breaking fourth European Championship title.[5]((https:/...), [2](https:/...), [3](https:/...), [4](https:/...)
Preços
Quando você usa o Embasamento com a Pesquisa Google, seu projeto é cobrado por cada
consulta de pesquisa que o modelo decide executar. Se o modelo decidir executar várias consultas de pesquisa para responder a um único comando (por exemplo, pesquisar "UEFA Euro 2024 winner" e "Spain vs England Euro 2024 final score" na mesma chamada de API), isso será contabilizado como dois usos faturáveis da ferramenta para essa solicitação.
Para informações detalhadas sobre preços, consulte a página de preços da API Gemini.
Modelos compatíveis
Os modelos experimentais e de prévia não estão incluídos. Você pode encontrar as capacidades deles na página Visão geral do modelo.
| Modelo | Embasamento com a Pesquisa Google |
|---|---|
| Gemini 2.5 Pro | ✔️ |
| Gemini 2.5 Flash | ✔️ |
| Gemini 2.5 Flash-Lite | ✔️ |
| Gemini 2.0 Flash | ✔️ |
| Gemini 1.5 Pro | ✔️ |
| Gemini 1.5 Flash | ✔️ |
Combinações de ferramentas compatíveis
Você pode usar o embasamento com a Pesquisa Google com outras ferramentas, como execução de código e contexto de URL para casos de uso mais complexos.
Fundamentação com modelos do Gemini 1.5 (legado)
Embora a ferramenta google_search seja recomendada para o Gemini 2.0 e versões mais recentes, o Gemini 1.5 é compatível com uma ferramenta legada chamada google_search_retrieval. Essa ferramenta oferece um modo dynamic que permite que o modelo decida se vai realizar uma pesquisa com base na confiança de que o comando exige informações atualizadas. Se a confiança do modelo estiver acima de um dynamic_threshold definido por você (um valor entre 0,0 e 1,0), ele vai realizar uma pesquisa.
Python
# Note: This is a legacy approach for Gemini 1.5 models.
# The 'google_search' tool is recommended for all new development.
import os
from google import genai
from google.genai import types
client = genai.Client()
retrieval_tool = types.Tool(
google_search_retrieval=types.GoogleSearchRetrieval(
dynamic_retrieval_config=types.DynamicRetrievalConfig(
mode=types.DynamicRetrievalConfigMode.MODE_DYNAMIC,
dynamic_threshold=0.7 # Only search if confidence > 70%
)
)
)
config = types.GenerateContentConfig(
tools=[retrieval_tool]
)
response = client.models.generate_content(
model='gemini-1.5-flash',
contents="Who won the euro 2024?",
config=config,
)
print(response.text)
if not response.candidates[0].grounding_metadata:
print("\nModel answered from its own knowledge.")
JavaScript
// Note: This is a legacy approach for Gemini 1.5 models.
// The 'googleSearch' tool is recommended for all new development.
import { GoogleGenAI, DynamicRetrievalConfigMode } from "@google/genai";
const ai = new GoogleGenAI({});
const retrievalTool = {
googleSearchRetrieval: {
dynamicRetrievalConfig: {
mode: DynamicRetrievalConfigMode.MODE_DYNAMIC,
dynamicThreshold: 0.7, // Only search if confidence > 70%
},
},
};
const config = {
tools: [retrievalTool],
};
const response = await ai.models.generateContent({
model: "gemini-1.5-flash",
contents: "Who won the euro 2024?",
config,
});
console.log(response.text);
if (!response.candidates?.[0]?.groundingMetadata) {
console.log("\nModel answered from its own knowledge.");
}
REST
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"contents": [
{"parts": [{"text": "Who won the euro 2024?"}]}
],
"tools": [{
"google_search_retrieval": {
"dynamic_retrieval_config": {
"mode": "MODE_DYNAMIC",
"dynamic_threshold": 0.7
}
}
}]
}'
A seguir
- Teste o embasamento com a Pesquisa Google no manual da API Gemini.
- Saiba mais sobre outras ferramentas disponíveis, como a chamada de função.
- Saiba como aumentar os comandos com URLs específicos usando a ferramenta de contexto de URL.