AI Product Support per Magento 2

Installazione e configurazione

Questo documento descrive come avviare il modulo AI Product Support in uno store Magento 2 e come prepararlo al funzionamento.

Il documento è pensato per uno store che vuole implementare un modulo pronto all'uso e iniziare a utilizzare la chat AI senza approfondire i dettagli tecnici del funzionamento lato codice.

È meglio considerare questo modulo come un livello applicativo. Prima lo store prepara la conoscenza, poi la mette a disposizione di dipendenti o clienti sotto forma di chat.

Cosa preparare prima dell'installazione

Prima dell'implementazione hai bisogno di:

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

La condizione pratica più importante è semplice: il modulo risponderà bene solo se lo store dispone di contenuti preparati che l'AI può utilizzare.

Se lo store 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 costruzione di una base di conoscenza ordinata e aggiornata per sistemi AI. AI Product Support è il naturale passo successivo, 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:

Riceverai i dati di accesso al repository Composer, indirizzo e-mail del cliente e token di licenza, 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 lo store 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 trovi le impostazioni del modulo qui:

Stores > Configuration > Kowal AI > AI Product Support

Come configurare il modulo

1. Abilita la chat nel pannello di amministrazione

Nella sezione General abilita:

• Enable Chat

Dopo aver salvato l'impostazione, nel pannello di amministrazione comparirà la scheda AI.

2. Decidi se abilitare la chat sul frontend

Se vuoi che anche i clienti dello store possano usare la chat, abilita:

• Enable Frontend Chat

Se il modulo deve essere usato solo dal team dello store, 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 store predefinita

Se lo store opera in più versioni linguistiche o ha diverse viste store, puoi indicare:

• Default Store View

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

5. Abilita o disabilita la modifica manuale della vista store

Il campo:

• Allow Store Switcher

decide se l'utente del pannello può cambiare la vista store direttamente nel popup della chat.

È utile quando un unico team gestisce più versioni dello store.

6. Abilita il logging tecnico durante l'implementazione

Il campo:

• Log Chat Requests

vale la pena abilitarlo nella fase di configurazione e test. In questo modo è più facile verificare se il modulo funziona correttamente. Dopo il rilascio in produzione si può decidere se il logging debba rimanere attivo.

Impostazioni della connessione con 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 recupererà l'elenco dei modelli, non leggerà la fonte di conoscenza e non invierà la domanda.

Response Model

È il modello responsabile della generazione della risposta.

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

Vector Store

È la fonte di conoscenza selezionata per il modulo.

Il modo più semplice per capirlo è questo:

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

Se lo store dispone già di una base di conoscenza ordinata preparata per l'AI, è qui che si indica questa fonte.

Anche l'elenco delle fonti di conoscenza può essere aggiornato dal livello della configurazione.

Maximum File Search Results

Questa impostazione definisce quanti materiali di supporto il modulo prende in considerazione per preparare una singola risposta.

In pratica influisce su:

• qualità della risposta,
• velocità di funzionamento,
• costo di utilizzo dell'AI.

Un buon valore iniziale è un valore medio, ad esempio 6.

Sicurezza del frontend

Se la chat funziona lato store, conviene impostare subito i limiti di sicurezza.

Nella sezione Frontend Security trovi:

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

Queste impostazioni aiutano a limitare:

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

Prompt di sistema aggiuntivo

Nella sezione Prompting puoi compilare:

• System Prompt Template

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

La sovrascrittura ha senso solo quando lo store vuole 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. Dopo il clic si apre il pannello della chat.

Nel pannello è possibile:

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

Sul frontend

Se la chat è stata abilitata, una scheda simile compare lato store. Il cliente può porre una domanda senza lasciare la pagina prodotto o il listing.

Come considerare una simile implementazione

Il modello più pratico è il seguente:

1. lo store 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 costruite sulla base dei contenuti preparati dallo store.

Questo approccio offre un risultato migliore rispetto all'avvio della sola chat senza dati preparati.

Configurazione iniziale consigliata

Pannello di amministrazione

• Enable Chat = Yes
• Enable Frontend Chat = a seconda del progetto
• Maximum Question Length = 1000
• Allow Store Switcher = Yes con più viste store
• Log Chat Requests = Yes in fase di test
• Maximum File Search Results = 6

Frontend

• Requests Per Minute = valore iniziale prudente
• Requests Per Hour = valore adattato al traffico dello store
• Minimum Submit Delay = almeno 1

Cosa verificare dopo l'implementazione

Dopo aver salvato la configurazione, esegui un semplice test:

1. verifica che nel pannello di amministrazione sia comparsa la scheda AI,
2. apri il popup e invia una domanda,
3. assicurati che la risposta compaia correttamente,
4. controlla se la sezione prodotti compare per domande su prodotti specifici,
5. se il frontend è abilitato, verifica il funzionamento della scheda anche nello store.

Problemi più comuni

Non si vedono modelli o fonti di conoscenza

Di solito 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ù comune 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 prodotto sono sensate e complete,
• se FAQ e documentazione sono aggiornate,
• se la base di conoscenza contiene realmente i contenuti necessari agli utenti,
• se la fonte di conoscenza selezionata è corretta per lo store specifico.

Il frontend blocca l'utente troppo rapidamente

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

Breve checklist di implementazione

1. Installa il modulo tramite composer.
2. Abilita il modulo ed esegui setup:upgrade.
3. Configura la connessione con OpenAI.
4. Seleziona la fonte di conoscenza corretta.
5. Abilita la chat nell'admin.
6. Opzionalmente abilita la chat sul frontend.
7. Imposta i limiti di sicurezza.
8. Testa il funzionamento con domande su prodotti reali e contenuti dello store.

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, seleziona il modello e la fonte di conoscenza per lo store, quindi abilita la chat nel pannello di amministrazione e opzionalmente sul frontend. Inoltre è possibile impostare limiti di sicurezza e adattare i parametri di base del funzionamento del modulo.