Gemini API 및 AI Studio의 Google 검색을 통한 그라운딩 기능을 사용하면 모델의 응답 정확성과 최신성을 개선할 수 있습니다. Google 검색을 사용한 그라운딩이 사용 설정된 경우 더 많은 사실 기반 대답 외에도 Gemini API는 응답 콘텐츠와 함께 그라운딩 소스 (인라인 지원 링크) 및 Google 검색 추천을 반환합니다. 추천 검색어는 사용자를 그라운딩된 응답에 해당하는 검색 결과로 안내합니다.
이 가이드를 통해 Gemini API SDK 또는 REST API 중 하나를 사용하여 Google 검색을 통한 그라운딩을 시작할 수 있습니다.
검색 그라운딩 구성
Gemini 2.0부터 Google 검색을 도구로 사용할 수 있습니다. 즉, 모델이 Google 검색을 사용할 시기를 결정할 수 있습니다. 다음 예는 Google 검색을 도구로 구성하는 방법을 보여줍니다.
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)
검색 도구 기능을 사용하면 여러 번의 검색과 여러 도구 쿼리 (예: 그라운딩을 Google 검색 및 코드 실행과 결합)도 가능합니다.
도구로서 검색을 사용하면 계획, 추론, 사고가 필요한 복잡한 프롬프트와 워크플로를 사용할 수 있습니다.
- 사실성과 최신성을 개선하고 더 정확한 답변을 제공하기 위한 그라운딩
- 웹에서 아티팩트를 가져와 추가 분석
- 다중 모달 추론 또는 생성 작업을 지원하는 관련 이미지, 동영상 또는 기타 미디어 찾기
- 코딩, 기술 문제 해결, 기타 전문 작업
- 지역별 정보를 찾거나 콘텐츠를 정확하게 번역하는 데 지원
- 추가 탐색을 위한 관련 웹사이트 찾기
Google 검색을 사용한 그라운딩은 텍스트 프롬프트를 사용할 때 모든 사용 가능한 언어로 작동합니다. Gemini Developer API의 유료 등급에서는 하루에 1,500회의 Google 검색을 사용한 그라운딩 쿼리를 무료로 사용할 수 있으며, 추가 쿼리는 쿼리 1,000개당 표준 $35(USD)의 요금이 청구됩니다.
검색 도구 메모장을 사용해 자세히 알아보세요.
Google 추천 검색어
Google 검색으로 그라운딩을 사용하려면 그라운딩된 응답의 메타데이터에 포함된 추천 검색어인 Google 추천 검색어를 표시해야 합니다. 디스플레이 요구사항에 관한 자세한 내용은 Google 추천 검색어 사용을 참고하세요.
Google 검색 검색
동적 검색
일부 검색어는 다른 검색어보다 Google 검색으로 그라운딩하는 것에서 더 많은 이점을 얻을 수 있습니다. 동적 검색 기능을 사용하면 Google 검색으로 그라운딩을 사용할 시기를 추가로 제어할 수 있습니다.
동적 검색 모드가 지정되지 않으면 Google 검색으로 그라운딩이 항상 트리거됩니다. 모드가 동적으로 설정된 경우 모델은 구성할 수 있는 임곗값을 기반으로 접지 사용 시점을 결정합니다. 기준점은 [0,1] 범위의 부동 소수점 값이며 기본값은 0.3입니다. 기준점 값이 0이면 응답이 항상 Google 검색에서 그라운딩됩니다. 1이면 그라운딩되지 않습니다.
동적 검색의 작동 방식
요청에서 동적 검색을 사용하여 Google 검색 시 그라운딩을 사용 설정할 경우를 선택할 수 있습니다. 이 기능은 Google 검색으로 그라운딩된 답변이 프롬프트에 필요하지 않고 모델이 그라운딩 없이도 자체 지식을 기반으로 답변을 제공할 수 있는 경우에 유용합니다. 이렇게 하면 지연 시간, 품질, 비용을 더 효과적으로 관리할 수 있습니다.
요청에서 동적 검색 구성을 호출하기 전에 다음 용어를 이해하세요.
예측 점수: 근거 있는 답변을 요청하면 Gemini가 프롬프트에 예측 점수를 할당합니다. 예측 점수는 [0,1] 범위의 부동 소수점 값입니다. 값은 프롬프트가 Google 검색의 최신 정보로 답변을 그라운딩함으로써 이득을 얻을 수 있는지 여부에 따라 달라집니다. 따라서 웹의 최신 사실 데이터로 그라운딩된 답변이 필요한 프롬프트는 예측 점수가 더 높습니다. 모델에서 생성된 답변으로 충분한 프롬프트는 예측 점수가 더 낮습니다.
다음은 몇 가지 프롬프트와 해당 예측 점수에 대한 예시입니다.
프롬프트 예측 점수 의견 "피오니에 대한 시를 만들어주세요" 0.13 모델이 기본 지식에 의존할 수 있고 답변에 그라운딩이 필요하지 않습니다. "2세 아이를 위한 장난감을 추천해주세요" 0.36 모델이 기본 지식에 의존할 수 있고 답변에 그라운딩이 필요하지 않습니다. "아시아식 과카몰리 레시피를 알려줄 수 있을까요?" 0.55 Google 검색은 그라운딩된 답변을 제공할 수 있지만 그라운딩이 엄격하게 필요하지는 않습니다. 모델 지식으로 충분할 수 있습니다. "Agent Builder란 무엇인가요? Agent Builder에서 그라운딩 비용은 어떻게 청구되나요?" 0.72 Google 검색으로 잘 그라운딩된 답변을 생성해야 합니다. "최근 F1 그랑프리 우승자는 누구인가요?" 0.97 Google 검색으로 잘 그라운딩된 답변을 생성해야 합니다. 기준점: API 요청에서 기준점과 함께 동적 검색 구성을 지정할 수 있습니다. 기준점은 [0,1] 범위의 부동 소수점 값이며 기본값은 0.3입니다. 기준점 값이 0이면 응답이 항상 Google 검색에서 그라운딩됩니다. 다른 모든 기준점 값에는 다음이 적용됩니다.
- 예측 점수가 기준점보다 크거나 같으면 답변이 Google 검색에서 그라운딩됩니다. 기준점이 낮으면 Google 검색의 그라운딩을 사용하여 생성된 답변이 포함되는 프롬프트가 증가합니다.
- 예측 점수가 기준점보다 낮으면 모델이 여전히 답변을 생성할 수 있지만 Google 검색으로 그라운딩되지 않습니다.
SDK 또는 REST API를 사용하여 동적 검색 기준점을 설정하는 방법을 알아보려면 적절한 코드 예를 참고하세요.
비즈니스 요구에 적합한 올바른 기준점을 찾으려면 발생할 것으로 예상되는 쿼리 대표 집합을 만들 수 있습니다. 그런 다음 응답의 예측 점수에 따라 쿼리를 정렬하고 사용 사례에 적합한 기준점을 선택할 수 있습니다.
그라운딩된 응답
프롬프트가 Google 검색에 성공적으로 그라운딩되면 응답에 groundingMetadata가 포함됩니다. 근거 있는 응답은 다음과 같이 표시될 수 있습니다(간결성을 위해 응답의 일부가 생략됨).
{
"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"
]
}
}
],
...
}
응답에 groundingMetadata가 포함되지 않으면 응답이 제대로 접지되지 않은 것입니다. 이러한 일이 발생하는 데는 소스 관련성이 낮거나 모델 응답 내의 정보가 불완전한 경우를 비롯한 몇 가지 이유가 있습니다.
그라운딩된 결과가 생성되면 그라운딩된 결과를 생성하는 데 사용된 콘텐츠의 게시자로 리디렉션되는 URI가 메타데이터에 포함됩니다.
이러한 URI에는 vertexaisearch 하위 도메인이 포함됩니다(예: https://vertexaisearch.cloud.google.com/grounding-api-redirect/...). 메타데이터에는 게시자 도메인도 포함됩니다. 제공된 URI는 그라운딩된 결과가 생성된 후 30일 동안 액세스 가능한 상태로 유지됩니다.
searchEntryPoint 내의 renderedContent 필드는 Google 검색 추천을 구현하기 위해 제공된 코드입니다. 자세한 내용은 Google 추천 검색어 사용을 참고하세요.