Flamehaven FileSearch — công cụ tìm kiếm tài liệu RAG mã nguồn mở có thể tự lưu trữ

 (github.com/flamehaven01)
29 điểm bởi flamehaven01 2025-11-13 | 4 bình luận | Chia sẻ qua WhatsApp

🔥Flamehaven FileSearch

  • Flamehaven FileSearch là công cụ tìm kiếm ngữ nghĩa mã nguồn mở có thể tự lưu trữ, giúp bất kỳ ai cũng có thể xây dựng hệ thống RAG (Retrieval-Augmented Generation) dựa trên tài liệu chỉ trong 5 phút.
  • Hoạt động trên nền tảng Python, FastAPI và SQLite, đồng thời sử dụng Google Gemini Embedding để thực hiện hỏi đáp bằng ngôn ngữ tự nhiên trên nhiều loại tài liệu như PDF/DOCX/TXT/MD.

Tại sao lại tạo ra nó?

  • Phần lớn các bản triển khai RAG mã nguồn mở chạy tốt trong môi trường Colab hoặc Jupyter, nhưng khi đưa lên máy chủ thực tế để vận hành thì thường có cấu trúc phức tạp hoặc thiếu tính ổn định.
  • Flamehaven FileSearch được thiết kế với mục tiêu “một stack RAG gọn nhẹ thực sự chạy được”, để nhà nghiên cứu, startup và lập trình viên cá nhân có thể ngay lập tức thử nghiệm tìm kiếm ngữ nghĩa với chính dữ liệu của mình.

Vì sao đáng chú ý?

  • Tính tự chủ hoàn toàn: Không phụ thuộc vào máy chủ bên ngoài hay đám mây, toàn bộ dữ liệu được lưu cục bộ.
  • Cấu trúc hướng nhà phát triển: Python SDK + REST API, tự động cung cấp tài liệu Swagger dựa trên FastAPI.
  • Phát hành gói PyPI: Có thể cài đặt ngay từ PyPI — cài đặt hoàn toàn tự động chỉ với một dòng pip install flamehaven-filesearch[api].
  • Chạy ngay lập tức: Sau khi cài đặt, có thể khởi động máy chủ ngay bằng lệnh flamehaven-api, và thử nghiệm API tại /docs trên trình duyệt.
  • Khả năng mở rộng: Hỗ trợ kho lưu trữ SQLite, kiến trúc plugin và triển khai bằng Docker.
  • Thân thiện với giáo dục/nghiên cứu: Sử dụng Gemini Embedding, rất phù hợp để thực hành tìm kiếm ngữ nghĩa dựa trên LLM hiện đại.

Có những gì bên trong? (điểm nổi bật)

  • Python SDK: from flamehaven_filesearch import FlamehavenFileSearch

    → Cung cấp đầy đủ chức năng tải tài liệu lên / tìm kiếm / quản lý store.

  • REST API: endpoint /upload, /search, /stores + Swagger UI.

    Quảng cáo

  • Hỗ trợ Docker: docker run -e GEMINI_API_KEY=... -p 8000:8000 flamehaven/filesearch:latest

  • Cấu trúc: core(engine) / api(FastAPI) / data(SQLite) / examples / docs

Dùng thử nhanh

1️⃣ Gói PyPI

Flamehaven FileSearch có thể được cài đặt ngay thông qua PyPI.

Xem phiên bản mới nhất: https://pypi.org/project/flamehaven-filesearch

pip install flamehaven-filesearch[api]
Quảng cáo

2️⃣ Cài đặt

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

3️⃣ Tải tài liệu lên & tìm kiếm

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

4️⃣ Ví dụ dùng SDK

from flamehaven_filesearch import FlamehavenFileSearch  
fs = FlamehavenFileSearch()  
fs.upload_file("handbook.pdf")  
print(fs.search("vacation policy")["answer"])
Quảng cáo

Hiệu năng & thông số

  • Môi trường: Ubuntu 22.04 / 2vCPU / 4GB RAM / SSD
  • Tải lên PDF 10MB → khoảng 5 giây
  • Thời gian phản hồi tìm kiếm trung bình → 2 giây (khi trích dẫn 5 nguồn)
  • Xóa/tạo store → dưới 1 giây
  • Chi phí lưu trữ phát sinh → khoảng 5% kích thước tài liệu

