Instalação e configuração
Este documento descreve como ativar o módulo AI Product Support numa loja Magento 2 e como prepará-lo para funcionamento.
O documento foi escrito a pensar numa loja que pretende implementar um módulo pronto a usar e começar a utilizar o chat AI sem entrar nos detalhes técnicos do funcionamento ao nível do código.
É melhor encarar este módulo como uma camada de utilização. Primeiro, a loja prepara o conhecimento e só depois o disponibiliza aos colaboradores ou clientes sob a forma de chat.
O que preparar antes da instalação
Antes da implementação, precisa de:
- uma loja Magento 2 funcional,
- acesso ao servidor,
- composer,
- conta OpenAI,
- base de conhecimento AI preparada para a loja,
- ligação do servidor à internet.
A condição prática mais importante é simples: o módulo só responderá bem se a loja tiver conteúdos preparados que a AI possa utilizar.
Se a loja já utiliza o módulo Kowal AI Product Feed, é precisamente ele que pode desempenhar o papel de preparação e organização dos conteúdos para AI. Na página desse módulo, isto foi descrito como a criação de uma base de conhecimento organizada e atualizada para sistemas AI. AI Product Support é o passo seguinte natural, ou seja, a utilização desse conhecimento na conversa com o utilizador. Fonte: Kowal AI Product Feed para OpenAI Vector Store
Instalação do módulo
O módulo é instalado através do composer.
Processo de instalação de exemplo:
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 a loja funcionar em modo de produção, após a instalação execute também:
bin/magento setup:di:compilebin/magento setup:static-content:deploy -fbin/magento cache:clean
Onde se encontra a configuração
Após a instalação, encontrará as definições do módulo aqui:
Stores > Configuration > Kowal AI > AI Product Support
Como configurar o módulo
1. Ative o chat no painel de administração
Na secção General, ative:
Depois de guardar a definição, surgirá um separador AI no painel de administração.
2. Decida se pretende ativar o chat no frontend
Se quiser que os clientes da loja também possam utilizar o chat, ative:
Se o módulo se destinar apenas à equipa da loja, mantenha o frontend desativado.
3. Defina o comprimento da pergunta
O campo:
define o comprimento máximo da mensagem que o utilizador pode enviar. Isto ajuda a manter a organização e a limitar pedidos demasiado longos e pouco legíveis.
4. Defina a vista de loja predefinida
Se a loja funcionar em várias versões linguísticas ou tiver várias vistas de loja, pode indicar:
Isto facilita o trabalho no painel e ajuda a começar no contexto correto.
5. Ative ou desative a alteração manual da vista de loja
O campo:
determina se o utilizador do painel pode alterar a vista de loja diretamente no popup do chat.
Isto é útil quando uma equipa gere várias versões da loja.
6. Ative o registo técnico durante a implementação
Vale a pena ativar o campo:
na fase de configuração e testes. Assim, é mais fácil verificar se o módulo funciona corretamente. Após a implementação em produção, pode decidir se o registo deve continuar ativo.
Definições de ligação à AI
Na secção OpenAI, configure os elementos básicos necessários para o funcionamento do módulo.
OpenAI API Key
Esta é a chave de acesso ao serviço AI. Sem ela, o módulo não obterá a lista de modelos, não lerá a fonte de conhecimento e não enviará perguntas.
Response Model
Este é o modelo responsável pela criação das respostas.
A lista de modelos é carregada a partir da API. Se, após guardar a chave, as opções não aparecerem, pode usar o botão de atualização da lista de modelos.
Vector Store
Esta é a fonte de conhecimento selecionada para o módulo.
A forma mais simples de o compreender é esta:
- é o local onde estão guardados os conteúdos que o chat utiliza ao responder,
- o módulo procura respostas precisamente aí,
- se selecionar a fonte errada, as respostas serão fracas ou incompletas.
Se a loja já tiver uma base de conhecimento organizada e preparada para AI, é aqui que essa fonte deve ser indicada.
A lista de fontes de conhecimento também pode ser atualizada a partir da configuração.
Maximum File Search Results
Esta definição determina quantos materiais de apoio o módulo considera ao preparar uma única resposta.
Na prática, isto influencia:
- a qualidade da resposta,
- a velocidade de funcionamento,
- o custo de utilização da AI.
Um bom valor inicial é um valor médio, por exemplo 6.
Segurança do frontend
Se o chat funcionar no lado da loja, convém definir logo os limites de segurança.
Na secção Frontend Security, encontrará:
Requests Per MinuteRequests Per HourMinimum Submit Delay
Estas definições ajudam a limitar:
- o envio demasiado frequente de perguntas,
- abusos por parte de bots,
- consumo desnecessário de recursos e custos.
Prompt de sistema adicional
Na secção Prompting, pode preencher:
Este campo não é obrigatório. Na maioria das implementações, pode deixá-lo vazio e utilizar a definição predefinida do módulo.
A substituição só faz sentido se a loja quiser introduzir o seu próprio estilo de resposta ou regras adicionais de comunicação.
Como o módulo funciona da perspetiva do utilizador
No painel de administração
Depois de ativar o módulo, o utilizador vê um separador AI junto à extremidade direita do ecrã. Ao clicar, abre-se o painel de chat.
No painel é possível:
- introduzir uma pergunta,
- receber uma resposta,
- ver cartões de produto, se a resposta disser respeito a um produto específico,
- trabalhar sem recarregar a página.
No frontend
Se o chat tiver sido ativado, surge um separador semelhante no lado da loja. O cliente pode fazer uma pergunta sem sair da página de produto ou da listagem.
Como pensar numa implementação deste tipo
O modelo mais prático é o seguinte:
- a loja organiza os conteúdos e prepara a base de conhecimento,
- o administrador indica essa base de conhecimento na configuração do módulo,
- o utilizador utiliza o chat,
- as respostas são criadas com base nos conteúdos preparados pela loja.
Esta abordagem oferece um resultado melhor do que ativar apenas o chat sem dados preparados.
Configuração inicial recomendada
Painel de administração
Enable Chat = YesEnable Frontend Chat = dependendo do projetoMaximum Question Length = 1000Allow Store Switcher = Yes com várias vistas de lojaLog Chat Requests = Yes na fase de testesMaximum File Search Results = 6
Frontend
Requests Per Minute = valor inicial prudenteRequests Per Hour = valor ajustado ao tráfego da lojaMinimum Submit Delay = pelo menos 1
O que verificar após a implementação
Depois de guardar a configuração, faça um teste simples:
- verifique se o separador AI apareceu no painel de administração,
- abra o popup e envie uma pergunta,
- certifique-se de que a resposta aparece corretamente,
- verifique se a secção de produtos aparece em perguntas sobre produtos específicos,
- se o frontend estiver ativado, verifique também o funcionamento do separador na loja.
Problemas mais comuns
Os modelos ou as fontes de conhecimento não aparecem
Na maioria dos casos, isto significa:
- ausência de uma chave OpenAI correta,
- ausência de ligação do servidor à internet,
- cache não limpa após alterações.
O chat responde mal ou não acerta no tema
A causa mais comum não é o próprio módulo, mas a qualidade da base de conhecimento preparada. Se os conteúdos forem incompletos, desatualizados ou demasiado pobres, as respostas também serão mais fracas.
Antes de avaliar o próprio módulo, vale a pena verificar:
- se as descrições dos produtos são relevantes e completas,
- se as FAQ e a documentação estão atualizadas,
- se a base de conhecimento contém de facto os conteúdos necessários para os utilizadores,
- se a fonte de conhecimento selecionada é adequada para a loja em questão.
O frontend bloqueia o utilizador demasiado depressa
Nesse caso, vale a pena verificar as definições de limites e atraso de envio na secção Frontend Security.
Checklist curta de implementação
- Instale o módulo através do
composer. - Ative o módulo e execute
setup:upgrade. - Configure a ligação à OpenAI.
- Selecione a fonte de conhecimento correta.
- Ative o chat no admin.
- Opcionalmente, ative o chat no frontend.
- Defina os limites de segurança.
- Teste o funcionamento com perguntas sobre produtos reais e conteúdos da loja.
Descrição curta para a secção Instalação e configuração
O módulo é instalado através do composer e configurado em Stores > Configuration > Kowal AI > AI Product Support. O administrador introduz os dados de acesso à OpenAI, seleciona o modelo e a fonte de conhecimento da loja e, em seguida, ativa o chat no painel de administração e, opcionalmente, no frontend. Além disso, é possível definir limites de segurança e ajustar os parâmetros básicos de funcionamento do módulo.