AI Product Support dla Magento 2

Instalacja i konfiguracja

Ten dokument opisuje, jak uruchomić moduł AI Product Support w sklepie Magento 2 i jak przygotować go do pracy.

Dokument jest napisany z myślą o sklepie, który chce wdrożyć gotowy moduł i zacząć korzystać z czatu AI bez zagłębiania się w techniczne szczegóły działania po stronie kodu.

Najlepiej traktować ten moduł jako warstwę użytkową. Najpierw sklep przygotowuje wiedzę, a dopiero potem udostępnia ją pracownikom lub klientom w formie czatu.

Co trzeba przygotować przed instalacją

Przed wdrożeniem potrzebujesz:

• działającego sklepu Magento 2,
• dostępu do serwera,
• composera,
• konta OpenAI,
• przygotowanej bazy wiedzy AI dla sklepu,
• połączenia serwera z internetem.

Najważniejszy warunek praktyczny jest prosty: moduł będzie odpowiadał dobrze tylko wtedy, gdy sklep ma przygotowane treści, z których AI może korzystać.

Jeśli sklep korzysta już z modułu Kowal AI Product Feed, to właśnie on może pełnić rolę przygotowania i porządkowania treści dla AI. Na stronie tego modułu zostało to opisane jako budowanie uporządkowanej i aktualnej bazy wiedzy dla systemów AI. AI Product Support jest naturalnym kolejnym krokiem, czyli wykorzystaniem tej wiedzy w rozmowie z użytkownikiem. Źródło: Kowal AI Product Feed dla OpenAI Vector Store

Instalacja modułu

Moduł instalowany jest przez composer.

Przykładowy proces instalacji:

composer config repositories.ai.product.support vcs https://github.com/kowalco/ai-product-support
composer config --global --auth github-oauth.github.com <YOUR_TOKEN>
composer require kowal/module-ai-product-support
bin/magento module:enable Kowal_AiProductSupport
bin/magento setup:upgrade
bin/magento cache:clean

Jeśli sklep działa w trybie produkcyjnym, po instalacji wykonaj także:

bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f
bin/magento cache:clean

Gdzie znajduje się konfiguracja

Po instalacji ustawienia modułu znajdziesz tutaj:

Stores > Configuration > Kowal AI > AI Product Support

Jak skonfigurować moduł

1. Włącz czat w panelu administracyjnym

W sekcji General włącz:

• Enable Chat

Po zapisaniu ustawienia w panelu administracyjnym pojawi się zakładka AI.

2. Zdecyduj, czy włączyć czat na frontendzie

Jeżeli chcesz, aby z czatu mogli korzystać także klienci sklepu, włącz:

• Enable Frontend Chat

Jeśli moduł ma służyć tylko zespołowi sklepu, pozostaw frontend wyłączony.

3. Ustaw długość pytania

Pole:

• Maximum Question Length

określa maksymalną długość wiadomości, jaką użytkownik może wysłać. To pomaga utrzymać porządek i ograniczać zbyt długie, nieczytelne zapytania.

4. Ustaw domyślny widok sklepu

Jeśli sklep działa w wielu wersjach językowych lub ma kilka widoków sklepu, możesz wskazać:

• Default Store View

To ułatwia pracę w panelu i pomaga startować z właściwego kontekstu.

5. Włącz lub wyłącz ręczną zmianę widoku sklepu

Pole:

• Allow Store Switcher

decyduje, czy użytkownik panelu może zmieniać widok sklepu bezpośrednio w popupie czatu.

To przydatne wtedy, gdy jeden zespół obsługuje kilka wersji sklepu.

6. Włącz logowanie techniczne na czas wdrożenia

Pole:

• Log Chat Requests

warto włączyć na etapie konfiguracji i testów. Dzięki temu łatwiej sprawdzić, czy moduł działa poprawnie. Po wdrożeniu produkcyjnym można zdecydować, czy logowanie ma pozostać aktywne.

Ustawienia połączenia z AI

W sekcji OpenAI skonfiguruj podstawowe elementy potrzebne do działania modułu.

OpenAI API Key

To klucz dostępu do usługi AI. Bez niego moduł nie pobierze listy modeli, nie odczyta źródła wiedzy i nie wyśle pytania.

Response Model

To model odpowiedzialny za budowanie odpowiedzi.

Lista modeli ładuje się z API. Jeśli po zapisaniu klucza nie pojawią się opcje, można użyć przycisku odświeżania listy modeli.

Vector Store

To wybrane źródło wiedzy dla modułu.

Najprościej można to rozumieć tak:

• to miejsce, w którym zapisane są treści, z których czat korzysta podczas odpowiadania,
• moduł szuka odpowiedzi właśnie tam,
• jeśli wybierzesz niewłaściwe źródło, odpowiedzi będą słabe albo niepełne.

Jeśli sklep ma już uporządkowaną bazę wiedzy przygotowaną dla AI, to tutaj wskazuje się właśnie to źródło.

Lista źródeł wiedzy również może być odświeżona z poziomu konfiguracji.

Maximum File Search Results

To ustawienie określa, ile materiałów pomocniczych moduł bierze pod uwagę przy przygotowaniu jednej odpowiedzi.

