Kowal AI Product Feed - installatie en configuratie
Doel van het document
Dit document beschrijft het volledige proces voor de installatie, ingebruikname en configuratie van de module Kowal_AiProductFeed in Magento 2. Het is zo opgesteld dat u van de technische implementatie kunt doorgaan naar de eerste werkende export en publicatie van llms.txt.
Functionele scope van de module
De module maakt het mogelijk om:
- winkelcontent te exporteren naar
JSON- en JSONL-bestanden, - gegevens te synchroniseren met
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 sectie head, - optioneel een link naar
llms.txt toe te voegen in de footer van de winkel.
llms.txt werkt per actuele Store View. Dit betekent dat elke taalversie een eigen manifest en eigen links naar feeds kan retourneren.
Vereisten
Controleer vóór de installatie of:
- Magento 2 correct werkt,
- u SSH-toegang hebt tot de hoofdmap van Magento,
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 met OpenAI Vector Store wilt gebruiken.
Installatie van de module
1. Het Composer-repository toevoegen
Voeg het Composer-repository van Kowal toe:
De toegangsgegevens voor het Composer-repository, het e-mailadres van de klant en de licentietoken, ontvangt u per e-mail na aankoop. Ze zijn ook beschikbaar in het klantpaneel 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 opdrachten uit in de hoofdmap van Magento.
composer config repositories.kowal composer https://repo.kowal.store
Als het repository privé is:
composer config http-basic.repo.kowal.store 'TWOJ_EMAIL_KLIENTA' 'TWOJ_TOKEN'
2. Installatie van het pakket
composer require kowal/module-ai-product-feed
3. De module inschakelen
bin/magento module:enable Kowal_AiProductFeed
4. Magento bijwerken
bin/magento setup:upgrade
5. Compilatie en cache
Voer in een productieomgeving aanvullend uit:
bin/magento setup:di:compilebin/magento cache:flush
In een developmentomgeving 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 zijde van:
VarnishCloudflareNginx fastcgi/proxy cache- een andere reverse proxy of CDN
6. De modulestatus bevestigen
bin/magento module:status Kowal_AiProductFeed
Locatie van de configuratie
De configuratie van de module is beschikbaar in het paneel:
Stores -> Configuration -> General -> Kowal AI Feed
Aanbevolen configuratiemodel
De 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 = een aparte openbare AI-feedlaag.
Voorbeeld:
PL store view -> Poolse Vector Store IDEN store view -> Engelse Vector Store ID
Configuratie van velden
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 met
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/, - stel deze map niet rechtstreeks beschikbaar via de webserver.
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 de winkelweergaven 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 niet dat er gegenereerde bestanden bestaan 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 beperkt geheugen heeft,
- extra AI-bewerkingen 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 de 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-bewerkingen.
Standaard:
Polling Timeout
Maximale wachttijd totdat de bestandsverwerking aan de zijde van OpenAI is voltooid.
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 de installatie in deze volgorde:
- Schakel de module in voor de doel-
Store View. - Voeg de
OpenAI API Key toe als u synchronisatie met OpenAI plant. - Stel de
Vector Store ID in voor elke taal. - Controleer de
Feed Location. - Stel de
Docs Location in als u Markdown-documentatie gebruikt. - Schakel de benodigde contenttypen en kanalen in.
- Schakel
Enable Public AI Feed in als de endpoints openbaar beschikbaar moeten zijn. - Schakel optioneel
Show LLMs.txt Link in Footer in. - Maak de Magento-cache leeg.
bin/magento cache:flush
Eerste uitvoering
Dry run
Voer eerst een droge test uit voor één Store View:
bin/magento kowal:ai-export:sync --channel=product --store=1 --dry-run
Werkelijke export
Start vervolgens de eigenlijke synchronisatie:
bin/magento kowal:ai-export:sync --channel=product --store=1
Status controleren
bin/magento kowal:ai-export:status --store=1
Verificatie van openbare endpoints
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 afzonderlijke taalversies in de URL heeft, controleer dan ook:
curl -i https://twoja-domena.pl/en/llms.txtcurl -i https://twoja-domena.pl/de/llms.txt
Verwacht gedrag:
/llms.txt retourneert alleen het manifest voor de huidige Store View/llms.txt werkt zelfs wanneer 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
Verificatie van cacheheaders:
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-opdrachten
Synchronisatie
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
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:generatebin/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 geïmplementeerd,
- 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 van 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:
- de export nog niet 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 eigenlijke 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 juistheid van de
OpenAI API Key, - de juistheid van de
Vector Store ID, - de beschikbaarheid van uitgaande HTTP-verbindingen,
- de waarden van time-outs en retries.
Samenvatting
Na correcte installatie en configuratie biedt de module Magento 2 een kant-en-klare gegevenslaag voor AI:
- lokaal,
- meertalig,
- synchroniseerbaar met
OpenAI, - klaar voor publicatie via
llms.txt en NDJSON-feeds, - uitbreidbaar voor verdere AI-integraties en modules.