Lộ trình

  • v1.1 : bộ nhớ đệm và quản lý quota
  • v1.2 : tìm kiếm hàng loạt + streaming qua WebSocket
  • v2.0 : hỗ trợ tài liệu đa ngôn ngữ, bảng điều khiển phân tích
  • Tương lai : tích hợp vector DB Pinecone/Weaviate, OCR, store cộng tác

Giấy phép

  • MIT License (mã nguồn mở hoàn toàn)

🛡️ Thông báo bảo mật GitHub và tài khoản Flamehaven

Gần đây, tài khoản GitHub Flamehaven (tài khoản chính thức này) đã bị tạm khóa sau khi phát hiện các nỗ lực đăng nhập đáng ngờ. Hiện tại, chúng tôi đang phối hợp với đội ngũ bảo mật GitHub để xác minh vấn đề.

Qua sự việc lần này, các tài khoản bao gồm dir2md, flashrecord, crom-efficient, Arr-medic-cyp3a4 và các tài khoản liên quan hiện sẽ tạm thời ngừng sử dụng.

Chúng tôi chân thành xin lỗi vì sự bất tiện này và mong người dùng thông cảm thêm một chút cho đến khi việc kiểm tra bảo mật hoàn tất.

Bài viết liên quan

4 bình luận

 
flamehaven01 2025-12-09

Cập nhật: phát hành v1.2.2

Sau khi đăng bài trước, tính đến hôm nay đã lên tới v1.2.2.
Tóm tắt ngắn gọn các thay đổi như sau:

Tăng cường kiểm thử/độ ổn định

Dịch vụ mã hóa: kiểm thử vòng lặp encrypt/decrypt dựa trên khóa env + đường dẫn invalid token

Tìm kiếm hàng loạt: hàng đợi ưu tiên song song, dịch vụ chưa được khởi tạo → 503, tách riêng ngoại lệ theo từng truy vấn

Bộ nhớ đệm Redis: dùng fake client in-memory để kiểm thử get/set/delete/clear + khả năng sử dụng

Đưa cache_redis.py, vốn trước đây bị bỏ sót khỏi coverage, vào phạm vi coverage

Mức sẵn sàng của dịch vụ (Service readiness)

Khi máy chủ khởi động lần đầu, tự động tạo store mặc định và một tài liệu fallback nhỏ

Ngay cả khi chưa tải gì lên, /search và /health vẫn phản hồi 200 ngay lập tức
→ có thể dùng ngay cho demo / health check CI / khởi động agent

Sắp xếp lại khía cạnh vận hành

Chuỗi phiên bản, metadata log, nhãn Prometheus, tiêu đề OpenAPI đã được đồng bộ thành v1.2.2

Redis vẫn là tùy chọn, và nếu không có thì sẽ tự nhiên fallback sang bộ nhớ đệm LRU trong process

Không có breaking change, người dùng hiện tại chỉ cần nâng cấp như cũ là được.
Đang dần được tinh chỉnh theo hướng “có thể dùng ngay trong môi trường vận hành”.
 
flamehaven01 2025-11-29

🚀 Phát hành Flamehaven Filesearch v1.2.1!

Chúng tôi công bố phiên bản mới nhất v1.2.1 của Flamehaven Filesearch, được cải tiến liên tục kể từ bản cập nhật trước. Bản phát hành lần này tập trung vào tăng cường bảo mật, mở rộng công cụ quản trị và cải thiện sự thuận tiện trong vận hành.

🔐 Các cập nhật chính
🔺Thêm Admin Cache Controls
Có thể xem trạng thái cache và flush qua các đường dẫn /api/admin/cache/stats, /api/admin/cache/flush (chỉ dành cho Admin)

🔺Tăng cường quyền cho API Key
Các key không có quyền Admin sẽ trả về 403 khi sử dụng chức năng quản trị
API key mới được tạo mặc định bao gồm quyền admin

