AI Product Support per Magento 2

Installazione e configurazione

Questo documento descrive come avviare il modulo AI Product Support in un negozio Magento 2 e come prepararlo all’uso.

Il documento è pensato per un negozio che desidera implementare un modulo pronto all’uso e iniziare a utilizzare la chat AI senza entrare nei dettagli tecnici del funzionamento lato codice.

È preferibile considerare questo modulo come un livello applicativo. Prima il negozio prepara la conoscenza, poi la rende disponibile ai dipendenti o ai clienti sotto forma di chat.

Cosa preparare prima dell’installazione

Prima dell’implementazione sono necessari:

• un negozio Magento 2 funzionante,
• accesso al server,
• composer,
• un account OpenAI,
• una base di conoscenza AI preparata per il negozio,
• connessione del server a Internet.

La condizione pratica più importante è semplice: il modulo risponderà correttamente solo se il negozio dispone di contenuti preparati da cui l’AI può attingere.

Se il negozio utilizza già il modulo Kowal AI Product Feed, proprio questo può svolgere il ruolo di preparazione e organizzazione dei contenuti per l’AI. Nella pagina di questo modulo è descritto come creazione di una base di conoscenza ordinata e aggiornata per i sistemi AI. AI Product Support è il passaggio successivo naturale, cioè l’utilizzo di questa conoscenza nella conversazione con l’utente. Fonte: Kowal AI Product Feed per OpenAI Vector Store

Installazione del modulo

Il modulo viene installato tramite composer.

Esempio di processo di installazione:

I dati di accesso al repository Composer, ovvero l’indirizzo e-mail del cliente e il token di licenza, saranno inviati via e-mail dopo l’acquisto. Sono disponibili anche nel pannello cliente dopo l’accesso su kowal.store. Sostituisci TWOJ_EMAIL_KLIENTA con l’indirizzo e-mail del tuo account e TWOJ_TOKEN con il token ricevuto. Esegui i comandi nella directory principale di Magento.

composer config repositories.kowal composer https://repo.kowal.store

composer config http-basic.repo.kowal.store 'TWOJ_EMAIL_KLIENTA' 'TWOJ_TOKEN'composer require kowal/module-ai-product-supportbin/magento module:enable Kowal_AiProductSupportbin/magento setup:upgradebin/magento cache:clean

Se il negozio funziona in modalità produzione, dopo l’installazione esegui anche:

bin/magento setup:di:compilebin/magento setup:static-content:deploy -fbin/magento cache:clean

Dove si trova la configurazione

Dopo l’installazione, le impostazioni del modulo sono disponibili qui:

Stores > Configuration > Kowal AI > AI Product Support

Come configurare il modulo

1. Attiva la chat nel pannello di amministrazione

Nella sezione General attiva:

• Enable Chat

Dopo aver salvato l’impostazione, nel pannello di amministrazione apparirà la scheda AI.

2. Decidi se attivare la chat sul frontend

Se desideri che anche i clienti del negozio possano utilizzare la chat, attiva:

• Enable Frontend Chat

Se il modulo deve essere utilizzato solo dal team del negozio, lascia il frontend disattivato.

3. Imposta la lunghezza della domanda

Il campo:

• Maximum Question Length

definisce la lunghezza massima del messaggio che l’utente può inviare. Questo aiuta a mantenere ordine e a limitare richieste troppo lunghe e poco leggibili.

4. Imposta la vista negozio predefinita

Se il negozio opera in più versioni linguistiche o ha diverse viste negozio, puoi indicare:

• Default Store View

Questo facilita il lavoro nel pannello e aiuta a iniziare dal contesto corretto.

5. Attiva o disattiva il cambio manuale della vista negozio

Il campo:

• Allow Store Switcher

stabilisce se l’utente del pannello può cambiare la vista negozio direttamente nel popup della chat.

È utile quando un unico team gestisce più versioni del negozio.

6. Attiva il logging tecnico durante l’implementazione

Il campo:

• Log Chat Requests

conviene attivarlo nella fase di configurazione e test. In questo modo è più facile verificare se il modulo funziona correttamente. Dopo la messa in produzione si può decidere se il logging deve rimanere attivo.

Impostazioni di connessione con l’AI

Nella sezione OpenAI configura gli elementi di base necessari al funzionamento del modulo.

OpenAI API Key

È la chiave di accesso al servizio AI. Senza di essa il modulo non scaricherà l’elenco dei modelli, non leggerà la fonte di conoscenza e non invierà la domanda.

Response Model

È il modello responsabile della generazione delle risposte.

L’elenco dei modelli viene caricato dall’API. Se dopo il salvataggio della chiave non compaiono opzioni, è possibile usare il pulsante di aggiornamento dell’elenco dei modelli.

Vector Store

È la fonte di conoscenza selezionata per il modulo.

Il modo più semplice per comprenderlo è questo:

• è il luogo in cui sono salvati i contenuti che la chat utilizza per rispondere,
• il modulo cerca le risposte proprio lì,
• se scegli una fonte errata, le risposte saranno deboli o incomplete.

Se il negozio dispone già di una base di conoscenza ordinata e preparata per l’AI, qui si indica proprio quella fonte.

