▲

Show GN: Flamehaven FileSearch — 셀프호스팅 가능한 오픈소스 RAG 문서 검색 엔진

 (github.com/flamehaven01)
29P by flamehaven01 5달전 | ★ favorite | 댓글 4개

🔥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에서 바로 설치 가능 — 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

pip install flamehaven-filesearch[api]

2️⃣ 설치

pip install flamehaven-filesearch[api]  
export GEMINI_API_KEY="your-google-gemini-key"  
flamehaven-api

3️⃣ 문서 업로드 & 검색

curl -X POST "http://localhost:8000/upload"; -F "file=@handbook.pdf"  
curl "http://localhost:8000/search?q=vacation+policy";

4️⃣ SDK 사용 예시

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 등이 포함된 계정은 당분간 사용 중단된 상태입니다.

이용자 여러분께 불편을 드려 진심으로 사과드리며, 보안 점검이 완료될 때까지 조금만 양해 부탁드립니다.

함께 보면 좋은 글 β

▲
flamehaven01 5달전  [-]

오늘 v1.1.0을 릴리즈했습니다.

이번 버전은 주로 경로 탐색 취약점 패치, FastAPI/Starlette 보안 업데이트, 요청 ID 트레이싱, 레이트 리미트, 캐싱(<10ms hit), Prometheus 메트릭 추가 등이 포함돼 있습니다. 이전 버전보다 훨씬 안정적으로 동작합니다.

이번 업데이트도 여전히 가볍고 자체 호스팅 가능한 구조에 초점을 맞췄습니다. 감사합니다.

답변달기
▲
flamehaven01 4달전  [-]

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 캐시로 자연스럽게 폴백

브레이킹 체인지 없이, 기존 사용자들은 그대로 업그레이드하시면 됩니다.
조금씩 “운영에 바로 쓸 수 있는 쪽”으로 다듬어가는 중입니다.

답변달기
▲
flamehaven01 4달전  [-]

🚀 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 통합과 대시보드 고도화를 위한 기반도 함께 다졌습니다.

답변달기
▲
flamehaven01 5달전  [-]

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)도 준비 중입니다.

답변달기