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 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 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:conquiste a confiança do usuário mostrando as fontes das declarações do modelo.
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" \
-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_search
ativada. - 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 se baseia nos resultados da pesquisa. Essa resposta inclui a resposta de texto do modelo e
groundingMetadata
com as consultas de pesquisa, os resultados da Web e as citações.
Noções básicas sobre 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 (uri
etitle
).groundingSupports
: matriz de partes para conectar a resposta do modelotext
às fontes emgroundingChunks
. Cada trecho vincula um textosegment
(definido porstartIndex
eendIndex
) a um ou maisgroundingChunkIndices
. Essa é a chave para criar citações inline.
A fundamentação com a Pesquisa Google também pode ser usada em combinação com a ferramenta de contexto de URL para fundamentar respostas em dados públicos da Web e nos URLs específicos que você fornece.
Atribuir fontes com citações inline
A API retorna dados de citação estruturados, a você controle total sobre como exibir as 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
Ao usar o Embasamento com a Pesquisa Google, seu projeto é faturado 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 prévia não estão incluídos. Você pode encontrar os recursos 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.0 Flash | ✔️ |
Gemini 1.5 Pro | ✔️ |
Gemini 1.5 Flash | ✔️ |
Embasamento 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 ao modelo decidir 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.