Kowal AI Product Feed - Installation und Konfiguration
Ziel des Dokuments
Dieses Dokument beschreibt den vollständigen Prozess der Installation, Inbetriebnahme und Konfiguration des Moduls Kowal_AiProductFeed in Magento 2. Es wurde so vorbereitet, dass Sie vom technischen Deployment bis zum ersten funktionierenden Export und zur Veröffentlichung von llms.txt gelangen können.
Funktionsumfang des Moduls
Das Modul ermöglicht:
- den Export von Shop-Inhalten in
JSON- und JSONL-Dateien, - 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 Endpunkte:
/llms.txt/ai-feed/{storeCode}/index.json/ai-feed/{storeCode}/{contentType}.ndjson
- das Hinzufügen eines Links zu
llms.txt im Bereich head, - optional das Hinzufügen eines Links zu
llms.txt im Shop-Footer.
llms.txt funktioniert pro aktuellem Store 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 korrekt funktioniert,
- Sie SSH-Zugriff auf das Magento-Hauptverzeichnis haben,
Composer in der Umgebung verfügbar ist,- der PHP-Prozess Schreibzugriff auf das Verzeichnis
var/ hat, - Sie einen aktiven
OpenAI API Key haben, wenn Sie die Synchronisierung mit OpenAI Vector Store nutzen möchten.
Installation des Moduls
1. Composer-Repository hinzufügen
Wenn das Modul aus einem Git-Repository installiert wird:
composer config repositories.ai.product.feed vcs https://github.com/kowalco/module-ai-product-feed
Wenn das Repository privat ist:
composer config --global --auth github-oauth.github.com
2. Paketinstallation
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 Produktionsumgebung zusätzlich Folgendes aus:
bin/magento setup:di:compilebin/magento cache:flush
In der Entwicklungsumgebung reicht normalerweise aus:
bin/magento cache:flush
Wenn vor Magento eine zusätzliche Cache-Schicht arbeitet, führen Sie auch einen Purge auf der Seite von Folgendem aus:
VarnishCloudflareNginx fastcgi/proxy cache- einem anderen Reverse Proxy oder CDN
6. Modulstatus bestätigen
bin/magento module:status Kowal_AiProductFeed
Speicherort der Konfiguration
Die Modulkonfiguration ist im Panel verfügbar unter:
Stores -> Configuration -> General -> Kowal AI Feed
Empfohlenes Konfigurationsmodell
Best Practice ist die Konfiguration auf Store View-Ebene, insbesondere wenn der Shop in mehreren Sprachen betrieben wird.
Empfehlung:
- ein
Store View = eine Sprache, - ein
Store View = eine Vector Store ID, - ein
Store View = eine separate öffentliche Ebene von AI-Feeds.
Beispiel:
PL Store View -> polnische Vector Store IDEN Store View -> englische Vector Store ID
Feldkonfiguration
Enable Module
Aktiviert das Modul für den ausgewählten Geltungsbereich.
Empfehlung:
- setzen Sie
Yes für die Store View, die AI-Daten generieren sollen
OpenAI API Key
Globaler API-Schlüssel für die Kommunikation mit OpenAI.
Erforderlich, wenn:
- Sie Dateien mit
OpenAI Vector Store synchronisieren möchten
Nicht erforderlich, wenn:
- Sie nur lokale Exporte nutzen möchten,
- Sie nur
llms.txt und öffentliche Feeds verwenden möchten.
Vector Store ID
Die Kennung des OpenAI Vector Store für einen bestimmten Store View.
Empfehlung:
- auf
Store View-Ebene konfigurieren, - für jede Sprache eine separate Kennung festlegen.
Feed Location
Relativer Pfad zum Verzeichnis, in dem die Exportdateien gespeichert werden.
Standardwert:
var/ai-feeds
Empfehlung:
- das Verzeichnis in
var/ belassen, - dieses Verzeichnis nicht direkt über den Webserver bereitstellen.
Enable Public AI Feed
Aktiviert öffentliche Endpunkte:
/llms.txt/ai-feed/{storeCode}/index.json/ai-feed/{storeCode}/{contentType}.ndjson
Aktivieren Sie diese Option nur für die Store Views, deren Inhalte öffentlich verfügbar sein dürfen.
Wichtig:
/llms.txt ist kein globaler Index aller Shops- jede Sprachversion des Shops liefert ein eigenes Manifest zurück
/llms.txt selbst benötigt keine vorhandenen generierten Dateien, um korrekt zu antworten
Fügt im Shop-Footer einen sichtbaren Link zu /llms.txt hinzu.
Empfehlung:
No standardmäßig,Yes, wenn Sie die Verfügbarkeit der AI-Ebene für Partner, Integratoren oder Bots ausdrücklich kommunizieren möchten.
Docs Location
Relativer Pfad zum Verzeichnis mit der Markdown-Produktdokumentation für product.docs.
Beispiele:
var/ai-docsvar/ai-docs/pl
Unterstützt werden unter anderem folgende 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
Paketgröße für den Produktexport.
Startwert:
Verringern Sie den Wert, wenn:
- der Katalog sehr groß ist,
- die Umgebung nur begrenzten Speicher hat,
- zusätzliche AI-Operationen die Last erhöhen.
Sync Product Core
Aktiviert den Inhaltstyp product.core.
Empfehlung:
Sync Product FAQ
Aktiviert product.faq.
Verwenden Sie dies, wenn der Shop Daten in der Tabelle kowal_zapytajoprodukt_pytania enthält.
Sync Product Docs
Aktiviert product.docs.
Verwenden Sie dies, wenn die Markdown-Dokumentation bereits vorbereitet ist.
Sync Blog Content
Aktiviert den Kanal blog und den Typ blog.article.
Sync Category Content
Aktiviert den Kanal category und den Typ category.content.
Sync CMS Pages
Aktiviert den Kanal cms_page und den Typ cms.page.
Max Retries
Maximale Anzahl von API-Versuchen.
Standardmäßig:
Polling Timeout
Maximale Wartezeit auf den Abschluss der Dateiverarbeitung auf der Seite von OpenAI.
Standardmäßig:
Polling Interval
Intervall zwischen den einzelnen Statusprüfungen.
Standardmäßig:
HTTP Timeout
Maximale Dauer einer einzelnen HTTP-Anfrage an OpenAI.
Standardmäßig:
Empfohlene Reihenfolge der Konfiguration
Konfigurieren Sie das Modul nach der Installation in dieser Reihenfolge:
- Aktivieren Sie das Modul für den Ziel-
Store View. - Fügen Sie den
OpenAI API Key hinzu, wenn Sie die Synchronisierung mit OpenAI planen. - Legen Sie die
Vector Store ID für jede Sprache fest. - Prüfen Sie den
Feed Location. - Legen Sie den
Docs Location fest, wenn Sie Markdown-Dokumentation verwenden. - Aktivieren Sie die benötigten Inhaltstypen und Kanäle.
- Aktivieren Sie
Enable Public AI Feed, wenn die Endpunkte öffentlich verfügbar sein sollen. - Aktivieren Sie optional
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 einen Store View aus:
bin/magento kowal:ai-export:sync --channel=product --store=1 --dry-run
Echter Export
Starten Sie anschließend die eigentliche Synchronisierung:
bin/magento kowal:ai-export:sync --channel=product --store=1
Status prüfen
bin/magento kowal:ai-export:status --store=1
Prüfung öffentlicher Endpunkte
Wenn Enable Public AI Feed aktiviert ist, prüfen Sie:
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
Wenn der Shop separate Sprachversionen in der URL hat, prüfen Sie auch:
curl -i https://twoja-domena.pl/en/llms.txtcurl -i https://twoja-domena.pl/de/llms.txt
Erwartetes Verhalten:
/llms.txt liefert nur ein Manifest für den aktuellen Store View zurück/llms.txt funktioniert auch dann, wenn noch keine Feed-Dateien generiert wurden/ai-feed/{storeCode}/index.json zeigt nur vorhandene Feeds für den jeweiligen Shop an/ai-feed/{storeCode}/{contentType}.ndjson funktioniert erst dann, wenn die entsprechenden Quelldateien vorhanden sind
Prüfung der Cache-Header:
curl -I https://twoja-domena.pl/llms.txtcurl -I https://twoja-domena.pl/ai-feed/pl/index.json
Sie sollten Folgendes sehen:
- für
/llms.txt Header, die den Cache praktisch deaktivieren, - für
index.json eine kurze Cache-Lebensdauer und erzwungene Revalidierung.
Prüfung von HTML:
- im Seitenquelltext sollte im
head ein Link zu /llms.txt erscheinen, - wenn Sie die Footer-Option aktiviert haben, sollte im Footer ein Link
LLMs.txt erscheinen.
CLI-Befehle
Synchronisierung
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
Import von Blog-Quellen
bin/magento kowal:ai-blog-source:import --source=amasty_blog --store=1
Alter Produkt-Alias
Weiterhin verfügbar für Abwärtskompatibilität:
bin/magento kowal:ai-feed:generatebin/magento kowal:ai-feed:generate --store=1 --content-type=product.core --sku=example-sku --dry-run
Cron
Das Modul verwendet drei Cron-Jobs:
kowal_ai_blog_source_importkowal_ai_feed_generatekowal_ai_feed_cleanup
Stellen Sie sicher, dass der Magento-Cron in der Umgebung korrekt funktioniert.
Häufigste Probleme
/llms.txt gibt 404 zurück
Prüfen Sie:
- ob die aktuelle Modulversion mit Frontend-Routing bereitgestellt wurde,
- ob Sie
bin/magento setup:upgrade ausgeführt haben, - ob Sie im Production Mode
bin/magento setup:di:compile ausgeführt haben, - ob Sie den standardmäßigen Static-Content-Deploy gemäß Projektprozess ausgeführt haben,
- ob Sie den Cache geleert haben,
- ob Sie einen Purge der CDN- / Reverse-Proxy-Schicht durchgeführt haben,
- ob
Enable Public AI Feed aktiviert ist.
Wenn https://twoja-domena.pl/llms.txt?v=123 funktioniert, aber https://twoja-domena.pl/llms.txt nicht, bedeutet das normalerweise, dass unterwegs noch ein alter gemeinsam genutzter Cache aktiv ist.
/llms.txt funktioniert, aber die Feeds sind leer
Das bedeutet in der Regel, dass:
- der Export noch nicht ausgeführt wurde,
- keine aktiven Inhalte für den jeweiligen Kanal vorhanden sind,
- die entsprechenden Synchronisierungs-Flags deaktiviert sind.
Dieses Verhalten ist korrekt. Das Manifest selbst kann früher funktionieren als die eigentlichen Feeds.
Keine Dateien in var/ai-feeds
Prüfen Sie:
- ob das Modul im richtigen
Store View aktiv ist, - ob die erforderlichen Inhaltstypen aktiviert sind,
- ob Magento Schreibrechte für
var/ hat, - ob der Synchronisierungsprozess gestartet wurde.
Probleme bei der Synchronisierung mit OpenAI
Prüfen Sie:
- die Korrektheit des
OpenAI API Key, - die Korrektheit der
Vector Store ID, - die Verfügbarkeit ausgehender HTTP-Verbindungen,
- die Werte für Timeouts und Retries.
Zusammenfassung
Nach korrekter Installation und Konfiguration bietet das Modul Magento 2 eine fertige Datenebene für AI:
- lokal,
- mehrsprachig,
- mit
OpenAI synchronisierbar, - bereit zur Veröffentlichung über
llms.txt und NDJSON-Feeds, - erweiterbar für weitere Integrationen und AI-Module.
WhatsApp
+48608012047
