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 que sea posible pasar desde la implementació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 cada Store View actual. Esto significa que cada versión lingüística puede devolver su propio manifiesto y sus propios enlaces a los feeds.
Requisitos previos
Antes de la instalación, asegúrate de que:
- Magento 2 funciona correctamente,
- tienes acceso SSH al directorio raíz de Magento,
Composer está disponible en el entorno,- el proceso PHP puede escribir en el directorio
var/, - tienes una clave
OpenAI API Key activa si quieres utilizar la sincronización con OpenAI Vector Store.
Instalación del módulo
1. Añadir el repositorio Composer
Añade el repositorio Composer de Kowal:
Recibirás por correo electrónico los datos de acceso al repositorio Composer, es decir, la dirección de correo electrónico del cliente y el token de licencia, después de la compra. También están disponibles en el panel de cliente tras iniciar sesión en kowal.store. Sustituye TWOJ_EMAIL_KLIENTA por la dirección de correo electrónico de tu cuenta y TWOJ_TOKEN por el token recibido. Ejecuta los comandos en el directorio raíz de Magento.
composer config repositories.kowal composer https://repo.kowal.store
Si el repositorio es privado:
composer config http-basic.repo.kowal.store 'TWOJ_EMAIL_KLIENTA' 'TWOJ_TOKEN'
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 un entorno de producción, ejecuta además:
bin/magento setup:di:compilebin/magento cache:flush
En un entorno de desarrollo, normalmente basta con:
bin/magento cache:flush
Si delante de Magento funciona una capa de caché adicional, realiza 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 de feeds AI independiente.
Ejemplo:
PL store view -> Vector Store ID polacoEN store view -> Vector Store ID inglés
Configuración de campos
Enable Module
Activa el módulo para el ámbito seleccionado.
Recomendación:
- establece
Yes en aquellos Store View que deben generar datos AI
OpenAI API Key
Clave API global utilizada para comunicarse con OpenAI.
Es necesaria si:
- quieres sincronizar archivos con
OpenAI Vector Store
No es necesaria si:
- quieres utilizar solo exportaciones locales,
- quieres utilizar 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 donde 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 webserver.
Enable Public AI Feed
Activa los endpoints públicos:
/llms.txt/ai-feed/{storeCode}/index.json/ai-feed/{storeCode}/{contentType}.ndjson
Activa esta opción solo para aquellas vistas de tienda cuyos contenidos puedan estar disponibles públicamente.
Importante:
/llms.txt no es un índice global de todas las tiendas- cada versión lingüística de la tienda devuelve su propio manifiesto
- el propio
/llms.txt no requiere que existan 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 de forma predeterminada,Yes si quieres comunicar de forma explícita la disponibilidad de la capa AI a partners, integradores o bots.
Docs Location
Ruta relativa al directorio con 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:
Reduce 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.
Úsalo si la tienda tiene datos en la tabla kowal_zapytajoprodukt_pytania.
Sync Product Docs
Activa product.docs.
Úsalo 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 las operaciones API.
Por defecto:
Polling Timeout
Tiempo máximo de espera para que finalice el procesamiento del archivo por parte de OpenAI.
Por defecto:
Polling Interval
Intervalo entre comprobaciones de estado consecutivas.
Por defecto:
HTTP Timeout
Tiempo máximo de una solicitud HTTP individual a OpenAI.
Por defecto:
Orden de configuración recomendado
Después de la instalación, configura el módulo en este orden:
- Activa el módulo para el
Store View de destino. - Añade
OpenAI API Key si tienes previsto sincronizar con OpenAI. - Establece
Vector Store ID para cada idioma. - Verifica
Feed Location. - Establece
Docs Location si utilizas documentación Markdown. - Activa los tipos de contenido y canales necesarios.
- Activa
Enable Public AI Feed si los endpoints deben estar disponibles públicamente. - Opcionalmente, activa
Show LLMs.txt Link in Footer. - Limpia la caché de Magento.
bin/magento cache:flush
Primera puesta en marcha
Dry run
Primero realiza 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, ejecuta 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 los endpoints públicos
Si Enable Public AI Feed está activado, comprueba:
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 lingüísticas independientes en la URL, comprueba 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 si aún no hay archivos de feed generados/ai-feed/{storeCode}/index.json muestra solo los feeds existentes para una tienda determinada/ai-feed/{storeCode}/{contentType}.ndjson funciona solo cuando existen los archivos fuente correspondientes
Verificación de las cabeceras de caché:
curl -I https://twoja-domena.pl/llms.txtcurl -I https://twoja-domena.pl/ai-feed/pl/index.json
Deberías ver:
- para
/llms.txt, cabeceras que prácticamente desactivan la caché, - para
index.json, una vida útil de caché corta 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 has activado la opción del pie de página, en el footer debería aparecer 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 de producto antiguo
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úrate de que cron de Magento funciona correctamente en el entorno.
Problemas más frecuentes
/llms.txt devuelve 404
Comprueba:
- si está desplegada la versión actual del módulo con frontend routing,
- si has ejecutado
bin/magento setup:upgrade, - si en production mode has ejecutado
bin/magento setup:di:compile, - si has realizado el deploy static content estándar según el proceso del proyecto,
- si has limpiado la caché,
- si has 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 en algún punto sigue activa una caché compartida antigua.
/llms.txt funciona, pero los feeds están vacíos
Esto normalmente significa que:
- todavía no se ha realizado la exportación,
- no hay contenido activo para el canal dado,
- las flags de sincronización correspondientes están desactivadas.
Este comportamiento es correcto. El manifiesto puede funcionar antes que los feeds reales.
No hay archivos en var/ai-feeds
Comprueba:
- si el módulo está activo en el
Store View correcto, - si los tipos de contenido necesarios están activados,
- si Magento tiene permisos de escritura en
var/, - si se ha iniciado el proceso de sincronización.
Problemas con la sincronización con OpenAI
Comprueba:
- la corrección de
OpenAI API Key, - la corrección de
Vector Store ID, - la disponibilidad de conexiones HTTP salientes,
- los valores de timeouts y retry.
Resumen
Después de una instalación y configuración correctas, el módulo proporciona a Magento 2 una capa de datos lista para AI:
- local,
- multilingüe,
- sincronizable con
OpenAI, - lista para publicarse mediante
llms.txt y feeds NDJSON, - ampliable para futuras integraciones y módulos AI.
