# Show GN: Flamehaven FileSearch — 셀프호스팅 가능한 오픈소스 RAG 문서 검색 엔진 > Clean Markdown view of GeekNews topic #24323. Use the original source for factual precision when an external source URL is present. ## Metadata - GeekNews HTML: [https://news.hada.io/topic?id=24323](https://news.hada.io/topic?id=24323) - GeekNews Markdown: [https://news.hada.io/topic/24323.md](https://news.hada.io/topic/24323.md) - Type: show - Author: [flamehaven01](https://news.hada.io/@flamehaven01) - Published: 2025-11-13T01:37:12+09:00 - Updated: 2025-11-13T01:37:12+09:00 - Original source: [github.com/flamehaven01](https://github.com/flamehaven01/Flamehaven-Filesearch) - Points: 29 - Comments: 4 ## Summary **Flamehaven FileSearch**는 **Python·FastAPI·SQLite**로 구성된 경량 **셀프호스팅 RAG 검색 엔진**으로, 로컬 환경에서 바로 **자연어 기반 문서 질의응답**을 구현할 수 있게 합니다. 복잡한 인프라 없이 `pip install` 한 줄로 서버를 띄우고, **Gemini Embedding**을 활용해 PDF나 Markdown 등 다양한 포맷을 처리할 수 있다는 점이 인상적입니다. 특히 **로컬 데이터 보안**과 **개발자 친화적 API 구조**를 모두 잡은 설계가 돋보이며, 연구나 스타트업 초기 실험용으로 이상적인 스택입니다. “실제로 돌아가는 RAG”를 찾고 있었다면, 이 프로젝트가 꽤 반가울 것입니다. ## Topic Body #### 🔥Flamehaven FileSearch - **Flamehaven FileSearch**는 문서 기반 RAG(Retrieval-Augmented Generation) 시스템을 누구나 5분 만에 구축할 수 있게 해주는 **셀프호스팅 가능한 오픈소스 시맨틱 검색 엔진**입니다. - Python, FastAPI, SQLite 기반으로 동작하며, Google Gemini Embedding을 활용 PDF/DOCX/TXT/MD 등 다양한 문서에서 **자연어 질의 응답**을 수행합니다. --- #### 왜 만들었나? - 대부분의 오픈소스 RAG 구현체가 Colab이나 Jupyter 환경에서는 잘 돌아가지만, 실제 서버에 올려서 운영하기엔 구조가 복잡하거나 안정성이 부족합니다. - Flamehaven FileSearch는 **“실제로 돌아가는 경량 RAG 스택”** 을 목표로, 연구자·스타트업·개인 개발자가 누구나 자신의 데이터로 시맨틱 검색을 즉시 실험할 수 있도록 설계되었습니다. --- #### 왜 주목해야 할까? - **완전한 자율성**: 외부 서버나 클라우드에 의존하지 않으며, 데이터는 모두 로컬에 저장됩니다. - **개발자 중심 구조**: Python SDK + REST API, FastAPI 기반 Swagger 문서 자동 제공. - **PyPI 패키지 배포**: [PyPI](https://pypi.org/project/flamehaven-filesearch)에서 바로 설치 가능 — `pip install flamehaven-filesearch[api]` 한 줄로 완전 자동 설치. - **즉시 실행**: 설치 후 `flamehaven-api` 명령어로 바로 서버 구동, 브라우저에서 `/docs`로 API 테스트 가능. - **확장성**: SQLite 저장소, 플러그인 아키텍처, Docker 배포 지원. - **교육/연구 친화성**: Gemini 임베딩을 사용하여 최신 LLM 기반 시맨틱 검색 실습에 이상적. --- #### 무엇이 들어 있나? (하이라이트) - **Python SDK**: `from flamehaven_filesearch import FlamehavenFileSearch` → 문서 업로드 / 검색 / 스토어 관리 전 기능 제공. - **REST API**: `/upload`, `/search`, `/stores` 엔드포인트 + Swagger UI. - **Docker 지원**: `docker run -e GEMINI_API_KEY=... -p 8000:8000 flamehaven/filesearch:latest` - **구조**: `core(엔진)` / `api(FastAPI)` / `data(SQLite)` / `examples` / `docs` --- ##### 빠르게 써보기 **1️⃣** PyPI 패키지 Flamehaven FileSearch는 PyPI를 통해 바로 설치할 수 있습니다. 최신 버전 확인: https://pypi.org/project/flamehaven-filesearch ```bash pip install flamehaven-filesearch[api] ``` **2️⃣ 설치** ```bash pip install flamehaven-filesearch[api] export GEMINI_API_KEY="your-google-gemini-key" flamehaven-api ``` **3️⃣ 문서 업로드 & 검색** ```bash curl -X POST "http://localhost:8000/upload" -F "file=@handbook.pdf" curl "http://localhost:8000/search?q=vacation+policy" ``` **4️⃣ SDK 사용 예시** ```python from flamehaven_filesearch import FlamehavenFileSearch fs = FlamehavenFileSearch() fs.upload_file("handbook.pdf") print(fs.search("vacation policy")["answer"]) ``` --- #### 성능 & 스펙 - **환경**: Ubuntu 22.04 / 2vCPU / 4GB RAM / SSD - **업로드 10MB PDF** → 약 5초 - **검색 응답 평균** → 2초 (소스 5개 인용 시) - **스토어 삭제/생성** → 1초 이내 - **스토리지 오버헤드** → 문서 크기의 약 5 % --- #### 로드맵 - **v1.1** : 캐싱 및 쿼터 관리 - **v1.2** : 배치 검색 + WebSocket 스트리밍 - **v2.0** : 다국어 문서 지원, 분석 대시보드 - **향후** : Pinecone/Weaviate 벡터DB 통합, OCR, 협업 스토어 --- #### 라이선스 - **MIT License** (완전 오픈소스) --- ##### 🛡️ Flamehaven Github 보안 및 계정 공지 최근 Flamehaven GitHub 계정(본 계정)에서 의심스러운 로그인 시도가 감지되면서 계정이 정지 상태에 놓였습니다. 현재 GitHub 보안팀과 협력하여 문제를 확인 중입니다. 이번 사건을 통해 - dir2md, flashrecord, crom-efficient, Arr-medic-cyp3a4 등이 포함된 계정은 당분간 사용 중단된 상태입니다. 이용자 여러분께 불편을 드려 진심으로 사과드리며, 보안 점검이 완료될 때까지 조금만 양해 부탁드립니다. ## Comments ### Comment 46548 - Author: flamehaven01 - Created: 2025-11-19T14:41:44+09:00 - Points: 1 Flamehaven FileSearch v1.2.0을 어제 릴리스했습니다. 이번 버전은 서비스 전체를 “공개 API”에서 보안·확장성 중심의 엔터프라이즈급 플랫폼으로 전환하는 데 초점을 맞췄습니다. 주요 변경 사항은 다음과 같습니다: API 인증·권한 시스템 추가 모든 보호된 엔드포인트는 Bearer Token 인증을 필요로 합니다. API Key는 업로드/검색/스토어/삭제 등 세분화된 권한을 지원하며, 키별 rate limit, 감사 로그, SHA256 해시 저장(원본 키 저장 없음)을 포함합니다. Admin Dashboard 추가 API Key 생성·조회·폐기, 요청 통계, 엔드포인트 사용량 분포 등을 볼 수 있는 웹 UI입니다. HTML/CSS/JS로 완전 자체 포함되어 외부 의존성이 없습니다. Batch Search API 한 요청에 1–100개의 쿼리를 처리합니다. 병렬/순차 실행 모드, 우선순위 기반 정렬, 쿼리별 에러 격리, 상세 타이밍 메트릭을 제공합니다. Redis 캐시 백엔드 멀티 워커 환경을 위한 분산 캐시 옵션입니다. <10ms 조회 지연, 자동 LRU fallback, LLM 호출량 40–60% 절감 효과가 있습니다. 배포 템플릿 제공(Docker/Kubernetes) Docker, Docker Compose, Kubernetes(ConfigMap/Secret/Deployment) 예제가 포함되어 바로 배포할 수 있습니다. 성능 요약: 캐시 히트: <10ms 캐시 미스(LLM 호출): ~0.5–3s Batch Search(10개): ~2–5s GitHub: https://github.com/flamehaven01/Flamehaven-Filesearch 보안 설계, API 사용성, 배포 구조 등 개선 의견이 있으면 환영합니다. v1.2.1(어드민 인증 개선, Redis 설정 UI), v1.3.0(키 로테이션 + OAuth2/OIDC)도 준비 중입니다. ### Comment 46295 - Author: flamehaven01 - Created: 2025-11-13T19:26:10+09:00 - Points: 1 오늘 v1.1.0을 릴리즈했습니다. 이번 버전은 주로 경로 탐색 취약점 패치, FastAPI/Starlette 보안 업데이트, 요청 ID 트레이싱, 레이트 리미트, 캐싱(<10ms hit), Prometheus 메트릭 추가 등이 포함돼 있습니다. 이전 버전보다 훨씬 안정적으로 동작합니다. 이번 업데이트도 여전히 가볍고 자체 호스팅 가능한 구조에 초점을 맞췄습니다. 감사합니다. ### Comment 47469 - Author: flamehaven01 - Created: 2025-12-09T23:34:52+09:00 - Points: 1 Update: v1.2.2 출시 기존 글 올린 뒤, 오늘 기준으로 v1.2.2까지 올라왔습니다. 간단히 변경사항만 정리하면: 테스트/안정성 강화 암호화 서비스: env 키 기반 encrypt/decrypt 라운드 트립 + invalid token 경로 테스트 배치 검색: 병렬 우선순위 큐, 초기화 안 된 서비스 → 503, 쿼리별 예외 분리 Redis 캐시: in-memory fake client로 get/set/delete/clear + 사용 가능 여부 테스트 그동안 커버리지에서 빠져 있던 cache_redis.py를 커버리지 대상에 포함 서비스 준비성(Service readiness) 서버 첫 기동 시 기본 스토어와 작은 fallback 문서를 자동 생성 아무것도 업로드하지 않아도 /search와 /health가 바로 200 응답 → 데모/CI 헬스 체크/에이전트 부팅에 바로 사용 가능 운영 측 정리 버전 문자열, 로그 메타데이터, Prometheus 라벨, OpenAPI 제목을 v1.2.2로 정리 Redis는 여전히 옵션이고, 없으면 in-process LRU 캐시로 자연스럽게 폴백 브레이킹 체인지 없이, 기존 사용자들은 그대로 업그레이드하시면 됩니다. 조금씩 “운영에 바로 쓸 수 있는 쪽”으로 다듬어가는 중입니다. ### Comment 46959 - Author: flamehaven01 - Created: 2025-11-29T11:05:46+09:00 - Points: 1 🚀 Flamehaven Filesearch v1.2.1 Release! 지난 업데이트 이후 꾸준히 개선해 온 Flamehaven Filesearch의 최신 버전 v1.2.1을 공개합니다. 이번 릴리즈는 보안 강화, 관리 도구 확장, 그리고 운영 편의성 개선에 초점을 맞췄습니다. 🔐 주요 업데이트 사항 🔺Admin Cache Controls 추가 /api/admin/cache/stats, /api/admin/cache/flush 경로로 캐시 상태 조회 및 플러시 가능 (Admin 전용) 🔺API Key 권한 강화 Admin 권한이 없는 키는 관리자 기능 사용 시 403 반환 기본 신규 API 키에 admin 권한 포함 🔺IAMProvider Hook 도입 향후 OIDC/IAM 백엔드 통합을 위한 구조 준비 🔺Metrics 확장 Cache, health_status, prometheus placeholder 추가로 대시보드 활용도 향상 🔺Frontend 업데이트 Cache / Metrics 페이지를 백엔드와 연동 Upload / Admin 페이지에 Token 입력 기능 연결 신규 Landing 및 Dashboard 페이지 정비 🔺테스트 강화 test_admin_cache.py 추가로 캐시 관련 관리자 API 테스트 도입 🔺문서 업데이트 README 버전 업데이트 및 FLAMEHAVEN_ENC_KEY 환경 변수를 포함한 보안 관련 가이드 보강 🐛 Fixed Admin 권한 없이 관리자 기능 요청 시 접근 차단(403) 🔗 GitHub: https://github.com/flamehaven01/Flamehaven-Filesearch 이번 버전은 앞으로 예정된 IAM 통합과 대시보드 고도화를 위한 기반도 함께 다졌습니다.