ADR-0022: Dokumentacja i stos RAG¶
Status: Zaakceptowano Ostatnia aktualizacja: 2026-03-12
Streszczenie podjętej decyzji¶
Platforma Jorvis wykorzystuje zestaw narzędziowy zbudowany wokół:
- MkDocs na rzecz renderowania przejrzystej i zorganizowanej warstwy dokumentacji
- Open WebUI + pgvector stanowiących centralne komponenty systemu klasyfikacji danych z czatu oraz przeszukiwania semantycznego w ramach procedur RAG
- Przetworników formatów ProcessorFactory ukierunkowanych na wydajne importowanie plików firmowych prosto do obszarów indeksowania i konwersacji.
Wspierane źródła i typy do importu¶
- Źródła i chmura: Pliki z Google Docs, dysków zdalnych (Google Drive), tabele ze środowiska Google Sheets (wszystko uruchamiane domyślnie wyłącznie z uprawnieniami read-only)
- Pliki biurowe: Dokumenty PDF, raporty DOCX oraz XLSX, a także bazy prezentacyjne (PPTX)
- Środowiska i zapisy strukturalne: Typowe zbiory z ustandaryzowaną składnią: ciągi tekstowe (plain text), rozszerzenia internetowe HTML, konfiguracje z plików JSON, dokumentacje typu Markdown i bazy danych w rozszerzeniach CSV.
- Implementacja embeddingu: Zawartość źródłowa ulega automatycznemu poszatkowaniu, po czym zamieniana jest na odrębne powiązane formacje wektorowe i deponowana bezpiecznie po stronie systemu
pgvector. Wymiarowanie realizuje na tym etapie wyodrębniony moduł z grupy produktów Gemini.
Analiza uzasadniająca wybór tego stosu technologicznego¶
- Wysoce kompatybilna natura z wewnętrznym i self-hosted stosem Jorvis.
- Redukcja potencjalnych zakłóceń sprzętowych po stronie samego środowiska generatywnego (niskie obciążenie zasobów).
- Kompleksowe wsparcie integracji schematów wektorowych czy wykresów strukturalnych wytycznych na platformie ustandaryzowanej przez Mermaid, oferującej pełne generowanie środowiska typu "Static".
- Usystematyzowana koncepcja "ProcessorFactory" tworzy architekturę zdolną do szybkiej ewolucji. W razie konieczności dopięcia nowego formatu od strony użytkownika można po prostu wydłużyć kolejkę zadań fabryki nie destabilizując reszty logiki biznesowej.
Efekt z punktu widzenia upublicznionych stron referencyjnych¶
Obecnie wyodrębnione panele prezentujące wizualnie logikę wewnętrzną oraz instrukcje nawigacyjne na podstronach Jorvis połączone są z niezależnym modułem mkdocs-public.yml. Zabieg ten sprawia, iż wizyty po stronie adresu /reference-pl/ wyświetlają się dla badającego dokumentację użytkownika czy analityka jako klasyczne, wyrenderowane wizualizacje front-endowe na podstawie standardów HTML. Dzieje się to kosztem starszego wymuszania na interfejsach operowania natywnym tekstem (formatki standardowe z tagami Markdown).