Kowal AI Product Feed – Installation und Konfiguration
Zweck des Dokuments
Dieses Dokument beschreibt den vollständigen Prozess zur Installation, Inbetriebnahme und Konfiguration des ModulsKowal_AiProductFeedin Magento 2. Es wurde so erstellt, dass Sie von der technischen Implementierung bis zum ersten funktionsfähigen Export und zur Veröffentlichung vonllms.txt.
Funktionsumfang des Moduls
Das Modul ermöglicht:
- den Export von Shopinhalten in
JSONundJSONL,
- die Synchronisierung von Daten mit
OpenAI Vector Store,
- die Unterstützung mehrerer Content-Kanäle wie Produkt, Blog, Kategorie und CMS,
- die Veröffentlichung öffentlicher Endpoints:
/llms.txt/ai-feed/{storeCode}/index.json/ai-feed/{storeCode}/{contentType}.ndjson
- das Hinzufügen eines Links zu
llms.txtim Bereichhead,
- das optionale Hinzufügen eines Links zu
llms.txtim Shop-Footer.
llms.txtfunktioniert für den jeweils aktuellenStore View. Das bedeutet, dass jede Sprachversion ein eigenes Manifest und eigene Links zu den Feeds zurückgeben kann.
Voraussetzungen
Stellen Sie vor der Installation sicher, dass:
- Magento 2 ordnungsgemäß funktioniert,
- Sie SSH-Zugriff auf das Magento-Stammverzeichnis haben,
Composerin der Umgebung verfügbar ist,- der PHP-Prozess Schreibzugriff auf das Verzeichnis
var/,
- Sie über einen aktiven
OpenAI API Keyverfügen, wenn Sie die Synchronisierung mitOpenAI Vector Store.
Installation des Moduls
1. Composer-Repository hinzufügen
Fügen Sie das Composer-Repository von Kowal hinzu:
Die Zugangsdaten zum Composer-Repository (E-Mail-Adresse des Kunden und Lizenz-Token) erhalten Sie nach dem Kauf per E-Mail. Sie sind außerdem nach dem Login im Kundenbereich unter kowal.storeverfügbar. Ersetzen Sie TWOJ_EMAIL_KLIENTA durch die E-Mail-Adresse Ihres Kontos und TWOJ_TOKEN durch den erhaltenen Token. Führen Sie die Befehle im Magento-Stammverzeichnis aus.
composer config repositories.kowal composer https://repo.kowal.store
Wenn das Repository privat ist:
composer config http-basic.repo.kowal.store "TWOJ_EMAIL_KLIENTA" "TWOJ_TOKEN"
2. Paket installieren
composer require kowal/module-ai-product-feed
3. Modul aktivieren
bin/magento module:enable Kowal_AiProductFeed
4. Magento aktualisieren
bin/magento setup:upgrade
5. Kompilierung und Cache
Führen Sie in der Produktivumgebung zusätzlich Folgendes aus:
bin/magento setup:di:compile
bin/magento cache:flush
In der Entwicklungsumgebung genügt normalerweise:
bin/magento cache:flush
Wenn vor Magento eine zusätzliche Cache-Schicht liegt, führen Sie auch einen Purge aus bei:
VarnishCloudflareNginx fastcgi/proxy cache- einem anderen Reverse Proxy oder CDN
6. Modulstatus bestätigen
bin/magento module:status Kowal_AiProductFeed
Konfigurationsort
Die Modulkonfiguration finden Sie im Adminbereich unter:
Stores -> Configuration -> General -> Kowal AI Feed
Empfohlenes Konfigurationsmodell
Bewährt hat sich die Konfiguration auf Ebene derStore View, besonders bei mehrsprachigen Shops.
Empfehlung:
- eine
Store View= eine Sprache,
- eine
Store View= einVector Store ID,
- eine
Store View= eine eigene öffentliche KI-Feed-Ebene.
Beispiel:
PLStore View -> PolnischVector Store IDENStore View -> EnglischVector Store ID
Feldkonfiguration
Enable Module
Aktiviert das Modul für den gewählten Geltungsbereich.
Empfehlung:
- setze
Yesin denjenigenStore View, die KI-Daten generieren sollen
OpenAI API Key
Globaler API-Schlüssel für die Kommunikation mitOpenAI.
Erforderlich, wenn:
- Sie Dateien synchronisieren möchten mit
OpenAI Vector Store
Nicht erforderlich, wenn:
- Sie nur lokale Exporte verwenden möchten,
- Sie ausschließlich
llms.txtund öffentliche Feeds verwenden möchten.
Vector Store ID
Kennung desOpenAI Vector Storefür eine bestimmteStore View.
Empfehlung:
- auf Ebene der
Store View,
- eine eigene Kennung für jede Sprache festlegen.
Feed Location
Relativer Pfad zum Verzeichnis der Exportdateien.
Standardwert:
var/ai-feeds
Empfehlung:
- das Verzeichnis belassen unter
var/,
- dieses Verzeichnis nicht direkt über den Webserver bereitstellen.
Enable Public AI Feed
Aktiviert öffentliche Endpoints:
/llms.txt/ai-feed/{storeCode}/index.json/ai-feed/{storeCode}/{contentType}.ndjson
Aktivieren Sie diese Option nur für Store Views, deren Inhalte öffentlich verfügbar sein dürfen.
Wichtig:
/llms.txtist kein globaler Index aller Shops- jede Shopsprachversion liefert ihr eigenes Manifest
- das alleinige
/llms.txtbenötigt keine generierten Dateien, um korrekt zu antworten
Ergänzt einen sichtbaren Link zu/llms.txtim Shop-Footer.
Empfehlung:
Nostandardmäßig,Yes, wenn Sie Partner, Integratoren oder Bots ausdrücklich auf die KI-Ebene hinweisen möchten.
Docs Location
Relativer Pfad zum Verzeichnis der Markdown-Produktdokumentation fürproduct.docs.
Beispiele:
var/ai-docsvar/ai-docs/pl
Unterstützt werden unter anderem Dateien:
{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
Stapelgröße für den Produktexport.
Startwert:
Reduzieren Sie den Wert, wenn:
- der Katalog sehr groß ist,
- die Umgebung begrenzten Speicher besitzt,
- zusätzliche KI-Operationen die Belastung erhöhen.
Sync Product Core
Aktiviert den Inhaltstypproduct.core.
Empfehlung:
Sync Product FAQ
Aktiviertproduct.faq.
Verwenden, wenn der Shop Daten in der Tabelle besitztkowal_zapytajoprodukt_pytania.
Sync Product Docs
Aktiviertproduct.docs.
Verwenden, wenn die Markdown-Dokumentation bereits vorbereitet ist.
Sync Blog Content
Aktiviert den Kanalblogund den Typblog.article.
Sync Category Content
Aktiviert den Kanalcategoryund den Typcategory.content.
Sync CMS Pages
Aktiviert den Kanalcms_pageund den Typcms.page.
Max Retries
Maximale Anzahl von API-Versuchen.
Standard:
Polling Timeout
Maximale Wartezeit bis zum Abschluss der Dateiverarbeitung beiOpenAI.
Standard:
Polling Interval
Intervall zwischen Statusprüfungen.
Standard:
HTTP Timeout
Maximale Dauer einer HTTP-Anfrage anOpenAI.
Standard:
Empfohlene Konfigurationsreihenfolge
Konfigurieren Sie nach der Installation in dieser Reihenfolge:
- Das Modul für die Zielansicht aktivieren:
Store View.
- Ergänzen Sie
OpenAI API Key, wenn Sie eine Synchronisation planen mitOpenAI.
- Legen Sie
Vector Store IDfür jede Sprache.
- Prüfen Sie
Feed Location.
- Legen Sie
Docs Location, wenn Sie Markdown-Dokumentation verwenden.
- Benötigte Inhaltstypen und Kanäle aktivieren.
- Aktivieren Sie
Enable Public AI Feed, wenn die Endpoints öffentlich verfügbar sein sollen.
- Optional aktivieren:
Show LLMs.txt Link in Footer.
- Leeren Sie den Magento-Cache.
bin/magento cache:flush
Erster Start
Dry Run
Führen Sie zunächst einen Testlauf für eine einzelneStore View:
bin/magento kowal:ai-export:sync --channel=product --store=1 --dry-run
Tatsächlicher Export
Starten Sie anschließend die eigentliche Synchronisation:
bin/magento kowal:ai-export:sync --channel=product --store=1
Statusprüfung
bin/magento kowal:ai-export:status --store=1
Öffentliche Endpoints prüfen
WennEnable Public AI Feed aktiviert ist, prüfen Sie:
curl -i https://twoja-domena.pl/llms.txt
curl -i https://twoja-domena.pl/ai-feed/pl/index.json
curl -i https://twoja-domena.pl/ai-feed/pl/product.core.ndjson
Prüfen Sie bei eigenen Sprachversionen in der URL außerdem:
curl -i https://twoja-domena.pl/en/llms.txt
curl -i https://twoja-domena.pl/de/llms.txt
Erwartetes Verhalten:
/llms.txtliefert ein Manifest nur für die aktuelleStore View/llms.txtfunktioniert auch ohne bereits generierte Feed-Dateien/ai-feed/{storeCode}/index.jsonzeigt nur vorhandene Feeds des jeweiligen Shops/ai-feed/{storeCode}/{contentType}.ndjsonfunktioniert erst mit den entsprechenden Quelldateien
Cache-Header prüfen:
curl -I https://twoja-domena.pl/llms.txt
curl -I https://twoja-domena.pl/ai-feed/pl/index.json
Sie sollten Folgendes sehen:
- für
/llms.txtHeader, die den Cache praktisch deaktivieren,
- für
index.jsonkurze Cache-Lebensdauer und erzwungene Revalidierung.
HTML prüfen:
- im Seitenquelltext sollte ein Link erscheinen in
headnach/llms.txt,
- bei aktivierter Footer-Option sollte im Footer ein Link erscheinen
LLMs.txt.
CLI-Befehle
Synchronisation
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
Blogquellen importieren
bin/magento kowal:ai-blog-source:import --source=amasty_blog --store=1
Alter Produkt-Alias
Aus Gründen der Abwärtskompatibilität weiterhin verfügbar:
bin/magento kowal:ai-feed:generate
bin/magento kowal:ai-feed:generate --store=1 --content-type=product.core --sku=example-sku --dry-run
Cron
Das Modul verwendet drei Cronjobs:
kowal_ai_blog_source_importkowal_ai_feed_generatekowal_ai_feed_cleanup
Stellen Sie sicher, dass Magento-Cron in der Umgebung korrekt funktioniert.
Häufige Probleme
/llms.txtliefert404
Prüfen Sie:
- ob die aktuelle Modulversion mit Frontend-Routing installiert ist,
- ob Sie Folgendes ausgeführt haben:
bin/magento setup:upgrade,
- ob Sie im Production-Modus Folgendes ausgeführt haben:
bin/magento setup:di:compile,
- ob statische Inhalte gemäß dem Projektprozess bereitgestellt wurden,
- ob der Cache geleert wurde,
- ob ein CDN-/Reverse-Proxy-Purge ausgeführt wurde,
- ob
Enable Public AI Feedaktiviert ist.
Wennhttps://twoja-domena.pl/llms.txt?v=123funktioniert, aberhttps://twoja-domena.pl/llms.txtnicht, liegt dies meist an einem weiterhin aktiven alten gemeinsamen Cache.
/llms.txtfunktioniert, aber die Feeds sind leer
Dies bedeutet normalerweise:
- noch kein Export ausgeführt,
- keine aktiven Inhalte für den jeweiligen Kanal,
- die entsprechenden Synchronisationsflags sind deaktiviert.
Dieses Verhalten ist korrekt. Das Manifest kann bereits vor den eigentlichen Feeds funktionieren.
Keine Dateien invar/ai-feeds
Prüfen Sie:
- ob das Modul in der richtigen Ansicht aktiv ist:
Store View,
- ob die erforderlichen Inhaltstypen aktiviert sind,
- ob Magento Schreibrechte besitzt für
var/,
- ob der Synchronisationsprozess gestartet wurde.
Probleme bei der Synchronisation mit OpenAI
Prüfen Sie:
- Korrektheit von
OpenAI API Key,
- Korrektheit von
Vector Store ID,
- Verfügbarkeit ausgehender HTTP-Verbindungen,
- Timeout- und Retry-Werte.
Zusammenfassung
Nach korrekter Installation und Konfiguration bietet das Modul Magento 2 eine fertige KI-Datenebene:
- lokal,
- mehrsprachig,
- synchronisierbar mit
OpenAI,
- zur Veröffentlichung bereit über
llms.txt- undNDJSON,
- erweiterbar um weitere KI-Integrationen und -Module.
