Gemini API 가이드: URL 컨텍스트와 검색 그라운딩

InYourLeague 리서치 · 2026-09-05

핵심 답변

Gemini API는 웹 콘텐츠를 활용하여 모델 상호작용을 강화할 수 있도록 URL 컨텍스트 및 Google 검색 그라운딩 도구를 제공합니다. 개발자는 특정 URL을 전달하여 심층 분석을 수행하거나 웹 검색을 통해 검증 가능한 실시간 출처를 인용하도록 구성할 수 있습니다. 이 항목에서는 제품 고유의 선택 가능한 모델 ID가 검증되지 않았습니다.

핵심 정보 한눈에 보기

오류 유형과 검증

자주 묻는 질문

URL 컨텍스트 도구는 웹 페이지 콘텐츠를 어떻게 가져오나요?

URL 컨텍스트 도구는 먼저 최적화된 내부 인덱스 캐시에서 콘텐츠 조회를 시도하고, 페이지가 캐시에 없으면 실시간 라이브 수집으로 전환하는 2단계 방식을 사용합니다.

이 기능에 사용할 수 있는 공식 검증 모델 목록은 무엇인가요?

이 항목에서는 제품 고유의 선택 가능한 모델 ID가 검증되지 않았습니다. 문서 예제에 등장하는 gemini-3.6-flash 및 gemini-3.8-flash는 예시 설정일 뿐 고정 요구사항이 아닙니다.

검색된 원본 출처와 인용 정보는 응답에서 어떻게 확인하나요?

응답 텍스트 블록의 url_citation 주석에서 start_index, end_index, title, url 필드를 확인하여 특정 텍스트 구간과 원본 링크를 매핑할 수 있습니다.

URL 컨텍스트와 Google 검색 그라운딩을 함께 사용할 수 있나요?

예, tools 배열에 url_context와 google_search를 동시에 선언하여 광범위한 실시간 검색과 특정 URL에 대한 정밀 분석을 결합할 수 있습니다.

관련 공식 문서는 어디에서 확인할 수 있나요?

공식 문서는 https://ai.google.dev/gemini-api/docs/url-context 및 https://ai.google.dev/gemini-api/docs/google-search 에서 제공됩니다.

출처와 확인 날짜

• 공식 출처
• 공식 출처
• 최종 확인일: 2026-09-05

상세 가이드

Gemini API는 상호작용(Interactions) 환경에서 웹 콘텐츠를 활용할 수 있도록 URL 컨텍스트(URL context)와 Google 검색 그라운딩(Google Search grounding) 도구를 제공합니다. URL 컨텍스트는 호출자가 제공한 특정 웹 문서의 내용을 수집하여 분석하며, Google 검색 그라운딩은 실시간 웹 검색을 동적으로 수행하여 응답에 검증 가능한 출처를 연결합니다.

핵심 그라운딩 기능 및 동작 원리

Gemini API의 두 가지 도구는 상이한 데이터 검색 및 처리 구조를 가지고 있습니다:

1. URL 컨텍스트: 요청에 포함된 URL의 내용을 모델이 참조하여 정보 추출, 문서 비교, 콘텐츠 요약, 기술 문서 분석을 수행합니다. 2단계 검색 구조를 채택하여 먼저 내부 인덱스 캐시에서 콘텐츠를 탐색하고, 페이지가 인덱스에 없으면 실시간 라이브 수집으로 자동 전환됩니다. 수집된 웹 페이지 데이터는 토큰 사용량에 포함되며, 안전 모니터링 검사에서 제외 기준에 걸릴 경우 결과 메타데이터에 안전하지 않음(unsafe) 상태가 기록됩니다.
2. Google 검색 그라운딩: google_search 도구를 활성화하면 모델이 프롬프트를 분석하여 필요한 경우 자체적으로 검색어를 생성하고 실행합니다. 수집된 검색 결과를 종합하여 인라인 출처 표기가 포함된 응답을 반환하며, 실행된 검색 쿼리(google_search_call)와 검색 추천 위젯 마크업(google_search_result) 단계가 함께 제공됩니다.
3. 도구 결합: 애플리케이션은 url_context와 google_search 도구를 동시에 활성화할 수 있습니다. 이를 통해 웹 전반의 광범위한 검색과 지정된 URL의 정밀한 세부 분석을 하나의 상호작용에서 결합할 수 있습니다.

지원 모델 확인 및 검증 범위

이 항목에서는 제품 고유의 선택 가능한 모델 ID가 검증되지 않았습니다. 공식 문서 예제 코드에서 URL 컨텍스트의 경우 gemini-3.6-flash, 검색 그라운딩의 경우 gemini-3.8-flash와 같은 식별자가 등장하지만, 이는 설명 목적의 예시 설정일 뿐 고정된 기본값이나 전체 지원 모델 목록을 의미하지 않습니다.

단계별 연동 절차

URL 컨텍스트 및 검색 그라운딩을 적용하는 단계는 다음과 같습니다:

1. 공식 GenAI SDK 클라이언트(google.genai 모듈의 Client)를 초기화합니다.
2. 상호작용 생성 요청 시 {"type": "url_context"} 또는 {"type": "google_search"} 도구를 파라미터에 선언합니다.
3. 대상 프롬프트와 분석할 URL을 입력값으로 전달하여 API 호출을 실행합니다.
4. 반환된 상호작용 단계(steps)를 순회하며 model_output 유형의 텍스트 응답을 추출합니다.
5. 텍스트 블록에 포함된 url_citation 주석의 start_index, end_index, title, url 메타데이터를 확인하여 원본 출처 인용을 UI에 표시합니다.

도구 비교 요약표

개발 체크리스트

• 공식 문서 확인: URL 컨텍스트 가이드 및 Google 검색 가이드.
• 요청 파라미터의 tools 배열에 필요한 도구 식별자 선언 완료.
• url_citation의 start_index 및 end_index 속성을 활용한 UI 출처 링크 구성.
• URL 수집 실패 및 콘텐츠 안전 검사 결과 상태에 대한 예외 처리 반영.
• 이 항목에서는 제품 고유의 선택 가능한 모델 ID가 검증되지 않았음을 아키텍처 구성 시 고려.