O recurso "Embasamento com a Pesquisa Google" na API Gemini e no AI Studio pode ser usado para melhorar a precisão e a recência das respostas do modelo. Além de respostas mais factuais, quando o Embasamento com a Pesquisa Google está ativado, a API Gemini retorna fontes de fundamentação (links de suporte inline) e sugestões da Pesquisa Google junto com o conteúdo da resposta. As Sugestões de pesquisa direcionam os usuários aos resultados de pesquisa correspondentes à resposta fundamentada.
Este guia vai ajudar você a começar a usar o recurso "Embasamento com a Pesquisa Google" com um dos SDKs da API Gemini ou da API REST.
Configurar o embasamento da Pesquisa
A Pesquisa Google está disponível como uma ferramenta desde o Gemini 2.0. Isso significa que o modelo pode decidir quando usar a Pesquisa Google. O exemplo a seguir mostra como configurar a Pesquisa como uma ferramenta.
from google import genai
from google.genai.types import Tool, GenerateContentConfig, GoogleSearch
client = genai.Client()
model_id = "gemini-2.0-flash"
google_search_tool = Tool(
google_search = GoogleSearch()
)
response = client.models.generate_content(
model=model_id,
contents="When is the next total solar eclipse in the United States?",
config=GenerateContentConfig(
tools=[google_search_tool],
response_modalities=["TEXT"],
)
)
for each in response.candidates[0].content.parts:
print(each.text)
# Example response:
# The next total solar eclipse visible in the contiguous United States will be on ...
# To get grounding metadata as web content.
print(response.candidates[0].grounding_metadata.search_entry_point.rendered_content)
A funcionalidade de pesquisa como ferramenta também permite pesquisas com várias etapas e consultas com várias ferramentas (por exemplo, combinar o Grounding com a Pesquisa Google e a execução de código).
A pesquisa como ferramenta permite comandos e fluxos de trabalho complexos que exigem planejamento, raciocínio e pensamento:
- Embasamento para melhorar a precisão e a atualidade e fornecer respostas mais precisas
- Recuperar artefatos da Web para fazer outras análises em
- Encontrar imagens, vídeos ou outras mídias relevantes para ajudar em tarefas de raciocínio ou geração multimodais
- Programação, solução de problemas técnicos e outras tarefas especializadas
- Encontrar informações específicas da região ou ajudar a traduzir conteúdo com precisão
- Como encontrar sites relevantes para navegar
O Embasamento com a Pesquisa Google funciona com todos os idiomas disponíveis ao fazer comandos de texto. No nível pago da API Gemini Developer, você pode receber 1.500 consultas de Grounding com a Pesquisa Google por dia sem custos financeiros, com consultas adicionais cobradas no padrão de US $35 por 1.000 consultas.
Para saber mais, teste o notebook da ferramenta de pesquisa.
Sugestões de pesquisa do Google
Para usar o Embasamento com a Pesquisa Google, você precisa mostrar as Sugestões de pesquisa do Google, que são consultas sugeridas incluídas nos metadados da resposta embasada. Para saber mais sobre os requisitos de exibição, consulte Usar as Sugestões da Pesquisa Google.
Recuperação da Pesquisa Google
Recuperação dinâmica
Algumas consultas podem se beneficiar mais do que outras com a Base de conhecimento da Pesquisa Google. O recurso de recuperação dinâmica oferece mais controle sobre quando usar o Embasamento com a Pesquisa Google.
Se o modo de recuperação dinâmica não for especificado, a integração com a Pesquisa Google será sempre acionada. Se o modo estiver definido como dinâmico, o modelo vai decidir quando usar a aterramento com base em um limite que você pode configurar. O limite é um valor de ponto flutuante no intervalo [0,1] e tem o valor padrão 0,3. Se o valor de limite for 0, a resposta será sempre com base na Pesquisa Google. Se for 1, nunca será.
Como funciona a recuperação dinâmica
Você pode usar a recuperação dinâmica na sua solicitação para escolher quando ativar o Embasamento com a Pesquisa Google. Isso é útil quando o comando não exige uma resposta com embasamento na Pesquisa Google e o modelo pode fornecer uma resposta com base no próprio conhecimento sem embasamento. Isso ajuda a gerenciar a latência, a qualidade e o custo com mais eficiência.
Antes de invocar a configuração de recuperação dinâmica na solicitação, entenda a seguinte terminologia:
Pontuação da previsão: quando você solicita uma resposta com embasamento, o Gemini atribui uma pontuação de previsão ao comando. A pontuação de previsão é um valor de ponto flutuante no intervalo [0,1]. O valor depende se a instrução pode se beneficiar ao basear a resposta com as informações mais atualizadas da Pesquisa Google. Portanto, se uma instrução exigir uma resposta com base nos fatos mais recentes da Web, ela terá uma pontuação de previsão mais alta. Um comando para o qual uma resposta gerada pelo modelo é suficiente tem uma pontuação de previsão mais baixa.
Confira exemplos de algumas solicitações e as notas de previsão delas.
Comando Pontuação de previsão Comentário "Escreva um poema sobre peônias" 0,13 O modelo pode confiar no próprio conhecimento, e a resposta não precisa de embasamento. "Sugira um brinquedo para uma criança de 2 anos" 0.36 O modelo pode confiar no próprio conhecimento, e a resposta não precisa de embasamento. "Você pode dar uma receita de guacamole de inspiração asiática?" 0,55 A Pesquisa Google pode dar uma resposta com embasamento, mas o embasamento não é estritamente necessário. O conhecimento do modelo pode ser suficiente. "O que é o Agent Builder? Como o embasamento é cobrado no Agent Builder?" 0,72 Requer que a Pesquisa Google gere uma resposta com bom embasamento. "Quem ganhou o último Grande Prêmio de F1?" 0.97 Requer que a Pesquisa Google gere uma resposta com bom embasamento. Limite: na solicitação da API, é possível especificar uma configuração de recuperação dinâmica com um limite. O limite é um valor de ponto flutuante no intervalo [0,1] e tem o valor padrão 0,3. Se o valor de limite for zero, a resposta será sempre com embasamento com a Pesquisa Google. Para todos os outros valores de limite, o seguinte é aplicável:
- Se a pontuação da previsão for maior ou igual ao limite, a resposta será baseada na Pesquisa Google. Um limite mais baixo implica que mais comandos têm respostas geradas usando o Embasamento com a Pesquisa Google.
- Se a pontuação da previsão for menor que o limite, o modelo ainda poderá gerar a resposta, mas ela não será baseada na Pesquisa Google.
Para saber como definir o limite de recuperação dinâmica usando um SDK ou a API REST, consulte o exemplo de código apropriado.
Para encontrar um bom limite que atenda às necessidades da sua empresa, crie um conjunto representativo de consultas que você espera encontrar. Em seguida, você pode classificar as consultas de acordo com a pontuação de previsão na resposta e selecionar um limite adequado para seu caso de uso.
Uma resposta fundamentada
Se o comando for embasado corretamente na Pesquisa Google, a resposta vai incluir
groundingMetadata. Uma resposta com base pode ser semelhante a esta
(partes da resposta foram omitidas para encurtar):
{
"candidates": [
{
"content": {
"parts": [
{
"text": "Carlos Alcaraz won the Gentlemen's Singles title at the 2024 Wimbledon Championships. He defeated Novak Djokovic in the final, winning his second consecutive Wimbledon title and fourth Grand Slam title overall. \n"
}
],
"role": "model"
},
...
"groundingMetadata": {
"searchEntryPoint": {
"renderedContent": "\u003cstyle\u003e\n.container {\n align-items: center;\n border-radius: 8px;\n display: flex;\n font-family: Google Sans, Roboto, sans-serif;\n font-size: 14px;\n line-height: 20px;\n padding: 8px 12px;\n}\n.chip {\n display: inline-block;\n border: solid 1px;\n border-radius: 16px;\n min-width: 14px;\n padding: 5px 16px;\n text-align: center;\n user-select: none;\n margin: 0 8px;\n -webkit-tap-highlight-color: transparent;\n}\n.carousel {\n overflow: auto;\n scrollbar-width: none;\n white-space: nowrap;\n margin-right: -12px;\n}\n.headline {\n display: flex;\n margin-right: 4px;\n}\n.gradient-container {\n position: relative;\n}\n.gradient {\n position: absolute;\n transform: translate(3px, -9px);\n height: 36px;\n width: 9px;\n}\n@media (prefers-color-scheme: light) {\n .container {\n background-color: #fafafa;\n box-shadow: 0 0 0 1px #0000000f;\n }\n .headline-label {\n color: #1f1f1f;\n }\n .chip {\n background-color: #ffffff;\n border-color: #d2d2d2;\n color: #5e5e5e;\n text-decoration: none;\n }\n .chip:hover {\n background-color: #f2f2f2;\n }\n .chip:focus {\n background-color: #f2f2f2;\n }\n .chip:active {\n background-color: #d8d8d8;\n border-color: #b6b6b6;\n }\n .logo-dark {\n display: none;\n }\n .gradient {\n background: linear-gradient(90deg, #fafafa 15%, #fafafa00 100%);\n }\n}\n@media (prefers-color-scheme: dark) {\n .container {\n background-color: #1f1f1f;\n box-shadow: 0 0 0 1px #ffffff26;\n }\n .headline-label {\n color: #fff;\n }\n .chip {\n background-color: #2c2c2c;\n border-color: #3c4043;\n color: #fff;\n text-decoration: none;\n }\n .chip:hover {\n background-color: #353536;\n }\n .chip:focus {\n background-color: #353536;\n }\n .chip:active {\n background-color: #464849;\n border-color: #53575b;\n }\n .logo-light {\n display: none;\n }\n .gradient {\n background: linear-gradient(90deg, #1f1f1f 15%, #1f1f1f00 100%);\n }\n}\n\u003c/style\u003e\n\u003cdiv class=\"container\"\u003e\n \u003cdiv class=\"headline\"\u003e\n \u003csvg class=\"logo-light\" width=\"18\" height=\"18\" viewBox=\"9 9 35 35\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\"\u003e\n \u003cpath fill-rule=\"evenodd\" clip-rule=\"evenodd\" d=\"M42.8622 27.0064C42.8622 25.7839 42.7525 24.6084 42.5487 23.4799H26.3109V30.1568H35.5897C35.1821 32.3041 33.9596 34.1222 32.1258 35.3448V39.6864H37.7213C40.9814 36.677 42.8622 32.2571 42.8622 27.0064V27.0064Z\" fill=\"#4285F4\"/\u003e\n \u003cpath fill-rule=\"evenodd\" clip-rule=\"evenodd\" d=\"M26.3109 43.8555C30.9659 43.8555 34.8687 42.3195 37.7213 39.6863L32.1258 35.3447C30.5898 36.3792 28.6306 37.0061 26.3109 37.0061C21.8282 37.0061 18.0195 33.9811 16.6559 29.906H10.9194V34.3573C13.7563 39.9841 19.5712 43.8555 26.3109 43.8555V43.8555Z\" fill=\"#34A853\"/\u003e\n \u003cpath fill-rule=\"evenodd\" clip-rule=\"evenodd\" d=\"M16.6559 29.8904C16.3111 28.8559 16.1074 27.7588 16.1074 26.6146C16.1074 25.4704 16.3111 24.3733 16.6559 23.3388V18.8875H10.9194C9.74388 21.2072 9.06992 23.8247 9.06992 26.6146C9.06992 29.4045 9.74388 32.022 10.9194 34.3417L15.3864 30.8621L16.6559 29.8904V29.8904Z\" fill=\"#FBBC05\"/\u003e\n \u003cpath fill-rule=\"evenodd\" clip-rule=\"evenodd\" d=\"M26.3109 16.2386C28.85 16.2386 31.107 17.1164 32.9095 18.8091L37.8466 13.8719C34.853 11.082 30.9659 9.3736 26.3109 9.3736C19.5712 9.3736 13.7563 13.245 10.9194 18.8875L16.6559 23.3388C18.0195 19.2636 21.8282 16.2386 26.3109 16.2386V16.2386Z\" fill=\"#EA4335\"/\u003e\n \u003c/svg\u003e\n \u003csvg class=\"logo-dark\" width=\"18\" height=\"18\" viewBox=\"0 0 48 48\" xmlns=\"http://www.w3.org/2000/svg\"\u003e\n \u003ccircle cx=\"24\" cy=\"23\" fill=\"#FFF\" r=\"22\"/\u003e\n \u003cpath d=\"M33.76 34.26c2.75-2.56 4.49-6.37 4.49-11.26 0-.89-.08-1.84-.29-3H24.01v5.99h8.03c-.4 2.02-1.5 3.56-3.07 4.56v.75l3.91 2.97h.88z\" fill=\"#4285F4\"/\u003e\n \u003cpath d=\"M15.58 25.77A8.845 8.845 0 0 0 24 31.86c1.92 0 3.62-.46 4.97-1.31l4.79 3.71C31.14 36.7 27.65 38 24 38c-5.93 0-11.01-3.4-13.45-8.36l.17-1.01 4.06-2.85h.8z\" fill=\"#34A853\"/\u003e\n \u003cpath d=\"M15.59 20.21a8.864 8.864 0 0 0 0 5.58l-5.03 3.86c-.98-2-1.53-4.25-1.53-6.64 0-2.39.55-4.64 1.53-6.64l1-.22 3.81 2.98.22 1.08z\" fill=\"#FBBC05\"/\u003e\n \u003cpath d=\"M24 14.14c2.11 0 4.02.75 5.52 1.98l4.36-4.36C31.22 9.43 27.81 8 24 8c-5.93 0-11.01 3.4-13.45 8.36l5.03 3.85A8.86 8.86 0 0 1 24 14.14z\" fill=\"#EA4335\"/\u003e\n \u003c/svg\u003e\n \u003cdiv class=\"gradient-container\"\u003e\u003cdiv class=\"gradient\"\u003e\u003c/div\u003e\u003c/div\u003e\n \u003c/div\u003e\n \u003cdiv class=\"carousel\"\u003e\n \u003ca class=\"chip\" href=\"https://vertexaisearch.cloud.google.com/grounding-api-redirect/AWhgh4x8Epe-gzpwRBvp7o3RZh2m1ygq1EHktn0OWCtvTXjad4bb1zSuqfJd6OEuZZ9_SXZ_P2SvCpJM7NaFfQfiZs6064MeqXego0vSbV9LlAZoxTdbxWK1hFeqTG6kA13YJf7Fbu1SqBYM0cFM4zo0G_sD9NKYWcOCQMvDLDEJFhjrC9DM_QobBIAMq-gWN95G5tvt6_z6EuPN8QY=\"\u003ewho won wimbledon 2024\u003c/a\u003e\n \u003c/div\u003e\n\u003c/div\u003e\n"
},
"groundingChunks": [
{
"web": {
"uri": "https://vertexaisearch.cloud.google.com/grounding-api-redirect/AWhgh4whET1ta3sDETZvcicd8FeNe4z0VuduVsxrT677KQRp2rYghXI0VpfYbIMVI3THcTuMwggRCbFXS_wVvW0UmGzMe9h2fyrkvsnQPJyikJasNIbjJLPX0StM4Bd694-ZVle56MmRA4YiUvwSqad1w6O2opmWnw==",
"title": "wikipedia.org"
}
},
{
"web": {
"uri": "https://vertexaisearch.cloud.google.com/grounding-api-redirect/AWhgh4wR1M-9-yMPUr_KdHlnoAmQ8ZX90DtQ_vDYTjtP2oR5RH4tRP04uqKPLmesvo64BBkPeYLC2EpVDxv9ngO3S1fs2xh-e78fY4m0GAtgNlahUkm_tBm_sih5kFPc7ill9u2uwesNGUkwrQlmP2mfWNU5lMMr23HGktr6t0sV0QYlzQq7odVoBxYWlQ_sqWFH",
"title": "wikipedia.org"
}
},
{
"web": {
"uri": "https://vertexaisearch.cloud.google.com/grounding-api-redirect/AWhgh4wsDmROzbP-tmt8GdwCW_pqISTZ4IRbBuoaMyaHfcQg8WW-yKRQQvMDTPAuLxJh-8_U8_iw_6JKFbQ8M9oVYtaFdWFK4gOtL4RrC9Jyqc5BNpuxp6uLEKgL5-9TggtNvO97PyCfziDFXPsxylwI1HcfQdrz3Jy7ZdOL4XM-S5rC0lF2S3VWW0IEAEtS7WX861meBYVjIuuF_mIr3spYPqWLhbAY2Spj-4_ba8DjRvmevIFUhRuESTKvBfmpxNSM",
"title": "cbssports.com"
}
},
{
"web": {
"uri": "https://vertexaisearch.cloud.google.com/grounding-api-redirect/AWhgh4yzjLkorHiUKjhOPkWaZ9b4cO-cLG-02vlEl6xTBjMUjyhK04qSIclAa7heR41JQ6AAVXmNdS3WDrLOV4Wli-iezyzW8QPQ4vgnmO_egdsuxhcGk3-Fp8-yfqNLvgXFwY5mPo6QRhvplOFv0_x9mAcka18QuAXtj0SPvJfZhUEgYLCtCrucDS5XFc5HmRBcG1tqFdKSE1ihnp8KLdaWMhrUQI21hHS9",
"title": "jagranjosh.com"
}
},
{
"web": {
"uri": "https://vertexaisearch.cloud.google.com/grounding-api-redirect/AWhgh4y9L4oeNGWCatFz63b9PpP3ys-Wi_zwnkUT5ji9lY7gPUJQcsmmE87q88GSdZqzcx5nZG9usot5FYk2yK-FAGvCRE6JsUQJB_W11_kJU2HVV1BTPiZ4SAgm8XDFIxpCZXnXmEx5HUfRqQm_zav7CvS2qjA2x3__qLME6Jy7R5oza1C5_aqjQu422le9CaigThS5bvJoMo-ZGcXdBUCj2CqoXNVjMA==",
"title": "apnews.com"
}
}
],
"groundingSupports": [
{
"segment": {
"endIndex": 85,
"text": "Carlos Alcaraz won the Gentlemen's Singles title at the 2024 Wimbledon Championships."
},
"groundingChunkIndices": [
0,
1,
2,
3
],
"confidenceScores": [
0.97380733,
0.97380733,
0.97380733,
0.97380733
]
},
{
"segment": {
"startIndex": 86,
"endIndex": 210,
"text": "He defeated Novak Djokovic in the final, winning his second consecutive Wimbledon title and fourth Grand Slam title overall."
},
"groundingChunkIndices": [
1,
0,
4
],
"confidenceScores": [
0.96145374,
0.96145374,
0.96145374
]
}
],
"webSearchQueries": [
"who won wimbledon 2024"
]
}
}
],
...
}
Se a resposta não incluir groundingMetadata, isso significa que a resposta
não foi fundamentada. Isso pode acontecer por vários motivos,
incluindo baixa relevância da fonte ou informações incompletas na
resposta do modelo.
Quando um resultado com base é gerado, os metadados contêm URIs que redirecionam
para os editores do conteúdo usado para gerar o resultado com base.
Esses URIs contêm o subdomínio vertexaisearch, como neste exemplo truncado:
https://vertexaisearch.cloud.google.com/grounding-api-redirect/.... Os
metadados também contêm os domínios dos editores. Os URIs fornecidos permanecem
acessíveis por 30 dias após a geração do resultado com embasamento.
O campo renderedContent em searchEntryPoint é o código fornecido para
implementar as sugestões da Pesquisa Google. Consulte
Usar as sugestões da Pesquisa Google
para saber mais.