W praktyce wpływa to na:

• jakość odpowiedzi,
• szybkość działania,
• koszt korzystania z AI.

Dobrym ustawieniem startowym jest wartość średnia, na przykład 6.

Zabezpieczenia frontendu

Jeżeli czat działa po stronie sklepu, warto od razu ustawić limity bezpieczeństwa.

W sekcji Frontend Security znajdziesz:

• Requests Per Minute
• Requests Per Hour
• Minimum Submit Delay

Te ustawienia pomagają ograniczyć:

• zbyt częste wysyłanie pytań,
• nadużycia ze strony botów,
• niepotrzebne zużycie zasobów i kosztów.

Dodatkowy prompt systemowy

W sekcji Prompting można uzupełnić:

• System Prompt Template

To pole nie jest obowiązkowe. W większości wdrożeń można zostawić je puste i korzystać z domyślnego ustawienia modułu.

Nadpisanie ma sens tylko wtedy, gdy sklep chce wprowadzić własny styl odpowiedzi lub dodatkowe zasady komunikacji.

Jak moduł działa z perspektywy użytkownika

W panelu administracyjnym

Po uruchomieniu modułu użytkownik widzi zakładkę AI przy prawej krawędzi ekranu. Po kliknięciu otwiera się panel czatu.

W panelu można:

• wpisać pytanie,
• otrzymać odpowiedź,
• zobaczyć karty produktów, jeśli odpowiedź dotyczy konkretnego produktu,
• pracować bez przeładowywania strony.

Na frontendzie

Jeśli czat został włączony, podobna zakładka pojawia się po stronie sklepu. Klient może zadać pytanie bez opuszczania strony produktu lub listingu.

Jak myśleć o takim wdrożeniu

Najbardziej praktyczny model wygląda tak:

1. sklep porządkuje treści i przygotowuje bazę wiedzy,
2. administrator wskazuje tę bazę wiedzy w konfiguracji modułu,
3. użytkownik korzysta z czatu,
4. odpowiedzi są budowane na podstawie treści przygotowanych przez sklep.

To podejście daje lepszy efekt niż uruchamianie samego czatu bez przygotowanych danych.

Rekomendowana konfiguracja startowa

Panel administracyjny

• Enable Chat = Yes
• Enable Frontend Chat = zależnie od projektu
• Maximum Question Length = 1000
• Allow Store Switcher = Yes przy wielu widokach sklepu
• Log Chat Requests = Yes na etapie testów
• Maximum File Search Results = 6

Frontend

• Requests Per Minute = ostrożna wartość startowa
• Requests Per Hour = wartość dopasowana do ruchu sklepu
• Minimum Submit Delay = co najmniej 1

Co sprawdzić po wdrożeniu

Po zapisaniu konfiguracji wykonaj prosty test:

1. sprawdź, czy w panelu administracyjnym pojawiła się zakładka AI,
2. otwórz popup i wyślij pytanie,
3. upewnij się, że odpowiedź pojawia się poprawnie,
4. sprawdź, czy sekcja produktów pojawia się przy pytaniach o konkretne produkty,
5. jeśli frontend jest włączony, sprawdź działanie zakładki także na sklepie.

Najczęstsze problemy

Nie widać modeli lub źródeł wiedzy

Najczęściej oznacza to:

• brak poprawnego klucza OpenAI,
• brak połączenia serwera z internetem,
• niewyczyszczony cache po zmianach.

Czat odpowiada zbyt słabo albo nie trafia w temat

Najczęstsza przyczyna to nie sam moduł, ale jakość przygotowanej bazy wiedzy. Jeśli treści są niepełne, nieaktualne albo zbyt ubogie, odpowiedzi też będą słabsze.

Przed oceną samego modułu warto więc sprawdzić:

• czy opisy produktów są sensowne i kompletne,
• czy FAQ i dokumentacja są aktualne,
• czy baza wiedzy rzeczywiście zawiera treści potrzebne użytkownikom,
• czy wybrane źródło wiedzy jest właściwe dla danego sklepu.

Frontend zbyt szybko blokuje użytkownika

Wtedy warto sprawdzić ustawienia limitów i opóźnienia wysyłki w sekcji Frontend Security.

Krótka checklista wdrożeniowa

1. Zainstaluj moduł przez composer.
2. Włącz moduł i wykonaj setup:upgrade.
3. Skonfiguruj połączenie z OpenAI.
4. Wybierz właściwe źródło wiedzy.
5. Włącz czat w adminie.
6. Opcjonalnie włącz czat na frontendzie.
7. Ustaw limity bezpieczeństwa.
8. Przetestuj działanie na pytaniach o realne produkty i treści sklepu.

Krótki opis do sekcji „Instalacja i konfiguracja”

Moduł instaluje się przez composer i konfiguruje w Stores > Configuration > Kowal AI > AI Product Support. Administrator wprowadza dane dostępu do OpenAI, wybiera model oraz źródło wiedzy dla sklepu, a następnie włącza czat w panelu administracyjnym i opcjonalnie na frontendzie. Dodatkowo można ustawić limity bezpieczeństwa i dopasować podstawowe parametry działania modułu.