Strona główna / Artykuły

Lokalny pipeline RAG z Qdrant, fastembed i Gemini w Pythonie

Mała pipeline RAG w Pythonie: dzieli lokalne dokumenty na fragmenty, wgra je offline za pomocą fastembed, przechowuje wektory w Qdrant i odpowiada na pytania za pomocą Gemini z interfejsu wiersza poleceń.

Wydawca: REACTAPP.TOP6 min czytania1485 słów

Źródła: How to Build a Simple RAG Pipeline using Qdrant

Ustawienie specjalistycznego RAG (retrieval-augmented generation) wydaje się trudniejsze, niż w rzeczywistości jest. Panuje przekonanie, że potrzebna jest cała infrastruktura korporacyjna, aby model językowy mógł czytać lokalne pliki. To nieprawda. Pełnie funkcjonalny, stopniowy proces może działać na jednym komputerze przy użyciu Qdrant i Gemini, bez konieczności stosowania ciężkich frameworków ani zarządzania serwerem. Poniżej opisano, jak to działa, co robi kod oraz jak go uruchomić.

Problem, który rozwiązuje RAG

Modele językowe znają jedynie dane treningowe. Nigdy nie widziały twoich notatek, raportów ani pliku PDF, który zapisałeś dziś rano. RAG eliminuje tę luki. Zamiast liczyć na to, że model odgadnie odpowiedź na podstawie ogólnej wiedzy, system wyszukuje w twoich dokumentach odpowiednie fragmenty, przekazuje je modelowi i każe mu odpowiadać wyłącznie na podstawie tego kontekstu. Dzięki temu model przestaje wymyślać rzeczy, ponieważ czyta twoje materiały.

Zwykłe wyszukiwanie według słów kluczowych mogłoby znaleźć te fragmenty, ale szybko traci skuteczność, dlatego zwykle wybiera się wyszukiwanie wektorowe.

Wektory i wyszukiwanie wektorowe

Wektor to lista liczb reprezentująca znaczenie fragmentu tekstu. Przekształcając „how are you” i „how old are you” na wektory, można obliczyć, na jak duży stopień są one podobne. Wyszukiwanie wektorowe wykorzystuje tę koncepcję do znajdowania odpowiedzi nawet wtedy, gdy sformułowanie jest inne. Pytanie oraz każdy fragment dokumentu są umieszczane w tym samym przestrzeni liczbowej, a zwycięża ten, który ma najbliższe znaczenie. Jest to istotne, ponieważ ludzie rzadko formułują pytania w taki sam sposób jak dokumenty. Osoba pytająca „how do I get my money back” nadal potrzebuje sekcji zatytułowanej „Polityka zwrotów”.

