# Bolmo RAG Toolkit Zestaw narzędzi do eksperymentów z Retrieval-Augmented Generation (RAG) oparty na skrypcie `rag.py`. Repozytorium zawiera gotowy skrypt instalacyjny `install.sh` oraz dopasowany `Makefile`, które w kilka sekund przygotowują środowisko uruchomieniowe i dostarczają wygodne cele (`install`, `run`, `clean`). ## Wymagania wstępne - Linux / macOS z `python3` i `venv` - Dostęp do internetu w celu pobrania zależności Pythona ## Instalacja środowiska (install.sh) 1. Nadaj plikowi uprawnienia wykonywalne: ```bash chmod +x install.sh ``` 2. Uruchom skrypt: ```bash ./install.sh ``` Skrypt: - tworzy virtualenv (`.venv`), - aktywuje środowisko, - aktualizuje `pip`, - instaluje komplet zależności zpinowanych pod Python 3.13/3.11, aby uniknąć kompilacji Rust/C (`transformers==4.46.2`, `tokenizers==0.20.3`, `sentence-transformers==2.6.1`, `faiss-cpu==1.13.2`, `torch==2.10.0`, `PyPDF2==3.0.1`, `python-docx==1.2.0`, `html2text==2025.4.15`, `python-dotenv==1.0.1`). Po zakończeniu aktywuj środowisko komendą `source .venv/bin/activate`. > **Uwaga:** jeśli pracujesz na starszej dystrybucji, upewnij się, że masz zainstalowane `build-essential`, `rustc` oraz `cargo`; nowe paczki powinny jednak instalować się z gotowych kółek (wheels) i nie wymagać kompilacji. ## Przykładowa kolekcja `docs/` Repozytorium zawiera katalog `docs/` z wieloma formatami, które możesz wykorzystać do szybkiego testu pipeline'u: - `readme.txt` – tekstowe wprowadzenie do korpusu. - `faq.md` – markdown z najczęstszymi pytaniami. - `support.html` – prosty dokument HTML do sprawdzenia ekstrakcji z treści webowych. - `schedule.csv` – tabela z harmonogramem zadań. - `config.json` – przykładowa konfiguracja indeksowania. - `meeting_notes.docx` – notatki ze spotkania w formacie Word. - `overview.pdf` – krótki PDF opisujący demo Bolmo RAG. Aby uruchomić demo na tych danych: ```bash make run FOLDER=./docs QUERY="Co zawiera pakiet demo?" ``` Wyniki, z cytowaniem źródeł: ```bash $ make run CUDA_HOME=/usr/local/cuda .venv/bin/python rag.py --folder ./docs --query "Co to jest Bolmo?" --k 5 [rag] Ładowanie dokumentów z ./docs... [rag] Załadowano 7 plików. [rag] Chunkowanie dokumentów... [rag] Chunkowanie zakończone – 7 fragmentów. [rag] Ładowanie embeddera all-MiniLM-L6-v2... [rag] Ładowanie istniejącego indexu FAISS... [rag] Retrieval – wyszukiwanie 5 fragmentów... [rag] Pobrano 5 fragmentów kontekstu. [rag] Ładowanie modelu allenai/Bolmo-1B na urządzeniu cuda... Loading checkpoint shards: 100%|██████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 2/2 [00:00<00:00, 90.62it/s] [rag] Generowanie odpowiedzi... [1] support.html # Kontakt zespołem Bolmo Napisz do nas na [help@bolmo.ai](mailto:help@bolmo.ai), aby uzyskać wsparcie. * Aktualizacje produktu w każdy wtorek * Wsparcie 24/7 dla klientów enterprise [2] faq.md # Najczęstze pytania ## Czym jest Bolmo? Bolmo to przykład systemu wspomagającego analizę dokumentów w modelu RAG. ## Jak korzystać z próbek? Ustaw `FOLDER=./docs` podczas wywołania `make run`, aby przetestować pipeline na zróżnich plikach. [3] overview.pdf Bolmo RAG DemoTen PDF ilustruje obsÅugÄ plików binarnych w pipeline.Możesz zastÄpiÄ go wÅasnymi materiaÅami referencyjnymi. [4] readme.txt Bolmo RAG Sample Corpus =============================== To demo the pipeline, point the --folder flag to this directory. It contains multiple document formats that mirror real-world inputs. [5] meeting_notes.docx Spotkanie: Harmonogram wdrożeń Ustalenia: Przygotować demo dla zespołu sprzedaży. ``` ### Konfiguracja modeli przez `.env` 1. Sklonuj plik wzorcowy i ustaw zmienną: ```bash cp .env.example .env ``` 2. Otwórz `.env` i ustaw: - `BOLMO_MODEL` – model generatywny (domyślnie `allenai/Bolmo-1B`). Jeśli masz zasoby GPU, możesz przełączyć na `allenai/Bolmo-7B`. - `BOLMO_EMBEDDER` – sentence-transformer do częśći retrieval (domyślnie `all-MiniLM-L6-v2`). Możesz wskazać np. `sentence-transformers/all-mpnet-base-v2`. Skrypt `rag.py` ładuje `.env` automatycznie dzięki `python-dotenv`, więc każda zmiana wartości jest widoczna przy kolejnym uruchomieniu `make run`. ## Automatyzacja za pomocą Makefile Makefile udostępnia zestaw celów: ```bash make install # tworzy .venv poprzez install.sh make run FOLDER=./docs QUERY="?" # uruchamia rag.py z parametrami make test # uruchamia pytest make clean # usuwa katalog .venv make docker-build # buduje obraz Dockera bolmo-rag make docker-run FOLDER=... QUERY=... # buduje i uruchamia obraz z zamontowanymi docs/.env make docker-shell # wchodzi do python:3.11 z repo pod /app make docker-up / docker-logs / docker-stop # zarządza kontenerem w tle ``` ### Opis celów - **install** – zależy od pliku `.venv/bin/activate`; jeżeli środowisko nie istnieje, uruchamia `install.sh` i tworzy plik znacznika w katalogu `.venv`. - **run** – zapewnia, że środowisko jest gotowe (wywołuje `make install`), a następnie uruchamia `rag.py` z przekazanymi argumentami `--folder` oraz `--query`. - **test** – uruchamia `pytest`, aby sprawdzić podstawowe wczytywanie dokumentów. - **clean** – usuwa katalog `.venv`, pozwalając rozpocząć instalację od zera. - **docker-build** – pakuje aplikację w obraz Dockera z wykorzystaniem `requirements.txt`. - **docker-run** – uruchamia wcześniej zbudowany obraz z podmontowanym katalogiem `docs/` i plikiem `.env`, dzięki czemu można zmieniać korpusy bez przebudowy obrazu. - **docker-shell** – otwiera tymczasowy kontener `python:3.11` z repozytorium zamontowanym pod `/app`; idealne do ręcznego testowania `pip install -r requirements.txt && make run ...` w kontrolowanym środowisku. - **docker-up** – startuje kontener w tle (nazwa `bolmo-rag-run`), - **docker-logs** – tailuje logi działającego kontenera, - **docker-stop** – zatrzymuje i usuwa kontener uruchomiony przez `docker-up`. ### Scenariusz „Docker + logi” 1. Zbuduj obraz i odpal pipeline w tle: ```bash make docker-up FOLDER=./docs QUERY="Co to jest Bolmo?" ``` 2. Podejrzyj logi na żywo (działa jak `docker logs -f`): ```bash make docker-logs ``` 3. Po zakończeniu zatrzymaj kontener: ```bash make docker-stop ``` Jeżeli chcesz jedynie wejść w interaktywnego `bash`a w obrazie referencyjnym, uruchom `make docker-shell`, a następnie w kontenerze wykonaj `python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt && make run ...`. ### Przykładowe użycie celu `run` ```bash make run FOLDER=./docs QUERY="Co to jest Bolmo?" ``` Zmodyfikuj wartości `FOLDER` i `QUERY`, aby wskazać własny zbiór dokumentów oraz pytanie kierowane do modułu RAG. ### Reset i ponowna instalacja środowiska Jeśli chcesz upewnić się, że pracujesz na świeżej konfiguracji, wykonaj kolejno: ```bash make clean # usuwa poprzednią virtualenv make install # ponownie tworzy środowisko i instaluje zależności make run FOLDER=./docs QUERY="Co to jest Bolmo?" # uruchamia RAG na próbkach z docs/ ``` Pierwsze dwa kroki gwarantują czyste środowisko, a trzeci demonstruje pełne wywołanie pipeline'u na przykładowej kolekcji. ## Dalsze kroki - Rozbuduj `rag.py` (lub alternatywny skrypt, np. `bolmo_rag.py`) o własne logiki indeksowania czy interfejs CLI. Makefile i struktura środowiska są gotowe na kolejne rozszerzenia. Powodzenia w pracy z Bolmo RAG! # Bolmo RAG A simple Retrieval-Augmented Generation (RAG) system for processing documents and answering queries based on their content. ## Overview Bolmo RAG allows you to index documents in a specified folder and query them using natural language. It supports three retrieval backends: - `faiss` (default): FAISS with persistent cache in `FOLDER/.rag_cache` (fast repeated runs) - `faiss_nocache`: baseline, rebuilds chunks/embeddings/index on every run - `qdrant`: Qdrant vector database (ingest + query) ## Installation To set up the environment and install dependencies: ```bash make install ``` **Expected Outcome**: This will create a virtual environment and install all necessary packages. You should see the installation process complete with a message indicating the environment is ready. ## Usage ### Quickstart (recommended) Build cache once, then query: ```bash make index BACKEND=faiss FOLDER=./docs make run BACKEND=faiss FOLDER=./docs QUERY="Czym jest Bolmo?" K=5 ``` ### Indexing Documents Indexing requirements depend on the backend: - `faiss`: indexing is persisted in `FOLDER/.rag_cache` (use `make index` or `make reindex`) - `faiss_nocache`: no separate indexing step (everything is built on the fly) - `qdrant`: requires ingest into a Qdrant collection (use `make reindex BACKEND=qdrant` or start Qdrant manually + `make index BACKEND=qdrant`) #### With FAISS Backend (Default) ```bash make index BACKEND=faiss FOLDER=./docs ``` **Expected Outcome**: The system will process all supported document types in the specified folder, create chunks, and build a FAISS index. You should see a message like `Cache/index gotowy.` indicating the index is ready. To force rebuild: ```bash make reindex BACKEND=faiss FOLDER=./docs ``` #### With FAISS Baseline (No Cache) No separate indexing step. Just run: ```bash make run BACKEND=faiss_nocache FOLDER=./docs QUERY="Czym jest Bolmo?" K=5 ``` #### With Qdrant Backend ```bash make reindex BACKEND=qdrant FOLDER=./docs ``` **Expected Outcome**: Similar to FAISS, but the system will (via `make reindex`) attempt to start a local Qdrant container named `qdrant-server` and then ingest the document chunks into a Qdrant collection. You should see `Ingest do Qdrant zakończony.` upon completion. **Note**: Ensure Docker is installed and running for Qdrant backend. ### Querying After indexing (if required), you can query the documents: ```bash .venv/bin/python rag.py --backend faiss --folder ./docs --query "Czym jest Bolmo?" ``` **Expected Outcome**: The system will retrieve relevant document chunks and generate an answer based on the context using the Bolmo model. The response will be in Markdown format with citations to the source documents. #### Specify Backend for Query ```bash .venv/bin/python rag.py --backend qdrant --folder ./docs --query "Czym jest Bolmo?" --k 5 ``` **Expected Outcome**: Same as above, but uses Qdrant for retrieval if the collection exists. ### Reindexing If documents change or you want to force a rebuild of the index: ```bash make reindex BACKEND=faiss FOLDER=./docs ``` or for Qdrant: ```bash make reindex BACKEND=qdrant FOLDER=./docs ``` **Expected Outcome**: The cache and index will be rebuilt from scratch, reflecting any changes in the documents. ## Make targets The default interface is via `make`: ```bash make install make run BACKEND=faiss FOLDER=./docs QUERY="..." K=5 make index BACKEND=faiss FOLDER=./docs make query BACKEND=faiss FOLDER=./docs QUERY="..." K=5 make reindex BACKEND=faiss FOLDER=./docs ``` ## Backend Comparison - **FAISS**: - **Pros**: Lightweight, local, no external dependencies beyond Python packages. Fast for small to medium datasets. - **Cons**: Not designed for distributed systems or very large datasets. Limited scalability. - **Use Case**: Ideal for personal projects or when simplicity and speed are priorities. - **FAISS (no cache)**: - **Pros**: Simplest baseline, no persistent artifacts. - **Cons**: Slow for repeated runs (re-chunking + re-embedding + rebuilding index every time). - **Use Case**: Debugging / one-off runs. - **Qdrant**: - **Pros**: Scalable, supports distributed setups, designed for vector similarity search with advanced features like filtering. - **Cons**: Requires Docker and more setup (server must be running). Slightly slower for small datasets due to network overhead. - **Use Case**: Better for larger datasets or when you need advanced search capabilities and plan to scale. ## Environment Variables You can customize settings via environment variables (see `.env.example` for defaults): - `BOLMO_BACKEND`: Default backend (`faiss`, `faiss_nocache`, or `qdrant`) - `BOLMO_EMBEDDER`: Embedding model (default: `all-MiniLM-L6-v2`) - `BOLMO_MODEL`: Language model for generation (default: `allenai/Bolmo-1B`) - `QDRANT_URL`: URL for Qdrant server (default: `http://localhost:6333`) - `QDRANT_COLLECTION`: Collection name in Qdrant (default: `bolmo_docs`) - `BOLMO_CHUNK_SIZE`: Size of text chunks (default: `800`) - `BOLMO_CHUNK_OVERLAP`: Overlap between chunks (default: `200`) - `BOLMO_FORCE_CPU`: Force CPU usage even if CUDA is available (`1` or `true`) ## Benchmarks There is a benchmark script that measures retrieval speed and a simple quality proxy (`hit@k`) for all three backends: ```bash python benchmarks/benchmark_rag.py --folder ./docs --k 5 --reindex ``` More examples are in `BENCHMARKS.md`. ## Tests ```bash make test ``` Optional Qdrant smoke tests (requires running Qdrant): ```bash RUN_QDRANT_TESTS=1 QDRANT_URL=http://localhost:6333 make test ``` ## Troubleshooting - **Qdrant Connection Issues**: Ensure Docker is installed and the Qdrant container is running (`docker ps` to check). Restart with `docker restart qdrant-server` if needed. - **Model Loading Errors**: Check if CUDA is properly set up if using GPU. Set `BOLMO_FORCE_CPU=1` to fallback to CPU.