Instalación y configuración
Este documento describe cómo poner en marcha el módulo AI Product Support en una tienda Magento 2 y cómo prepararlo para trabajar.
El documento está pensado para una tienda que quiere implementar un módulo listo para usar y empezar a utilizar el chat AI sin profundizar en los detalles técnicos de su funcionamiento a nivel de código.
Lo mejor es considerar este módulo como una capa de uso. Primero la tienda prepara el conocimiento y solo después lo pone a disposición de empleados o clientes en forma de chat.
Qué hay que preparar antes de la instalación
Antes de la implementación necesitas:
- una tienda Magento 2 operativa,
- acceso al servidor,
- composer,
- una cuenta OpenAI,
- una base de conocimiento AI preparada para la tienda,
- conexión del servidor a internet.
La condición práctica más importante es sencilla: el módulo solo responderá bien si la tienda cuenta con contenidos preparados que AI pueda utilizar.
Si la tienda ya utiliza el módulo Kowal AI Product Feed, este puede encargarse precisamente de preparar y ordenar los contenidos para AI. En la página de este módulo se describe como la creación de una base de conocimiento ordenada y actualizada para sistemas AI. AI Product Support es el siguiente paso natural, es decir, utilizar ese conocimiento en la conversación con el usuario. Fuente: Kowal AI Product Feed para OpenAI Vector Store
Instalación del módulo
El módulo se instala mediante composer.
Proceso de instalación de ejemplo:
composer config repositories.ai.product.support vcs https://github.com/kowalco/ai-product-supportcomposer config --global --auth github-oauth.github.com composer require kowal/module-ai-product-supportbin/magento module:enable Kowal_AiProductSupportbin/magento setup:upgradebin/magento cache:clean
Si la tienda funciona en modo producción, después de la instalación ejecuta también:
bin/magento setup:di:compilebin/magento setup:static-content:deploy -fbin/magento cache:clean
Dónde se encuentra la configuración
Después de la instalación encontrarás la configuración del módulo aquí:
Stores > Configuration > Kowal AI > AI Product Support
Cómo configurar el módulo
1. Activa el chat en el panel de administración
En la sección General, activa:
Tras guardar la configuración, aparecerá la pestaña AI en el panel de administración.
2. Decide si activar el chat en el frontend
Si quieres que los clientes de la tienda también puedan utilizar el chat, activa:
Si el módulo debe servir solo al equipo de la tienda, deja el frontend desactivado.
3. Configura la longitud de la pregunta
El campo:
define la longitud máxima del mensaje que puede enviar el usuario. Esto ayuda a mantener el orden y a limitar consultas demasiado largas y poco legibles.
4. Configura la vista de tienda predeterminada
Si la tienda funciona en varias versiones lingüísticas o tiene varias vistas de tienda, puedes indicar:
Esto facilita el trabajo en el panel y ayuda a empezar desde el contexto adecuado.
5. Activa o desactiva el cambio manual de vista de tienda
El campo:
decide si el usuario del panel puede cambiar la vista de tienda directamente en el popup del chat.
Esto resulta útil cuando un equipo gestiona varias versiones de la tienda.
6. Activa el registro técnico durante la implementación
El campo:
conviene activarlo durante la fase de configuración y pruebas. Gracias a ello es más fácil comprobar si el módulo funciona correctamente. Tras la puesta en producción, se puede decidir si el registro debe permanecer activo.
Configuración de la conexión con AI
En la sección OpenAI, configura los elementos básicos necesarios para que el módulo funcione.
OpenAI API Key
Es la clave de acceso al servicio AI. Sin ella, el módulo no descargará la lista de modelos, no leerá la fuente de conocimiento y no enviará la pregunta.
Response Model
Es el modelo responsable de construir la respuesta.
La lista de modelos se carga desde la API. Si después de guardar la clave no aparecen opciones, se puede usar el botón para actualizar la lista de modelos.
Vector Store
Es la fuente de conocimiento seleccionada para el módulo.
La forma más sencilla de entenderlo es esta:
- es el lugar donde se guardan los contenidos que el chat utiliza al responder,
- el módulo busca allí las respuestas,
- si eliges una fuente incorrecta, las respuestas serán pobres o incompletas.
Si la tienda ya tiene una base de conocimiento ordenada y preparada para AI, aquí es donde se indica esa fuente.
La lista de fuentes de conocimiento también puede actualizarse desde la configuración.
Maximum File Search Results
Esta configuración define cuántos materiales de ayuda tiene en cuenta el módulo al preparar una respuesta.
En la práctica, esto influye en:
- la calidad de la respuesta,
- la velocidad de funcionamiento,
- el coste de uso de AI.
Un buen valor inicial es un valor medio, por ejemplo 6.
Seguridad del frontend
Si el chat funciona en la parte de la tienda, conviene configurar desde el principio los límites de seguridad.
En la sección Frontend Security encontrarás:
Requests Per MinuteRequests Per HourMinimum Submit Delay
Estos ajustes ayudan a limitar:
- el envío demasiado frecuente de preguntas,
- abusos por parte de bots,
- consumo innecesario de recursos y costes.
Prompt de sistema adicional
En la sección Prompting se puede completar:
Este campo no es obligatorio. En la mayoría de las implementaciones se puede dejar vacío y utilizar la configuración predeterminada del módulo.
Sobrescribirlo solo tiene sentido si la tienda quiere introducir su propio estilo de respuesta o reglas de comunicación adicionales.
Cómo funciona el módulo desde la perspectiva del usuario
En el panel de administración
Tras activar el módulo, el usuario ve una pestaña AI en el borde derecho de la pantalla. Al hacer clic, se abre el panel de chat.
En el panel se puede:
- escribir una pregunta,
- recibir una respuesta,
- ver tarjetas de producto si la respuesta se refiere a un producto concreto,
- trabajar sin recargar la página.
En el frontend
Si el chat se ha activado, aparece una pestaña similar en la parte de la tienda. El cliente puede hacer una pregunta sin salir de la página de producto o del listing.
Cómo enfocar una implementación de este tipo
El modelo más práctico es el siguiente:
- la tienda ordena los contenidos y prepara la base de conocimiento,
- el administrador indica esa base de conocimiento en la configuración del módulo,
- el usuario utiliza el chat,
- las respuestas se construyen a partir de los contenidos preparados por la tienda.
Este enfoque ofrece mejores resultados que activar solo el chat sin datos preparados.
Configuración inicial recomendada
Panel de administración
Enable Chat = YesEnable Frontend Chat = según el proyectoMaximum Question Length = 1000Allow Store Switcher = Yes con varias vistas de tiendaLog Chat Requests = Yes durante la fase de pruebasMaximum File Search Results = 6
Frontend
Requests Per Minute = valor inicial prudenteRequests Per Hour = valor adaptado al tráfico de la tiendaMinimum Submit Delay = al menos 1
Qué comprobar después de la implementación
Tras guardar la configuración, realiza una prueba sencilla:
- comprueba si la pestaña AI aparece en el panel de administración,
- abre el popup y envía una pregunta,
- asegúrate de que la respuesta aparece correctamente,
- comprueba si la sección de productos aparece en preguntas sobre productos concretos,
- si el frontend está activado, comprueba también el funcionamiento de la pestaña en la tienda.
Problemas más frecuentes
No se ven modelos ni fuentes de conocimiento
Lo más habitual es que signifique:
- falta de una clave OpenAI correcta,
- falta de conexión del servidor a internet,
- cache sin limpiar después de los cambios.
El chat responde con poca precisión o no acierta con el tema
La causa más frecuente no es el módulo en sí, sino la calidad de la base de conocimiento preparada. Si los contenidos están incompletos, desactualizados o son demasiado pobres, las respuestas también serán más débiles.
Por eso, antes de evaluar el propio módulo conviene comprobar:
- si las descripciones de productos son útiles y completas,
- si las FAQ y la documentación están actualizadas,
- si la base de conocimiento contiene realmente los contenidos que necesitan los usuarios,
- si la fuente de conocimiento seleccionada es la adecuada para la tienda en cuestión.
El frontend bloquea al usuario demasiado rápido
En ese caso conviene revisar la configuración de límites y el retraso de envío en la sección Frontend Security.
Breve checklist de implementación
- Instala el módulo mediante
composer. - Activa el módulo y ejecuta
setup:upgrade. - Configura la conexión con OpenAI.
- Selecciona la fuente de conocimiento adecuada.
- Activa el chat en el admin.
- Opcionalmente, activa el chat en el frontend.
- Configura los límites de seguridad.
- Prueba el funcionamiento con preguntas sobre productos reales y contenidos de la tienda.
Breve descripción para la sección «Instalación y configuración»
El módulo se instala mediante composer y se configura en Stores > Configuration > Kowal AI > AI Product Support. El administrador introduce los datos de acceso a OpenAI, selecciona el modelo y la fuente de conocimiento para la tienda y, a continuación, activa el chat en el panel de administración y, opcionalmente, en el frontend. Además, se pueden configurar límites de seguridad y ajustar los parámetros básicos de funcionamiento del módulo.