한 줄 정의

Gemini API File Search는 Gemini API에서 파일을 올려 검색 가능한 store로 만들고, 모델 응답이 그 파일 내용을 근거로 쓰게 해 주는 RAG 도구야. 새 Gemini 모델명이 아니라, 문서와 이미지를 API 호출 흐름에 붙이는 검색 계층이라고 보면 돼.

2026년 5월 5일 Google 발표에서 이 도구는 세 가지가 크게 바뀌었어.

  • 멀티모달 검색: 텍스트와 이미지를 같은 검색 흐름에서 다룰 수 있어.
  • 커스텀 메타데이터: department: Legal 같은 키-값을 붙여 질의 범위를 좁힐 수 있어.
  • 페이지 단위 인용: PDF 같은 문서에서 어느 페이지를 근거로 썼는지 보여 줄 수 있어.

실제로 무엇을 하나

사용 흐름은 비교적 단순해. 개발자가 file search store를 만들고, PDF나 이미지가 섞인 자료를 올리면 Gemini API가 그 자료를 인덱싱해. 그다음 generate_content 호출에 File Search tool을 붙이면 모델이 store에서 관련 조각을 찾아 답변에 넣어. 검색된 조각은 grounding_metadata로 따라오고, 페이지가 있는 문서에서는 page_number, 이미지 조각에서는 media_id 같은 근거 정보도 받을 수 있어.

여기서 중요한 변화는 검색 대상이 텍스트 파일만이 아니라는 점이야. 다만 Gemini Embedding 2의 입력 한도와 File Search가 지금 받아 주는 파일 형식은 분리해서 읽어야 해.

  • 임베딩 모델 범위: Gemini Embedding 2 소개 글은 한 호출에서 최대 8,192 text tokens, 6 images, 120 seconds video, 180 seconds audio, 6 pages of PDFs를 다룬다고 설명해.
  • File Search 범위: 공식 문서는 텍스트 임베딩과 이미지/멀티모달 임베딩을 지원한다고 적지만, audio와 video 형식은 현재 지원하지 않는다고 따로 제한해.

그래서 이 페이지에서 말하는 멀티모달 검색은 제품 카탈로그 이미지, 연구 보고서의 도표, 설계 문서의 이미지, 보험 청구 사진처럼 텍스트와 이미지 자료가 섞인 검색 흐름으로 좁혀 보는 게 맞아.

커스텀 메타데이터도 실무에서는 꽤 중요해. store 하나에 모든 파일을 넣어 두면 질문마다 엉뚱한 자료가 섞이기 쉬운데, 업로드할 때 category, season, price_tier 같은 값을 붙이면 질의 시점에 필요한 범위만 좁혀 검색할 수 있어. 이건 벡터 데이터베이스에서 필터를 같이 쓰는 감각과 비슷하지만, Gemini API 안에서는 store와 tool 호출 형태로 드러난다는 차이가 있어.

왜 중요한가

이 항목이 중요한 이유는 RAG 구축에서 귀찮은 부분을 Gemini API 쪽 기능으로 많이 넘기기 때문이야. 원래는 파일 업로드, 문서 분할, 임베딩 생성, 벡터 저장소, 검색, 인용 표시를 따로 이어 붙여야 했어. File Search는 이 중 store 관리와 검색, 근거 메타데이터 반환을 API 기능으로 묶어 줘서 작은 팀이 멀티모달 문서 검색을 더 빨리 시험하게 해 줘.

특히 페이지 단위 인용은 “답이 그럴듯한가”보다 “어디를 보고 말했는가”를 확인하게 해 줘. 사내 규정, 법무 문서, 연구 보고서, 제품 매뉴얼처럼 출처 확인이 중요한 업무에서는 이 차이가 커. 답변 아래에 파일명만 띄우는 것과 37쪽 근처를 바로 보여 주는 건 사용자 신뢰가 꽤 다르거든.

또 하나는 모델 비교를 덜 헷갈리게 해 준다는 점이야. 검색 품질이 좋아졌다는 말이 항상 생성 모델 자체의 성능 향상을 뜻하지는 않아. 이 기능 맥락에서는 임베딩 모델, 메타데이터 필터, store 설계, 인용 반환 방식이 같이 바뀐 결과일 수 있어. 그래서 기사에서 이 이름이 보이면 “모델이 바뀐 건지, 검색 계층이 바뀐 건지”부터 갈라 보는 게 좋아.

주의해서 볼 점

File Search를 붙였다고 Grounding이 자동으로 완벽해지는 건 아니야. 잘못된 파일을 올리거나, 문서를 너무 크게 묶거나, 메타데이터를 대충 붙이면 검색 결과도 흔들려. 페이지 번호와 media_id는 검증을 돕는 힌트이지, 원문 자체가 맞는지까지 보장하는 장치는 아니야.

제한과 과금은 이렇게 나눠 보면 빨라.

  • 파일 크기: 공식 문서 기준 문서 하나는 최대 100 MB야.
  • store 총량: 프로젝트의 File Search store 총량은 Free 1 GB, Tier 1 10 GB, Tier 2 100 GB, Tier 3 1 TB로 갈려.
  • 권장 크기: store 하나는 20 GB 아래로 두는 걸 권장하고, 실제 store 크기는 입력 파일과 생성된 임베딩을 합쳐 보통 입력 데이터의 약 3배로 계산된다고 적혀 있어.
  • 파일 형식: audio와 video 파일 형식은 현재 지원하지 않아. 이미지 쪽도 PNG와 JPEG, 4K x 4K 이하 같은 조건을 확인해야 해.
  • 비용: 저장소와 질의 시점의 임베딩은 무료지만, 인덱싱할 때의 임베딩 비용과 검색된 문서 토큰의 컨텍스트 토큰 비용은 따로 봐야 해.
  • 도구 조합: Live API에서는 지원하지 않고, 현재 Grounding with Google Search나 URL Context 같은 다른 tool과 함께 쓸 수 없다는 제한도 있어.

사용자 화면에 바로 적용하기 전에 이 제약부터 확인하는 편이 안전해.