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óduloKowal_AiProductFeeden 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 dellms.txt.
Alcance funcional del módulo
El módulo permite:
- exportar el contenido de la tienda a archivos
JSONyJSONL,
- 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.txten la secciónhead,
- añadir opcionalmente un enlace a
llms.txten el pie de página de la tienda.
llms.txtfunciona por cadaStore Viewactual. 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,
Composerestá disponible en el entorno,- el proceso PHP puede escribir en el directorio
var/,
- tienes una clave
OpenAI API Keyactiva si quieres utilizar la sincronización conOpenAI Vector Store.
Instalación del módulo
1. Añadir el repositorio Composer
Añade el repositorio Composer de Kowal:
Recibirás por e-mail los datos de acceso al repositorio Composer, dirección de e-mail del cliente y token de licencia, tras 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:compile
bin/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 deStore View, especialmente si la tienda funciona en varios idiomas.
Recomendación:
- un
Store View= un idioma,
- un
Store View= unVector Store ID,
- un
Store View= una capa pública de feeds AI independiente.
Ejemplo:
PLvista de tienda -> polacoVector Store IDENvista de tienda -> inglésVector Store ID
Configuración de campos
Enable Module
Activa el módulo para el ámbito seleccionado.
Recomendación:
- establece
Yesen aquellosStore Viewque deben generar datos AI
OpenAI API Key
Clave API global utilizada para comunicarse conOpenAI.
Es necesaria si:
- quieres sincronizar archivos con
OpenAI Vector Store
No es necesaria si:
- quieres utilizar solo exportaciones locales,
- quieres utilizar solo
llms.txty feeds públicos.
Vector Store ID
Identificador deOpenAI Vector Storepara unStore View.
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.txtno es un índice global de todas las tiendas- cada versión lingüística de la tienda devuelve su propio manifiesto
- el propio
/llms.txtno requiere que existan archivos generados para responder correctamente
Añade un enlace visible a/llms.txten el pie de página de la tienda.
Recomendación:
Node forma predeterminada,Yessi 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 paraproduct.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 contenidoproduct.core.
Recomendación:
Sync Product FAQ
Activaproduct.faq.
Úsalo si la tienda tiene datos en la tablakowal_zapytajoprodukt_pytania.
Sync Product Docs
Activaproduct.docs.
Úsalo si la documentación Markdown ya está preparada.
Sync Blog Content
Activa el canalblogy el tipoblog.article.
Sync Category Content
Activa el canalcategoryy el tipocategory.content.
Sync CMS Pages
Activa el canalcms_pagey el tipocms.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 deOpenAI.
Por defecto:
Polling Interval
Intervalo entre comprobaciones de estado consecutivas.
Por defecto:
HTTP Timeout
Tiempo máximo de una solicitud HTTP individual aOpenAI.
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.
- Añade
OpenAI API Keysi tienes previsto sincronizar conOpenAI.
- Configura
Vector Store IDpara cada idioma.
- Verifica
Feed Location.
- Configura
Docs Locationsi utilizas documentación Markdown.
- Activa los tipos de contenido y canales necesarios.
- Activa
Enable Public AI Feedsi 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 únicoStore 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
SiEnable Public AI Feed está activado, comprueba:
curl -i https://twoja-domena.pl/llms.txt
curl -i https://twoja-domena.pl/ai-feed/pl/index.json
curl -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.txt
curl -i https://twoja-domena.pl/de/llms.txt
Comportamiento esperado:
/llms.txtdevuelve el manifiesto solo para la vista actualStore View/llms.txtfunciona incluso cuando aún no se han generado archivos del feed/ai-feed/{storeCode}/index.jsonmuestra solo los feeds existentes para esa tienda/ai-feed/{storeCode}/{contentType}.ndjsonsolo funciona cuando existen los archivos fuente correspondientes
Verificación de las cabeceras de caché:
curl -I https://twoja-domena.pl/llms.txt
curl -I https://twoja-domena.pl/ai-feed/pl/index.json
Deberías ver:
- para
/llms.txtcabeceras 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
heada/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=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
Estado
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
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:generate
bin/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.txtdevuelve404
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 Feedestá activado.
Sihttps://twoja-domena.pl/llms.txt?v=123funciona yhttps://twoja-domena.pl/llms.txtno, normalmente significa que en algún punto sigue activa una caché compartida antigua.
/llms.txtfunciona, 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 envar/ai-feeds
Comprueba:
- si el módulo está activo en el
Store View,
- 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.txty feedsNDJSON,
- ampliable para futuras integraciones y módulos AI.
