O Embasamento com a Pesquisa Google conecta o modelo Gemini ao conteúdo da Web em tempo real e funciona com todos os idiomas disponíveis. Isso permite que o Gemini forneça respostas mais precisas e cite fontes verificáveis além do limite de conhecimento.
A conexão à terra ajuda a criar aplicativos que podem:
- Aumentar a precisão factual:reduza as alucinações do modelo baseando as respostas em informações reais.
- Acessar informações em tempo real:responda a perguntas sobre eventos e temas recentes.
Fornecer citações:mostre as fontes das afirmações do modelo para conquistar a confiança do usuário.
Python
from google import genai
from google.genai import types
# Configure the client
client = genai.Client()
# Define the grounding tool
grounding_tool = types.Tool(
google_search=types.GoogleSearch()
)
# Configure generation settings
config = types.GenerateContentConfig(
tools=[grounding_tool]
)
# Make the request
response = client.models.generate_content(
model="gemini-2.5-flash",
contents="Who won the euro 2024?",
config=config,
)
# Print the grounded response
print(response.text)
JavaScript
import { GoogleGenAI } from "@google/genai";
// Configure the client
const ai = new GoogleGenAI();
// Define the grounding tool
const groundingTool = {
googleSearch: {},
};
// Configure generation settings
const config = {
tools: [groundingTool],
};
// Make the request
const response = await ai.models.generateContent({
model: "gemini-2.5-flash",
contents: "Who won the euro 2024?",
config,
});
// Print the grounded response
console.log(response.text);
REST
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent?key=$GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"contents": [
{
"parts": [
{"text": "Who won the euro 2024?"}
]
}
],
"tools": [
{
"google_search": {}
}
]
}'
Teste o notebook da ferramenta de pesquisa para saber mais.
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, processamento e citação de informações automaticamente.
- Solicitação do usuário:o app envia uma solicitação do usuário para a API Gemini com a ferramenta
google_search
ativada. - Análise de comando:o modelo analisa o comando e determina se uma pesquisa do Google pode melhorar a resposta.
- Pesquisa Google:se necessário, o modelo gera e executa automaticamente uma ou várias consultas de pesquisa.
- Processamento de resultados da pesquisa:o modelo processa os resultados da pesquisa, sintetiza as informações e formula uma resposta.
- Resposta com base:a API retorna uma resposta final e fácil de usar com base nos resultados da pesquisa. Essa resposta inclui a resposta de texto do modelo e
groundingMetadata
com as consultas de pesquisa, resultados da Web e citações.
Noções básicas sobre a resposta de aterramento
Quando uma resposta é fundamentada, ela inclui um campo groundingMetadata
. Esses dados estruturados são essenciais para verificar as declarações e criar uma experiência de citação rica 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 origens da Web (uri
etitle
).groundingSupports
: matriz de blocos para conectar a resposta do modelotext
às origens emgroundingChunks
. Cada bloco vincula umsegment
de texto (definido porstartIndex
eendIndex
) a um ou maisgroundingChunkIndices
. Essa é a chave para criar citações inline.
A base na Pesquisa Google também pode ser usada em conjunto com a ferramenta de contexto de URL para embasar as respostas em dados públicos da Web e nos URLs específicos fornecidos.
Como atribuir fontes com citações inline
A API retorna dados estruturados de citação, a você controle total sobre como as fontes são exibidas na interface do usuário. Você pode usar os campos groundingSupports
e groundingChunks
para vincular as declarações do modelo diretamente às origens. 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 solicitação de API que inclui a ferramenta google_search
. 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 um único uso faturável 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 visualização não estão incluídos. Você pode encontrar os recursos na página Visão geral do modelo.
Modelo | Embasamento com a Pesquisa Google |
---|---|
Gemini 2.5 Pro | ✔️ |
Gemini 2.5 Flash | ✔️ |
Gemini 2.0 Flash | ✔️ |
Gemini 1.5 Pro | ✔️ |
Gemini 1.5 Flash | ✔️ |
Aterramento com modelos 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 oferece suporte a 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 (um valor entre 0,0 e 1,0), uma pesquisa será realizada.
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(api_key=os.getenv("GEMINI_API_KEY"))
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({ apiKey: process.env.GEMINI_API_KEY });
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?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.
- Aprenda a aumentar os comandos com URLs específicos usando a ferramenta de contexto de URL.