Gemini Search Grounding
Google Search Grounding으로 답변 부분과 웹페이지 출처를 연결합니다.
Gemini Search Grounding은 해당 기능을 지원하는 Gemini 모델이 Google Search로 최신 정보를 얻고 groundingMetadata로 답변 부분과 웹페이지 출처를 연결하도록 합니다.
Grounding은 단순히 “검색을 활성화하는 것”이 아닙니다. 클라이언트 프로그램은 쿼리, 출처 및 텍스트 부분의 연결 관계도 읽어야 화면에 검증 가능한 인용을 표시할 수 있습니다.
프로토콜 지원이 모델 지원을 의미하지는 않습니다
Generate Content는 Google Search 도구를 표현할 수 있지만 실제 사용 범위는 현재 모델과 계정에 따라 다릅니다. 먼저 모델 목록에서 모델을 확인하고 Gemini Generate Content Reference를 기준으로 합니다.
Grounding 요청 보내기
Gemini 네이티브 경로는 사이트 Origin에 /v1beta를 붙입니다. 이미 /v1이 있는 Base URL 뒤에 /v1beta를 다시 붙여서는 안 됩니다:
curl --request POST \
'https://api.agtcloud.cn/v1beta/models/MODEL_ID:generateContent' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer your-api-key' \
--data '{
"contents": [
{
"role": "user",
"parts": [
{
"text": "오늘 주목할 만한 인공지능 뉴스는 무엇인가요? 출처를 제시해 주세요."
}
]
}
],
"tools": [
{
"google_search": {}
}
]
}'모델은 검색 필요 여부를 판단하며 하나 이상의 검색 쿼리를 생성할 수 있습니다. 도구를 활성화할 때마다 Grounding Metadata가 생성된다고 가정해서는 안 됩니다.
Grounding 처리 흐름
1. 질문과 검색 도구 제출
사용자 질문을 contents[].parts에 넣고 tools에서 Google Search를 활성화합니다.
2. 답변 텍스트 읽기
후보의 content.parts에서 모델 텍스트를 읽으며 항상 후보나 Part가 하나뿐이라고 가정하지 않습니다.
3. Grounding Metadata 읽기
검색 쿼리, 웹페이지 출처 및 답변 부분과 출처 인덱스의 연결 관계를 저장합니다.
4. 클릭 가능한 인용 표시
텍스트 부분의 끝 위치에 인용 표시를 삽입하거나 답변 옆에 출처 카드를 표시하여 사용자가 원본 페이지를 확인할 수 있도록 합니다.
groundingMetadata 이해
{
"candidates": [
{
"content": {
"role": "model",
"parts": [
{"text": "최근 보도 내용을 보면, 관련 진전으로는…"}
]
},
"groundingMetadata": {
"webSearchQueries": [
"인공지능 뉴스 오늘"
],
"groundingChunks": [
{
"web": {
"uri": "https://example.com/article",
"title": "출처 제목"
}
}
],
"groundingSupports": [
{
"segment": {
"startIndex": 0,
"endIndex": 12,
"text": "최근 보도 내용을 보면"
},
"groundingChunkIndices": [0]
}
]
}
}
]
}| 필드 | 클라이언트 용도 |
|---|---|
webSearchQueries | 모델이 실제로 사용한 검색 쿼리를 기록하여 문제 해결과 검색 범위 설명에 활용합니다 |
groundingChunks | 웹페이지 URI, 제목 등 출처 정보를 저장합니다 |
groundingSupports | 답변 텍스트 부분을 하나 이상의 출처 인덱스에 연결합니다 |
응답에 일부 필드가 없을 수 있으므로 선택적 접근과 빈 배열 기본값을 사용해야 합니다.
텍스트에 인용 삽입
인용을 삽입할 때는 앞선 삽입으로 이후 위치가 바뀌지 않도록 segment.endIndex가 큰 것부터 처리합니다:
function addCitations(text, supports = [], chunks = []) {
const sorted = [...supports].sort(
(a, b) => (b.segment?.endIndex ?? 0) - (a.segment?.endIndex ?? 0),
);
for (const support of sorted) {
const endIndex = support.segment?.endIndex;
if (endIndex == null) continue;
const links = (support.groundingChunkIndices ?? [])
.map((index) => {
const source = chunks[index]?.web;
return source?.uri ? `[${index + 1}](${source.uri})` : null;
})
.filter(Boolean);
if (links.length > 0) {
text = `${text.slice(0, endIndex)}${links.join('')}${text.slice(endIndex)}`;
}
}
return text;
}브라우저에서 모델 콘텐츠를 렌더링할 때는 안전한 Markdown 또는 HTML 처리 방식을 사용하고 외부 링크에 새 탭 보안 속성을 추가해야 합니다.
실패 및 대체 처리
| 현상 | 처리 방법 |
|---|---|
groundingMetadata 없음 | 답변을 정상 표시하고 표시할 Grounding 출처가 없음을 명시합니다 |
| 출처 인덱스가 범위를 벗어남 | 유효하지 않은 연결은 무시하고 마스킹된 응답을 기록하며 잘못된 링크를 삽입하지 않습니다 |
| 텍스트 위치가 일치하지 않음 | 잘못된 위치에 인용하지 않고 답변 끝의 출처 목록으로 대체합니다 |
| 검색 실패 | 응답 오류에 따라 제한적으로 재시도하거나 검색 없는 답변으로 전환합니다 |
| 출처 내용이 상충함 | 여러 출처와 날짜를 표시하여 사용자가 판단하도록 하며 중요한 차이를 숨기지 않습니다 |
운영 전 확인 사항
- 현재 모델이 Google Search Grounding을 지원합니다.
- Gemini Endpoint는 사이트 Origin을 사용하며
/v1/v1beta가 발생하지 않습니다. - 답변 텍스트, 쿼리, 출처 및 텍스트 부분의 연결 관계를 각각 저장합니다.
- 인용 인덱스가 유효하지 않아도 페이지에 오류가 발생하지 않습니다.
- 외부 웹페이지 내용을 신뢰할 수 있는 업무 지시로 직접 취급하지 않습니다.
- 출처가 없을 때 가짜 Citation을 생성하지 않습니다.
애플리케이션이 Gemini 네이티브 구조가 아닌 Chat을 사용한다면 대상 모델이 명시적으로 지원하는 Chat 검색 필드를 사용하며 groundingMetadata 파서를 그대로 복사하지 않습니다.