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 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:

• Enable Chat

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:

• Enable Frontend Chat

Se il modulo deve servire solo al 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 funziona in più versioni linguistiche o ha diverse viste negozio, puoi indicare:

• Default Store View

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:

• Allow Store Switcher

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:

• Log Chat Requests

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 Minute
• Requests Per Hour
• Minimum 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:

• 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 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:

1. il negozio organizza i contenuti e prepara la knowledge base,
2. l’amministratore indica questa knowledge base 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 un risultato migliore rispetto all’avvio 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 in fase di test
• Maximum File Search Results = 6

Frontend

• Requests Per Minute = valore iniziale prudente
• Requests Per Hour = valore adattato 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 è comparsa la scheda AI,
2. apri il popup e invia una domanda,
3. assicurati che la risposta venga visualizzata correttamente,
4. verifica se la sezione prodotti compare per domande su prodotti specifici,
5. 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

1. Installa il modulo tramite composer.
2. Attiva il modulo ed esegui setup:upgrade.
3. Configura la connessione con OpenAI.
4. Seleziona la fonte di conoscenza corretta.
5. Attiva la chat nell’admin.
6. Opzionalmente 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, 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.