Gemini API File Search, 문서 검색 파이프라인을 도구로 붙이는 방법 | DAKER 커뮤니티

문서 기반 답변을 붙이려 하면 보통 벡터 저장소, 청킹, 재순위, 전처리까지 한 번에 설계하게 됩니다. 프로토타입 단계부터 선택지가 너무 많아지는 이유입니다. 이번에 정리한 Gemini API File Search는 그중 검색 단계를 도구로 넘겨, 앱이 핵심 로직에 더 집중할 수 있게 합니다.

이 글은 Google for Developers 채널의 Google I/O 2026 세션 Create advanced data driven Gemini API apps와 공식 File Search 문서를 함께 읽으며 정리한 실험 메모입니다. 발표자는 Google DeepMind developer experience의 Mark McDonald 님입니다. 영상 길이는 약 14분(814초)이며, 업로드 날짜는 2026년 5월 21일입니다.

파일 검색을 도구로 붙입니다 썸네일

왜 지금 File Search를 볼 만한가

전통적인 RAG는 저장소 선택부터 호스팅, 청크 크기, 오버랩, PDF 표 처리, 질의 확장, 재순위까지 직접 결정해야 합니다. 영상은 이런 선택이 프로토타이핑을 늦춘다고 설명합니다. naive RAG, agentic RAG, self RAG, graph RAG, iterative RAG처럼 갈래도 많고, 실제 구현으로 들어가면 비정형 문서 전처리와 검색 품질 조정까지 이어집니다.

File Search는 이 복잡한 흐름 중 인덱싱과 검색의 많은 단계를 추상화한 관리형 RAG 도구로 소개됩니다. 영상과 문서 모두 같은 방향을 말합니다. Gemini 임베딩 모델을 사용하고, PDF 등에 자동 OCR을 적용해 텍스트 인덱스로 넣을 수 있다고 영상은 설명합니다. 공식 문서에서는 이를 의미 검색으로 설명합니다. 단순한 키워드 일치가 아니라 질의와 문서 조각을 임베딩으로 맞추는 방식입니다.

벡터 저장소와 검색 파이프라인을 처음부터 짓지 않고도 문서 근거 답변을 프로토타입할 수 있습니다.

구조는 두 단계입니다: 적재와 검색

영상과 문서는 File Search 흐름을 두 단계로 나눕니다. 먼저 File Search store를 만들고 문서를 올립니다. 업로드와 동시에 스토어에 넣는 경로가 있고, Files API로 먼저 올린 뒤 import하는 경로도 있습니다. 문서에 따르면 Files API의 원본 파일은 약 48시간 후 삭제되지만, 스토어에 들어간 임베딩 데이터는 직접 지울 때까지 남습니다.

스토어는 여러 개 만들 수 있고, 이름 범위는 전역입니다. 생성·목록·조회·삭제 API로 관리하며, 문서 단위로도 목록·조회·삭제가 가능합니다.

그다음 생성 호출에 file_search 도구와 스토어 이름을 붙입니다. 영상은 generate content 호출에 도구를 붙인다고 설명하고, 최신 문서 예시는 interactions 경로도 보여 줍니다. 앱이 한 번만 호출하더라도 모델이 도구를 여러 번 사용해 관련 조각을 모을 수 있습니다. 영상은 이를 에이전트형 검색이라고 부릅니다.

예를 들어 휴가 규정처럼 질문이 모호하면, 모델은 휴가 종류를 찾고, 필요한 양식을 찾고, 승인 절차를 찾는 식으로 검색을 이어 갈 수 있습니다. 핵심은 앱이 검색 루프를 직접 짜지 않아도 한 번의 호출 안에서 검색이 연쇄될 수 있다는 점입니다.

한 번의 앱 호출 안에서 검색이 연쇄될 수 있다는 점이 File Search의 핵심입니다.

청킹과 메타데이터는 어디까지 맡길 수 있나

영상은 PDF 전처리기와 청킹 전략을 직접 정의하지 않아도 된다고 말합니다. 스마트 기본값으로 대부분의 콘텐츠가 동작한다는 설명입니다. 필요하면 전처리를 직접 할 수도 있습니다.

공식 문서에는 chunking_config로 청크당 최대 토큰과 오버랩 토큰을 지정할 수 있다고 나옵니다. 또 커스텀 메타데이터를 붙이면 작성자·연도 같은 조건으로 검색 범위를 줄일 수 있습니다. 응답의 annotations에는 파일 인용, PDF 페이지, 이미지 조각 media_id가 포함될 수 있습니다. media_id를 이용하면 모델이 참조한 이미지 조각을 다시 받을 수 있습니다.

문서와 영상이 공통으로 말하는 점

사실관계를 먼저 정리하면 다음과 같습니다.

다만 블로그나 문서에 적힌 인덱싱 단가는 시점에 따라 달라질 수 있으므로, 이 글에서는 구체 단가를 단정하지 않습니다. 최신 가격표를 함께 보는 것이 좋습니다.

미리 구분해 둘 제한 사항

지원 범위를 먼저 분리해 두면 실험이 훨씬 깔끔해집니다.

한도와 미지원 조합을 먼저 표시해 두면 실험과 운영이 훨씬 단순해집니다.

데모에서 볼 만한 장면

