Gemini API 가이드: File Search 저장소와 RAG 경계

InYourLeague 리서치 · 2026-08-28

Answer in brief

Gemini API File Search는 파일을 가져와 청크로 나누고 색인한 뒤, 관련 정보를 검색하여 Gemini 모델의 문맥으로 제공하는 RAG 도구입니다. 공식 출처는 이 제품에 대해 선택 가능한 모델 ID를 공개하지 않습니다.

Key facts at a glance

Failure modes and verification

FAQ

File Search에 선택 가능한 모델 ID가 있습니까?

공식 출처에는 선택 가능한 File Search 제품 모델 ID가 게시되어 있지 않습니다. gemini-3.7-flash는 예제의 생성 모델이고, models/gemini-embedding-2는 임베딩 구성값입니다.

Gemini API가 RAG용 파일을 수집할 때 어떤 처리를 합니까?

File Search는 데이터를 가져오고, 청크로 나누고, 검색용 색인을 만듭니다. 업로드는 비동기 작업이므로 공식 예제는 operation.done이 참이 될 때까지 반환된 작업의 상태를 조회합니다.

의미 기반 검색은 최종 답변에 어떻게 반영됩니까?

File Search는 프롬프트와 관련된 정보를 검색하여 Gemini 모델의 문맥으로 전달합니다. 공식 문서는 구체적인 순위 결정 알고리즘이나 유사도 점수를 명시하지 않습니다.

어떤 콘텐츠 유형이 공식적으로 설명되어 있습니까?

공식 출처는 텍스트 임베딩에 gemini-embedding-001, 이미지 및 멀티모달 임베딩에 gemini-embedding-2를 명시합니다. 오디오와 비디오 형식은 현재 지원되지 않습니다.

어떤 수명주기와 도구 호환성을 신뢰할 수 있습니까?

공식 예제에서 확인되는 범위는 저장소 생성, 비동기 업로드, Interactions API를 통한 검색, file_citation 처리입니다. 모든 모델이나 도구와의 호환성은 보장되지 않으며, 제공된 출처는 만료, 보존, 삭제 또는 정리 동작을 명시하지 않습니다.

Sources and freshness

• Official source
• Last verified: 2026-08-28

Extended guide

직답하면, File Search는 Gemini API에서 RAG를 구현하는 도구입니다. Gemini API는 업로드된 데이터를 가져오고, 검색 가능한 청크로 나누고, 색인을 만든 뒤, 프롬프트와 관련된 정보를 검색하여 Gemini 모델의 문맥으로 제공합니다. 공식 출처는 이 제품에 대해 선택 가능한 모델 ID를 공개하지 않습니다. 예제에 나오는 생성 모델과 임베딩 모델은 각각 별도로 설정되는 구성 요소이며, 독립적인 File Search 제품 모델 ID가 아닙니다.

확인된 범위

이 문서는 2026-08-28을 기준으로 확인했습니다. 공식 문서는 색인된 데이터와 임베딩을 바탕으로 주어진 프롬프트에 관련된 정보를 빠르게 검색한다고 설명합니다. 따라서 기능적 의미에서는 이 과정을 의미 기반 검색으로 설명할 수 있습니다. 다만 공식 출처는 구체적인 순위 결정 알고리즘, 유사도 점수, 검색 품질 지표, 점수 임계값 또는 사용자가 조절할 수 있는 순위 제어 기능을 명시하지 않습니다. 문서에 없는 세부 동작을 제품 보장 사항으로 추정해서는 안 됩니다.

저장소 생성부터 검색까지의 수명주기

1. File Search 저장소를 생성합니다. file_search_stores.create를 호출하고 display_name을 지정합니다. 공식 예제는 저장소 생성 설정에서 embedding_model을 models/gemini-embedding-2로 지정합니다. 이 값은 저장소의 임베딩 구성에 사용되며, File Search 자체의 선택 가능한 모델 ID를 뜻하지 않습니다.
2. 대상 파일을 저장소에 업로드합니다. upload_to_file_search_store에 로컬 파일, 생성된 저장소의 이름, 그리고 파일에 사용할 선택적 표시 이름을 전달합니다. 검색 요청에서 저장소를 다시 지정해야 하므로, 생성 결과로 받은 저장소 이름을 애플리케이션이 보관해야 합니다.
3. 수집 작업이 끝날 때까지 기다립니다. 업로드 호출은 즉시 완성된 색인을 반환하지 않고 작업 객체를 반환합니다. 공식 예제는 operations.get으로 작업 상태를 다시 조회하며, operation.done이 참이 될 때까지 기다립니다. 새로 업로드한 자료를 검색하기 전에 이 비동기 수집 단계가 완료되었는지 확인해야 합니다.
4. File Search 도구로 검색을 실행합니다. 상호작용을 생성할 때 도구 유형으로 file_search를 지정하고, 검색할 저장소를 file_search_store_names에 전달합니다. 공식 예제는 상호작용을 실행하는 생성 모델로 gemini-3.7-flash를 사용합니다. 이 예제 값은 File Search 제품 모델 ID가 아니라, 검색 문맥을 받아 답변을 생성하는 모델 필드의 값입니다.
5. 답변과 근거 주석을 읽습니다. 모델 출력 단계의 텍스트를 처리하고, 함께 제공된 file_citation 주석이 있으면 파일 이름과 출처를 확인합니다. 검색된 정보는 생성 모델의 문맥으로 사용됩니다. 따라서 File Search는 검색과 근거 제공을 담당하며, 최종 답변을 만드는 생성 모델을 대체하지 않습니다.

RAG 경계와 도구 호환성

제공된 공식 근거는 Interactions API에서 File Search를 사용하는 흐름을 보여주며, Python, JavaScript, Java용 SDK 예제를 포함합니다. 그러나 이 근거만으로 모든 Gemini 모델, 모든 Gemini API 도구, 함수 호출 또는 임의의 도구 조합과 호환된다고 결론 내릴 수는 없습니다. 공식 발췌문은 저장소 만료 시점, 보존 기간, 삭제 동작, 정리 API, 사용자 정의 청크 분할 설정, 색인 내보내기, 검색 점수 열람 기능도 명시하지 않습니다. 이런 수명주기와 제어 기능은 별도의 공식 근거 없이 지원된다고 가정해서는 안 됩니다.

비용의 경계는 명시되어 있습니다. 파일 저장과 쿼리 시점의 임베딩 생성은 무료이며, 파일을 처음 색인할 때 생성되는 임베딩에는 비용이 부과됩니다. 또한 Gemini 생성 모델의 일반적인 입력 토큰과 출력 토큰 비용도 적용됩니다. 이 설명은 저장소 사용 전체가 무조건 무료라는 뜻이 아닙니다.

구현 점검표

• 저장소를 생성하고 반환된 저장소 이름을 보관합니다.
• 콘텐츠 유형에 대해 공식 문서가 명시한 임베딩 모델만 선택합니다.
• 업로드 후 수집 작업이 완료될 때까지 상태를 확인합니다.
• 검색 요청의 file_search_store_names에 대상 저장소를 명시합니다.
• 오디오와 비디오 형식을 지원 대상으로 처리하지 않습니다.
• 출처 추적이 필요하면 file_citation 주석을 보존하고 표시합니다.
• File Search, 임베딩 모델, 생성 모델의 식별자를 서로 구분합니다.
• 배포 전에 File Search 공식 문서를 다시 확인합니다.

모델 제공 범위 안내: 공식 출처는 선택 가능한 모델 ID를 지정하지 않습니다.