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șiJSONL, - 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țiuneahead, - 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,
Composereste disponibil în mediu,- procesul PHP poate scrie în directorul
var/, - ai o cheie activă
OpenAI API Key, dacă dorești să folosești sincronizarea cuOpenAI 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-feedDacă repository-ul este privat:
composer config --global --auth github-oauth.github.com 2. Instalarea pachetului
composer require kowal/module-ai-product-feed3. Activarea modulului
bin/magento module:enable Kowal_AiProductFeed4. Actualizarea Magento
bin/magento setup:upgrade5. 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:flushDacă î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_AiProductFeedLocaț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= unVector Store ID, - un
Store View= un strat public separat de feed-uri AI.
Exemplu:
PLstore view -> polonezVector Store IDENstore view -> englezVector Store ID
Configurarea câmpurilor
Enable Module
Activează modulul pentru domeniul selectat.
Recomandare:
- setează
Yespentru aceleStore Viewcare 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.txtnu 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
Show LLMs.txt Link in Footer
Adaugă un link vizibil către /llms.txt în footer-ul magazinului.
Recomandare:
Noimplicit,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:
500
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:
Yes
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:
3
Polling Timeout
Timpul maxim de așteptare pentru finalizarea procesării fișierului pe partea OpenAI.
Implicit:
600
Polling Interval
Intervalul dintre verificările succesive ale statusului.
Implicit:
5
HTTP Timeout
Timpul maxim pentru un singur request HTTP către OpenAI.
Implicit:
60
Ordinea recomandată de configurare
După instalare, configurează modulul în această ordine:
- Activează modulul pentru
Store Viewțintă. - Adaugă
OpenAI API Key, dacă planifici sincronizarea cuOpenAI. - Setează
Vector Store IDpentru 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:flushPrima 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-runExport real
Apoi pornește sincronizarea propriu-zisă:
bin/magento kowal:ai-export:sync --channel=product --store=1Verificarea statusului
bin/magento kowal:ai-export:status --store=1Verificarea 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.ndjsonDacă 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.txtComportament așteptat:
/llms.txtreturnează manifestul doar pentruStore Viewcurent/llms.txtfuncționează chiar și atunci când nu există încă fișiere feed generate/ai-feed/{storeCode}/index.jsonarată doar feed-urile existente pentru magazinul respectiv/ai-feed/{storeCode}/{contentType}.ndjsonfuncț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.jsonAr trebui să vezi:
- pentru
/llms.txtheadere care practic dezactivează cache-ul, - pentru
index.jsonun timp scurt de viață al cache-ului și revalidare forțată.
Verificarea HTML:
- în sursa paginii ar trebui să apară un link în
headcă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=1Status
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_blogImportul surselor blogului
bin/magento kowal:ai-blog-source:import --source=amasty_blog --store=1Alias 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-runCron
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 Feedeste 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 Viewcorect, - 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-uriNDJSON, - extensibil pentru integrări și module AI suplimentare.



















