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ă puteți 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 în
OpenAI Vector Store, - gestionarea mai multor canale de conținut, precum produs, blog, categorie și CMS,
- publicarea endpointurilor 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 footerul magazinului.
llms.txt funcționează per Store View curent. Aceasta înseamnă că fiecare versiune lingvistică poate returna propriul manifest și propriile linkuri către feeduri.
Cerințe preliminare
Înainte de instalare, asigurați-vă că:
- Magento 2 funcționează corect,
- aveți acces SSH la directorul rădăcină Magento,
Composer este disponibil în mediu,- procesul PHP poate scrie în directorul
var/, - aveți o cheie
OpenAI API Key activă, dacă doriți să utilizați sincronizarea cu OpenAI Vector Store.
Instalarea modulului
1. Adăugarea repository-ului Composer
Adăugați repository-ul Composer Kowal:
Datele de acces la repository-ul Composer adresa de e-mail a clientului și tokenul de licență le veți primi prin e-mail după achiziție. Sunt disponibile și în panoul clientului după autentificare pe kowal.store. Înlocuiți TWOJ_EMAIL_KLIENTA cu adresa de e-mail a contului dumneavoastră, iar TWOJ_TOKEN cu tokenul primit. Executați comenzile în directorul rădăcină Magento.
composer config repositories.kowal composer https://repo.kowal.store
Dacă repository-ul este privat:
composer config http-basic.repo.kowal.store 'TWOJ_EMAIL_KLIENTA' 'TWOJ_TOKEN'
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, executați suplimentar:
bin/magento setup:di:compile
bin/magento cache:flush
În mediul de dezvoltare, de obicei este suficient:
bin/magento cache:flush
Dacă înaintea Magento funcționează un strat suplimentar de cache, executați și purge pe partea:
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 panou:
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 feeduri AI.
Exemplu:
PL store view -> Vector Store ID polonezEN store view -> Vector Store ID englez
Configurarea câmpurilor
Enable Module
Activează modulul pentru domeniul selectat.
Recomandare:
- setați
Yes pentru acele Store View care trebuie să genereze date AI
OpenAI API Key
Cheie API globală utilizată pentru comunicarea cu OpenAI.
Necesară dacă:
- doriți să sincronizați fișierele în
OpenAI Vector Store
Nu este necesară dacă:
- doriți să utilizați doar exporturi locale,
- doriți să utilizați doar
llms.txt și feeduri publice.
Vector Store ID
Identificatorul OpenAI Vector Store pentru un anumit Store View.
Recomandare:
- configurați la nivel de
Store View, - setați 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:
- lăsați directorul în
var/, - nu expuneți acest director direct prin webserver.
Enable Public AI Feed
Activează endpointurile publice:
/llms.txt/ai-feed/{storeCode}/index.json/ai-feed/{storeCode}/{contentType}.ndjson
Activați această opțiune doar pentru acele view-uri ale magazinului ale căror conținuturi pot fi disponibile 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 footerul magazinului.
Recomandare:
No implicit,Yes, dacă doriți să comunicați explicit disponibilitatea stratului AI pentru parteneri, integratori sau boți.
Docs Location
Calea relativă către directorul cu documentație 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 inițială:
Reduceți valoarea dacă:
- catalogul este foarte mare,
- mediul are memorie limitată,
- operațiile AI suplimentare cresc încărcarea.
Sync Product Core
Activează tipul de conținut product.core.
Recomandare:
Sync Product FAQ
Activează product.faq.
Utilizați dacă magazinul are date în tabelul kowal_zapytajoprodukt_pytania.
Sync Product Docs
Activează product.docs.
Utilizați 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 al unei singure cereri HTTP către OpenAI.
Implicit:
Ordinea recomandată de configurare
După instalare, configurați modulul în această ordine:
- Activați modulul pentru
Store View țintă. - Adăugați
OpenAI API Key, dacă planificați sincronizarea cu OpenAI. - Setați
Vector Store ID pentru fiecare limbă. - Verificați
Feed Location. - Setați
Docs Location, dacă utilizați documentație Markdown. - Activați tipurile de conținut și canalele necesare.
- Activați
Enable Public AI Feed, dacă endpointurile trebuie să fie disponibile public. - Opțional, activați
Show LLMs.txt Link in Footer. - Curățați cache-ul Magento.
bin/magento cache:flush
Prima pornire
Dry run
Mai întâi executați un test uscat pentru un singur Store View:
bin/magento kowal:ai-export:sync --channel=product --store=1 --dry-run
Export real
Apoi porniți sincronizarea propriu-zisă:
bin/magento kowal:ai-export:sync --channel=product --store=1
Verificarea statusului
bin/magento kowal:ai-export:status --store=1
Verificarea endpointurilor publice
Dacă Enable Public AI Feed este activat, verificați:
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, verificați ș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 fișierele feedului nu au fost încă generate/ai-feed/{storeCode}/index.json afișează doar feedurile 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ă vedeți:
- pentru
/llms.txt, headere care practic dezactivează cache-ul, - pentru
index.json, o durată scurtă de viață a cache-ului și revalidare forțată.
Verificare HTML:
- în sursa paginii ar trebui să apară un link în
head către /llms.txt, - dacă ați activat opțiunea footerului, în footer ar trebui să apară linkul
LLMs.txt.
Comenzi CLI
Sincronizare
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
Importul surselor blogului
bin/magento kowal:ai-blog-source:import --source=amasty_blog --store=1
Alias vechi de produs
Încă disponibil pentru compatibilitate inversă:
bin/magento kowal:ai-feed:generate
bin/magento kowal:ai-feed:generate --store=1 --content-type=product.core --sku=example-sku --dry-run
Cron
Modulul utilizează trei sarcini cron:
kowal_ai_blog_source_importkowal_ai_feed_generatekowal_ai_feed_cleanup
Asigurați-vă că cron Magento funcționează corect în mediu.
Cele mai frecvente probleme
/llms.txt returnează 404
Verificați:
- dacă este implementată versiunea actuală a modulului cu frontend routing,
- dacă ați executat
bin/magento setup:upgrade, - dacă în production mode ați executat
bin/magento setup:di:compile, - dacă ați executat deploy static content standard conform procesului proiectului,
- dacă ați curățat cache-ul,
- dacă ați 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, de obicei înseamnă că pe traseu încă funcționează un cache partajat vechi.
/llms.txt funcționează, dar feedurile sunt goale
De obicei, aceasta înseamnă că:
- exportul nu a fost încă executat,
- nu există conținut activ pentru canalul respectiv,
- flagurile de sincronizare corespunzătoare sunt dezactivate.
Acest comportament este corect. Manifestul în sine poate funcționa mai devreme decât feedurile propriu-zise.
Lipsă fișiere în var/ai-feeds
Verificați:
- 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
Verificați:
- corectitudinea
OpenAI API Key, - corectitudinea
Vector Store ID, - disponibilitatea conexiunilor HTTP de ieșire,
- valorile timeouturilor și retry.
Rezumat
După instalarea și configurarea corectă, modulul oferă Magento 2 un strat de date gata pentru AI:
- local,
- multilingv,
- posibil de sincronizat cu
OpenAI, - gata de publicare prin
llms.txt și feeduri NDJSON, - extensibil pentru integrări și module AI ulterioare.
