Kowal AI Product Feed - instalacja i konfiguracja
Cel dokumentu
Ten dokument opisuje pełny proces instalacji, uruchomienia i konfiguracji modułu Kowal_AiProductFeed w Magento 2. Został przygotowany tak, aby można było przejść od wdrożenia technicznego do pierwszego działającego eksportu oraz publikacji llms.txt.
Zakres funkcjonalny modułu
Moduł umożliwia:
- eksport treści sklepu do plików
JSON i JSONL,
- synchronizację danych do
OpenAI Vector Store,
- obsługę wielu kanałów treści, takich jak produkt, blog, kategoria i CMS,
- publikację publicznych endpointów:
/llms.txt/ai-feed/{storeCode}/index.json/ai-feed/{storeCode}/{contentType}.ndjson
- dodanie linku do
llms.txt w sekcji head,
- opcjonalne dodanie linku do
llms.txt w stopce sklepu.
llms.txt działa per aktualny Store View. Oznacza to, że każda wersja językowa może zwracać własny manifest i własne linki do feedów.
Wymagania wstępne
Przed instalacją upewnij się, że:
- Magento 2 działa poprawnie,
- masz dostęp SSH do katalogu głównego Magento,
Composer jest dostępny w środowisku,- proces PHP ma możliwość zapisu do katalogu
var/,
- masz aktywny klucz
OpenAI API Key, jeśli chcesz korzystać z synchronizacji do OpenAI Vector Store.
Instalacja modułu
1. Dodanie repozytorium Composer
Jeżeli moduł jest instalowany z repozytorium Git:
composer config repositories.ai.product.feed vcs https://github.com/kowalco/module-ai-product-feed
Jeżeli repozytorium jest prywatne:
composer config --global --auth github-oauth.github.com <YOUR_TOKEN>
2. Instalacja pakietu
composer require kowal/module-ai-product-feed
3. Włączenie modułu
bin/magento module:enable Kowal_AiProductFeed
4. Aktualizacja Magento
bin/magento setup:upgrade
5. Kompilacja i cache
W środowisku produkcyjnym wykonaj dodatkowo:
bin/magento setup:di:compile
bin/magento cache:flush
W środowisku developerskim zwykle wystarczy:
bin/magento cache:flush
Jeżeli przed Magento działa dodatkowa warstwa cache, wykonaj również purge po stronie:
VarnishCloudflareNginx fastcgi/proxy cache- innego reverse proxy lub CDN
6. Potwierdzenie statusu modułu
bin/magento module:status Kowal_AiProductFeed
Lokalizacja konfiguracji
Konfiguracja modułu jest dostępna w panelu:
Stores -> Configuration -> General -> Kowal AI Feed
Zalecany model konfiguracji
Najlepszą praktyką jest konfiguracja na poziomie Store View, szczególnie jeśli sklep działa w wielu językach.
Zalecenie:
- jeden
Store View = jeden język,
- jeden
Store View = jeden Vector Store ID,
- jeden
Store View = osobna publiczna warstwa feedów AI.
Przykład:
PL store view -> polski Vector Store IDEN store view -> angielski Vector Store ID
Konfiguracja pól
Enable Module
Włącza moduł dla wybranego zakresu.
Zalecenie:
- ustaw
Yes na tych Store View, które mają generować dane AI
OpenAI API Key
Globalny klucz API wykorzystywany do komunikacji z OpenAI.
Wymagany, jeśli:
- chcesz synchronizować pliki do
OpenAI Vector Store
Nie jest wymagany, jeśli:
- chcesz korzystać tylko z lokalnych eksportów,
- chcesz korzystać tylko z
llms.txt i publicznych feedów.
Vector Store ID
Identyfikator OpenAI Vector Store dla konkretnego Store View.
Zalecenie:
- konfigurować na poziomie
Store View,
- ustawić osobny identyfikator dla każdego języka.
Feed Location
Ścieżka względna do katalogu, w którym będą zapisywane pliki eksportu.
Domyślna wartość:
var/ai-feeds
Zalecenie:
- pozostawić katalog w
var/,
- nie wystawiać tego katalogu bezpośrednio przez webserver.
Enable Public AI Feed
Włącza publiczne endpointy:
/llms.txt/ai-feed/{storeCode}/index.json/ai-feed/{storeCode}/{contentType}.ndjson
Włącz tę opcję tylko dla tych widoków sklepu, których treści mogą być publicznie dostępne.
Ważne:
/llms.txt nie jest globalnym indeksem wszystkich sklepów- każda wersja językowa sklepu zwraca własny manifest
- sam
/llms.txt nie wymaga istnienia wygenerowanych plików, aby odpowiedzieć poprawnie
Dodaje widoczny link do /llms.txt w stopce sklepu.
Zalecenie:
No domyślnie,Yes, jeśli chcesz jawnie komunikować dostępność warstwy AI dla partnerów, integratorów lub botów.
Docs Location
Ścieżka względna do katalogu z dokumentacją produktową Markdown dla product.docs.
Przykłady:
var/ai-docsvar/ai-docs/pl
Obsługiwane są m.in. pliki:
{docsLocation}/{SKU}.md{docsLocation}/{SKU}.markdown{docsLocation}/{storeCode}/{SKU}.md{docsLocation}/{storeCode}/{SKU}.markdown{docsLocation}/{SKU}/*.md{docsLocation}/{SKU}/*.markdown{docsLocation}/{storeCode}/{SKU}/*.md{docsLocation}/{storeCode}/{SKU}/*.markdown
Max Products Per Batch
Rozmiar paczki dla eksportu produktów.
Wartość startowa:
Zmniejsz wartość, jeżeli:
- katalog jest bardzo duży,
- środowisko ma ograniczoną pamięć,
- dodatkowe operacje AI zwiększają obciążenie.
Sync Product Core
Włącza typ treści product.core.
Zalecenie:
Sync Product FAQ
Włącza product.faq.
Użyj, jeśli sklep posiada dane w tabeli kowal_zapytajoprodukt_pytania.
Sync Product Docs
Włącza product.docs.
Użyj, jeśli dokumentacja Markdown jest już przygotowana.
Sync Blog Content
Włącza kanał blog i typ blog.article.
Sync Category Content
Włącza kanał category i typ category.content.
Sync CMS Pages
Włącza kanał cms_page i typ cms.page.
Max Retries
Maksymalna liczba prób operacji API.
Domyślnie:
Polling Timeout
Maksymalny czas oczekiwania na zakończenie przetwarzania pliku po stronie OpenAI.
Domyślnie:
Polling Interval
Interwał pomiędzy kolejnymi sprawdzeniami statusu.
Domyślnie:
HTTP Timeout
Maksymalny czas pojedynczego requestu HTTP do OpenAI.
Domyślnie:
Zalecana kolejność konfiguracji
Po instalacji skonfiguruj moduł w tej kolejności:
- Włącz moduł dla docelowego
Store View.
- Dodaj
OpenAI API Key, jeśli planujesz synchronizację z OpenAI.
- Ustaw
Vector Store ID dla każdego języka.
- Zweryfikuj
Feed Location.
- Ustaw
Docs Location, jeśli używasz dokumentacji Markdown.
- Włącz potrzebne typy treści i kanały.
- Włącz
Enable Public AI Feed, jeśli endpointy mają być dostępne publicznie.
- Opcjonalnie włącz
Show LLMs.txt Link in Footer.
- Wyczyść cache Magento.
bin/magento cache:flush
Pierwsze uruchomienie
Dry run
Najpierw wykonaj suchy test dla jednego Store View:
bin/magento kowal:ai-export:sync --channel=product --store=1 --dry-run
Realny eksport
Następnie uruchom synchronizację właściwą:
bin/magento kowal:ai-export:sync --channel=product --store=1
Sprawdzenie statusu
bin/magento kowal:ai-export:status --store=1
Weryfikacja publicznych endpointów
Jeżeli Enable Public AI Feed jest włączone, sprawdź:
curl -i https://twoja-domena.pl/llms.txt
curl -i https://twoja-domena.pl/ai-feed/pl/index.json
curl -i https://twoja-domena.pl/ai-feed/pl/product.core.ndjson
Jeżeli sklep ma osobne wersje językowe w URL, sprawdź również:
curl -i https://twoja-domena.pl/en/llms.txt
curl -i https://twoja-domena.pl/de/llms.txt
Oczekiwane zachowanie:
/llms.txt zwraca manifest tylko dla bieżącego Store View/llms.txt działa nawet wtedy, gdy nie ma jeszcze wygenerowanych plików feedu/ai-feed/{storeCode}/index.json pokazuje tylko istniejące feedy dla danego sklepu/ai-feed/{storeCode}/{contentType}.ndjson działa dopiero wtedy, gdy istnieją odpowiednie pliki źródłowe
Weryfikacja nagłówków cache:
curl -I https://twoja-domena.pl/llms.txt
curl -I https://twoja-domena.pl/ai-feed/pl/index.json
Powinieneś zobaczyć:
- dla
/llms.txt nagłówki praktycznie wyłączające cache,
- dla
index.json krótki czas życia cache i wymuszoną rewalidację.
Weryfikacja HTML:
- w źródle strony powinien pojawić się link w
head do /llms.txt,
- jeżeli aktywowałeś opcję stopki, w footerze powinien pojawić się link
LLMs.txt.
Komendy CLI
Synchronizacja
bin/magento kowal:ai-export:sync --channel=product
bin/magento kowal:ai-export:sync --channel=product --store=1
bin/magento kowal:ai-export:sync --channel=product --store=1 --content-type=product.core --identifier=example-sku --dry-run
bin/magento kowal:ai-export:sync --channel=blog --store=1 --source=amasty_blog
bin/magento kowal:ai-export:sync --channel=category --store=1
bin/magento kowal:ai-export:sync --channel=cms_page --store=1
Status
bin/magento kowal:ai-export:status
bin/magento kowal:ai-export:status --store=1
bin/magento kowal:ai-export:status --channel=blog --store=1
bin/magento kowal:ai-export:status --channel=blog --store=1 --source=amasty_blog
Import źródeł bloga
bin/magento kowal:ai-blog-source:import --source=amasty_blog --store=1
Stary alias produktowy
Wciąż dostępny dla zgodności wstecznej:
bin/magento kowal:ai-feed:generate
bin/magento kowal:ai-feed:generate --store=1 --content-type=product.core --sku=example-sku --dry-run
Cron
Moduł korzysta z trzech zadań cron:
kowal_ai_blog_source_importkowal_ai_feed_generatekowal_ai_feed_cleanup
Upewnij się, że cron Magento działa poprawnie w środowisku.
Najczęstsze problemy
/llms.txt zwraca 404
Sprawdź:
- czy wdrożona jest aktualna wersja modułu z frontend routingiem,
- czy wykonałeś
bin/magento setup:upgrade,
- czy w production mode wykonałeś
bin/magento setup:di:compile,
- czy wykonałeś standardowy deploy static content zgodnie z procesem projektu,
- czy wyczyściłeś cache,
- czy wykonałeś purge warstwy CDN / reverse proxy,
- czy
Enable Public AI Feed jest włączone.
Jeżeli https://twoja-domena.pl/llms.txt?v=123 działa, a https://twoja-domena.pl/llms.txt nie, to zwykle oznacza, że po drodze nadal działa stary cache współdzielony.
/llms.txt działa, ale feedy są puste
To oznacza zwykle, że:
- nie wykonano jeszcze eksportu,
- brak aktywnych treści dla danego kanału,
- odpowiednie flagi synchronizacji są wyłączone.
To zachowanie jest poprawne. Sam manifest może działać wcześniej niż właściwe feedy.
Brak plików w var/ai-feeds
Sprawdź:
- czy moduł jest aktywny na właściwym
Store View,
- czy są włączone wymagane typy treści,
- czy Magento ma prawa zapisu do
var/,
- czy proces synchronizacji został uruchomiony.
Problemy z synchronizacją do OpenAI
Sprawdź:
- poprawność
OpenAI API Key,
- poprawność
Vector Store ID,
- dostępność połączeń wychodzących HTTP,
- wartości timeoutów i retry.
Podsumowanie
Po poprawnej instalacji i konfiguracji moduł daje Magento 2 gotową warstwę danych dla AI:
- lokalną,
- wielojęzyczną,
- możliwą do synchronizacji z
OpenAI,
- gotową do publikacji przez
llms.txt i feedy NDJSON,
- rozwijalną pod kolejne integracje i moduły AI.
WhatsApp
+48608012047