영상은 스토어를 만들고 로컬 문서를 하나씩 올리는 코드를 보여 줍니다. 전처리기를 길게 정의하지 않고, 업로드가 끝나면 검색 UI를 붙입니다. Gutenberg 공개 도메인 책을 넣어 도서관 전체를 대화로 묻는 장면도 나옵니다. 운동 능력으로 유명한 등장인물을 찾아 달라는 질의 예시가 등장하지만, 이 글에서는 그 데모의 정답 목록이나 지연 수치를 만들지 않습니다.

중요한 것은 장면의 의미입니다. 스토어에 말뭉치를 넣고, 도구가 붙은 채팅으로 질의한다는 흐름입니다. 휴가 규정 예시는 모호한 질의에서 도구가 여러 번 도는 이유를 보여 줍니다. 다만 이것은 서버 세션 전체를 맡기는 Managed Agents와는 다른 층위의 이야기입니다. 여기서는 문서 검색 도구에 한정해 보는 편이 맞습니다.

File Search 적재와 도구 호출 설명 이미지

실험을 시작할 때 유용한 기준

작게 시작하는 편이 좋습니다

사내 FAQ, README, 정책 PDF 몇 개 정도로 File Search store를 하나 만들면 됩니다. 처음에는 스토어를 하나로 두고, 도메인이 갈릴 때 나누는 방식이 자연스럽습니다.

기본값부터 측정하는 편이 낫습니다

기본 청킹으로 올린 뒤 file_search 도구만 붙인 최소 질의를 시험해 보면 됩니다. 모호한 질문 하나, 구체 질문 하나, 메타데이터로 좁혀야 하는 질문 하나 정도면 비교가 가능합니다.

인용과 로그를 먼저 봐야 합니다

annotations에 인용이 오는지, PDF라면 페이지 번호가 붙는지, 이미지 문서를 넣었다면 media_id가 오는지를 확인해 두는 것이 좋습니다. 같은 질문을 문서를 직접 컨텍스트에 붙여 넣는 방식과 비교해 토큰, 지연, 답변 근거를 남기면 차이가 더 분명해집니다. 다만 숫자는 직접 측정한 값만 적는 편이 맞습니다.

설계 메모: 스토어를 어떻게 나눌까

스토어는 도메인 경계로 나누는 편이 안전합니다. 인사 규정과 제품 스펙을 한 스토어에 섞으면 모호한 질의에서 잘못된 조각을 고를 위험이 커집니다. 메타데이터에 제품, 버전, 언어, 공개범위를 넣고 필터를 먼저 거는 실험도 의미가 있습니다.

청크를 너무 잘게 쪼개면 인용이 잘게 깨지고, 너무 크게 잡으면 관련 없는 문장이 함께 섞일 수 있습니다. 그래서 기본값으로 먼저 측정한 뒤, chunking_config를 한 변수씩만 바꿔 비교하는 방식이 좋습니다.

앱 쪽에서는 검색 루프를 직접 짜는 코드와 도구에 맡기는 코드를 한 실험 안에 섞지 않는 편이 낫습니다. 이번 주제에서는 도구 경로만 따라가며, 모델이 도구를 몇 번 호출했는지, 어떤 파일명이 인용됐는지, 사람이 얼마나 수정했는지를 먼저 보는 정도로도 충분합니다.

실험 기록은 간단할수록 반복하기 쉽습니다

실험 노트에는 스토어 이름, 올린 파일 목록과 형식, 임베딩 모델 설정, 질의 세 문장, 도구 호출 횟수, 인용된 파일명, 사람이 수정한 문장 수, 그리고 Live API·다른 그라운딩 도구·오디오·비디오를 쓰지 않았다는 확인 정도만 남겨도 됩니다. 스크린샷보다 로그 한 줄이 더 중요하다는 뜻입니다.

실험이 끝나면 스토어 삭제 여부도 적어 두는 편이 좋습니다. 테스트 스토어를 계속 남기면 용량 한도에 먼저 닿을 수 있습니다.

함께 보면 좋은 범위 밖의 항목

영상 후반에는 Google Cloud Storage 버킷을 미리 승인한 뒤 URI를 프롬프트에 넣는 경로, 다른 클라우드의 서명 URL을 넣는 경로, 요청에 service tier를 두어 우선순위와 flex를 고르는 경로도 빠르게 소개합니다. 다만 이 항목들은 File Search 본론과는 분리해서 보는 편이 좋습니다. 데이터 반입과 우선순위 실험의 별도 주제로 두면 혼선이 줄어듭니다.

정리

이번 주제는 에이전트 루프를 서버에 맡기는 이야기가 아니라, 문서 인덱싱과 검색을 Gemini API의 도구로 붙이는 이야기입니다. 스토어를 만들고 파일을 올린 뒤 생성 호출에 검색 도구를 붙이면, 복잡한 검색 파이프라인을 처음부터 직접 짜지 않고도 문서 근거 답변을 빠르게 시험할 수 있습니다.

File Search는 검색 단계를 도구로 넘겨, 앱이 핵심 로직에 집중하게 해 주는 관리형 RAG 접근입니다.

참고 자료

Google for Developers
Gemini API 공식 문서

문서 검색을 직접 짜는 방식과 File Search에 맡기는 방식 사이에서, 지금 팀에 더 맞는 출발점은 어느 쪽인지 궁금합니다.