Gemini의 파일 검색 (managed RAG) API를 위한 누락된 UI를 만들었습니다

Source: Dev.to

Retrieval Augmented Generation (RAG) 은 특정 데이터에 대한 지식을 갖춘 AI 앱을 구축하기 위한 표준 아키텍처가 되었습니다.

보통 RAG 파이프라인을 구축하려면 여러 단계가 필요합니다: 벡터 데이터베이스(Pinecone이나 Weaviate 등)를 띄우고, PDF를 청크로 나누는 파이썬 스크립트를 작성하고, 임베딩을 생성하고, 검색 로직을 관리하는 등 말이죠.

Google은 최근 Gemini File Search 라는 기능을 출시했으며, 이를 통해 이 과정을 크게 단순화할 수 있습니다.
Gemini API에 직접 내장된 완전 관리형 RAG 파이프라인으로, 청크 분할, 임베딩 생성, 저장을 모두 자동으로 처리해 줍니다. 게다가 가격 모델이 가장 큰 장점이라고 할 수 있습니다.

• 기존의 벡터 데이터베이스처럼 시간당 포드 사용료나 저장 용량에 비용을 지불하는 것이 아니라, Gemini File Search는 쿼리 시점에 무료 저장 및 무료 임베딩 생성을 제공합니다.
• 문서를 처음 인덱싱할 때 한 번만 비용을 지불하면 됩니다(현재 1 백만 토큰당 $0.15), 이후에는 모델 응답에 대한 표준 입력/출력 토큰 비용만 발생합니다.

이 덕분에 유휴 벡터 저장소에 비용을 낭비하지 않으면서, 사이드 프로젝트든 규모가 큰 애플리케이션이든 비용 효율적으로 운영할 수 있습니다.

하지만 문제가 있습니다

Gemini File Search는 완전히 **“헤드리스”**입니다. 파일을 볼 수 있는 콘솔도 없고, 끌어다 놓기 업로드도 없으며, 스크립트를 작성하지 않고는 지식 베이스를 테스트할 방법도 없습니다. 파일을 삭제하거나 청크 전략이 제대로 작동하는지 확인하려면 코드를 작성해야 합니다.

지식 베이스를 관리하기 위해 일회성 스크립트를 계속 작성하는 데 지쳤기 때문에 Gemini File Search Manager를 만들었습니다.

Gemini File Search Manager란?

오픈‑소스이며 local‑first 웹 인터페이스로, Gemini File Search API의 제어 플레인 역할을 합니다. Next.js 로 구축되어 RAG 파이프라인을 시각적으로 관리할 수 있습니다.

코드를 확인하고 로컬에서 실행하려면 여기에서 확인하세요:

👉

Source: …

왜 만들었는지 & 해결하는 문제

“블랙 박스” 시각화

File Search API를 프로그래밍 방식으로 사용할 때는 대부분 눈이 가려진 채 작업합니다. Store를 만들고 파일을 업로드한 뒤, 제대로 처리됐는지 기대하게 되죠.

대시보드에는 다음이 표시됩니다:

• 모든 활성 스토어
• 스토어별 문서 수
• 인제스트 상태 (활성, 대기, 실패)

드래그‑앤‑드롭 인제스트 (스크립트 필요 없음)

API를 통해 파일을 업로드하는 과정은 여러 단계로 이루어집니다: 바이트를 전송하고, 작업이 완료될 때까지 기다린 뒤, 스토어에 연결합니다.

매니저는 전체 오케스트레이션을 처리하는 드래그‑앤‑드롭 인터페이스를 제공합니다. PDF, TXT, MD, CSV, JSON 및 Gemini가 지원하는 100가지 이상의 형식을 지원합니다.

Gemini API의 가장 강력한 기능 중 하나는 맞춤 청킹 및 메타데이터입니다. 보통은 복잡한 JSON 객체를 코드로 작성해야 하지만, 이제 UI에서 다음을 할 수 있습니다:

• maxTokensPerChunk와 maxOverlapTokens 조정
• 나중에 필터링할 수 있도록 메타데이터 태그 추가 (예: author, year)

