Kowal AI Product Feed - installation et configuration
Objectif du document
Ce document décrit le processus complet d’installation, de lancement et de configuration du module Kowal_AiProductFeed dans Magento 2. Il a été préparé afin de permettre de passer du déploiement technique au premier export fonctionnel ainsi qu’à la publication de llms.txt.
Périmètre fonctionnel du module
Le module permet :
- l’export des contenus 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 produit, blog, catégorie et 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 pour le Store View actuel. Cela signifie que chaque version linguistique peut renvoyer son propre manifeste et ses propres liens vers les feeds.
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 peut écrire 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
Ajoutez le dépôt Composer Kowal :
Les données d’accès au dépôt Composer, adresse e-mail du client et token de licence, vous seront envoyées par e-mail après l’achat. Elles sont également disponibles dans l’espace client après connexion sur kowal.store. Remplacez TWOJ_EMAIL_KLIENTA par l’adresse e-mail de votre compte et TWOJ_TOKEN par le token reçu. Exécutez les commandes dans le répertoire racine de Magento.
composer config repositories.kowal composer https://repo.kowal.store
Si le dépôt est privé :
composer config http-basic.repo.kowal.store 'TWOJ_EMAIL_KLIENTA' 'TWOJ_TOKEN'
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:compile
bin/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 se trouve devant Magento, effectuez aussi un purge côté :
VarnishCloudflareNginx fastcgi/proxy cache- 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 bonne pratique consiste à configurer au niveau 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 feeds 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éfinissez
Yes pour 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 les exports locaux,
- vous souhaitez utiliser uniquement
llms.txt et les feeds publics.
Vector Store ID
Identifiant OpenAI Vector Store pour un Store View donné.
Recommandation :
- configurer au niveau
Store View, - définir un identifiant distinct pour chaque langue.
Feed Location
Chemin relatif vers le répertoire dans lequel les fichiers d’export 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 les contenus peuvent être accessibles 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 seul 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’export des produits.
Valeur de départ :
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 possède des données dans la table kowal_zapytajoprodukt_pytania.
Sync Product Docs
Active product.docs.
À utiliser si la documentation Markdown est déjà préparée.
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 d’opération API.
Par défaut :
Polling Timeout
Temps maximal d’attente de la fin du traitement du fichier côté OpenAI.
Par défaut :
Polling Interval
Intervalle entre les 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
Vector Store ID pour chaque langue. - Vérifiez
Feed Location. - Définissez
Docs Location si vous utilisez la documentation Markdown. - Activez les types de contenus et les canaux nécessaires.
- Activez
Enable Public AI Feed si les endpoints doivent être accessibles publiquement. - Activez optionnellement
Show LLMs.txt Link in Footer. - Videz le cache Magento.
bin/magento cache:flush
Premier lancement
Dry run
Effectuez d’abord un test à blanc pour un Store View :
bin/magento kowal:ai-export:sync --channel=product --store=1 --dry-run
Export réel
Lancez ensuite la synchronisation effective :
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 lorsqu’aucun fichier de feed n’a encore été généré/ai-feed/{storeCode}/index.json affiche uniquement les feeds existants pour la boutique concernée/ai-feed/{storeCode}/{contentType}.ndjson fonctionne seulement lorsque les fichiers sources 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 courte durée de vie du cache et une revalidation forcée.
Vérification HTML :
- dans le code source de la page, un lien vers
/llms.txt doit apparaître dans le head, - si vous avez activé l’option de pied de page, un lien
LLMs.txt doit apparaître dans le footer.
Commandes CLI
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
Statut
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
Import des sources de blog
bin/magento kowal:ai-blog-source:import --source=amasty_blog --store=1
Ancien alias produit
Toujours disponible pour la rétrocompatibilité :
bin/magento kowal:ai-feed:generate
bin/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 fréquents
/llms.txt renvoie 404
Vérifiez :
- si la version actuelle du module avec routage frontend est déployée,
- si vous avez exécuté
bin/magento setup:upgrade, - si en production mode vous avez exécuté
bin/magento setup:di:compile, - si vous avez effectué le deploy static content standard conformément au processus du projet,
- si vous avez vidé le cache,
- si vous avez effectué le purge de la couche CDN / reverse proxy,
- si
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 en chemin.
/llms.txt fonctionne, mais les feeds sont vides
Cela signifie généralement que :
- aucun export n’a encore été effectué,
- il n’y a pas de contenus actifs pour le canal donné,
- les flags de synchronisation correspondants sont désactivés.
Ce comportement est correct. Le manifeste seul peut fonctionner avant les feeds effectifs.
Absence de fichiers dans var/ai-feeds
Vérifiez :
- si le module est actif sur le bon
Store View, - si les types de contenus requis sont activés,
- si Magento dispose des droits d’écriture dans
var/, - si le processus de synchronisation a été lancé.
Problèmes de synchronisation vers 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 retry.
Résumé
Après une installation et une configuration correctes, le module fournit à Magento 2 une couche de données prête pour l’IA :
- locale,
- multilingue,
- synchronisable avec
OpenAI, - prête à être publiée via
llms.txt et les feeds NDJSON, - évolutive pour de futures intégrations et modules IA.
