Kowal AI Product Feed - installazione e configurazione
Obiettivo del documento
Questo documento descrive il processo completo di installazione, avvio e configurazione del modulo Kowal_AiProductFeed in Magento 2. È stato preparato in modo da consentire di passare dall'implementazione tecnica alla prima esportazione funzionante e alla pubblicazione di llms.txt.
Ambito funzionale del modulo
Il modulo consente:
- l'esportazione dei contenuti del negozio in file
JSON e JSONL, - la sincronizzazione dei dati con
OpenAI Vector Store, - la gestione di più canali di contenuto, come prodotto, blog, categoria e CMS,
- la pubblicazione di endpoint pubblici:
/llms.txt/ai-feed/{storeCode}/index.json/ai-feed/{storeCode}/{contentType}.ndjson
- l'aggiunta del link a
llms.txt nella sezione head, - l'aggiunta facoltativa del link a
llms.txt nel footer del negozio.
llms.txt funziona per l'attuale Store View. Ciò significa che ogni versione linguistica può restituire il proprio manifest e i propri link ai feed.
Prerequisiti
Prima dell'installazione assicurati che:
- Magento 2 funzioni correttamente,
- tu abbia accesso SSH alla directory principale di Magento,
Composer sia disponibile nell'ambiente,- il processo PHP possa scrivere nella directory
var/, - tu disponga di una chiave
OpenAI API Key attiva, se vuoi utilizzare la sincronizzazione con OpenAI Vector Store.
Installazione del modulo
1. Aggiunta del repository Composer
Se il modulo viene installato da un repository Git:
composer config repositories.ai.product.feed vcs https://github.com/kowalco/module-ai-product-feed
Se il repository è privato:
composer config --global --auth github-oauth.github.com
2. Installazione del pacchetto
composer require kowal/module-ai-product-feed
3. Abilitazione del modulo
bin/magento module:enable Kowal_AiProductFeed
4. Aggiornamento di Magento
bin/magento setup:upgrade
5. Compilazione e cache
Nell'ambiente di produzione esegui inoltre:
bin/magento setup:di:compilebin/magento cache:flush
Nell'ambiente di sviluppo di solito è sufficiente:
bin/magento cache:flush
Se davanti a Magento è presente un ulteriore layer di cache, esegui anche il purge lato:
VarnishCloudflareNginx fastcgi/proxy cache- altro reverse proxy o CDN
6. Conferma dello stato del modulo
bin/magento module:status Kowal_AiProductFeed
Posizione della configurazione
La configurazione del modulo è disponibile nel pannello:
Stores -> Configuration -> General -> Kowal AI Feed
Modello di configurazione consigliato
La best practice consiste nella configurazione a livello di Store View, soprattutto se il negozio opera in più lingue.
Raccomandazione:
- uno
Store View = una lingua, - uno
Store View = un Vector Store ID, - uno
Store View = un layer pubblico separato di feed AI.
Esempio:
PL store view -> Vector Store ID polaccoEN store view -> Vector Store ID inglese
Configurazione dei campi
Enable Module
Abilita il modulo per l'ambito selezionato.
Raccomandazione:
- imposta
Yes per gli Store View che devono generare dati AI
OpenAI API Key
Chiave API globale utilizzata per la comunicazione con OpenAI.
Richiesta se:
- vuoi sincronizzare i file con
OpenAI Vector Store
Non è richiesta se:
- vuoi utilizzare solo esportazioni locali,
- vuoi utilizzare solo
llms.txt e feed pubblici.
Vector Store ID
Identificatore di OpenAI Vector Store per uno specifico Store View.
Raccomandazione:
- configurarlo a livello di
Store View, - impostare un identificatore separato per ogni lingua.
Feed Location
Percorso relativo della directory in cui verranno salvati i file di esportazione.
Valore predefinito:
var/ai-feeds
Raccomandazione:
- mantenere la directory in
var/, - non esporre questa directory direttamente tramite il webserver.
Enable Public AI Feed
Abilita gli endpoint pubblici:
/llms.txt/ai-feed/{storeCode}/index.json/ai-feed/{storeCode}/{contentType}.ndjson
Attiva questa opzione solo per le viste del negozio i cui contenuti possono essere resi disponibili pubblicamente.
Importante:
/llms.txt non è un indice globale di tutti i negozi- ogni versione linguistica del negozio restituisce il proprio manifest
/llms.txt non richiede l'esistenza dei file generati per rispondere correttamente
Aggiunge un link visibile a /llms.txt nel footer del negozio.
Raccomandazione:
No per impostazione predefinita,Yes se vuoi comunicare esplicitamente la disponibilità del layer AI a partner, integratori o bot.
Docs Location
Percorso relativo della directory con la documentazione prodotto in Markdown per product.docs.
Esempi:
var/ai-docsvar/ai-docs/pl
Sono supportati, tra gli altri, i file:
{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
Dimensione del batch per l'esportazione dei prodotti.
Valore iniziale:
Riduci il valore se:
- il catalogo è molto grande,
- l'ambiente ha memoria limitata,
- operazioni AI aggiuntive aumentano il carico.
Sync Product Core
Abilita il tipo di contenuto product.core.
Raccomandazione:
Sync Product FAQ
Abilita product.faq.
Usalo se il negozio dispone di dati nella tabella kowal_zapytajoprodukt_pytania.
Sync Product Docs
Abilita product.docs.
Usalo se la documentazione Markdown è già pronta.
Sync Blog Content
Abilita il canale blog e il tipo blog.article.
Sync Category Content
Abilita il canale category e il tipo category.content.
Sync CMS Pages
Abilita il canale cms_page e il tipo cms.page.
Max Retries
Numero massimo di tentativi per le operazioni API.
Valore predefinito:
Polling Timeout
Tempo massimo di attesa per il completamento dell'elaborazione del file lato OpenAI.
Valore predefinito:
Polling Interval
Intervallo tra un controllo dello stato e il successivo.
Valore predefinito:
HTTP Timeout
Tempo massimo di una singola request HTTP verso OpenAI.
Valore predefinito:
Ordine di configurazione consigliato
Dopo l'installazione, configura il modulo in questo ordine:
- Abilita il modulo per lo
Store View di destinazione. - Aggiungi
OpenAI API Key se prevedi la sincronizzazione con OpenAI. - Imposta il
Vector Store ID per ogni lingua. - Verifica
Feed Location. - Imposta
Docs Location se utilizzi documentazione Markdown. - Abilita i tipi di contenuto e i canali necessari.
- Abilita
Enable Public AI Feed se gli endpoint devono essere accessibili pubblicamente. - Facoltativamente abilita
Show LLMs.txt Link in Footer. - Svuota la cache di Magento.
bin/magento cache:flush
Primo avvio
Dry run
Esegui prima un test a secco per uno Store View:
bin/magento kowal:ai-export:sync --channel=product --store=1 --dry-run
Esportazione reale
Quindi avvia la sincronizzazione effettiva:
bin/magento kowal:ai-export:sync --channel=product --store=1
Verifica dello stato
bin/magento kowal:ai-export:status --store=1
Verifica degli endpoint pubblici
Se Enable Public AI Feed è abilitato, controlla:
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 il negozio ha versioni linguistiche separate nell'URL, controlla anche:
curl -i https://twoja-domena.pl/en/llms.txtcurl -i https://twoja-domena.pl/de/llms.txt
Comportamento atteso:
/llms.txt restituisce il manifest solo per lo Store View corrente/llms.txt funziona anche quando non esistono ancora file feed generati/ai-feed/{storeCode}/index.json mostra solo i feed esistenti per quel negozio/ai-feed/{storeCode}/{contentType}.ndjson funziona solo quando esistono i file sorgente corrispondenti
Verifica degli header di cache:
curl -I https://twoja-domena.pl/llms.txtcurl -I https://twoja-domena.pl/ai-feed/pl/index.json
Dovresti vedere:
- per
/llms.txt header che disabilitano praticamente la cache, - per
index.json una durata cache breve e revalidazione forzata.
Verifica HTML:
- nel sorgente della pagina dovrebbe comparire un link nel
head verso /llms.txt, - se hai attivato l'opzione footer, nel footer dovrebbe comparire il link
LLMs.txt.
Comandi CLI
Sincronizzazione
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
Stato
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
Import delle fonti blog
bin/magento kowal:ai-blog-source:import --source=amasty_blog --store=1
Vecchio alias prodotto
Ancora disponibile per compatibilità retroattiva:
bin/magento kowal:ai-feed:generatebin/magento kowal:ai-feed:generate --store=1 --content-type=product.core --sku=example-sku --dry-run
Cron
Il modulo utilizza tre job cron:
kowal_ai_blog_source_importkowal_ai_feed_generatekowal_ai_feed_cleanup
Assicurati che il cron di Magento funzioni correttamente nell'ambiente.
Problemi più comuni
/llms.txt restituisce 404
Controlla:
- che sia stata distribuita la versione attuale del modulo con frontend routing,
- che tu abbia eseguito
bin/magento setup:upgrade, - che in production mode tu abbia eseguito
bin/magento setup:di:compile, - che tu abbia eseguito il deploy standard dei contenuti statici secondo il processo del progetto,
- che tu abbia svuotato la cache,
- che tu abbia eseguito il purge del layer CDN / reverse proxy,
- che
Enable Public AI Feed sia abilitato.
Se https://twoja-domena.pl/llms.txt?v=123 funziona, ma https://twoja-domena.pl/llms.txt no, di solito significa che è ancora attiva una vecchia cache condivisa lungo il percorso.
/llms.txt funziona, ma i feed sono vuoti
Di solito significa che:
- l'esportazione non è stata ancora eseguita,
- mancano contenuti attivi per il canale specifico,
- i relativi flag di sincronizzazione sono disabilitati.
Questo comportamento è corretto. Il manifest stesso può funzionare prima dei feed veri e propri.
Mancanza di file in var/ai-feeds
Controlla:
- che il modulo sia attivo nel corretto
Store View, - che i tipi di contenuto richiesti siano abilitati,
- che Magento abbia i permessi di scrittura in
var/, - che il processo di sincronizzazione sia stato avviato.
Problemi con la sincronizzazione verso OpenAI
Controlla:
- la correttezza di
OpenAI API Key, - la correttezza di
Vector Store ID, - la disponibilità delle connessioni HTTP in uscita,
- i valori di timeout e retry.
Riepilogo
Dopo la corretta installazione e configurazione, il modulo fornisce a Magento 2 un layer dati pronto per l'AI:
- locale,
- multilingua,
- sincronizzabile con
OpenAI, - pronto per la pubblicazione tramite
llms.txt e feed NDJSON, - estendibile per future integrazioni e moduli AI.
WhatsApp
+48608012047
