Google Search Grounding: Gemini가 실시간 웹 정보 검색

학습 후 수행 가능한 작업

• Gemini 모델에 Google Search를 활성화하여 AI가 실시간 웹 정보를 검색할 수 있도록 설정
• 검색 임계값을 조정하여 모델의 검색 빈도 제어
• Google Search Grounding의 작동 원리와 적용 사례 이해
• 작업 요구사항에 맞는 적절한 구성 선택

현재의 난관

Google Search Grounding이란?

Google Search Grounding은 Gemini의 기능으로, 모델이 필요할 때 자동으로 Google을 검색하여 실시간 정보(뉴스, 통계, 제품 가격 등)를 가져올 수 있게 합니다. 훈련 데이터에만 의존하는 것이 아닙니다.

Gemini에게 "오늘 날씨 어때?" 또는 "최신 VS Code 버전은?"이라고 물어보면 모델이 대답하지 못할 수 있습니다. 훈련 데이터가 오래되었기 때문입니다. Google Search Grounding을 활성화하면 모델이 브라우저를 사용하는 것처럼 직접 인터넷에서 답을 찾을 수 있습니다.

이 기능을 사용해야 하는 경우

시나리오	활성화 필요 여부	이유
코드 생성, 프로그래밍 질문	❌ 필요 없음	프로그래밍 지식은 상대적으로 안정적이며 훈련 데이터가 충분함
최신 정보 가져오기 (뉴스, 가격, 버전)	✅ 강력 추천	실시간 데이터 필요
사실 확인 (구체적인 날짜, 통계)	✅ 추천	모델의 잘못된 정보 생성 방지
창의적 글쓰기, 브레인스토밍	❌ 필요 없음	사실 정확성 불필요
기술 문서 조회	✅ 추천	최신 API 문서 검색

핵심 개념

Google Search Grounding의 핵심은 모델이 필요할 때 자동으로 검색하는 것이며, 매번 검색하는 것이 아닙니다. 플러그인은 googleSearchRetrieval 도구를 주입하여 Gemini가 Google 검색 API를 호출할 수 있게 합니다.

핵심 개념

• Auto 모드: 모델이 임계값을 기준으로 검색 여부를 스스로 결정
• 임계값 (grounding_threshold): 모델의 검색 "문턱"을 제어. 값이 작을수록 검색이 더 자주 발생

🎒 시작 전 준비

전제 조건 확인

시작하기 전에 다음 사항을 확인하세요:

• [ ] 빠른 설치 완료
• [ ] 최소 하나의 Google 계정 추가
• [ ] 첫 번째 요청 성공 (첫 번째 요청 참조)

따라 해보기

1단계: 구성 파일 위치 확인

플러그인의 구성 파일 위치:

• macOS/Linux: ~/.config/opencode/antigravity.json
• Windows: %APPDATA%\opencode\antigravity.json

파일이 없는 경우 먼저 생성:

# macOS/Linux
cat > ~/.config/opencode/antigravity.json << 'EOF'
{
  "$schema": "https://raw.githubusercontent.com/NoeFabris/opencode-antigravity-auth/main/assets/antigravity.schema.json"
}
EOF

# Windows
@"
{
  "\$schema": "https://raw.githubusercontent.com/NoeFabris/opencode-antigravity-auth/main/assets/antigravity.schema.json"
}
"@ | Out-File -FilePath "$env:APPDATA\opencode\antigravity.json" -Encoding utf8

확인해야 할 사항: 구성 파일이 생성되어 $schema 필드 포함

2단계: Google Search 활성화

구성 파일에 web_search 구성 추가:

{
  "$schema": "https://raw.githubusercontent.com/NoeFabris/opencode-antigravity-auth/main/assets/antigravity.schema.json",
  "web_search": {
    "default_mode": "auto",
    "grounding_threshold": 0.3
  }
}

구성 설명:

필드	값	설명
web_search.default_mode	"auto" 또는 "off"	Google Search 활성화 또는 비활성화, 기본값 "off"
web_search.grounding_threshold	0.0 - 1.0	검색 임계값, 기본값 0.3, auto 모드에서만 적용

확인해야 할 사항: 구성 파일에 web_search 구성 포함

3단계: 검색 임계값 조정 (선택)

grounding_threshold는 모델의 검색 빈도를 제어:

임계값	동작	적용 시나리오
0.0 - 0.2	빈번한 검색, 거의 모든 불확실한 경우 검색	높은 정확도의 실시간 데이터 필요
0.3 (기본)	적절한 균형, 모델이 비교적 확신할 때만 검색	일상 사용, 정확성과 속도 균형
0.7 - 1.0	드문 검색, 높은 신뢰도에서만 검색	검색 횟수 줄이고 속도 향상

경험담

기본값 0.3에서 시작하여 다음과 같은 경우:

• 모델이 검색하지 않음 → 임계값 낮추기 (예: 0.2)
• 검색이 너무 잦고 응답이 느림 → 임계값 높이기 (예: 0.5)

확인해야 할 사항: 임계값이 조정되었으며 실제 사용 경험에 따라 최적화 가능

4단계: 구성 검증

OpenCode를 다시 시작하거나 구성을 다시 로드한 후(지원되는 경우) 실시간 정보가 필요한 요청을 보냅니다:

사용자 입력:
VS Code 최신 버전은?

시스템 응답 (Google Search 활성화):
VS Code의 최신 안정 버전은 1.96.4입니다 (2026년 1월 기준)...

[citation:1] ← 출처 인용 표시

