AI Product Support para Magento 2

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:

• Enable Chat

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:

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

• 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

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:

• Log Chat Requests

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

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

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 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 = Yes
• Enable Frontend Chat = dependendo do projeto
• Maximum Question Length = 1000
• Allow Store Switcher = Yes com várias vistas de loja
• Log Chat Requests = Yes na 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 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

1. Instale o módulo através do composer.
2. Ative o módulo e execute setup:upgrade.
3. Configure a ligação à OpenAI.
4. Selecione a fonte de conhecimento correta.
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 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.