RAG 플레이그라운드

데이터를 업로드한 뒤에는 모델이 실제로 해당 데이터를 찾을 수 있는지 확인해야 합니다. 각 Store에 대한 Playground 뷰에서는 다음을 할 수 있습니다:

• Chat: 특정 문서와 대화 (대화 기록이 보존됨)
• 다양한 모델 선택 (Gemini 3 Pro Preview, Gemini 3 Flash, Gemini 2.5 Pro 등)
• 메타데이터 필터링: AIP‑160 구문 사용 (예: author = "Smith" AND year > 2020)
• 인용 보기: UI가 API 응답의 groundingMetadata를 파싱해 답변을 생성할 때 사용된 정확한 문서 청크를 표시합니다.

Under the Hood: The Tech Stack

비동기 폴링 문제 해결

Gemini에 파일을 업로드하면 바로 활성화되지 않습니다. API는 Operation 객체를 반환하고 파일은 PROCESSING 상태가 됩니다.

브라우저가 멈추는 것을 방지하기 위해 매니저는 폴링 메커니즘을 구현합니다:

// Pseudo‑code
const pollOperation = async (operationId) => {
  while (true) {
    const status = await fetchOperationStatus(operationId);
    if (status === 'DONE') break;
    await new Promise(r => setTimeout(r, 3000)); // poll every 3 seconds
  }
};

초기 업로드가 완료된 후, 애플리케이션은 파일 상태가 ACTIVE(또는 오류가 발생)로 바뀔 때까지 3 초마다 operations 엔드포인트를 폴링합니다. 이렇게 하면 UI가 반응성을 유지하면서 데이터 수집 진행 상황에 대한 실시간 피드백을 제공할 수 있습니다.

백그라운드 처리

문서가 업로드되면 서버는 즉시 백그라운드에서 임베딩 생성을 시작합니다. 임베딩이 준비되면 자동으로 캐시를 무효화하고 UI를 업데이트합니다—문서 상태가 스피너에서 초록색 체크마크로 바뀝니다.

문서 목록 자체는 TanStack Query가 5초마다 백그라운드에서 다시 가져와 상태 변화를 감지합니다.

스트리밍 채팅 응답

채팅 플레이그라운드는 **Server‑Sent Events (SSE)**를 사용하여 실시간으로 응답을 스트리밍합니다. 모델이 텍스트를 생성하면 UI에 문자 단위로 표시됩니다. 스트림이 완료되면 근거 메타데이터(인용)가 추출되어 응답 아래에 표시됩니다.

보안

이 도구는 개발자를 위한 것이므로 사용자 계정이나 데이터베이스를 다루고 싶지 않았습니다. 앱은 로컬에서 실행되며 환경 변수를 사용합니다.

1. GEMINI_API_KEY를 포함한 .env.local 파일을 생성합니다.
2. 앱은 서버 측에서만 키를 읽습니다.

키는 절대로 당신의 머신을 떠나지 않으며 클라이언트 브라우저에 노출되지 않습니다.

빠른 시작

프로젝트를 약 2 분 안에 실행할 수 있습니다.

1. 레포지토리 복제

git clone https://github.com/prashantrohilla-max/gemini-file-search-manager
cd gemini-file-search-manager
npm install

2. API 키 추가

.env.local 파일을 생성하세요:

GEMINI_API_KEY=your_key_here

3. 앱 실행

npm run dev

http://localhost:3000을 열면 준비가 완료됩니다.

다음은?

• 구조화된 출력 – 데이터 추출 워크플로를 테스트하기 위해.
• URL 가져오기 – 웹 페이지에서 직접 콘텐츠를 가져오는 기능.
• 지속적인 채팅 세션 – 현재는 페이지를 떠나거나 서버를 중지하면 사라지며, 지속성은 로드맵에 포함되어 있습니다.

프로젝트는 오픈 소스이며 MIT‑라이선스입니다. 유용하다고 생각되면 저장소에 ⭐를 달거나 PR을 제출해주세요!

Repo: