AI Product Support para Magento 2

Instalação e configuração

Este documento descreve como iniciar 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 se aprofundar nos detalhes técnicos do funcionamento ao nível do código.

O melhor é tratar 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 deve preparar antes da instalação

Antes da implementação, precisa de:

• uma loja Magento 2 em funcionamento,
• acesso ao servidor,
• composer,
• uma conta OpenAI,
• uma 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 assumir a função de preparar e organizar conteúdos para a AI. Na página desse módulo, isto foi descrito como a construção de uma base de conhecimento organizada e atualizada para sistemas de AI. AI Product Support é o passo seguinte natural, ou seja, a utilização desse conhecimento numa conversa com o utilizador. Fonte: Kowal AI Product Feed para OpenAI Vector Store

Instalação do módulo

O módulo é instalado através de composer.

Exemplo de processo de instalação:

Receberá por e-mail, após a compra, os dados de acesso ao repositório Composer, endereço de e-mail do cliente e token de licença. Também estão disponíveis na área de cliente após iniciar sessão em kowal.store. Substitua TWOJ_EMAIL_KLIENTA pelo endereço de e-mail da sua conta e TWOJ_TOKEN pelo token recebido. Execute os comandos no diretório raiz do 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 a loja estiver a 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:

• Enable Chat

Depois de guardar a definição, o separador AI aparecerá 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:

• Enable Frontend Chat

Se o módulo se destinar apenas à equipa da loja, mantenha o frontend desativado.

3. Defina o comprimento da pergunta

O campo:

• Maximum Question Length

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 claros.

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:

• Default Store View

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:

• Allow Store Switcher

define 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

O campo:

• Log Chat Requests

vale a pena ativar durante a 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 permanecer 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á a pergunta.

Response Model

Este é o modelo responsável por construir a resposta.

A lista de modelos é carregada a partir da API. Se, depois de guardar a chave, as opções não aparecerem, pode utilizar o botão para atualizar a lista de modelos.

Vector Store

Esta é a fonte de conhecimento selecionada para o módulo.

A forma mais simples de o entender é a seguinte:

• é o local onde estão guardados os conteúdos que o chat utiliza ao responder,
• é aí que o módulo procura as respostas,
• se escolher uma fonte incorreta, as respostas serão fracas ou incompletas.

Se a loja já tiver uma base de conhecimento organizada e preparada para AI, é aqui que deve indicar essa fonte.

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.

Uma boa definição inicial é um valor médio, por exemplo 6.

Segurança do frontend

Se o chat funcionar no lado da loja, vale a pena definir de imediato os limites de segurança.

Na secção Frontend Security, encontrará:

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

Estas definições ajudam a limitar:

• o envio demasiado frequente de perguntas,
• abusos por parte de bots,
• o consumo desnecessário de recursos e custos.

Prompt de sistema adicional

Na secção Prompting, pode preencher:

• System Prompt Template

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 do ponto de vista do utilizador

No painel de administração

Depois de iniciar o módulo, o utilizador vê o separador AI junto à margem direita do ecrã. Ao clicar, o painel do chat abre.

No painel, é possível:

• introduzir uma pergunta,
• receber uma resposta,
• ver cartões de produtos, se a resposta disser respeito a um produto específico,
• trabalhar sem recarregar a página.

No frontend

Se o chat tiver sido ativado, aparece um separador semelhante no lado da loja. O cliente pode fazer uma pergunta sem sair da página do produto ou da listagem.

Como encarar uma implementação deste tipo

O modelo mais prático é o seguinte:

1. a loja organiza os conteúdos e prepara a base de conhecimento,
2. o administrador indica essa base de conhecimento na configuração do módulo,
3. o utilizador utiliza o chat,
4. as respostas são construídas com base nos conteúdos preparados pela loja.

Esta abordagem produz melhores resultados do que iniciar apenas o chat sem dados preparados.

Configuração inicial recomendada

Painel de administração

• Enable Chat = Yes
• Enable Frontend Chat = consoante o projeto
• Maximum Question Length = 1000
• Allow Store Switcher = Yes com várias vistas de loja
• Log Chat Requests = Yes durante a fase de testes
• Maximum File Search Results = 6

Frontend

• Requests Per Minute = valor inicial prudente
• Requests Per Hour = valor ajustado ao tráfego da loja
• Minimum Submit Delay = pelo menos 1

O que verificar após a implementação

Depois de guardar a configuração, faça um teste simples:

1. verifique se o separador AI apareceu no painel de administração,
2. abra o popup e envie uma pergunta,
3. certifique-se de que a resposta aparece corretamente,
4. verifique se a secção de produtos aparece em perguntas sobre produtos específicos,
5. se o frontend estiver ativado, verifique também o funcionamento do separador na loja.

Problemas mais frequentes

Não são visíveis modelos ou fontes de conhecimento

Normalmente, isto significa:

• ausência de uma chave OpenAI correta,
• falta de ligação do servidor à internet,
• cache não limpa após as alterações.

O chat responde de forma demasiado fraca ou não acerta no tema

A causa mais frequente não é o próprio módulo, mas sim 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.

Por isso, antes de avaliar o próprio módulo, vale a pena verificar:

• se as descrições dos produtos são úteis e completas,
• se as FAQ e a documentação estão atualizadas,
• se a base de conhecimento contém realmente os conteúdos de que os utilizadores precisam,
• 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 dos limites e do atraso de envio na secção Frontend Security.

Checklist curta de implementação

1. Instale o módulo através de composer.
2. Ative o módulo e execute setup:upgrade.
3. Configure a ligação à OpenAI.
4. Escolha a fonte de conhecimento adequada.
5. Ative o chat no admin.
6. Opcionalmente, ative o chat no frontend.
7. Defina os limites de segurança.
8. 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 de composer e configurado em Stores > Configuration > Kowal AI > AI Product Support. O administrador introduz os dados de acesso à OpenAI, escolhe o modelo e a fonte de conhecimento para a 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.