Kowal AI Product Feed - installatie en configuratie
Doel van het document
Dit document beschrijft het volledige proces van installatie, activering en configuratie van de module Kowal_AiProductFeed in Magento 2. Het is zo opgesteld dat u van technische implementatie naar de eerste werkende export en publicatie van llms.txt kunt gaan.
Functionele scope van de module
De module maakt het mogelijk om:
- winkelcontent te exporteren naar
JSON- en JSONL-bestanden, - gegevens te synchroniseren naar
OpenAI Vector Store, - meerdere contentkanalen te ondersteunen, zoals product, blog, categorie en CMS,
- openbare endpoints te publiceren:
/llms.txt/ai-feed/{storeCode}/index.json/ai-feed/{storeCode}/{contentType}.ndjson
- een link naar
llms.txt toe te voegen in de head-sectie, - optioneel een link naar
llms.txt toe te voegen in de footer van de winkel.
llms.txt werkt per huidige Store View. Dit betekent dat elke taalversie een eigen manifest en eigen links naar feeds kan retourneren.
Vereisten vooraf
Controleer vóór installatie of:
- Magento 2 correct werkt,
- u SSH-toegang hebt tot de Magento-rootmap,
Composer beschikbaar is in de omgeving,- het PHP-proces schrijfrechten heeft voor de map
var/, - u een actieve
OpenAI API Key hebt als u synchronisatie naar OpenAI Vector Store wilt gebruiken.
Installatie van de module
1. Composer-repository toevoegen
Voeg de Kowal Composer-repository toe:
Toegangsgegevens voor de Composer-repository (e-mailadres van de klant en licentietoken) ontvangt u per e-mail na aankoop. Ze zijn ook beschikbaar in het klantenpanel na inloggen op kowal.store. Vervang TWOJ_EMAIL_KLIENTA door het e-mailadres van uw account en TWOJ_TOKEN door de ontvangen token. Voer de commando’s uit in de Magento-rootmap.
composer config repositories.kowal composer https://repo.kowal.store
Als de repository privé is:
composer config http-basic.repo.kowal.store 'TWOJ_EMAIL_KLIENTA' 'TWOJ_TOKEN'
2. Pakket installeren
composer require kowal/module-ai-product-feed
3. Module inschakelen
bin/magento module:enable Kowal_AiProductFeed
4. Magento bijwerken
bin/magento setup:upgrade
5. Compilatie en cache
Voer in de productieomgeving aanvullend uit:
bin/magento setup:di:compile
bin/magento cache:flush
In een ontwikkelomgeving is meestal voldoende:
bin/magento cache:flush
Als er vóór Magento een extra cachelaag actief is, voer dan ook een purge uit aan de kant van:
VarnishCloudflareNginx fastcgi/proxy cache- een andere reverse proxy of CDN
6. Modulestatus bevestigen
bin/magento module:status Kowal_AiProductFeed
Locatie van de configuratie
De moduleconfiguratie is beschikbaar in het panel:
Stores -> Configuration -> General -> Kowal AI Feed
Aanbevolen configuratiemodel
Best practice is configuratie op Store View-niveau, vooral als de winkel in meerdere talen werkt.
Aanbeveling:
- één
Store View = één taal, - één
Store View = één Vector Store ID, - één
Store View = aparte openbare AI-feedlaag.
Voorbeeld:
PL store view -> Poolse Vector Store IDEN store view -> Engelse Vector Store ID
Veldconfiguratie
Enable Module
Schakelt de module in voor de geselecteerde scope.
Aanbeveling:
- stel
Yes in voor de Store Views die AI-gegevens moeten genereren
OpenAI API Key
Globale API-sleutel die wordt gebruikt voor communicatie met OpenAI.
Vereist als:
- u bestanden wilt synchroniseren naar
OpenAI Vector Store
Niet vereist als:
- u alleen lokale exports wilt gebruiken,
- u alleen
llms.txt en openbare feeds wilt gebruiken.
Vector Store ID
Identifier van OpenAI Vector Store voor een specifieke Store View.
Aanbeveling:
- configureren op
Store View-niveau, - een aparte identifier instellen voor elke taal.
Feed Location
Relatief pad naar de map waarin exportbestanden worden opgeslagen.
Standaardwaarde:
var/ai-feeds
Aanbeveling:
- laat de map in
var/ staan, - stel deze map niet rechtstreeks via de webserver beschikbaar.
Enable Public AI Feed
Schakelt openbare endpoints in:
/llms.txt/ai-feed/{storeCode}/index.json/ai-feed/{storeCode}/{contentType}.ndjson
Schakel deze optie alleen in voor die winkelviews waarvan de content openbaar beschikbaar mag zijn.
Belangrijk:
/llms.txt is geen globale index van alle winkels- elke taalversie van de winkel retourneert een eigen manifest
/llms.txt zelf vereist geen bestaande gegenereerde bestanden om correct te antwoorden
Voegt een zichtbare link naar /llms.txt toe in de footer van de winkel.
Aanbeveling:
No standaard,Yes als u de beschikbaarheid van de AI-laag expliciet wilt communiceren aan partners, integrators of bots.
Docs Location
Relatief pad naar de map met Markdown-productdocumentatie voor product.docs.
Voorbeelden:
var/ai-docsvar/ai-docs/pl
Onder andere de volgende bestanden worden ondersteund:
{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
Batchgrootte voor productexport.
Startwaarde:
Verlaag de waarde als:
- de catalogus zeer groot is,
- de omgeving beperkte hoeveelheid geheugen heeft,
- extra AI-operaties de belasting verhogen.
Sync Product Core
Schakelt het contenttype product.core in.
Aanbeveling:
Sync Product FAQ
Schakelt product.faq in.
Gebruik dit als de winkel gegevens heeft in de tabel kowal_zapytajoprodukt_pytania.
Sync Product Docs
Schakelt product.docs in.
Gebruik dit als Markdown-documentatie al is voorbereid.
Sync Blog Content
Schakelt het kanaal blog en het type blog.article in.
Sync Category Content
Schakelt het kanaal category en het type category.content in.
Sync CMS Pages
Schakelt het kanaal cms_page en het type cms.page in.
Max Retries
Maximaal aantal pogingen voor API-operaties.
Standaard:
Polling Timeout
Maximale wachttijd op voltooiing van bestandsverwerking aan de kant van OpenAI.
Standaard:
Polling Interval
Interval tussen opeenvolgende statuscontroles.
Standaard:
HTTP Timeout
Maximale tijd voor één HTTP-request naar OpenAI.
Standaard:
Aanbevolen configuratievolgorde
Configureer de module na installatie in deze volgorde:
- Schakel de module in voor de doel-
Store View. - Voeg
OpenAI API Key toe als u synchronisatie met OpenAI plant. - Stel
Vector Store ID in voor elke taal. - Controleer
Feed Location. - Stel
Docs Location in als u Markdown-documentatie gebruikt. - Schakel de benodigde contenttypen en kanalen in.
- Schakel
Enable Public AI Feed in als endpoints openbaar beschikbaar moeten zijn. - Schakel optioneel
Show LLMs.txt Link in Footer in. - Leeg de Magento-cache.
bin/magento cache:flush
Eerste start
Dry run
Voer eerst een droge test uit voor één Store View:
bin/magento kowal:ai-export:sync --channel=product --store=1 --dry-run
Echte export
Start vervolgens de daadwerkelijke synchronisatie:
bin/magento kowal:ai-export:sync --channel=product --store=1
Status controleren
bin/magento kowal:ai-export:status --store=1
Openbare endpoints verifiëren
Als Enable Public AI Feed is ingeschakeld, controleer dan:
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
Als de winkel aparte taalversies in de URL heeft, controleer ook:
curl -i https://twoja-domena.pl/en/llms.txtcurl -i https://twoja-domena.pl/de/llms.txt
Verwacht gedrag:
/llms.txt retourneert een manifest alleen voor de huidige Store View/llms.txt werkt zelfs als er nog geen feedbestanden zijn gegenereerd/ai-feed/{storeCode}/index.json toont alleen bestaande feeds voor de betreffende winkel/ai-feed/{storeCode}/{contentType}.ndjson werkt pas wanneer de juiste bronbestanden bestaan
Cacheheaders verifiëren:
curl -I https://twoja-domena.pl/llms.txtcurl -I https://twoja-domena.pl/ai-feed/pl/index.json
U zou moeten zien:
- voor
/llms.txt headers die cache praktisch uitschakelen, - voor
index.json een korte cachelevensduur en geforceerde revalidatie.
HTML-verificatie:
- in de paginabron moet een link in
head naar /llms.txt verschijnen, - als u de footeroptie hebt geactiveerd, moet in de footer een link
LLMs.txt verschijnen.
CLI-commando’s
Synchronisatie
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
Blogbronnen importeren
bin/magento kowal:ai-blog-source:import --source=amasty_blog --store=1
Oude productalias
Nog steeds beschikbaar voor achterwaartse compatibiliteit:
bin/magento kowal:ai-feed:generate
bin/magento kowal:ai-feed:generate --store=1 --content-type=product.core --sku=example-sku --dry-run
Cron
De module gebruikt drie cron-taken:
kowal_ai_blog_source_importkowal_ai_feed_generatekowal_ai_feed_cleanup
Zorg ervoor dat Magento cron correct werkt in de omgeving.
Meest voorkomende problemen
/llms.txt retourneert 404
Controleer:
- of de actuele versie van de module met frontend routing is gedeployed,
- of u
bin/magento setup:upgrade hebt uitgevoerd, - of u in production mode
bin/magento setup:di:compile hebt uitgevoerd, - of u de standaard deploy static content hebt uitgevoerd volgens het projectproces,
- of u de cache hebt geleegd,
- of u een purge van de CDN-/reverse-proxylaag hebt uitgevoerd,
- of
Enable Public AI Feed is ingeschakeld.
Als https://twoja-domena.pl/llms.txt?v=123 werkt en https://twoja-domena.pl/llms.txt niet, betekent dit meestal dat er onderweg nog steeds een oude gedeelde cache actief is.
/llms.txt werkt, maar de feeds zijn leeg
Dit betekent meestal dat:
- er nog geen export is uitgevoerd,
- er geen actieve content is voor het betreffende kanaal,
- de juiste synchronisatieflags zijn uitgeschakeld.
Dit gedrag is correct. Het manifest zelf kan eerder werken dan de daadwerkelijke feeds.
Geen bestanden in var/ai-feeds
Controleer:
- of de module actief is op de juiste
Store View, - of de vereiste contenttypen zijn ingeschakeld,
- of Magento schrijfrechten heeft voor
var/, - of het synchronisatieproces is gestart.
Problemen met synchronisatie naar OpenAI
Controleer:
- de correctheid van
OpenAI API Key, - de correctheid van
Vector Store ID, - de beschikbaarheid van uitgaande HTTP-verbindingen,
- timeout- en retrywaarden.
Samenvatting
Na correcte installatie en configuratie geeft de module Magento 2 een kant-en-klare datalaag voor AI:
- lokaal,
- meertalig,
- synchroniseerbaar met
OpenAI, - klaar voor publicatie via
llms.txt en NDJSON-feeds, - uitbreidbaar voor volgende AI-integraties en modules.
