Kowal AI Product Feed - installazione e configurazione
Scopo del documento
Questo documento descrive l'intero processo di installazione, avvio e configurazione del modulo Kowal_AiProductFeed in Magento 2. È stato preparato per consentire di passare dall'implementazione tecnica al primo export funzionante e alla pubblicazione di llms.txt.
Ambito funzionale del modulo
Il modulo consente di:
- esportare i contenuti dello store in file
JSON e JSONL, - sincronizzare i dati con
OpenAI Vector Store, - gestire più canali di contenuto, come prodotto, blog, categoria e CMS,
- pubblicare endpoint pubblici:
/llms.txt/ai-feed/{storeCode}/index.json/ai-feed/{storeCode}/{contentType}.ndjson
- aggiungere un link a
llms.txt nella sezione head, - aggiungere opzionalmente un link a
llms.txt nel footer dello store.
llms.txt funziona per lo Store View corrente. 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 root di Magento,
Composer sia disponibile nell'ambiente,- il processo PHP possa scrivere nella directory
var/, - tu abbia una chiave
OpenAI API Key attiva, se vuoi utilizzare la sincronizzazione con OpenAI Vector Store.
Installazione del modulo
1. Aggiunta del repository Composer
Aggiungi il repository Composer Kowal:
I dati di accesso al repository Composer (indirizzo e-mail del cliente e token di licenza) saranno inviati via e-mail dopo l'acquisto. Sono inoltre disponibili nel pannello cliente dopo l'accesso su kowal.store. Sostituisci TWOJ_EMAIL_KLIENTA con l'indirizzo e-mail del tuo account e TWOJ_TOKEN con il token ricevuto. Esegui i comandi nella directory root di Magento.
composer config repositories.kowal composer https://repo.kowal.store
Se il repository è privato:
composer config http-basic.repo.kowal.store 'TWOJ_EMAIL_KLIENTA' 'TWOJ_TOKEN'
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
In ambiente di produzione, esegui inoltre:
bin/magento setup:di:compilebin/magento cache:flush
In ambiente di sviluppo di solito è sufficiente:
bin/magento cache:flush
Se davanti a Magento è presente un ulteriore livello 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 è configurare a livello di Store View, soprattutto se lo store opera in più lingue.
Raccomandazione:
- uno
Store View = una lingua, - uno
Store View = un Vector Store ID, - uno
Store View = un livello 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 sugli 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 export locali,
- vuoi utilizzare solo
llms.txt e feed pubblici.
Vector Store ID
Identificatore OpenAI Vector Store per uno specifico Store View.
Raccomandazione:
- configurare 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 export.
Valore predefinito:
var/ai-feeds
Raccomandazione:
- lasciare 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
Abilita questa opzione solo per le viste store i cui contenuti possono essere disponibili pubblicamente.
Importante:
/llms.txt non è un indice globale di tutti gli store- ogni versione linguistica dello store restituisce il proprio manifest
/llms.txt non richiede l'esistenza di file generati per rispondere correttamente
Aggiunge un link visibile a /llms.txt nel footer dello store.
Raccomandazione:
No per impostazione predefinita,Yes, se vuoi comunicare esplicitamente la disponibilità del livello AI a partner, integratori o bot.
Docs Location
Percorso relativo della directory con la documentazione prodotto 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'export 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 lo store 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.
Predefinito:
Polling Timeout
Tempo massimo di attesa per il completamento dell'elaborazione del file lato OpenAI.
Predefinito:
Polling Interval
Intervallo tra i successivi controlli dello stato.
Predefinito:
HTTP Timeout
Tempo massimo di una singola richiesta HTTP a OpenAI.
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
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 disponibili pubblicamente. - Opzionalmente abilita
Show LLMs.txt Link in Footer. - Svuota la cache di Magento.
bin/magento cache:flush
Primo avvio
Dry run
Per prima cosa esegui un test a secco per un singolo Store View:
bin/magento kowal:ai-export:sync --channel=product --store=1 --dry-run
Export 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, verifica:
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 lo store ha versioni linguistiche separate nell'URL, verifica 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 sono ancora stati generati file di feed/ai-feed/{storeCode}/index.json mostra solo i feed esistenti per il relativo store/ai-feed/{storeCode}/{contentType}.ndjson funziona solo quando esistono i file sorgente appropriati
Verifica degli header 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 di fatto disabilitano la cache, - per
index.json una breve durata della cache e una revalidazione forzata.
Verifica HTML:
- nel sorgente della pagina dovrebbe comparire un link in
head a /llms.txt, - se hai attivato l'opzione del 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
Importazione delle fonti del blog
bin/magento kowal:ai-blog-source:import --source=amasty_blog --store=1
Vecchio alias prodotto
Ancora disponibile per retrocompatibilità:
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 cron Magento funzioni correttamente nell'ambiente.
Problemi più comuni
/llms.txt restituisce 404
Verifica:
- che sia stata implementata la versione corrente 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 dello static content secondo il processo del progetto,
- che tu abbia svuotato la cache,
- che tu abbia eseguito il purge del livello 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 lungo il percorso è ancora attiva una vecchia cache condivisa.
/llms.txt funziona, ma i feed sono vuoti
Di solito significa che:
- l'export non è ancora stato eseguito,
- mancano contenuti attivi per il relativo canale,
- i flag di sincronizzazione appropriati sono disabilitati.
Questo comportamento è corretto. Il manifest può funzionare prima dei feed effettivi.
Nessun file in var/ai-feeds
Verifica:
- che il modulo sia attivo sullo
Store View corretto, - che i tipi di contenuto richiesti siano abilitati,
- che Magento abbia i permessi di scrittura su
var/, - che il processo di sincronizzazione sia stato avviato.
Problemi con la sincronizzazione verso OpenAI
Verifica:
- 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 una corretta installazione e configurazione, il modulo fornisce a Magento 2 un livello dati pronto per l'AI:
- locale,
- multilingua,
- sincronizzabile con
OpenAI, - pronto per la pubblicazione tramite
llms.txt e feed NDJSON, - estensibile per ulteriori integrazioni e moduli AI.
