파일 검색을 도구로 붙입니다 | DAKER 커뮤니티

문서를 모델에 붙이려면 보통 벡터 저장소와 청킹과 재순위까지 한꺼번에 설계합니다. 오늘 정리한 Gemini API File Search는 그 검색 단계를 도구로 넘깁니다. 파일 검색을 도구로 붙입니다.

파일 검색을 도구로 붙입니다 썸네일 — 설명용 생성 이미지입니다. 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일입니다. 외부 사이트 주소는 본문에 넣지 않습니다. 가격·벤치마크·데모 수치는 영상과 문서에 없는 값을 만들지 않습니다.

오늘은 09-09에 다룬 Managed Agents 주제와도, 09-05 Antigravity 주제와도 겹치지 않습니다. 에이전트 루프를 서버에 맡기는 이야기가 아닙니다. 문서 인덱싱과 검색을 Gemini API의 도구로 붙이는 이야기입니다. 아침 뉴스 루틴의 다른 소재와도 각도를 나눕니다.

무엇이 바뀌는지

전통적인 RAG는 저장소 선택, 호스팅, 청크 크기, 오버랩, PDF 표 처리, 질의 확장, 재순위까지 직접 고릅니다. 영상은 이 선택이 프로토타이핑을 늦춘다고 말합니다. naive RAG부터 agentic RAG, self RAG, graph RAG, iterative RAG까지 이름만 해도 갈래가 많습니다. 그다음 벡터 데이터베이스를 고르고, 내 환경과 맞는지 확인하고, 호스팅 방법을 정합니다. 문서 전처리에서는 청크와 오버랩, 표가 섞인 PDF 같은 비정형 파일을 어떻게 풀지도 정해야 합니다. 검색 단계에서는 사용자 질문을 저장소 질의로 바꾸는 방법, 질의 확장, 문서 재순위까지 이어집니다.

File Search는 Gemini API 안에 있는 완전 관리형 RAG라고 영상과 문서가 같은 말을 합니다. 인덱싱과 검색의 많은 단계를 추상화하고, 앱은 핵심 로직에 집중합니다. Gemini 임베딩 모델을 쓰며, PDF 등에 자동 OCR을 넣어 텍스트 인덱스로 넣는다고 영상이 설명합니다. 공식 문서는 의미 검색이라고 적습니다. 키워드 일치가 아니라, 질의와 문서 조각을 임베딩으로 맞춥니다.

두 단계: 적재와 검색

영상과 문서 모두 단계를 둘로 나눕니다. 먼저 File Search store를 만들고 문서를 올립니다. 업로드와 동시에 스토어로 넣는 경로가 있고, Files API로 올린 뒤 import하는 경로도 있습니다. 문서에 따르면 Files API의 원본 파일은 약 48시간 후 삭제되지만, 스토어에 들어간 임베딩 데이터는 직접 지울 때까지 남습니다. 스토어는 여러 개 만들 수 있고, 이름 범위는 전역이라고 적혀 있습니다. 생성·목록·조회·삭제 API로 관리합니다. 문서 단위로도 목록·조회·삭제가 있습니다.

그다음 생성 호출에 file_search 도구와 스토어 이름을 붙입니다. 영상은 generate content 호출에 도구를 붙인다고 말하고, 최신 문서 예시는 interactions 경로도 보여 줍니다. 앱이 한 번 호출해도, 모델이 도구를 여러 번 쓰며 관련 조각을 모을 수 있습니다. 영상은 이를 에이전트형 검색이라고 부릅니다. 휴가 규정처럼 질문이 모호하면, 휴가 종류를 찾고, 양식을 찾고, 승인 절차를 찾는 식으로 이어진다고 설명합니다. 한 번의 앱 호출 안에서 검색이 연쇄될 수 있다는 점이 핵심입니다.

청킹은 기본값이 있습니다. 영상은 PDF 전처리기와 청킹 전략을 직접 정의하지 않아도 된다고 말합니다. 필요하면 전처리를 직접 할 수도 있지만, 스마트 기본값으로 대부분의 콘텐츠가 동작한다고 합니다. 공식 문서는 chunking_config로 청크당 최대 토큰과 오버랩 토큰을 줄 수 있다고 적습니다. 커스텀 메타데이터를 붙이면 작성자·연도 같은 조건으로 검색 범위를 줄일 수 있습니다. 응답 annotations에는 파일 인용, PDF 페이지, 이미지 조각 media_id가 올 수 있다고 문서에 적혀 있습니다. media_id로 모델이 참조한 이미지 조각을 다시 받을 수 있습니다.

맞는 말

File Search는 관리형 RAG 도구입니다. 스토리지와 질의 시점 임베딩 생성은 무료이고, 처음 인덱싱할 때의 임베딩과 일반 입출력 토큰은 과금된다고 문서가 설명합니다.
블로그에 적힌 인덱싱 단가는 시점에 따라 달라질 수 있습니다. 이 글에서는 구체 단가를 단정하지 않습니다. 최신 가격표로 확인하십시오.
자동 OCR로 PDF 같은 문서를 텍스트 인덱스에 넣을 수 있다고 영상이 말합니다.
문서는 멀티모달 임베딩 모델로 이미지 검색을 지원한다고 적습니다. 스토어 생성 때 embedding 모델을 지정합니다. PNG·JPEG, 최대 해상도 제한이 있습니다.
구조화 출력과 File Search를 함께 쓰는 예시가 최신 문서에 있습니다. Gemini 3 계열부터라고 적혀 있습니다.

조심할 말

