Kowal AI Product Feed - instalación y configuración
Objetivo del documento
Este documento describe el proceso completo de instalación, puesta en marcha y configuración del módulo Kowal_AiProductFeed en Magento 2. Se ha preparado para poder pasar desde la implantación técnica hasta la primera exportación funcional y la publicación de llms.txt.
Alcance funcional del módulo
El módulo permite:
- exportar el contenido de la tienda a archivos
JSON y JSONL, - sincronizar datos con
OpenAI Vector Store, - gestionar múltiples canales de contenido, como producto, blog, categoría y CMS,
- publicar endpoints públicos:
/llms.txt/ai-feed/{storeCode}/index.json/ai-feed/{storeCode}/{contentType}.ndjson
- añadir un enlace a
llms.txt en la sección head, - añadir opcionalmente un enlace a
llms.txt en el pie de página de la tienda.
llms.txt funciona por Store View actual. Esto significa que cada versión idiomática puede devolver su propio manifiesto y sus propios enlaces a los feeds.
Requisitos previos
Antes de la instalación, asegúrese de que:
- Magento 2 funciona correctamente,
- dispone de acceso SSH al directorio raíz de Magento,
Composer está disponible en el entorno,- el proceso PHP tiene permisos de escritura en el directorio
var/, - dispone de una clave
OpenAI API Key activa, si desea usar la sincronización con OpenAI Vector Store.
Instalación del módulo
1. Añadir el repositorio Composer
Si el módulo se instala desde un repositorio Git:
composer config repositories.ai.product.feed vcs https://github.com/kowalco/module-ai-product-feed
Si el repositorio es privado:
composer config --global --auth github-oauth.github.com
2. Instalación del paquete
composer require kowal/module-ai-product-feed
3. Activación del módulo
bin/magento module:enable Kowal_AiProductFeed
4. Actualización de Magento
bin/magento setup:upgrade
5. Compilación y caché
En el entorno de producción, ejecute además:
bin/magento setup:di:compilebin/magento cache:flush
En el entorno de desarrollo, normalmente basta con:
bin/magento cache:flush
Si delante de Magento existe una capa de caché adicional, realice también un purge en:
VarnishCloudflareNginx fastcgi/proxy cache- otro reverse proxy o CDN
6. Confirmación del estado del módulo
bin/magento module:status Kowal_AiProductFeed
Ubicación de la configuración
La configuración del módulo está disponible en el panel:
Stores -> Configuration -> General -> Kowal AI Feed
Modelo de configuración recomendado
La mejor práctica es configurar a nivel de Store View, especialmente si la tienda funciona en varios idiomas.
Recomendación:
- un
Store View = un idioma, - un
Store View = un Vector Store ID, - un
Store View = una capa pública independiente de feeds AI.
Ejemplo:
PL store view -> polaco Vector Store IDEN store view -> inglés Vector Store ID
Configuración de campos
Enable Module
Activa el módulo para el ámbito seleccionado.
Recomendación:
- establezca
Yes en aquellos Store View que deban generar datos AI
OpenAI API Key
Clave API global utilizada para la comunicación con OpenAI.
Obligatoria si:
- desea sincronizar archivos con
OpenAI Vector Store
No es obligatoria si:
- desea usar solo exportaciones locales,
- desea usar solo
llms.txt y feeds públicos.
Vector Store ID
Identificador de OpenAI Vector Store para un Store View concreto.
Recomendación:
- configurarlo a nivel de
Store View, - establecer un identificador independiente para cada idioma.
Feed Location
Ruta relativa al directorio en el que se guardarán los archivos de exportación.
Valor predeterminado:
var/ai-feeds
Recomendación:
- mantener el directorio en
var/, - no exponer este directorio directamente a través del servidor web.
Enable Public AI Feed
Activa los endpoints públicos:
/llms.txt/ai-feed/{storeCode}/index.json/ai-feed/{storeCode}/{contentType}.ndjson
Active esta opción solo para aquellas vistas de tienda cuyo contenido pueda estar disponible públicamente.
Importante:
/llms.txt no es un índice global de todas las tiendas- cada versión idiomática de la tienda devuelve su propio manifiesto
/llms.txt por sí solo no requiere la existencia de archivos generados para responder correctamente
Añade un enlace visible a /llms.txt en el pie de página de la tienda.
Recomendación:
No por defecto,Yes si desea comunicar de forma explícita la disponibilidad de la capa AI a socios, integradores o bots.
Docs Location
Ruta relativa al directorio con la documentación de producto en Markdown para product.docs.
Ejemplos:
var/ai-docsvar/ai-docs/pl
Se admiten, entre otros, los archivos:
{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
Tamaño del lote para la exportación de productos.
Valor inicial:
Reduzca el valor si:
- el catálogo es muy grande,
- el entorno tiene memoria limitada,
- las operaciones AI adicionales aumentan la carga.
Sync Product Core
Activa el tipo de contenido product.core.
Recomendación:
Sync Product FAQ
Activa product.faq.
Úselo si la tienda tiene datos en la tabla kowal_zapytajoprodukt_pytania.
Sync Product Docs
Activa product.docs.
Úselo si la documentación Markdown ya está preparada.
Sync Blog Content
Activa el canal blog y el tipo blog.article.
Sync Category Content
Activa el canal category y el tipo category.content.
Sync CMS Pages
Activa el canal cms_page y el tipo cms.page.
Max Retries
Número máximo de intentos para operaciones API.
Por defecto:
Polling Timeout
Tiempo máximo de espera para la finalización del procesamiento del archivo en el lado de OpenAI.
Por defecto:
Polling Interval
Intervalo entre comprobaciones sucesivas del estado.
Por defecto:
HTTP Timeout
Tiempo máximo de una única request HTTP a OpenAI.
Por defecto:
Orden de configuración recomendado
Después de la instalación, configure el módulo en este orden:
- Active el módulo para el
Store View de destino. - Añada
OpenAI API Key si planea sincronizar con OpenAI. - Configure
Vector Store ID para cada idioma. - Verifique
Feed Location. - Configure
Docs Location si utiliza documentación Markdown. - Active los tipos de contenido y canales necesarios.
- Active
Enable Public AI Feed si los endpoints deben estar disponibles públicamente. - Opcionalmente active
Show LLMs.txt Link in Footer. - Limpie la caché de Magento.
bin/magento cache:flush
Primera puesta en marcha
Dry run
Primero, ejecute una prueba en seco para un único Store View:
bin/magento kowal:ai-export:sync --channel=product --store=1 --dry-run
Exportación real
A continuación, ejecute la sincronización real:
bin/magento kowal:ai-export:sync --channel=product --store=1
Comprobación del estado
bin/magento kowal:ai-export:status --store=1
Verificación de endpoints públicos
Si Enable Public AI Feed está activado, compruebe:
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 tienda tiene versiones idiomáticas separadas en la URL, compruebe también:
curl -i https://twoja-domena.pl/en/llms.txtcurl -i https://twoja-domena.pl/de/llms.txt
Comportamiento esperado:
/llms.txt devuelve el manifiesto solo para el Store View actual/llms.txt funciona incluso cuando todavía no existen archivos feed generados/ai-feed/{storeCode}/index.json muestra solo los feeds existentes para esa tienda/ai-feed/{storeCode}/{contentType}.ndjson solo funciona cuando existen los archivos fuente correspondientes
Verificación de cabeceras de caché:
curl -I https://twoja-domena.pl/llms.txtcurl -I https://twoja-domena.pl/ai-feed/pl/index.json
Debería ver:
- para
/llms.txt, cabeceras que prácticamente desactivan la caché, - para
index.json, un tiempo de vida de caché corto y revalidación forzada.
Verificación HTML:
- en el código fuente de la página debería aparecer un enlace en
head a /llms.txt, - si ha activado la opción del pie, debería aparecer en el footer un enlace
LLMs.txt.
Comandos CLI
Sincronización
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
Estado
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
Importación de fuentes del blog
bin/magento kowal:ai-blog-source:import --source=amasty_blog --store=1
Alias antiguo de producto
Sigue disponible por compatibilidad con versiones anteriores:
bin/magento kowal:ai-feed:generatebin/magento kowal:ai-feed:generate --store=1 --content-type=product.core --sku=example-sku --dry-run
Cron
El módulo utiliza tres tareas cron:
kowal_ai_blog_source_importkowal_ai_feed_generatekowal_ai_feed_cleanup
Asegúrese de que el cron de Magento funciona correctamente en el entorno.
Problemas más frecuentes
/llms.txt devuelve 404
Compruebe:
- si está desplegada la versión actual del módulo con frontend routing,
- si ha ejecutado
bin/magento setup:upgrade, - si en production mode ha ejecutado
bin/magento setup:di:compile, - si ha realizado el despliegue estándar de static content según el proceso del proyecto,
- si ha limpiado la caché,
- si ha realizado el purge de la capa CDN / reverse proxy,
- si
Enable Public AI Feed está activado.
Si https://twoja-domena.pl/llms.txt?v=123 funciona y https://twoja-domena.pl/llms.txt no, normalmente significa que sigue existiendo una caché compartida antigua en algún punto intermedio.
/llms.txt funciona, pero los feeds están vacíos
Normalmente esto significa que:
- todavía no se ha ejecutado la exportación,
- no hay contenido activo para ese canal,
- las flags de sincronización correspondientes están desactivadas.
Este comportamiento es correcto. El propio manifiesto puede funcionar antes que los feeds reales.
No hay archivos en var/ai-feeds
Compruebe:
- si el módulo está activo en el
Store View correcto, - si están activados los tipos de contenido necesarios,
- si Magento tiene permisos de escritura en
var/, - si se ha iniciado el proceso de sincronización.
Problemas con la sincronización con OpenAI
Compruebe:
- la validez de
OpenAI API Key, - la validez de
Vector Store ID, - la disponibilidad de conexiones HTTP salientes,
- los valores de timeout y retry.
Resumen
Tras una instalación y configuración correctas, el módulo proporciona a Magento 2 una capa de datos lista para AI:
- local,
- multilingüe,
- capaz de sincronizarse con
OpenAI, - lista para publicarse mediante
llms.txt y feeds NDJSON, - ampliable para futuras integraciones y módulos AI.
WhatsApp
+48608012047
