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
JSON et JSONL, - 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.txt dans la section head, - l’ajout optionnel d’un lien vers
llms.txt dans 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,
Composer est disponible dans l’environnement,- le processus PHP dispose des droits d’écriture dans le répertoire
var/, - vous disposez d’une clé
OpenAI API Key active si vous souhaitez utiliser la synchronisation vers OpenAI 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-feed
Si le dépôt est privé :
composer config --global --auth github-oauth.github.com
2. Installation du package
composer require kowal/module-ai-product-feed
3. Activation du module
bin/magento module:enable Kowal_AiProductFeed
4. Mise à jour de Magento
bin/magento setup:upgrade
5. Compilation et cache
En environnement de production, exécutez également :
bin/magento setup:di:compilebin/magento cache:flush
En environnement de développement, il suffit généralement d’exécuter :
bin/magento cache:flush
Si 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_AiProductFeed
Emplacement 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 = un Vector Store ID, - un
Store View = une couche publique distincte de flux IA.
Exemple :
PL store view -> Vector Store ID polonaisEN store view -> Vector Store ID anglais
Configuration des champs
Enable Module
Active le module pour le périmètre sélectionné.
Recommandation :
- définir
Yes sur les Store View qui 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.txt et 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.txt n’est pas un index global de toutes les boutiques- chaque version linguistique de la boutique renvoie son propre manifeste
/llms.txt lui-même ne nécessite pas l’existence de fichiers générés pour répondre correctement
Ajoute un lien visible vers /llms.txt dans le pied de page de la boutique.
Recommandation :
No par défaut,Yes si 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 :
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 :
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 :
Polling Timeout
Temps d’attente maximal pour la fin du traitement du fichier côté OpenAI.
Par défaut :
Polling Interval
Intervalle entre deux vérifications successives du statut.
Par défaut :
HTTP Timeout
Durée maximale d’une requête HTTP unique vers OpenAI.
Par défaut :
Ordre de configuration recommandé
Après l’installation, configurez le module dans cet ordre :
- Activez le module pour le
Store View cible. - Ajoutez
OpenAI API Key si vous prévoyez une synchronisation avec OpenAI. - Définissez le
Vector Store ID pour chaque langue. - Vérifiez
Feed Location. - Définissez
Docs Location si vous utilisez une documentation Markdown. - Activez les types de contenu et canaux nécessaires.
- Activez
Enable Public AI Feed si les endpoints doivent être accessibles publiquement. - Activez éventuellement
Show LLMs.txt Link in Footer. - Videz le cache Magento.
bin/magento cache:flush
Premier 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-run
Exportation réelle
Lancez ensuite la synchronisation réelle :
bin/magento kowal:ai-export:sync --channel=product --store=1
Vérification du statut
bin/magento kowal:ai-export:status --store=1
Vé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.ndjson
Si 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.txt
Comportement attendu :
/llms.txt renvoie un manifeste uniquement pour le Store View courant/llms.txt fonctionne même s’il n’existe pas encore de fichiers de flux générés/ai-feed/{storeCode}/index.json affiche uniquement les flux existants pour la boutique concernée/ai-feed/{storeCode}/{contentType}.ndjson ne 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.json
Vous 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
head vers /llms.txt doit apparaître, - si vous avez activé l’option du pied de page, un lien
LLMs.txt doit 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=1
Statut
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 des sources du blog
bin/magento kowal:ai-blog-source:import --source=amasty_blog --store=1
Ancien 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-run
Cron
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 Feed est 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.txt et les flux NDJSON, - évolutive pour de futures intégrations et modules IA.
WhatsApp
+48608012047