L’elenco delle fonti di conoscenza può essere aggiornato anche dal livello della configurazione.

Maximum File Search Results

Questa impostazione definisce quanti materiali di supporto il modulo prende in considerazione durante la preparazione di una singola risposta.

In pratica influisce su:

• qualità delle risposte,
• velocità di funzionamento,
• costo di utilizzo dell’AI.

Una buona impostazione iniziale è un valore medio, ad esempio 6.

Sicurezza del frontend

Se la chat funziona lato negozio, è opportuno impostare subito i limiti di sicurezza.

Nella sezione Frontend Security troverai:

• Requests Per Minute
• Requests Per Hour
• Minimum Submit Delay

Queste impostazioni aiutano a limitare:

• l’invio troppo frequente di domande,
• abusi da parte dei bot,
• consumo inutile di risorse e costi.

Prompt di sistema aggiuntivo

Nella sezione Prompting è possibile completare:

• System Prompt Template

Questo campo non è obbligatorio. Nella maggior parte delle implementazioni può essere lasciato vuoto e si può utilizzare l’impostazione predefinita del modulo.

La sovrascrittura ha senso solo se il negozio desidera introdurre un proprio stile di risposta o regole di comunicazione aggiuntive.

Come funziona il modulo dal punto di vista dell’utente

Nel pannello di amministrazione

Dopo l’avvio del modulo, l’utente vede la scheda AI sul bordo destro dello schermo. Facendo clic, si apre il pannello della chat.

Nel pannello è possibile:

• inserire una domanda,
• ricevere una risposta,
• visualizzare le schede prodotto, se la risposta riguarda un prodotto specifico,
• lavorare senza ricaricare la pagina.

Sul frontend

Se la chat è stata attivata, una scheda simile appare lato negozio. Il cliente può fare una domanda senza uscire dalla pagina prodotto o dal listing.

Come considerare questo tipo di implementazione

Il modello più pratico è il seguente:

1. il negozio organizza i contenuti e prepara la base di conoscenza,
2. l’amministratore indica questa base di conoscenza nella configurazione del modulo,
3. l’utente utilizza la chat,
4. le risposte vengono generate sulla base dei contenuti preparati dal negozio.

Questo approccio offre risultati migliori rispetto all’attivazione della sola chat senza dati preparati.

Configurazione iniziale consigliata

Pannello di amministrazione

• Enable Chat = Yes
• Enable Frontend Chat = in base al progetto
• Maximum Question Length = 1000
• Allow Store Switcher = Yes con più viste negozio
• Log Chat Requests = Yes durante la fase di test
• Maximum File Search Results = 6

Frontend

• Requests Per Minute = valore iniziale prudente
• Requests Per Hour = valore adeguato al traffico del negozio
• Minimum Submit Delay = almeno 1

Cosa verificare dopo l’implementazione

Dopo aver salvato la configurazione, esegui un semplice test:

1. verifica se nel pannello di amministrazione è apparsa la scheda AI,
2. apri il popup e invia una domanda,
3. assicurati che la risposta venga visualizzata correttamente,
4. controlla se la sezione prodotti appare per le domande relative a prodotti specifici,
5. se il frontend è attivo, verifica il funzionamento della scheda anche nel negozio.

Problemi più frequenti

I modelli o le fonti di conoscenza non sono visibili

Il più delle volte significa:

• mancanza di una chiave OpenAI corretta,
• mancanza di connessione del server a Internet,
• cache non svuotata dopo le modifiche.

La chat risponde in modo troppo debole o non centra l’argomento

La causa più frequente non è il modulo in sé, ma la qualità della base di conoscenza preparata. Se i contenuti sono incompleti, non aggiornati o troppo poveri, anche le risposte saranno più deboli.

Prima di valutare il modulo stesso, vale quindi la pena verificare:

• se le descrizioni dei prodotti sono sensate e complete,
• se FAQ e documentazione sono aggiornate,
• se la base di conoscenza contiene davvero i contenuti necessari agli utenti,
• se la fonte di conoscenza selezionata è corretta per quel negozio.

Il frontend blocca l’utente troppo rapidamente

In questo caso conviene verificare le impostazioni dei limiti e del ritardo di invio nella sezione Frontend Security.

Breve checklist di implementazione

1. Installa il modulo tramite composer.
2. Attiva il modulo ed esegui setup:upgrade.
3. Configura la connessione con OpenAI.
4. Scegli la fonte di conoscenza corretta.
5. Attiva la chat nell’admin.
6. Facoltativamente, attiva la chat sul frontend.
7. Imposta i limiti di sicurezza.
8. Testa il funzionamento con domande su prodotti reali e contenuti del negozio.

Breve descrizione per la sezione Installazione e configurazione

Il modulo si installa tramite composer e si configura in Stores > Configuration > Kowal AI > AI Product Support. L’amministratore inserisce i dati di accesso a OpenAI, sceglie il modello e la fonte di conoscenza per il negozio, quindi attiva la chat nel pannello di amministrazione e, facoltativamente, sul frontend. Inoltre, è possibile impostare limiti di sicurezza e adattare i parametri di base del funzionamento del modulo.