Kowal AI Product Feed - installation et configuration
Objectif du document
Ce document décrit le processus complet d’installation, de mise en service et de configuration du module Kowal_AiProductFeed dans Magento 2. Il a été préparé pour permettre de passer du déploiement technique à une première exportation fonctionnelle ainsi qu’à la publication de llms.txt.
Périmètre fonctionnel du module
Le module permet :
- l’exportation du contenu de la boutique vers des fichiers
JSONetJSONL, - la synchronisation des données vers
OpenAI Vector Store, - la prise en charge de plusieurs canaux de contenu, tels que le produit, le blog, la catégorie et le CMS,
- la publication d’endpoints publics :
/llms.txt/ai-feed/{storeCode}/index.json/ai-feed/{storeCode}/{contentType}.ndjson
- l’ajout d’un lien vers
llms.txtdans la sectionhead, - l’ajout optionnel d’un lien vers
llms.txtdans le pied de page de la boutique.
llms.txt fonctionne par Store View courant. Cela signifie que chaque version linguistique peut renvoyer son propre manifeste et ses propres liens vers les flux.
Prérequis
Avant l’installation, assurez-vous que :
- Magento 2 fonctionne correctement,
- vous disposez d’un accès SSH au répertoire racine de Magento,
Composerest disponible dans l’environnement,- le processus PHP dispose des droits d’écriture dans le répertoire
var/, - vous disposez d’une clé
OpenAI API Keyactive si vous souhaitez utiliser la synchronisation versOpenAI Vector Store.
Installation du module
1. Ajout du dépôt Composer
Si le module est installé depuis un dépôt Git :
composer config repositories.ai.product.feed vcs https://github.com/kowalco/module-ai-product-feedSi le dépôt est privé :
composer config --global --auth github-oauth.github.com 2. Installation du package
composer require kowal/module-ai-product-feed3. Activation du module
bin/magento module:enable Kowal_AiProductFeed4. Mise à jour de Magento
bin/magento setup:upgrade5. Compilation et cache
En environnement de production, exécutez également :
bin/magento setup:di:compilebin/magento cache:flushEn environnement de développement, il suffit généralement d’exécuter :
bin/magento cache:flushSi une couche de cache supplémentaire est placée devant Magento, effectuez également un purge côté :
VarnishCloudflareNginx fastcgi/proxy cache- un autre reverse proxy ou CDN
6. Confirmation du statut du module
bin/magento module:status Kowal_AiProductFeedEmplacement de la configuration
La configuration du module est disponible dans le panneau :
Stores -> Configuration -> General -> Kowal AI Feed
Modèle de configuration recommandé
La meilleure pratique consiste à configurer au niveau du Store View, en particulier si la boutique fonctionne en plusieurs langues.
Recommandation :
- un
Store View= une langue, - un
Store View= unVector Store ID, - un
Store View= une couche publique distincte de flux IA.
Exemple :
PLstore view ->Vector Store IDpolonaisENstore view ->Vector Store IDanglais
Configuration des champs
Enable Module
Active le module pour le périmètre sélectionné.
Recommandation :
- définir
Yessur lesStore Viewqui doivent générer des données IA
OpenAI API Key
Clé API globale utilisée pour communiquer avec OpenAI.
Requise si :
- vous souhaitez synchroniser des fichiers vers
OpenAI Vector Store
Non requise si :
- vous souhaitez utiliser uniquement des exports locaux,
- vous souhaitez utiliser uniquement
llms.txtet les flux publics.
Vector Store ID
Identifiant OpenAI Vector Store pour un Store View donné.
Recommandation :
- configurer au niveau du
Store View, - définir un identifiant distinct pour chaque langue.
Feed Location
Chemin relatif vers le répertoire dans lequel les fichiers d’exportation seront enregistrés.
Valeur par défaut :
var/ai-feeds
Recommandation :
- laisser le répertoire dans
var/, - ne pas exposer ce répertoire directement via le serveur web.
Enable Public AI Feed
Active les endpoints publics :
/llms.txt/ai-feed/{storeCode}/index.json/ai-feed/{storeCode}/{contentType}.ndjson
Activez cette option uniquement pour les vues de boutique dont le contenu peut être accessible publiquement.
Important :
/llms.txtn’est pas un index global de toutes les boutiques- chaque version linguistique de la boutique renvoie son propre manifeste
/llms.txtlui-même ne nécessite pas l’existence de fichiers générés pour répondre correctement
Show LLMs.txt Link in Footer
Ajoute un lien visible vers /llms.txt dans le pied de page de la boutique.
Recommandation :
Nopar défaut,Yessi vous souhaitez communiquer explicitement la disponibilité de la couche IA aux partenaires, intégrateurs ou bots.
Docs Location
Chemin relatif vers le répertoire contenant la documentation produit Markdown pour product.docs.
Exemples :
var/ai-docsvar/ai-docs/pl
Sont notamment pris en charge les fichiers :
{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
Taille du lot pour l’exportation des produits.
Valeur initiale :
500
Réduisez la valeur si :
- le catalogue est très volumineux,
- l’environnement dispose d’une mémoire limitée,
- des opérations IA supplémentaires augmentent la charge.
Sync Product Core
Active le type de contenu product.core.
Recommandation :
Yes
Sync Product FAQ
Active product.faq.
À utiliser si la boutique dispose de données dans la table kowal_zapytajoprodukt_pytania.
Sync Product Docs
Active product.docs.
À utiliser si la documentation Markdown est déjà prête.
Sync Blog Content
Active le canal blog et le type blog.article.
Sync Category Content
Active le canal category et le type category.content.
Sync CMS Pages
Active le canal cms_page et le type cms.page.
Max Retries
Nombre maximal de tentatives pour les opérations API.
Par défaut :
3
Polling Timeout
Temps d’attente maximal pour la fin du traitement du fichier côté OpenAI.
Par défaut :
600
Polling Interval
Intervalle entre deux vérifications successives du statut.
Par défaut :
5
HTTP Timeout
Durée maximale d’une requête HTTP unique vers OpenAI.
Par défaut :
60
Ordre de configuration recommandé
Après l’installation, configurez le module dans cet ordre :
- Activez le module pour le
Store Viewcible. - Ajoutez
OpenAI API Keysi vous prévoyez une synchronisation avecOpenAI. - Définissez le
Vector Store IDpour chaque langue. - Vérifiez
Feed Location. - Définissez
Docs Locationsi vous utilisez une documentation Markdown. - Activez les types de contenu et canaux nécessaires.
- Activez
Enable Public AI Feedsi les endpoints doivent être accessibles publiquement. - Activez éventuellement
Show LLMs.txt Link in Footer. - Videz le cache Magento.
bin/magento cache:flushPremier lancement
Dry run
Commencez par effectuer un test à blanc pour un seul Store View :
bin/magento kowal:ai-export:sync --channel=product --store=1 --dry-runExportation réelle
Lancez ensuite la synchronisation réelle :
bin/magento kowal:ai-export:sync --channel=product --store=1Vérification du statut
bin/magento kowal:ai-export:status --store=1Vérification des endpoints publics
Si Enable Public AI Feed est activé, vérifiez :
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.ndjsonSi la boutique possède des versions linguistiques distinctes dans l’URL, vérifiez également :
curl -i https://twoja-domena.pl/en/llms.txtcurl -i https://twoja-domena.pl/de/llms.txtComportement attendu :
/llms.txtrenvoie un manifeste uniquement pour leStore Viewcourant/llms.txtfonctionne même s’il n’existe pas encore de fichiers de flux générés/ai-feed/{storeCode}/index.jsonaffiche uniquement les flux existants pour la boutique concernée/ai-feed/{storeCode}/{contentType}.ndjsonne fonctionne que lorsque les fichiers source correspondants existent
Vérification des en-têtes de cache :
curl -I https://twoja-domena.pl/llms.txtcurl -I https://twoja-domena.pl/ai-feed/pl/index.jsonVous devriez voir :
- pour
/llms.txt, des en-têtes désactivant pratiquement le cache, - pour
index.json, une durée de vie courte du cache et une revalidation forcée.
Vérification HTML :
- dans le code source de la page, un lien dans le
headvers/llms.txtdoit apparaître, - si vous avez activé l’option du pied de page, un lien
LLMs.txtdoit apparaître dans le footer.
Commandes CLI
Synchronisation
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=1Statut
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_blogImport des sources du blog
bin/magento kowal:ai-blog-source:import --source=amasty_blog --store=1Ancien alias produit
Toujours disponible pour assurer la rétrocompatibilité :
bin/magento kowal:ai-feed:generatebin/magento kowal:ai-feed:generate --store=1 --content-type=product.core --sku=example-sku --dry-runCron
Le module utilise trois tâches cron :
kowal_ai_blog_source_importkowal_ai_feed_generatekowal_ai_feed_cleanup
Assurez-vous que le cron Magento fonctionne correctement dans l’environnement.
Problèmes les plus fréquents
/llms.txt renvoie 404
Vérifiez :
- que la version actuelle du module avec routage frontend est bien déployée,
- que vous avez exécuté
bin/magento setup:upgrade, - qu’en mode production vous avez exécuté
bin/magento setup:di:compile, - que vous avez exécuté le déploiement standard du contenu statique conformément au processus du projet,
- que vous avez vidé le cache,
- que vous avez effectué le purge de la couche CDN / reverse proxy,
- que
Enable Public AI Feedest activé.
Si https://twoja-domena.pl/llms.txt?v=123 fonctionne mais que https://twoja-domena.pl/llms.txt ne fonctionne pas, cela signifie généralement qu’un ancien cache partagé est encore actif dans la chaîne.
/llms.txt fonctionne, mais les flux sont vides
Cela signifie généralement que :
- l’exportation n’a pas encore été exécutée,
- aucun contenu actif n’est disponible pour ce canal,
- les indicateurs de synchronisation correspondants sont désactivés.
Ce comportement est correct. Le manifeste lui-même peut fonctionner avant les flux proprement dits.
Aucun fichier dans var/ai-feeds
Vérifiez :
- que le module est actif sur le bon
Store View, - que les types de contenu requis sont activés,
- que Magento a les droits d’écriture sur
var/, - que le processus de synchronisation a bien été lancé.
Problèmes de synchronisation avec OpenAI
Vérifiez :
- la validité de
OpenAI API Key, - la validité de
Vector Store ID, - la disponibilité des connexions HTTP sortantes,
- les valeurs des timeouts et des tentatives.
Résumé
Après une installation et une configuration correctes, le module fournit à Magento 2 une couche de données IA prête à l’emploi :
- locale,
- multilingue,
- pouvant être synchronisée avec
OpenAI, - prête à être publiée via
llms.txtet les fluxNDJSON, - évolutive pour de futures intégrations et modules IA.


















