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 passar da implementação técnica à 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 com o
OpenAI Vector Store, - suportar vários canais de conteúdo, como produto, blogue, 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.
Requisitos prévios
Antes da instalação, certifique-se de que:
- o Magento 2 está a funcionar corretamente,
- tem acesso SSH ao diretório raiz do Magento,
- o
Composer está disponível no ambiente, - o processo PHP tem permissão de escrita no diretório
var/, - tem uma chave
OpenAI API Key ativa, se quiser utilizar a sincronização com o OpenAI Vector Store.
Instalação do módulo
1. Adicionar o repositório Composer
Se o módulo for instalado a partir de um repositório Git:
composer config repositories.ai.product.feed vcs https://github.com/kowalco/module-ai-product-feed
Se o repositório for privado:
composer config --global --auth github-oauth.github.com
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
Em ambiente de produção, execute adicionalmente:
bin/magento setup:di:compilebin/magento cache:flush
Em ambiente de desenvolvimento, normalmente basta:
bin/magento cache:flush
Se existir uma camada de cache adicional à frente do Magento, execute também purge do 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 nesses Store View que devem gerar dados AI
OpenAI API Key
Chave API global utilizada para comunicar com OpenAI.
Obrigatória se:
- quiser sincronizar ficheiros com o
OpenAI Vector Store
Não é obrigatória se:
- quiser usar apenas exportações locais,
- quiser usar apenas
llms.txt e feeds públicos.
Vector Store ID
Identificador do 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 guardados 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 servidor web.
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 possam 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 quiser comunicar de forma explícita 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 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 para operações API.
Por predefinição:
Polling Timeout
Tempo máximo de espera pela conclusão do processamento do ficheiro do lado do OpenAI.
Por predefinição:
Polling Interval
Intervalo entre verificações sucessivas do estado.
Por predefinição:
HTTP Timeout
Tempo máximo de um único pedido HTTP para OpenAI.
Por predefinição:
Ordem recomendada de configuração
Após a instalação, configure o módulo por esta ordem:
- Ative o módulo para o
Store View pretendido. - Adicione
OpenAI API Key, se planear sincronização com OpenAI. - Defina
Vector Store ID para cada idioma. - Verifique
Feed Location. - Defina
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 tiverem de 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 a seco para um único 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 um 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 a loja em causa/ai-feed/{storeCode}/{contentType}.ndjson só funciona quando existem os respetivos ficheiros de origem
Verificação de 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 HTML:
- no código-fonte da página deverá surgir uma ligação na secção
head para /llms.txt, - se tiver ativado a opção de rodapé, deverá surgir uma ligação
LLMs.txt no footer.
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 blogue
bin/magento kowal:ai-blog-source:import --source=amasty_blog --store=1
Alias antigo de produto
Ainda disponível por 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 está a funcionar corretamente no ambiente.
Problemas mais frequentes
/llms.txt devolve 404
Verifique:
- se foi 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 standard de static content de acordo com o processo do projeto,
- se limpou a cache,
- se executou o purge da camada CDN / reverse proxy,
- se
Enable Public AI Feed está ativado.
Se https://twoja-domena.pl/llms.txt?v=123 funcionar, mas https://twoja-domena.pl/llms.txt não, isso normalmente significa que ainda existe uma cache partilhada antiga no 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 causa,
- as respetivas flags de sincronização estão desativadas.
Este comportamento está correto. O próprio manifesto pode funcionar antes dos feeds propriamente ditos.
Sem 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 executado.
Problemas com a sincronização para 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 uma instalação e configuração corretas, o módulo dá 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, - evolutiva para futuras integrações e módulos AI.
WhatsApp
+48608012047