🔺Bổ sung IAMProvider Hook
Chuẩn bị cấu trúc cho việc tích hợp backend OIDC/IAM trong tương lai

🔺Mở rộng Metrics
Bổ sung cache, health_status, prometheus placeholder để tăng hiệu quả sử dụng dashboard

🔺Cập nhật Frontend
Kết nối các trang Cache / Metrics với backend
Liên kết tính năng nhập Token trên các trang Upload / Admin
Chỉnh lý mới các trang Landing và Dashboard

🔺Tăng cường kiểm thử
Bổ sung test_admin_cache.py để đưa vào kiểm thử API quản trị liên quan đến cache

🔺Cập nhật tài liệu
Cập nhật phiên bản trong README và bổ sung hướng dẫn bảo mật, bao gồm biến môi trường FLAMEHAVEN_ENC_KEY

🐛 Đã sửa

Chặn truy cập (403) khi yêu cầu chức năng quản trị mà không có quyền Admin

🔗 GitHub: https://github.com/flamehaven01/Flamehaven-Filesearch

Phiên bản này cũng đồng thời đặt nền móng cho việc tích hợp IAM và nâng cấp dashboard trong thời gian tới.
 
flamehaven01 2025-11-19

Hôm qua tôi đã phát hành Flamehaven FileSearch v1.2.0. Phiên bản này tập trung vào việc chuyển toàn bộ dịch vụ từ một “public API” sang nền tảng cấp doanh nghiệp chú trọng bảo mật và khả năng mở rộng.

Các thay đổi chính như sau:

Bổ sung hệ thống xác thực và phân quyền API
Tất cả các endpoint được bảo vệ đều yêu cầu xác thực Bearer Token.
API Key hỗ trợ quyền chi tiết như upload/tìm kiếm/store/xóa, đồng thời bao gồm rate limit theo từng key, audit log và lưu hash SHA256 (không lưu key gốc).

Bổ sung Admin Dashboard
Đây là web UI để xem và tạo/truy vấn/thu hồi API Key, thống kê request, phân bố mức sử dụng endpoint, v.v.
Được đóng gói hoàn toàn bằng HTML/CSS/JS nên không có phụ thuộc bên ngoài.

Batch Search API
Xử lý 1–100 truy vấn trong một request.
Cung cấp chế độ thực thi song song/tuần tự, sắp xếp theo mức ưu tiên, cô lập lỗi theo từng truy vấn và metric thời gian chi tiết.

Redis cache backend
Đây là tùy chọn cache phân tán cho môi trường multi-worker.
Có độ trễ truy xuất <10ms, tự động LRU fallback và giúp giảm 40–60% số lần gọi LLM.

Cung cấp template triển khai (Docker/Kubernetes)
Bao gồm các ví dụ Docker, Docker Compose, Kubernetes(ConfigMap/Secret/Deployment) để có thể triển khai ngay.

Tóm tắt hiệu năng:

Cache hit: <10ms

Cache miss (gọi LLM): ~0.5–3s

Batch Search(10 mục): ~2–5s

GitHub: https://github.com/flamehaven01/Flamehaven-Filesearch

Nếu có ý kiến đóng góp để cải thiện thiết kế bảo mật, tính tiện dụng của API hoặc cấu trúc triển khai, tôi rất hoan nghênh.
Tôi cũng đang chuẩn bị v1.2.1(cải thiện xác thực admin, UI cấu hình Redis) và v1.3.0(key rotation + OAuth2/OIDC).
 
flamehaven01 2025-11-13

Hôm nay chúng tôi đã phát hành v1.1.0.

Phiên bản này chủ yếu bao gồm vá lỗ hổng path traversal, cập nhật bảo mật FastAPI/Starlette, truy vết ID yêu cầu, giới hạn tốc độ, bộ nhớ đệm (hit <10ms), bổ sung metric Prometheus, v.v. Nó hoạt động ổn định hơn rất nhiều so với các phiên bản trước.

Bản cập nhật lần này vẫn tiếp tục tập trung vào kiến trúc nhẹ và có thể tự lưu trữ. Xin cảm ơn.