오디오·비디오는 현재 지원하지 않는다고 문서에 명시되어 있습니다.
Live API에서는 File Search를 쓸 수 없습니다.
Google Search 그라운딩이나 URL Context와 같은 요청에 함께 쓰지 못합니다.
문서당 최대 100MB입니다. 프로젝트 스토어 총량은 계정 티어별 한도가 있습니다. 문서에는 Free 1GB부터 Tier 3 1TB까지 적혀 있고, 지연을 위해 스토어당 20GB 미만을 권장합니다.
영상은 출력을 쓰기 전에 사람이 한 번 보라고 강조합니다. 특히 익숙한 SDK로 바로 배포하는 경우에도 검토가 필요하다고 말합니다.

영상 후반의 빠른 소개도 범위에 넣습니다. Google Cloud Storage 버킷을 미리 승인한 뒤 URI를 프롬프트에 넣는 경로, 다른 클라우드의 서명 URL을 넣는 경로, 요청에 service tier를 두어 우선순위와 flex(대기 가능·비용 절감)를 고르는 경로입니다. 자세한 한도와 요금은 이 잡담에서 숫자로 단정하지 않습니다. File Search 본론과 섞지 말고, 데이터 반입·우선순위 실험의 별도 항목으로 두십시오.

File Search 적재와 도구 호출 설명 이미지 — 설명용 생성 이미지입니다. File Search store 적재와 생성 호출의 도구 연결을 단순화해 그렸습니다.

데모에서 가져올 장면

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

휴가 규정 예시는 모호한 질의에서 도구가 여러 번 도는 이유를 보여 줍니다. 앱이 검색 루프를 직접 짜지 않아도, 모델이 도구 호출을 이어 갈 수 있습니다. 다만 어제 잡담의 Managed Agents처럼 서버 세션 전체를 맡기는 제품과는 층위가 다릅니다. 오늘은 문서 검색 도구에 한정합니다.

오늘 빌더가 할 일

작은 문서 묶음으로 File Search store를 하나 만듭니다. 사내 FAQ, README, 정책 PDF 몇 개면 충분합니다. 처음에는 스토어를 하나로 두고, 도메인이 갈리면 스토어를 나눕니다.
기본 청킹으로 올린 뒤, 생성 호출에 file_search 도구만 붙인 최소 질의 세 개를 적어 봅니다. 모호한 질문 하나, 구체 질문 하나, 메타데이터로 좁혀야 하는 질문 하나를 권합니다.
인용 annotations가 오는지 확인합니다. PDF라면 페이지 번호가 붙는지도 봅니다. 이미지 문서를 넣었다면 media_id가 오는지 기록합니다.
같은 질문을 직접 컨텍스트에 문서를 붙여 넣는 방식과 비교합니다. 토큰·지연·답변 근거를 표로 남깁니다. 숫자는 본인 측정만 적습니다. 남이 만든 벤치마크를 복사하지 않습니다.
실패 모드를 따로 적습니다. Live API 경로, 다른 그라운딩 도구와 동시 사용, 오디오·비디오 파일, 100MB 초과 문서. 지원하지 않는 조합을 체크리스트 맨 위에 둡니다.
프로덕션 전에는 사람 검토 체크리스트를 둡니다. 정책·법률·인사 문서는 자동 답변을 바로 외부에 보내지 않습니다. 인용 파일명과 페이지를 로그에 남깁니다.
비용 관측은 인덱싱 시점과 질의 시점을 나눕니다. 문서상 질의 시점 임베딩은 무료이고, 인덱싱 임베딩과 일반 입출력은 과금입니다. 단가는 최신 가격표를 보고, 이 글의 숫자를 쓰지 마십시오.

설계 메모

스토어는 도메인 경계로 나눕니다. 인사 규정과 제품 스펙을 한 스토어에 섞으면 모호한 질의가 잘못된 조각을 고를 위험이 커집니다. 메타데이터에 제품·버전·언어·공개범위를 넣어 필터를 먼저 거는 실험을 권합니다. 청크를 너무 잘게 쪼개면 인용이 잘게 깨지고, 너무 크면 관련 없는 문장이 섞입니다. 기본값으로 먼저 측정한 뒤, chunking_config를 한 변수만 바꿔 비교하십시오.

앱 쪽에서는 검색 루프를 직접 짜는 코드와 도구에 맡기는 코드를 나란히 두지 말고, 이번 실험에서는 도구 경로만 따라갑니다. 관측은 모델이 도구를 몇 번 호출했는지, 어떤 파일명이 인용됐는지, 사람이 고친 비율이 얼마인지 세 가지만 먼저 봅니다. 비율은 본인 로그로만 계산합니다.

실험 기록 양식

오늘 실험 노트에는 다음 칸만 채웁니다. 스토어 이름, 올린 파일 목록과 형식, 임베딩 모델 설정, 질의 세 문장, 도구 호출 횟수(로그 기준), 인용된 파일명, 사람이 수정한 문장 수, Live API·다른 그라운딩 도구·오디오·비디오를 쓰지 않았다는 확인. 이 양식만으로도 다음날 같은 실험을 반복할 수 있습니다. 스크린샷보다 로그 한 줄이 더 중요합니다.

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

정리하면, 벡터 저장소와 검색 파이프라인을 처음부터 짓지 않고도 문서 근거 답변을 프로토타입할 수 있습니다. 스토어를 만들고, 파일을 올리고, 생성 호출에 검색 도구를 붙이면 됩니다. 한도와 미지원 조합만 먼저 표시해 두십시오. 파일 검색을 도구로 붙입니다.