Kowal AI Product Feed - instalare și configurare
Scopul documentului
Acest document descrie procesul complet de instalare, pornire și configurare a modulului Kowal_AiProductFeed în Magento 2. A fost pregătit astfel încât să se poată trece de la implementarea tehnică la primul export funcțional și la publicarea llms.txt.
Domeniul funcțional al modulului
Modulul permite:
- exportul conținutului magazinului în fișiere
JSON și JSONL, - sincronizarea datelor cu
OpenAI Vector Store, - gestionarea mai multor canale de conținut, precum produs, blog, categorie și CMS,
- publicarea endpoint-urilor publice:
/llms.txt/ai-feed/{storeCode}/index.json/ai-feed/{storeCode}/{contentType}.ndjson
- adăugarea unui link către
llms.txt în secțiunea head, - adăugarea opțională a unui link către
llms.txt în footer-ul magazinului.
llms.txt funcționează per Store View curent. Acest lucru înseamnă că fiecare versiune lingvistică poate returna propriul manifest și propriile linkuri către feed-uri.
Cerințe preliminare
Înainte de instalare, asigură-te că:
- Magento 2 funcționează corect,
- ai acces SSH la directorul rădăcină Magento,
Composer este disponibil în mediu,- procesul PHP poate scrie în directorul
var/, - ai o cheie activă
OpenAI API Key, dacă dorești să folosești sincronizarea cu OpenAI Vector Store.
Instalarea modulului
1. Adăugarea repository-ului Composer
Dacă modulul este instalat din repository-ul Git:
composer config repositories.ai.product.feed vcs https://github.com/kowalco/module-ai-product-feed
Dacă repository-ul este privat:
composer config --global --auth github-oauth.github.com
2. Instalarea pachetului
composer require kowal/module-ai-product-feed
3. Activarea modulului
bin/magento module:enable Kowal_AiProductFeed
4. Actualizarea Magento
bin/magento setup:upgrade
5. Compilare și cache
În mediul de producție, execută suplimentar:
bin/magento setup:di:compilebin/magento cache:flush
În mediul de dezvoltare, de obicei este suficient:
bin/magento cache:flush
Dacă în fața Magento funcționează un strat suplimentar de cache, execută și purge la nivelul:
VarnishCloudflareNginx fastcgi/proxy cache- altui reverse proxy sau CDN
6. Confirmarea statusului modulului
bin/magento module:status Kowal_AiProductFeed
Locația configurării
Configurarea modulului este disponibilă în panoul:
Stores -> Configuration -> General -> Kowal AI Feed
Model de configurare recomandat
Cea mai bună practică este configurarea la nivel de Store View, mai ales dacă magazinul funcționează în mai multe limbi.
Recomandare:
- un
Store View = o limbă, - un
Store View = un Vector Store ID, - un
Store View = un strat public separat de feed-uri AI.
Exemplu:
PL store view -> polonez Vector Store IDEN store view -> englez Vector Store ID
Configurarea câmpurilor
Enable Module
Activează modulul pentru domeniul selectat.
Recomandare:
- setează
Yes pentru acele Store View care trebuie să genereze date AI
OpenAI API Key
Cheie API globală utilizată pentru comunicarea cu OpenAI.
Necesară dacă:
- dorești să sincronizezi fișierele cu
OpenAI Vector Store
Nu este necesară dacă:
- dorești să folosești doar exporturi locale,
- dorești să folosești doar
llms.txt și feed-urile publice.
Vector Store ID
Identificatorul OpenAI Vector Store pentru un anumit Store View.
Recomandare:
- configurează la nivel de
Store View, - setează un identificator separat pentru fiecare limbă.
Feed Location
Calea relativă către directorul în care vor fi salvate fișierele de export.
Valoare implicită:
var/ai-feeds
Recomandare:
- păstrează directorul în
var/, - nu expune acest director direct prin webserver.
Enable Public AI Feed
Activează endpoint-urile publice:
/llms.txt/ai-feed/{storeCode}/index.json/ai-feed/{storeCode}/{contentType}.ndjson
Activează această opțiune doar pentru acele vizualizări de magazin al căror conținut poate fi disponibil public.
Important:
/llms.txt nu este un index global al tuturor magazinelor- fiecare versiune lingvistică a magazinului returnează propriul manifest
/llms.txt în sine nu necesită existența fișierelor generate pentru a răspunde corect
Adaugă un link vizibil către /llms.txt în footer-ul magazinului.
Recomandare:
No implicit,Yes, dacă dorești să comunici explicit disponibilitatea stratului AI pentru parteneri, integratori sau boți.
Docs Location
Calea relativă către directorul cu documentația de produs Markdown pentru product.docs.
Exemple:
var/ai-docsvar/ai-docs/pl
Sunt acceptate, printre altele, fișierele:
{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
Dimensiunea lotului pentru exportul produselor.
Valoare de pornire:
Redu valoarea dacă:
- catalogul este foarte mare,
- mediul are memorie limitată,
- operațiunile AI suplimentare cresc încărcarea.
Sync Product Core
Activează tipul de conținut product.core.
Recomandare:
Sync Product FAQ
Activează product.faq.
Folosește dacă magazinul are date în tabela kowal_zapytajoprodukt_pytania.
Sync Product Docs
Activează product.docs.
Folosește dacă documentația Markdown este deja pregătită.
Sync Blog Content
Activează canalul blog și tipul blog.article.
Sync Category Content
Activează canalul category și tipul category.content.
Sync CMS Pages
Activează canalul cms_page și tipul cms.page.
Max Retries
Numărul maxim de încercări pentru operațiunile API.
Implicit:
Polling Timeout
Timpul maxim de așteptare pentru finalizarea procesării fișierului pe partea OpenAI.
Implicit:
Polling Interval
Intervalul dintre verificările succesive ale statusului.
Implicit:
HTTP Timeout
Timpul maxim pentru un singur request HTTP către OpenAI.
Implicit:
Ordinea recomandată de configurare
După instalare, configurează modulul în această ordine:
- Activează modulul pentru
Store View țintă. - Adaugă
OpenAI API Key, dacă planifici sincronizarea cu OpenAI. - Setează
Vector Store ID pentru fiecare limbă. - Verifică
Feed Location. - Setează
Docs Location, dacă folosești documentație Markdown. - Activează tipurile de conținut și canalele necesare.
- Activează
Enable Public AI Feed, dacă endpoint-urile trebuie să fie disponibile public. - Opțional, activează
Show LLMs.txt Link in Footer. - Golește cache-ul Magento.
bin/magento cache:flush
Prima pornire
Dry run
Mai întâi, execută un test uscat pentru un singur Store View:
bin/magento kowal:ai-export:sync --channel=product --store=1 --dry-run
Export real
Apoi pornește sincronizarea propriu-zisă:
bin/magento kowal:ai-export:sync --channel=product --store=1
Verificarea statusului
bin/magento kowal:ai-export:status --store=1
Verificarea endpoint-urilor publice
Dacă Enable Public AI Feed este activat, verifică:
curl -i https://twoja-domena.pl/llms.txtcurl -i https://twoja-domena.pl/ai-feed/pl/index.jsoncurl -i https://twoja-domena.pl/ai-feed/pl/product.core.ndjson
Dacă magazinul are versiuni lingvistice separate în URL, verifică și:
curl -i https://twoja-domena.pl/en/llms.txtcurl -i https://twoja-domena.pl/de/llms.txt
Comportament așteptat:
/llms.txt returnează manifestul doar pentru Store View curent/llms.txt funcționează chiar și atunci când nu există încă fișiere feed generate/ai-feed/{storeCode}/index.json arată doar feed-urile existente pentru magazinul respectiv/ai-feed/{storeCode}/{contentType}.ndjson funcționează doar atunci când există fișierele sursă corespunzătoare
Verificarea headerelor cache:
curl -I https://twoja-domena.pl/llms.txtcurl -I https://twoja-domena.pl/ai-feed/pl/index.json
Ar trebui să vezi:
- pentru
/llms.txt headere care practic dezactivează cache-ul, - pentru
index.json un timp scurt de viață al cache-ului și revalidare forțată.
Verificarea HTML:
- în sursa paginii ar trebui să apară un link în
head către /llms.txt, - dacă ai activat opțiunea din footer, în footer ar trebui să apară linkul
LLMs.txt.
Comenzi CLI
Sincronizare
bin/magento kowal:ai-export:sync --channel=productbin/magento kowal:ai-export:sync --channel=product --store=1bin/magento kowal:ai-export:sync --channel=product --store=1 --content-type=product.core --identifier=example-sku --dry-runbin/magento kowal:ai-export:sync --channel=blog --store=1 --source=amasty_blogbin/magento kowal:ai-export:sync --channel=category --store=1bin/magento kowal:ai-export:sync --channel=cms_page --store=1
Status
bin/magento kowal:ai-export:statusbin/magento kowal:ai-export:status --store=1bin/magento kowal:ai-export:status --channel=blog --store=1bin/magento kowal:ai-export:status --channel=blog --store=1 --source=amasty_blog
Importul surselor blogului
bin/magento kowal:ai-blog-source:import --source=amasty_blog --store=1
Alias vechi pentru produse
Încă disponibil pentru compatibilitate inversă:
bin/magento kowal:ai-feed:generatebin/magento kowal:ai-feed:generate --store=1 --content-type=product.core --sku=example-sku --dry-run
Cron
Modulul folosește trei joburi cron:
kowal_ai_blog_source_importkowal_ai_feed_generatekowal_ai_feed_cleanup
Asigură-te că cron Magento funcționează corect în mediu.
Cele mai frecvente probleme
/llms.txt returnează 404
Verifică:
- dacă este implementată versiunea actuală a modulului cu frontend routing,
- dacă ai executat
bin/magento setup:upgrade, - dacă în production mode ai executat
bin/magento setup:di:compile, - dacă ai executat deploy-ul standard de static content conform procesului proiectului,
- dacă ai golit cache-ul,
- dacă ai executat purge pentru stratul CDN / reverse proxy,
- dacă
Enable Public AI Feed este activat.
Dacă https://twoja-domena.pl/llms.txt?v=123 funcționează, iar https://twoja-domena.pl/llms.txt nu, acest lucru înseamnă de obicei că pe traseu încă funcționează un cache vechi partajat.
/llms.txt funcționează, dar feed-urile sunt goale
Acest lucru înseamnă de obicei că:
- exportul nu a fost încă executat,
- nu există conținut activ pentru canalul respectiv,
- flag-urile corespunzătoare de sincronizare sunt dezactivate.
Acest comportament este corect. Manifestul în sine poate funcționa mai devreme decât feed-urile propriu-zise.
Lipsesc fișierele din var/ai-feeds
Verifică:
- dacă modulul este activ pe
Store View corect, - dacă tipurile de conținut necesare sunt activate,
- dacă Magento are drepturi de scriere în
var/, - dacă procesul de sincronizare a fost pornit.
Probleme cu sincronizarea către OpenAI
Verifică:
- corectitudinea
OpenAI API Key, - corectitudinea
Vector Store ID, - disponibilitatea conexiunilor HTTP de ieșire,
- valorile timeout-urilor și retry.
Rezumat
După instalarea și configurarea corectă, modulul oferă pentru Magento 2 un strat de date AI gata pregătit:
- local,
- multilingv,
- care poate fi sincronizat cu
OpenAI, - gata de publicare prin
llms.txt și feed-uri NDJSON, - extensibil pentru integrări și module AI suplimentare.
WhatsApp
+48608012047