확인해야 할 사항:

• 모델 응답에 출처 인용 포함 ([citation:1] 등)
• 응답 내용이 최신이며 훈련 데이터의 오래된 버전이 아님

5단계: 다양한 임계값 테스트

grounding_threshold를 조정하여 모델 동작 변화를 관찰:

// 낮은 임계값 (빈번한 검색)
"grounding_threshold": 0.1

// 높은 임계값 (드문 검색)
"grounding_threshold": 0.7

각 조정 후 동일한 문제로 테스트하여 다음을 관찰:

• 검색 여부 (응답에 인용 있는지 확인)
• 검색 횟수 (여러 citation)
• 응답 속도

확인해야 할 사항:

• 낮은 임계값: 더 자주 검색하지만 응답이 약간 느림
• 높은 임계값: 검색이 줄어들지만 정확하지 않을 수 있음

확인 포인트 ✅

확인 목록 펼쳐보기

구성이 올바른지 확인하려면 다음 검사를 완료하세요:

• [ ] 구성 파일에 web_search 구성 포함
• [ ] default_mode가 "auto"로 설정
• [ ] grounding_threshold가 0.0에서 1.0 사이
• [ ] 실시간 정보가 필요한 요청을 보내고 모델이 인용을 포함하여 응답
• [ ] 임계값을 조정한 후 모델의 검색 동작이 변경

모두 통과하면 Google Search Grounding이 올바르게 활성화된 것입니다!

문제 해결

문제 1: 모델이 검색하지 않음

증상: auto 모드를 활성화한 후에도 모델이 여전히 검색하지 않고 인용 출처도 없음.

원인:

• 임계값이 너무 높음 (예: 0.9), 모델이 매우 높은 확신이 있어야만 검색
• 문제 자체가 검색을 필요로 하지 않음 (예: 프로그래밍 문제)

해결 방법:

• grounding_threshold를 0.2 또는 더 낮게 조정
• 실시간 정보가 명확히 필요한 문제로 테스트 (예: "오늘 날씨는?", "최신 뉴스")

문제 2: 검색이 너무 잦고 응답이 느림

증상: 모든 문제에 검색하며 응답 시간이 눈에 띄게 증가.

원인:

• 임계값이 너무 낮음 (예: 0.1), 모델이 너무 자주 검색 트리거
• 문제 유형 자체가 실시간 정보가 필요 (예: 주가, 뉴스)

해결 방법:

• grounding_threshold를 0.5 또는 더 높게 조정
• 실시간 정보가 필요 없는 경우 default_mode를 "off"로 변경

문제 3: 구성 파일 형식 오류

증상: 플러그인 오류가 발생하며 구성을 로드할 수 없음.

원인: JSON 형식 오류 (예: 추가 쉼표, 따옴표 불일치).

해결 방법: JSON 유효성 검사 도구를 사용하여 구성 파일을 확인하고 형식이 올바른지 확인.

# JSON 형식 확인
cat ~/.config/opencode/antigravity.json | python3 -m json.tool

수업 요약

• Google Search Grounding을 통해 Gemini 모델이 실시간 웹 정보를 검색할 수 있음
• web_search.default_mode: "auto"로 활성화, "off"로 비활성화
• grounding_threshold가 검색 빈도를 제어: 값이 작을수록 검색이 더 자주 발생
• 기본 임계값 0.3이 대부분의 시나리오에 적합하며 실제 사용 경험에 따라 조정 가능
• 모델은 응답에서 출처를 인용하며 [citation:1] 등으로 표시

다음 수업 예고

다음 수업에서는 **듀얼 쿼타 시스템**을 학습합니다.

배울 내용:

• Antigravity와 Gemini CLI 두 개의 독립된 쿼타 풀이 어떻게 작동하는지
• 쿼타 풀 간 전환하여 활용률 극대화하는 방법
• 쿼타 풀링 모범 사례

---

부록: 소스 코드 참조

소스 코드 위치 보기

업데이트 시간: 2026-01-23

기능	파일 경로	라인
Google Search 구성 스키마	src/plugin/config/schema.ts	303-319
Google Search 타입 정의	src/plugin/transform/types.ts	85-88
Google Search 주입 로직	src/plugin/transform/gemini.ts	402-419
Google Search 구성 로드	src/plugin/config/loader.ts	173-184
Google Search 구성 적용	src/plugin.ts	1194-1196

주요 구성 항목:

• web_search.default_mode: "auto" 또는 "off", 기본값 "off"
• web_search.grounding_threshold: 0.0 - 1.0, 기본값 0.3

주요 함수:

• applyGeminiTransforms(): 모든 Gemini 변환을 적용하며 Google Search 주입 포함
• normalizeGeminiTools(): 도구 형식을 정규화하며 googleSearchRetrieval 도구 보존
• wrapToolsAsFunctionDeclarations(): 도구를 functionDeclarations 형식으로 포장

작동 원리:

1. 플러그인이 구성 파일에서 web_search.default_mode와 web_search.grounding_threshold를 읽음
2. mode === "auto"일 때, 요청의 tools 배열에 googleSearchRetrieval 도구 주입:

   {
     "googleSearchRetrieval": {
       "dynamicRetrievalConfig": {
         "mode": "MODE_DYNAMIC",
         "dynamicThreshold": 0.3  // grounding_threshold
       }
     }
   }

3. Gemini 모델이 임계값을 기준으로 검색 도구 호출 여부 결정
4. 검색 결과는 응답에 포함되며 출처 인용 표시 ([citation:1] 등)