Proces RAG stanowi element łączący wszystko to ze sobą. Zazwyczaj składa się on z sześciu kroków:

  1. Przyjmowanie danych: plik trafia do folderu, documents/ w tym kodzie.
  2. Dzielenie na fragmenty: skrypt dzieli plik na mniejsze, nakładające się na siebie części. Poszukiwanie 50-stronicowego dokumentu jako jednej całości nie działa, dlatego konieczne jest jego podzielenie.
  3. Wbudowywanie: mały lokalny model przekształca każdy fragment w wektor, dzięki czemu fragmenty o podobnych tematach znajdują się blisko siebie.
  4. Przechowywanie: wektory trafiają do Qdrant, bazy danych wektorowych stworzonej tak, by przyjmować nowy wektor i szybko zwracać najbliższe dopasowania spośród milionów. Jest szybka, open source i działa lokalnie, bez konieczności konfiguracji serwera czy konta.
  5. Wyzyskiwanie wyników: pytanie również jest wbudowywane, a Qdrant zwraca fragmenty najbliższe mu, te, które najprawdopodobniej zawierają odpowiedź.
  • Generowanie: pobrane fragmenty są umieszczane w promptzie i wysyłane do Gemini, które tworzy odpowiedź opartą na rzeczywistych dokumentach.
  • Kroki od 1 do 4 są wykonywane automatycznie za pomocą flagi -i lub narzędzia monitorującego -w, dzięki czemu dokumenty zawsze są dostępne do wyszukiwania. Kroki 5 i 6 odbywają się na żądanie, gdy używana jest flaga -q.

    Implementacja w Pythonie

    Kod pozostaje lekki i unika dużych frameworków, więc łatwo jest zobaczyć, dokąd trafiają dane.

    Czytanie plików

    Najpierw należy znaleźć pliki i wydobyć z nich surowy tekst, niezależnie od tego, czy są to notatki w formacie Markdown, czy nieuporządkowane dokumenty Word:

    def read_document(path) -> str:
        # dispatches on extension: .txt/.md read directly,
        # .pdf via pypdf, .docx via docx2txt -> returns plain textdef file_status(path, state) -> str:
        # "not_indexed" if never seen, "modified" if file_hash(path)
        # differs from the hash stored in state, else "indexed"
    

    Dzielenie na fragmenty

    Następnie tekst jest dzielony za pomocą prostego okna przesuwającego się, dzięki czemu zdanie przekraczające granicę zachowuje swój kontekst:

    def chunk_text(text, chunk_size=500, overlap=50) -> list:
        words = text.split()
        step = chunk_size - overlap
        return [" ".join(words[i:i+chunk_size])
                for i in range(0, len(words), step)]
    

    Embeddingi i stabilne ID

    Proces embeddingu odbywa się lokalnie, bez żadnych zewnętrznych wywołań API na każde zdanie. Każdy fragment otrzymuje również przewidywalny ID uzyskany na podstawie hasha jego tekstu, dzięki czemu niezmieniony tekst zachowuje ten sam ID w każdym uruchomieniu:

    def chunk_ids_for(chunks) -> dict:
        # id = uuid5(namespace, chunk_text) for each chunk
        # -> same text always gets the same id, across re-indexes
        ...
    

    Samo wgranie odbywa się wewnątrz wywołania Qdrant:

    # inside index_file():
    client.add(collection_name=index_name, documents=new_chunks, ids=new_ids)
    # Qdrant's fastembed integration embeds `documents` automatically
    

    Synchronizacja plików z bazą danych

    Tutaj lokalne pliki są dostosowywane do bazy danych. Poprawka błędu pisowni nie usuwa indeksu ani nie wymusza ponownego uruchomienia. Kod porównuje ID, usuwa fragmenty, które zniknęły, oraz dodaje nowe:

    def index_file(path, state) -> bool:
        chunks = chunk_text(read_document(path))
        new_ids = chunk_ids_for(chunks)
        old_ids = state[path.name].chunk_ids  # from last time
        client.delete(collection_name, ids=old_ids - new_ids)   # removed chunks
        client.add(collection_name, ids=new_ids - old_ids, ...)  # new/changed chunks
        state[path.name] = {...updated record...}
    

    Pliki usunięte z foldera są również oczyszczane:

    def prune_deleted(state) -> int:
        # for each file in state no longer present in DOCUMENT_DIR:
        #     delete its Qdrant collection, drop its state entry
    

    Odpowiadanie na zapytanie

    Gdy przychodzi pytanie, Qdrant musi znaleźć najlepsze dopasowania wśród wybranych dokumentów. Najpierw narzędzie pomocnicze określa, w których indeksach należy przeprowadzić wyszukiwanie:

    def resolve_index_names(spec, state) -> list:
        # "all" -> every indexed collection; "a,b" -> ["a","b"], validated
    

    Następnie zapytanie jest wykonywane dla każdego z nich, a wyniki są łączone:

    def cmd_query(index_spec, question, top_k, show_sources):
        for name in resolve_index_names(index_spec, state):
            hits += client.query(collection_name=name, query_text=question, limit=top_k)
        hits = sorted(hits, key=score, reverse=True)[:top_k]
    

    Generowanie

    W końcu pozyskane fragmenty trafiają bezpośrednio do Gemini, które porównuje je z podanym tekstem:

    def generate_answer(question, context) -> str:
        prompt = f"Answer using only this context:\n{context}\n\nQuestion: {question}"
        return genai.Client(api_key=...).models.generate_content(
            model=GEMINI_MODEL, contents=prompt
        ).text
    

    Pozostała część to kod pomocniczy. get_client() otwiera połączenie z Qdrant, load_state() i save_state() czytają oraz zapisują plik .rag_state.json, a sanitize_index_name() przekształca nazwy plików w ważne nazwy kolekcji. Funkcje poleceń (cmd_list_files, cmd_index, cmd_watch) łączą wszystko z flagami linii poleceń.

    Uruchamianie lokalnie

    Klonuj repozytorium i przenieś się do folderu projektu:

    git clone https://github.com/Shivvam/rag-pipeline-qdrant.git
    cd rag-cli
    

    Następnie utwórz środowisko, zainstaluj wymagane elementy i skonfiguruj plik konfiguracyjny:

    python3 -m venv venv
    source venv/bin/activate   # on Windows: venv\Scripts\activate
    pip install -r requirements.txt
    cp .env.example .env   # then edit in your GEMINI_API_KEY
    

    Włącz ponownie środowisko wirtualne w dowolnym nowym terminalu przed uruchomieniem app.py. Aby -q mogło generować odpowiedzi, konieczne jest ustawienie GEMINI_API_KEY, podczas gdy pozostałe polecenia działają bez niego.

    Użycie w linii poleceń

    Wszystko związane z pobieraniem danych i ich wyszukiwaniem odbywa się z terminala. Aby zobaczyć, które pliki znajdują się w folderze dokumentów i które wymagają uwagi, lub jakie indeksy istnieją:

    python app.py -lf                        # list files in ./documents + status
    python app.py -li                        # list existing indexes
    

    Aby przetworzyć nowe dokumenty lub zaktualizować te, które uległy zmianie:

    python app.py -i myfile.md               # index one file (or re-index if changed)
    python app.py -i all                     # index every not_indexed/modified file
    

    Aby uzyskać automatyczne indeksowanie podczas edycji, utrzymuj to w tle w drugim terminalu:

    python app.py -w                          # watch ./documents, auto-index on add/edit
    

    Aby zadać pytania dotyczące jednego pliku, kilku plików lub wszystkiego:

    python app.py -q report "What is X?"      # query a single index
    python app.py -q report,notes "What is X?"  # query multiple indexes together
    python app.py -q all "What is X?" --sources # query everything, show retrieved chunks
    python app.py -q report "..." -k 8        # retrieve top 8 chunks instead of default 5
    

    Stan pokazywany przez -lf może przyjmować trzy wartości. not_indexed oznacza, że plik nigdy nie został przetworzony, indexed oznacza, że jest aktualny, a modified oznacza, że uległ zmianie od ostatniego uruchomienia i należy powtórzyć użycie -i.

    Decyzje projektowe

    Kilka decyzji sprawia, że proces jest szybki i prosty.

    • Qdrant: każdy plik ma swoją własną kolekcję, nazwaną na podstawie oczyszczonego nazwy pliku, z dodanym numerowym sufiksem w przypadku kolizji. Domyślnie używa lokalnego trybu na dysku (./qdrant_storage), więc nie jest potrzebny żaden serwer. Aby umożliwić jednoczesny dostęp, ustaw QDRANT_URL w pliku .env tak, aby wskazywał na rzeczywisty serwer Qdrant. Tryb lokalny blokuje katalog dla jednego procesu, więc -w i -q nie mogą działać jednocześnie.
    • Embeddings: model BAAI/bge-small-en-v1.5 jest uruchamiany za pomocą fastembed. Jest on pobierany raz i przechowywany w pamięci cache, dzięki czemu nie ma kosztów związanych z API ani zależności od sieci podczas wysyłania zapytań.
    • Gemini: zapisuje jedynie ostateczną odpowiedź z pobraanych fragmentów tekstu, przy czym domyślnie używany jest model gemini-3.5-flash.
    • State: plik .rag_state.json rejestruje hashe plików, status, nazwy indeksów oraz liczbę fragmentów, co umożliwia szybkie użycie opcji -lf i -li, ponieważ Qdrant nie musi ponownie skanować danych. ID fragmentów pochodzą bezpośrednio z tekstu, więc ponowne indeksowanie odbywa się stopniowo – tylko zmienione fragmenty są ponownie włączane do indeksu i aktualizowane.
    • Typy plików: .txt i .md działają natychmiast. .pdf i .docx wymagają biblioteki pypdf lub docx2txt, które obie są już wymienione w wymaganiach.

    Literatura pokrewna