Kowal AI Product Feed - instalação e configuração
Objetivo do documento
Este documento descreve o processo completo de instalação, arranque e configuração do módulo Kowal_AiProductFeed no Magento 2. Foi preparado para permitir avançar desde a implementação técnica até à primeira exportação funcional e à publicação de llms.txt.
Âmbito funcional do módulo
O módulo permite:
- exportar conteúdos da loja para ficheiros
JSON e JSONL, - sincronizar dados para
OpenAI Vector Store, - suportar vários canais de conteúdo, como produto, blog, categoria e CMS,
- publicar endpoints públicos:
/llms.txt/ai-feed/{storeCode}/index.json/ai-feed/{storeCode}/{contentType}.ndjson
- adicionar uma ligação para
llms.txt na secção head, - adicionar opcionalmente uma ligação para
llms.txt no rodapé da loja.
llms.txt funciona por Store View atual. Isto significa que cada versão linguística pode devolver o seu próprio manifesto e as suas próprias ligações para feeds.
Pré-requisitos
Antes da instalação, certifique-se de que:
- o Magento 2 funciona corretamente,
- tem acesso SSH ao diretório raiz do Magento,
Composer está disponível no ambiente,- o processo PHP tem permissões de escrita no diretório
var/, - tem uma chave
OpenAI API Key ativa, caso pretenda utilizar a sincronização com OpenAI Vector Store.
Instalação do módulo
1. Adicionar o repositório Composer
Adicione o repositório Composer Kowal:
Receberá os dados de acesso ao repositório Composer, o endereço de e-mail do cliente e o token de licença, por e-mail após a compra. Também estão disponíveis no painel do 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
Se o repositório for privado:
composer config http-basic.repo.kowal.store 'TWOJ_EMAIL_KLIENTA' 'TWOJ_TOKEN'
2. Instalação do pacote
composer require kowal/module-ai-product-feed
3. Ativação do módulo
bin/magento module:enable Kowal_AiProductFeed
4. Atualização do Magento
bin/magento setup:upgrade
5. Compilação e cache
No ambiente de produção, execute adicionalmente:
bin/magento setup:di:compilebin/magento cache:flush
No ambiente de desenvolvimento, normalmente basta:
bin/magento cache:flush
Se existir uma camada de cache adicional antes do Magento, efetue também o purge no lado de:
VarnishCloudflareNginx fastcgi/proxy cache- outro reverse proxy ou CDN
6. Confirmação do estado do módulo
bin/magento module:status Kowal_AiProductFeed
Localização da configuração
A configuração do módulo está disponível no painel:
Stores -> Configuration -> General -> Kowal AI Feed
Modelo de configuração recomendado
A melhor prática é configurar ao nível de Store View, especialmente se a loja funcionar em vários idiomas.
Recomendação:
- um
Store View = um idioma, - um
Store View = um Vector Store ID, - um
Store View = uma camada pública separada de feeds AI.
Exemplo:
PL store view -> Vector Store ID em polacoEN store view -> Vector Store ID em inglês
Configuração dos campos
Enable Module
Ativa o módulo para o âmbito selecionado.
Recomendação:
- defina
Yes nos Store View que devem gerar dados AI
OpenAI API Key
Chave API global utilizada para comunicação com OpenAI.
Obrigatória se:
- pretende sincronizar ficheiros para
OpenAI Vector Store
Não é obrigatória se:
- pretende utilizar apenas exportações locais,
- pretende utilizar apenas
llms.txt e feeds públicos.
Vector Store ID
Identificador de OpenAI Vector Store para um Store View específico.
Recomendação:
- configurar ao nível de
Store View, - definir um identificador separado para cada idioma.
Feed Location
Caminho relativo para o diretório onde serão gravados os ficheiros de exportação.
Valor predefinido:
var/ai-feeds
Recomendação:
- manter o diretório em
var/, - não expor este diretório diretamente através do webserver.
Enable Public AI Feed
Ativa os endpoints públicos:
/llms.txt/ai-feed/{storeCode}/index.json/ai-feed/{storeCode}/{contentType}.ndjson
Ative esta opção apenas para as vistas de loja cujos conteúdos podem estar publicamente disponíveis.
Importante:
/llms.txt não é um índice global de todas as lojas- cada versão linguística da loja devolve o seu próprio manifesto
- o próprio
/llms.txt não exige a existência de ficheiros gerados para responder corretamente
Adiciona uma ligação visível para /llms.txt no rodapé da loja.
Recomendação:
No por predefinição,Yes, se pretende comunicar explicitamente a disponibilidade da camada AI a parceiros, integradores ou bots.
Docs Location
Caminho relativo para o diretório com documentação de produto em Markdown para product.docs.
Exemplos:
var/ai-docsvar/ai-docs/pl
São suportados, entre outros, os ficheiros:
{docsLocation}/{SKU}.md{docsLocation}/{SKU}.markdown{docsLocation}/{storeCode}/{SKU}.md{docsLocation}/{storeCode}/{SKU}.markdown{docsLocation}/{SKU}/*.md{docsLocation}/{SKU}/*.markdown{docsLocation}/{storeCode}/{SKU}/*.md{docsLocation}/{storeCode}/{SKU}/*.markdown
Max Products Per Batch
Tamanho do lote para a exportação de produtos.
Valor inicial:
Reduza o valor se:
- o catálogo for muito grande,
- o ambiente tiver memória limitada,
- operações AI adicionais aumentarem a carga.
Sync Product Core
Ativa o tipo de conteúdo product.core.
Recomendação:
Sync Product FAQ
Ativa product.faq.
Utilize se a loja tiver dados na tabela kowal_zapytajoprodukt_pytania.
Sync Product Docs
Ativa product.docs.
Utilize se a documentação Markdown já estiver preparada.
Sync Blog Content
Ativa o canal blog e o tipo blog.article.
Sync Category Content
Ativa o canal category e o tipo category.content.
Sync CMS Pages
Ativa o canal cms_page e o tipo cms.page.
Max Retries
Número máximo de tentativas de operações API.
Predefinição:
Polling Timeout
Tempo máximo de espera pela conclusão do processamento do ficheiro no lado da OpenAI.
Predefinição:
Polling Interval
Intervalo entre verificações consecutivas do estado.
Predefinição:
HTTP Timeout
Tempo máximo de um único pedido HTTP para a OpenAI.
Predefinição:
Ordem de configuração recomendada
Após a instalação, configure o módulo pela seguinte ordem:
- Ative o módulo para o
Store View de destino. - Adicione a
OpenAI API Key, se planear a sincronização com OpenAI. - Defina o
Vector Store ID para cada idioma. - Verifique o
Feed Location. - Defina o
Docs Location, se utilizar documentação Markdown. - Ative os tipos de conteúdo e canais necessários.
- Ative
Enable Public AI Feed, se os endpoints devem estar disponíveis publicamente. - Opcionalmente, ative
Show LLMs.txt Link in Footer. - Limpe a cache do Magento.
bin/magento cache:flush
Primeira execução
Dry run
Primeiro, execute um teste sem alterações para um Store View:
bin/magento kowal:ai-export:sync --channel=product --store=1 --dry-run
Exportação real
Em seguida, execute a sincronização efetiva:
bin/magento kowal:ai-export:sync --channel=product --store=1
Verificação do estado
bin/magento kowal:ai-export:status --store=1
Verificação dos endpoints públicos
Se Enable Public AI Feed estiver ativado, verifique:
curl -i https://twoja-domena.pl/llms.txtcurl -i https://twoja-domena.pl/ai-feed/pl/index.jsoncurl -i https://twoja-domena.pl/ai-feed/pl/product.core.ndjson
Se a loja tiver versões linguísticas separadas no URL, verifique também:
curl -i https://twoja-domena.pl/en/llms.txtcurl -i https://twoja-domena.pl/de/llms.txt
Comportamento esperado:
/llms.txt devolve o manifesto apenas para o Store View atual/llms.txt funciona mesmo quando ainda não existem ficheiros de feed gerados/ai-feed/{storeCode}/index.json mostra apenas os feeds existentes para determinada loja/ai-feed/{storeCode}/{contentType}.ndjson só funciona quando existem os ficheiros de origem correspondentes
Verificação dos cabeçalhos de cache:
curl -I https://twoja-domena.pl/llms.txtcurl -I https://twoja-domena.pl/ai-feed/pl/index.json
Deverá ver:
- para
/llms.txt, cabeçalhos que praticamente desativam a cache, - para
index.json, um tempo de vida curto da cache e revalidação forçada.
Verificação do HTML:
- no código-fonte da página deverá aparecer uma ligação no
head para /llms.txt, - se ativou a opção do rodapé, deverá aparecer no footer uma ligação
LLMs.txt.
Comandos CLI
Sincronização
bin/magento kowal:ai-export:sync --channel=productbin/magento kowal:ai-export:sync --channel=product --store=1bin/magento kowal:ai-export:sync --channel=product --store=1 --content-type=product.core --identifier=example-sku --dry-runbin/magento kowal:ai-export:sync --channel=blog --store=1 --source=amasty_blogbin/magento kowal:ai-export:sync --channel=category --store=1bin/magento kowal:ai-export:sync --channel=cms_page --store=1
Estado
bin/magento kowal:ai-export:statusbin/magento kowal:ai-export:status --store=1bin/magento kowal:ai-export:status --channel=blog --store=1bin/magento kowal:ai-export:status --channel=blog --store=1 --source=amasty_blog
Importação de fontes do blog
bin/magento kowal:ai-blog-source:import --source=amasty_blog --store=1
Alias de produto antigo
Ainda disponível para compatibilidade retroativa:
bin/magento kowal:ai-feed:generatebin/magento kowal:ai-feed:generate --store=1 --content-type=product.core --sku=example-sku --dry-run
Cron
O módulo utiliza três tarefas cron:
kowal_ai_blog_source_importkowal_ai_feed_generatekowal_ai_feed_cleanup
Certifique-se de que o cron do Magento funciona corretamente no ambiente.
Problemas mais frequentes
/llms.txt devolve 404
Verifique:
- se está implementada a versão atual do módulo com frontend routing,
- se executou
bin/magento setup:upgrade, - se, em production mode, executou
bin/magento setup:di:compile, - se executou o deploy static content padrão de acordo com o processo do projeto,
- se limpou a cache,
- se efetuou o purge da camada CDN / reverse proxy,
- se
Enable Public AI Feed está ativado.
Se https://twoja-domena.pl/llms.txt?v=123 funcionar e https://twoja-domena.pl/llms.txt não funcionar, normalmente significa que ainda existe uma cache partilhada antiga pelo caminho.
/llms.txt funciona, mas os feeds estão vazios
Isto normalmente significa que:
- a exportação ainda não foi executada,
- não existem conteúdos ativos para o canal em questão,
- as flags de sincronização correspondentes estão desativadas.
Este comportamento está correto. O próprio manifesto pode funcionar antes dos feeds efetivos.
Faltam ficheiros em var/ai-feeds
Verifique:
- se o módulo está ativo no
Store View correto, - se os tipos de conteúdo necessários estão ativados,
- se o Magento tem permissões de escrita em
var/, - se o processo de sincronização foi iniciado.
Problemas com a sincronização para a OpenAI
Verifique:
- a correção da
OpenAI API Key, - a correção do
Vector Store ID, - a disponibilidade de ligações HTTP de saída,
- os valores de timeout e retry.
Resumo
Após a instalação e configuração corretas, o módulo fornece ao Magento 2 uma camada de dados pronta para AI:
- local,
- multilingue,
- sincronizável com
OpenAI, - pronta para publicação através de
llms.txt e feeds NDJSON, - extensível para futuras integrações e módulos AI.
