Installatie en configuratie
Dit document beschrijft hoe je de module AI Product Support in een Magento 2-winkel activeert en klaarmaakt voor gebruik.
Het document is geschreven voor een winkel die een kant-en-klare module wil implementeren en AI-chat wil gaan gebruiken zonder zich te verdiepen in de technische details van de werking aan de codezijde.
Deze module kun je het best beschouwen als een gebruikerslaag. Eerst bereidt de winkel de kennis voor en pas daarna stelt hij deze beschikbaar aan medewerkers of klanten in de vorm van een chat.
Wat moet je voorbereiden vóór de installatie
Voor de implementatie heb je nodig:
- een werkende Magento 2-winkel,
- toegang tot de server,
- Composer,
- een OpenAI-account,
- een voorbereide AI-kennisbank voor de winkel,
- internetverbinding voor de server.
De belangrijkste praktische voorwaarde is eenvoudig: de module geeft alleen goede antwoorden wanneer de winkel content heeft voorbereid waarvan AI gebruik kan maken.
Als de winkel al de module Kowal AI Product Feed gebruikt, kan juist die module de rol vervullen van het voorbereiden en ordenen van content voor AI. Op de pagina van die module wordt dit beschreven als het bouwen van een geordende en actuele kennisbank voor AI-systemen. AI Product Support is de logische volgende stap, namelijk het gebruiken van die kennis in een gesprek met de gebruiker. Bron: Kowal AI Product Feed voor OpenAI Vector Store
Installatie van de module
De module wordt geïnstalleerd via composer.
Voorbeeld van het installatieproces:
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
Als de winkel in productiemodus draait, voer dan na de installatie ook het volgende uit:
bin/magento setup:di:compilebin/magento setup:static-content:deploy -fbin/magento cache:clean
Waar bevindt de configuratie zich
Na de installatie vind je de instellingen van de module hier:
Stores > Configuration > Kowal AI > AI Product Support
Hoe configureer je de module
1. Schakel de chat in het beheerpaneel in
Schakel in de sectie General het volgende in:
Na het opslaan van de instelling verschijnt de AI-tab in het beheerpaneel.
2. Bepaal of je de chat op de frontend wilt inschakelen
Als je wilt dat ook klanten van de winkel de chat kunnen gebruiken, schakel dan het volgende in:
Als de module alleen voor het winkelteam bedoeld is, laat de frontend dan uitgeschakeld.
3. Stel de vraaglengte in
Het veld:
bepaalt de maximale lengte van het bericht dat een gebruiker kan verzenden. Dit helpt orde te houden en te lange, onduidelijke vragen te beperken.
4. Stel de standaard winkelweergave in
Als de winkel in meerdere taalversies werkt of meerdere winkelweergaven heeft, kun je het volgende aangeven:
Dit maakt het werken in het paneel eenvoudiger en helpt vanuit de juiste context te starten.
5. Schakel handmatige wijziging van de winkelweergave in of uit
Het veld:
bepaalt of de gebruiker van het paneel de winkelweergave rechtstreeks in de chatpop-up kan wijzigen.
Dit is handig wanneer één team meerdere versies van de winkel beheert.
6. Schakel technische logging in tijdens de implementatie
Het veld:
is de moeite waard om in te schakelen tijdens de configuratie- en testfase. Daardoor kun je gemakkelijker controleren of de module correct werkt. Na de productie-implementatie kun je beslissen of logging actief moet blijven.
Instellingen voor de verbinding met AI
Configureer in de sectie OpenAI de basiselementen die nodig zijn voor de werking van de module.
OpenAI API Key
Dit is de toegangssleutel tot de AI-service. Zonder deze sleutel haalt de module geen lijst met modellen op, leest hij de kennisbron niet uit en verzendt hij geen vraag.
Response Model
Dit is het model dat verantwoordelijk is voor het opbouwen van antwoorden.
De lijst met modellen wordt via de API geladen. Als er na het opslaan van de sleutel geen opties verschijnen, kun je de knop gebruiken om de modellenlijst te vernieuwen.
Vector Store
Dit is de gekozen kennisbron voor de module.
Het eenvoudigst is dit zo te begrijpen:
- dit is de plek waar de content is opgeslagen die de chat gebruikt bij het beantwoorden,
- de module zoekt de antwoorden juist daar,
- als je de verkeerde bron kiest, zullen de antwoorden zwak of onvolledig zijn.
Als de winkel al een geordende kennisbank heeft die voor AI is voorbereid, wijs je hier precies die bron aan.
De lijst met kennisbronnen kan ook vanuit de configuratie worden vernieuwd.
Maximum File Search Results
Deze instelling bepaalt hoeveel ondersteunende materialen de module meeneemt bij het voorbereiden van één antwoord.
In de praktijk heeft dit invloed op:
- de kwaliteit van antwoorden,
- de snelheid van werking,
- de kosten van het gebruik van AI.
Een goede startinstelling is een gemiddelde waarde, bijvoorbeeld 6.
Frontendbeveiliging
Als de chat aan de winkelzijde werkt, is het verstandig om meteen beveiligingslimieten in te stellen.
In de sectie Frontend Security vind je:
Requests Per MinuteRequests Per HourMinimum Submit Delay
Deze instellingen helpen het volgende te beperken:
- te vaak verzenden van vragen,
- misbruik door bots,
- onnodig gebruik van resources en kosten.
Aanvullende systeemprompt
In de sectie Prompting kun je het volgende aanvullen:
Dit veld is niet verplicht. Bij de meeste implementaties kun je het leeg laten en de standaardinstelling van de module gebruiken.
Overschrijven heeft alleen zin wanneer de winkel een eigen antwoordstijl of aanvullende communicatieregels wil invoeren.
Hoe de module werkt vanuit het perspectief van de gebruiker
In het beheerpaneel
Na het inschakelen van de module ziet de gebruiker een AI-tab aan de rechterrand van het scherm. Na een klik opent het chatpaneel.
In het paneel kun je:
- een vraag invoeren,
- een antwoord ontvangen,
- productkaarten zien als het antwoord een specifiek product betreft,
- werken zonder de pagina opnieuw te laden.
Op de frontend
Als de chat is ingeschakeld, verschijnt een vergelijkbare tab aan de winkelzijde. De klant kan een vraag stellen zonder de productpagina of listing te verlaten.
Hoe je over zo'n implementatie kunt denken
Het meest praktische model ziet er als volgt uit:
- de winkel ordent de content en bereidt de kennisbank voor,
- de beheerder wijst deze kennisbank aan in de moduleconfiguratie,
- de gebruiker gebruikt de chat,
- antwoorden worden opgebouwd op basis van content die door de winkel is voorbereid.
Deze aanpak geeft een beter resultaat dan alleen een chat starten zonder voorbereide gegevens.
Aanbevolen startconfiguratie
Beheerpaneel
Enable Chat = YesEnable Frontend Chat = afhankelijk van het projectMaximum Question Length = 1000Allow Store Switcher = Yes bij meerdere winkelweergavenLog Chat Requests = Yes tijdens de testfaseMaximum File Search Results = 6
Frontend
Requests Per Minute = voorzichtige startwaardeRequests Per Hour = waarde afgestemd op het winkelverkeerMinimum Submit Delay = ten minste 1
Wat controleren na de implementatie
Voer na het opslaan van de configuratie een eenvoudige test uit:
- controleer of de AI-tab in het beheerpaneel is verschenen,
- open de pop-up en verzend een vraag,
- controleer of het antwoord correct verschijnt,
- controleer of de productsectie verschijnt bij vragen over specifieke producten,
- als de frontend is ingeschakeld, controleer dan ook de werking van de tab in de winkel.
Meest voorkomende problemen
Modellen of kennisbronnen zijn niet zichtbaar
Meestal betekent dit:
- geen correcte OpenAI-sleutel,
- geen internetverbinding vanaf de server,
- cache niet geleegd na wijzigingen.
De chat geeft te zwakke antwoorden of mist het onderwerp
De meest voorkomende oorzaak is niet de module zelf, maar de kwaliteit van de voorbereide kennisbank. Als de content onvolledig, verouderd of te beperkt is, zullen de antwoorden ook zwakker zijn.
Voordat je de module zelf beoordeelt, is het daarom verstandig te controleren:
- of productbeschrijvingen logisch en compleet zijn,
- of FAQ en documentatie actueel zijn,
- of de kennisbank werkelijk de content bevat die gebruikers nodig hebben,
- of de gekozen kennisbron geschikt is voor de betreffende winkel.
De frontend blokkeert de gebruiker te snel
Controleer dan de instellingen voor limieten en verzendvertraging in de sectie Frontend Security.
Korte implementatiechecklist
- Installeer de module via
composer. - Schakel de module in en voer
setup:upgrade uit. - Configureer de verbinding met OpenAI.
- Kies de juiste kennisbron.
- Schakel de chat in de admin in.
- Schakel de chat op de frontend optioneel in.
- Stel beveiligingslimieten in.
- Test de werking met vragen over echte producten en winkelcontent.
Korte beschrijving voor de sectie Installatie en configuratie
De module wordt geïnstalleerd via composer en geconfigureerd in Stores > Configuration > Kowal AI > AI Product Support. De beheerder voert de toegangsgegevens voor OpenAI in, kiest het model en de kennisbron voor de winkel en schakelt vervolgens de chat in het beheerpaneel en optioneel op de frontend in. Daarnaast kunnen beveiligingslimieten worden ingesteld en kunnen de basisparameters van de werking van de module worden afgestemd.