Minimalne wymagania systemowe

Jedna instacja czatu działa bez zarzutu gdy posiadasz:

- 2GB RAM

- CPU 2 Core ~2GHz

- 10GB storage

Szybki start

1. Pobierz repozytorium:
git clone rocket-assistant
2. Stwórz plik .env w folderze backend i wklej tam zmienną globalną:
OPENAI_API_KEY={Twój klucz API do modeli od OpenAI}
(przykład: sh-proj-123123123123)
3. Stwórz plik .env w folderze frontend który zawiera:
NEXT_PUBLIC_WS_UR={Adres websocket aplikacji backend} (przykład: wss://localhost:8080/ws)
4. Wklej wiedze, którą będzie posługiwał się czat do pliku tekstowego chat_knowledge.txt w folderze backend/user_data
cp ./wiedza.txt user_data/chat_knowledge.txt

cp - linuxowa komenda do kopiowania zawartości, możesz też to zrobić ręcznie za pomocą np. VSCode

5. Uruchom cały projekt za pomocą polecenia:
docker compose up -d

Ważne! Upewnij się, że wpisujesz komendę będąc w folderze w którym znajduje się plik docker-compose.yml


To wszystko!

Projekt uruchomi się z domyślnymi parametrami ale już możesz z niego korzystać, bo działa na Twojej bazie wiedzy!

Start projektu- szczegółowy opis i konfiguracja

Najważniejsze parametry niezbędne do uruchomienia projektu zostały szczegółowo opisane w sekcji Szybki start. Dodatkowo, dostępnych jest więcej opcji konfiguracyjnych, które pozwolą Ci na jeszcze lepsze dostosowanie działania produktu do własnych potrzeb oraz zapewnią większą kontrolę nad jego funkcjonalnością.

W momencie pierwszego uruchomienia aplikacji komendą: 

docker compose up -d

W trakcie inicjalizacji pobierane są wszystkie niezbędne obrazy Dockerowe oraz biblioteki wymagane do poprawnego działania frontendowej i backendowej części systemu.

Po zakończeniu pobierania komponentów uruchamiany jest proces wektoryzacji. Polega on na przekształceniu dostarczonej bazy wiedzy - zazwyczaj obszernego dokumentu tekstowego – na mniejsze fragmenty, które zostają umieszczone w przestrzeni wektorowej.

Dzięki temu dane zostają automatycznie uporządkowane tematycznie, co znacząco ułatwia sztucznej inteligencji szybki i trafny dostęp do informacji podczas późniejszego użytkowania systemu.

Operacja wektoryzacji jest usługą płatną i zostanie przeprowadzona wyłącznie po wprowadzeniu poprawnego i aktualnego klucza OpenAI API Key. Szczegółowe informacje na temat kosztów tej operacji znajdują się w sekcji Koszty.

Po pierwszym uruchomieniu projektu i pomyślnym zakończeniu procesu wektoryzacji, możesz przejrzeć swoją kolekcję wiedzy, korzystając z poniższego linku:

http://localhost:6333/dashboard#/collections

W tym miejscu znajdziesz utworzoną kolekcję o nazwie prod_embedding, zawierającą Twoją przetworzoną bazę wiedzy w formie wektorów.

Jeśli chcesz wyłączyć automatyczne wykonywanie wektoryzacji przy każdym uruchomieniu aplikacji, przejdź do pliku konfiguracyjnego:

backend/src/user_data/chat_config.json

i zmień wartość parametru:

"vectorized_on_rebuild": true

na

"vectorized_on_rebuild": false

Dzięki temu przy kolejnych uruchomieniach aplikacja będzie korzystać z wcześniej utworzonej kolekcji, bez ponownego wykonywania kosztownego procesu wektoryzacji.

Parametry konfiguracyjne (chat_config.json)

vectorize_line_size <- określa ile linii Twojej wiedzy wchodzi do kolekcji bazy wektorowej. Aktualnie ta wartość jest ustawiona na 4 i jest to domyślny parametr, który działa bardzo dobrze w większości przypadków. Poniżej przykład tekstu, każdy inny kolor przedstawia jak ta baza wiedzy została podzielona z parametrem 4.

Aby przygotować domowe gofry,
należy w misce dokładnie wymieszać
dwie szklanki mąki pszennej z dwiema
łyżkami cukru, dwiema łyżeczkami

proszku do pieczenia oraz szczyptą
soli. W osobnym naczyniu łączymy
dwie szklanki mleka, dwa jajka oraz
około 100 gramów roztopionego masła

lub oleju roślinnego, a następnie
całość dokładnie mieszamy. Suche
składniki łączymy z mokrymi i mieszamy
do uzyskania gładkiej, dość gęstej masy.

Jeżeli chcesz aby Twoja baza wiedzy została podzielona na większe fragmenty, możesz zmienić ten parametr. Pamiętaj jednak aby ustawić po tym również parametr:

vecorized_on_rebuild na true. Co sprawi, że wykona się wektoryzacja z innym parametrem.

Jeżeli Twoja wiedza posiada długie zagadnienia, które wymagaja głębszego wchodzenia w detale, możesz podnieść wartość tego parametru. Wtedy w każdym fragmencie będzie przechowywane nieco więcej informacji.

qdrant_topk <- ten parametr określa jak dużo fragmentów, które opisałem wyżej dostaje sztuczna inteligencja do odpowiadania na pytanie. Domyślnie jest ona ustawiona na 5.

Gdy pytaj Chat o jakieś zagadnienia, AI do odpoiwedzenia bazuje na tych fragmentach. Im więcej mu je przekażesz tym odpowiedź będzie precyzyjniejsza. Ten parametr warto dobrać eksperymentalnie bo nie zawsze więcej znaczy lepiej, bo większa ich ilość generuje większy koszt odpowiedzi.

Jeżeli w swojej bazie wiedzy masz kilka albo kilnaście różnych rozwlekłych zagadnień warto ten parametr podnieść, aby AI miał możliwość lepiej poznać Twoje zagadnienia zanim odpowie. Jeżeli jednak Twoja baza wiedzy posiada dość krótkie tematy, których opis zmieściłby się w kilku zwektoryzowanych fragmentach, możesz mieć niższą wartość parametru qdrant_topk.

Personalizacja komunikatów (settings_prompts.json)

Plik konfiguracyjny personalizacji komunikatów znajduje się w backend/src/user_data/settings_prompts.json i zawiera dwa parametry:

welcome_msg <- możesz tutaj zadeklarować co Chat ma napisać jako pierwsza powitalna wiadomość. Domyślna wartość to:

"Hej, jestem Twoim ekspertem. Chętnie porozmawiam!"

system_prompt <- służy ona do nadania roli w jaką wdziela się nasza sztuczna inteligencja odpowiadająca na pytania. Domyślna wartość tego parametru to:

"Otrzymasz wiedzę. Twoja odpowiedź musi bazować tylko na dostarczonej wiedzy"

Sugerowane dodatki do system_prompt:

  • Dodaj informacje o reagowaniu na brak wiedzy („...odpisz: Niestety nie mam wystarczającej wiedzy...”)
  • Możliwość zapamiętywania imienia użytkownika
  • Odpowiednie reagowanie na wulgarne wiadomości

Przykłady:

"... jeżeli w bazie danych nie znajdziesz wystarczającej wiedzy aby odpowiedzieć, odpisz: Niestety nie mam wystarczającej wiedzy aby odpowiedzieć na to pytanie"
"... jeżeli użytkownik się przywita i poda swoje imie, to je zapamiętaj i przy odpowiadaniu posługuj się imieniem użytkownika"
"... jeżeli użytkownik jest nie miły i wulgarny, to odpowiedz mu, że nie możesz odpowiadać na wulgarne wiadomości"

Zalecamy zapoznanie się z tematem Prompt Engineering w celu lepszego dostosowania działania AI.

Poprawne przygotowanie bazy wiedzy

Aby baza wiedzy była skuteczna i zrozumiała, kluczowe jest zachowanie logicznej i spójnej struktury.

  • Układ treści powinien być przemyślany: zacznij od tematów podstawowych, a następnie przechodź do bardziej zaawansowanych. Unikaj chaotycznego przeskakiwania między zagadnieniami.
  • Każde zagadnienie omawiaj w całości - od początku do końca - zanim przejdziesz do kolejnego.
  • Informacje dotyczące jednego tematu powinny być umieszczone blisko siebie. Rozbijanie jednego wątku na wiele fragmentów rozproszonych po różnych częściach dokumentu utrudnia zarówno zrozumienie, jak i przetwarzanie danych.

Praca z materiałami źródłowymi (np. PDF)

Jeśli tworzysz bazę wiedzy na podstawie plików PDF, szczególną uwagę zwróć na tabele:

  • Nie kopiuj tabel bezpośrednio do dokumentu.
  • Zamiast tego wklej tabelę do narzędzia takiego jak ChatGPT i poproś o przekształcenie jej w zrozumiały opis tekstowy - pełnymi zdaniami.

To znacznie zwiększa czytelność i ułatwia analizę zawartości.

Dobre praktyki

  • Unikaj technicznego żargonu i zbędnych komplikacji.
  • Nie wprowadzaj dygresji, które nie wnoszą wartości do treści.
  • Im prostszy, bardziej uporządkowany przekaz – tym lepiej.

Uruchamianie projektu na serwerze - case study

  1. Połącz się z serwerem przez SSH
    Otwórz terminal i wpisz poniższą komendę: 
    ssh user@serwer_serwer.us -p 12345

  2. Sprawdź, czy masz zainstalowane wymagane narzędzia
    Projekt wymaga obecności GIT oraz Dockera z Docker Compose.
    Aby to sprawdzić, wpisz w terminalu: 
    docker -v
git -v

    Jeśli komendy zwracają wersję, oznacza to, że narzędzia są poprawnie zainstalowane.

  3. Sklonuj repozytorium
    git clone https://github.com/rocket-house-dev/rocket-assistant

    Po pobraniu repozytorium przejdź do folderu 
    cd rocket-assistant

  4. Utwórz pliki .env
    W folderach backend oraz frontend utwórz pliki .env które będą przechowywać zmienne środowiskowe dla tych usług. Skorzystaj z plików .env.example, które znajdują się w tych folderach, skopiuj je i uzupełnij własnymi danymi 
    cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env

  5. Sprawdź i dostosuj porty w docker-compose.yml
    W pliku docker-compose.yml przy każdej usłudze znajdziesz sekcję ports, np.: 
    ports:
 	- "8000:8000"

    Format tej deklaracji to: 
    HOST_PORT:CONTAINER_PORT
    • Lewa strona (HOST_PORT) – port widoczny na Twoim komputerze (maszynie hosta)
    • Prawa strona (CONTAINER_PORT) – port, na którym działa aplikacja wewnątrz kontenera
    Upewnij się, że porty po stronie hosta nie kolidują z innymi aplikacjami uruchomionymi na Twoim systemie (np. innym backendem, frontendem czy serwerem).

  6. Uruchomienie
    W katalogu głównym repozytorium (tam, gdzie jest docker-compose.yml) uruchom: 
    docker compose up -d

    To polecenie utworzy wymagane obrazy i kontenery Docker oraz uruchomi wszystkie usługi w tle.
  7. Podgląd logów i zatrzymywanie aplikacji
    Możesz monitorować usługi uruchamiając logi uruchomionych usług 
    docker compose logs -f

    Dodając nazwę usługi, możesz przefiltrować logi konkretnego kontenera, np.: 
    docker compose logs -f backend
docker compose logs -f frontend

    Aby poprawnie zatrzymać aplikację użyj: 
    docker compose down -t0

    Polecenie down:
    • zatrzymuje wszystkie kontenery,
    • usuwa je,
    • usuwa sieci Dockera utworzone dla projektu (ale nie usuwa danych trwale zapisanych w wolumenach).

Wystawienie aplikacji na świat z użyciem własnych domen

Poniższy przykład pokazuje, jak udostępnić czat na zewnątrz własnej sieci i skonfigurować dostęp przez własne domeny. W tym przykładzie użyto serwera NGINX jako reverse proxy.

Zakładamy, że
  • aplikacja frontendowa działa na porcie 3000,
  • backend działa na porcie 8000,
  • masz własne domeny (np. twoja-domena.com i api.twoja-domena.com) skierowane w DNS na adres Twojego serwera,
  • NGINX działa na porcie 80 (HTTP) i obsługuje ruch z zewnątrz.

Konfiguracja jest podzielona na dwa pliki – osobno dla frontendu i backendu – co ułatwia zarządzanie projektem.


Plik frontend.conf 

server {
    listen 80;
    server_name twoja-domena.com www.twoja-domena.com;  

    location / {
        proxy_pass http://localhost:3000/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        try_files $uri $uri/ /index.html;
    }
}

Plik backend.conf 

server {
    listen 80;
    server_name api.twoja-domena.com; 

    location / {
        proxy_pass http://localhost:8000/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Zmienna globalne - opis

Najważniejszą zmienną globalną w pliku .env backendu jest:

OPENAI_API_KEY

Bez tej zmiennej aplikacja nie będzie działać - jest ona kluczowa do komunikacji z usługą OpenAI.

Oprócz niej masz do dyspozycji kilka dodatkowych zmiennych, które pozwalają na bardziej zaawansowaną konfigurację i modyfikację działania aplikacji.

RESPONSE_MODEL

Określa nazwę modelu językowego, który ma zostać użyty do wygenerowania odpowiedzi.

Nie wszystkie modele są dostępne w każdym planie API – niektóre (np. gpt-4o) mogą wymagać subskrypcji wyższego planu.

Zalecane jest sprawdzenie aktualnej dostępności modeli w dokumentacji API OpenAI. Domyślnie jest to gpt-4o-mini.

RESPONSE_TEMPERATURE

Parametr sterujący poziomem losowości odpowiedzi generowanych przez model. Przyjmuje wartości z zakresu od 0.0 do 2.0.

  • Niższe wartości (np. 0.2) powodują, że model jest bardziej deterministyczny i zachowawczy, preferując najczęściej spotykane odpowiedzi.
  • Wyższe wartości (np. 1.0 i więcej) zwiększają kreatywność i różnorodność odpowiedzi, ale mogą obniżyć ich spójność.

Domyślna wartość którą proponujemy ustawić dla czatu to 0.7.

QDRANT_URL

Adres URL instancji serwera Qdrant, używany do komunikacji z wektorową bazą danych.

W przypadku środowiska opartego na Dockerze na którym domyślnie uruchamiany jest projekt, należy używać nazwy kontenera jako hosta

http://qdrant:6333

Koszty korzystania z aplikacji

Aplikacja wykorzystuje dwa modele sztucznej inteligencji od OpenAI:

  1. Model text-embedding-3-small
    Służy do przekształcania bazy wiedzy w tzw. wektory (czyli "zrozumiałą" dla AI formę danych).
    Koszt: 0,02 USD za 1 milion tokenów.

    Przykład:
    Baza wiedzy o długości 50 000 znaków (około 8–10 stron A4) generuje około 16 000 tokenów.
    Koszt takiej operacji to jedynie 0,00032 USD.
  2. Model gpt-4o-mini
    Odpowiada za generowanie odpowiedzi.
    Koszt: 0,80 USD za wygenerowanie około 4 milionów znaków odpowiedzi (czyli ok. 1 000 stron A4).

    Przykład kosztu jednej odpowiedzi:
    Dla prostego pytania, korzystającego z Twojej wiedzy, koszt odpowiedzi wynosi około 0,00047 USD
    (przy założeniu: vectorize_line_size=4, qdrant_topk=5 i tylko jedno pytanie w historii rozmowy).

Co warto wiedzieć:

  • Koszty każdej interakcji mogą się minimalnie różnić w zależności od długości historii rozmowy i ustawień technicznych.
  • Już teraz są to bardzo niskie kwoty.
  • W przyszłości planowane jest wdrożenie tańszego modelu DeepSeek – nawet o 50% mniej kosztów.

Przydatne linki:

Troubleshoot

Zmienna globalna w pliku .env powinna wyglądać tak:

OPENAI_API_KEY=sk123123123123123123123

Klucz rozpoczyna się od “sk” i wymaga wklejenia go bez cudzysłowii.

Umiejętności które pozwalają na swobodny rozwój aplikacji

Aplikacja oparta jest na architekturze mikroserwisowej i korzysta z bazy wektorowej Qdrant, Redis jako pamięć podręczna oraz frontend w React. Wszystkie komponenty uruchamiane są w środowisku kontenerowym (Docker). W związku z tym od osób rozwijających system oczekuje się znajomości poniższych technologii i narzędzi.

Backend:

  • Python (3.9+)
    • Tworzenie API (FastAPI, Flask lub inne frameworki)
    • Integracja z modelami LLM (np. OpenAI, Transformers, itp.)
  • Redis
    • Podstawowe operacje (cache, pub/sub, session storage)
  • Qdrant
    • Praca z bazami wektorowymi
    • Tworzenie i przeszukiwanie indeksów wektorowych
  • Obsługa modeli LLM
    • Integracja modeli językowych (API lub modele lokalne)
    • Rozumienie prompt engineering i zarządzania kontekstem modelu

Frontend:

  • React
    • Tworzenie komponentów i zarządzanie stanem
    • Integracja z backendem przez REST lub WebSocket

DevOps:

  • Docker
    • Tworzenie i debugowanie kontenerów
    • Tworzenie plików Dockerfile i docker-compose.yml

Inne:

  • Podstawowa znajomość systemu Linux/Unix
  • Git i systemy kontroli wersji
  • Podstawy architektury mikroserwisów