Installazione e configurazione
Questo documento descrive come avviare il modulo AI Product Support in un negozio Magento 2 e come prepararlo al lavoro.
Il documento è pensato per un negozio che desidera implementare un modulo pronto all’uso e iniziare a utilizzare la chat AI senza approfondire i 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 hai bisogno di:
- un negozio Magento 2 funzionante,
- accesso al server,
- Composer,
- account OpenAI,
- knowledge base AI preparata per il negozio,
- connessione del server a Internet.
La condizione pratica più importante è semplice: il modulo risponderà bene 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 modulo che può svolgere il ruolo di preparazione e organizzazione dei contenuti per l’AI. Nella pagina di questo modulo ciò viene descritto come la creazione di una knowledge base ordinata e aggiornata per i sistemi AI. AI Product Support è il passo 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:
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
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 trovi le impostazioni del modulo qui:
Stores > Configuration > Kowal AI > AI Product Support
Come configurare il modulo
1. Attiva la chat nel pannello di amministrazione
Nella sezione General attiva:
Dopo aver salvato l’impostazione, nel pannello di amministrazione comparirà la scheda AI.
2. Decidi se attivare la chat sul frontend
Se vuoi che anche i clienti del negozio possano utilizzare la chat, attiva:
Se il modulo deve servire solo al team del negozio, lascia il frontend disattivato.
3. Imposta la lunghezza della domanda
Il campo:
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 funziona in più versioni linguistiche o ha diverse viste negozio, puoi indicare:
Questo facilita il lavoro nel pannello e aiuta a partire dal contesto corretto.
5. Attiva o disattiva il cambio manuale della vista negozio
Il campo:
decide se l’utente del pannello può cambiare la vista negozio direttamente nel popup della chat.
È utile quando un solo team gestisce più versioni del negozio.
6. Attiva il logging tecnico durante l’implementazione
Il campo:
conviene attivarlo durante la configurazione e i test. In questo modo è più facile verificare se il modulo funziona correttamente. Dopo l’implementazione in produzione puoi decidere se il logging deve rimanere attivo.
Impostazioni della connessione con l’AI
Nella sezione OpenAI configura gli elementi di base necessari per il 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 della risposta.
L’elenco dei modelli viene caricato dall’API. Se dopo il salvataggio della chiave non compaiono opzioni, puoi utilizzare 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 sbagliata, le risposte saranno deboli o incomplete.
Se il negozio dispone già di una knowledge base organizzata e preparata per l’AI, è qui che si indica proprio 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 durante la preparazione di una singola risposta.
In pratica influisce su:
- qualità della risposta,
- 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, conviene impostare subito i limiti di sicurezza.
Nella sezione Frontend Security trovi:
Requests Per MinuteRequests Per HourMinimum Submit Delay
Queste impostazioni aiutano a limitare:
- l’invio troppo frequente di domande,
- abusi da parte dei bot,
- consumo non necessario di risorse e costi.
Prompt di sistema aggiuntivo
Nella sezione Prompting puoi compilare:
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 quando il negozio 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,
- visualizzare schede prodotto, se la risposta riguarda un prodotto specifico,
- lavorare senza ricaricare la pagina.
Sul frontend
Se la chat è stata attivata, una scheda simile compare lato negozio. Il cliente può porre una domanda senza lasciare la pagina prodotto o il listing.
Come considerare un’implementazione di questo tipo
Il modello più pratico è il seguente:
- il negozio organizza i contenuti e prepara la knowledge base,
- l’amministratore indica questa knowledge base nella configurazione del modulo,
- l’utente utilizza la chat,
- le risposte vengono generate sulla base dei contenuti preparati dal negozio.
Questo approccio offre un risultato migliore rispetto all’avvio della sola chat senza dati preparati.
Configurazione iniziale consigliata
Pannello di amministrazione
Enable Chat = YesEnable Frontend Chat = in base al progettoMaximum Question Length = 1000Allow Store Switcher = Yes con più viste negozioLog Chat Requests = Yes in fase di testMaximum File Search Results = 6
Frontend
Requests Per Minute = valore iniziale prudenteRequests Per Hour = valore adattato al traffico del negozioMinimum Submit Delay = almeno 1
Cosa verificare dopo l’implementazione
Dopo aver salvato la configurazione, esegui un semplice test:
- verifica se nel pannello di amministrazione è comparsa la scheda AI,
- apri il popup e invia una domanda,
- assicurati che la risposta venga visualizzata correttamente,
- verifica se la sezione prodotti compare per domande su prodotti specifici,
- se il frontend è attivo, verifica il funzionamento della scheda anche nel negozio.
Problemi più comuni
Non si vedono i modelli o le fonti di conoscenza
Di solito significa:
- chiave OpenAI non corretta,
- mancanza di connessione del server a Internet,
- cache non pulita dopo le modifiche.
La chat risponde in modo troppo debole o non centra l’argomento
La causa più comune non è il modulo stesso, ma la qualità della knowledge base preparata. Se i contenuti sono incompleti, non aggiornati o troppo poveri, anche le risposte saranno più deboli.
Prima di valutare il modulo stesso, conviene quindi verificare:
- se le descrizioni dei prodotti sono sensate e complete,
- se FAQ e documentazione sono aggiornate,
- se la knowledge base contiene effettivamente i contenuti necessari agli utenti,
- se la fonte di conoscenza selezionata è corretta per il negozio specifico.
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
- Installa il modulo tramite
composer. - Attiva il modulo ed esegui
setup:upgrade. - Configura la connessione con OpenAI.
- Seleziona la fonte di conoscenza corretta.
- Attiva la chat nell’admin.
- Opzionalmente attiva la chat sul frontend.
- Imposta i limiti di sicurezza.
- 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, seleziona il modello e la fonte di conoscenza per il negozio, quindi attiva 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.