RAG Chatbot NeoGadżet — zaawansowany pipeline retrieval-augmented generation

Projekt powstał jako dowód koncepcji: jak podłączyć chatbota opartego na LLM do własnej bazy wiedzy firmy — i zrobić to lepiej niż prymitywny RAG. Zamiast prostego “weź embedding zapytania → wyszukaj → wyślij do GPT”, pipeline zawiera cztery etapy, z których każdy poprawia jakość odpowiedzi: przepisanie zapytania, podwójne wyszukiwanie, LLM-reranking i asemblowanie kontekstu ze źródłami.

Baza wiedzy to zestaw plików Markdown opisujących produkty (AeroSound X2, HomeCam Mini 2K, WiLink AX1800, FitTime Pro), regulaminy dostawy, politykę zwrotów, gwarancję i FAQ — 10 dokumentów, które LLM dzieli na chunki z nakładaniem (overlap ~25%) i własnoręcznie generowanymi nagłówkami i streszczeniami.

01Pipeline RAG — cztery etapy

To co wyróżnia ten projekt to fakt, że każde pytanie przechodzi przez cztery oddzielne wywołania LLM zanim użytkownik zobaczy odpowiedź. Każdy etap jest niezależny, ma retry z exponential backoff i structured output przez Pydantic.

02Ingest — LLM-based chunking

Większość tutoriali RAG używa prostego splitu po X znakach lub zdaniach. Ten projekt robi inaczej: LLM sam dzieli dokumenty na chunki, generując dla każdego fragmentu nagłówek (headline), streszczenie (summary) i oryginalny tekst (original_text). Wynik zapisywany do ChromaDB to konkatenacja tych trzech pól — wyszukiwanie trafia na nagłówki dopasowane semantycznie do typowych pytań użytkownika.

class Chunk(BaseModel):
    headline:      str  # "Nagłówek prawdopodobnie będzie użyty w zapytaniu"
    summary:       str  # kilka zdań streszczenia
    original_text: str  # oryginalny fragment dokumentu

    def as_result(self, document):
        # wektor jest tworzony z headline + summary + original_text
        # → embedding "rozumie" kontekst, nie tylko surowy tekst
        return Result(
            page_content=self.headline + "\n\n" + self.summary + "\n\n" + self.original_text,
            metadata={"source": document["source"], "type": document["type"]}
        )

Przetwarzanie dokumentów jest zrównoleglone przez multiprocessing.Pool(processes=3) z progress barem (tqdm). Każde wywołanie ma retry z exponential backoff przez dekorator @retry(wait=wait_exponential(min=10, max=240)) — odporność na rate limiting OpenAI przy bulk processingu.

03LLM Re-ranking — zamiast modelu cross-encoder

Klasyczny reranking w RAG używa dedykowanego modelu (np. cross-encoder z Hugging Face). Tutaj zastosowałem inne podejście: LLM jest poproszone o posortowanie chunków według trafności i zwrócenie listy ich ID przez response_format=RankOrder. Structured output przez Pydantic zapewnia, że model nie może zwrócić “na oko” — musi podać konkretną listę liczb całkowitych w poprawnej strukturze JSON.

class RankOrder(BaseModel):
    order: list[int] = Field(
        description="Kolejność istotności fragmentów, od najbardziej do najmniej istotnych"
    )

def rerank(question, chunks):
    # prompt z numerowanymi chunkami → LLM sortuje → Pydantic waliduje
    response = completion(model=MODEL, messages=messages,
                          response_format=RankOrder, timeout=30, max_retries=0)
    order = RankOrder.model_validate_json(reply).order

    # filtracja błędnych indeksów + fallback na oryginalne chunks
    valid_chunks = [chunks[i-1] for i in order if 1 <= i <= len(chunks)]
    return valid_chunks if valid_chunks else chunks  # bezpieczny fallback

04Architektura systemu

05Interfejs — sklep + popup chatbot

Frontend to statyczny HTML/CSS/JS renderowany przez Jinja2 (Flask). Strona symuluje prawdziwy sklep z elektroniką NeoGadżet — działający header z nawigacją, hero z floating card produktu, siatka kategorii (Audio, Kamery, Sieć, Wearables, Komputery, Smart Home), 4 karty produktów z cenami i przyciskami koszyka, sekcja benefitów (dostawa, zwroty, gwarancja, wsparcie 24/7) i stopka.

Chatbot siedzi jako popup widget w prawym dolnym rogu — przycisk z ikoną i badge “1 nowa wiadomość”. Kliknięcie otwiera okno czatu z:

• Avatar robota i status “Online” z zieloną kropką
• Sugerowane pytania — 3 przyciski-skróty (“Koszt dostawy?”, “Jak zwrócić?”, “AeroSound X2 ANC?”)
• Wiadomości z źródłami — po odpowiedzi AI frontend renderuje listę plików-źródeł z typem (products/policies/faq) i fragmentem tekstu
• Historia sesji — Flask trzyma ostatnie 20 wiadomości per session_id w pamięci serwera
• Przycisk czyszczenia historii wywołujący POST /api/clear

06Struktura projektu

07REST API

Przykładowa odpowiedź /api/chat

{
  "response": "Dostawa do paczkomatu InPost kosztuje 12.99 zł...",
  "sources": [
    {
      "type": "sections",
      "source": "knowledge-base/sections/dostawa_i_koszty.md",
      "content": "Koszty dostawy: Paczkomat InPost - 12.99 zł, Kurier DPD..."
    }
  ],
  "session_id": "user123",
  "timestamp": "2026-04-21T20:15:32.000Z"
}

08Kluczowe decyzje techniczne

09Czego dowodzi ten projekt