Kowal AI Product Feed - installazione e configurazione
Scopo del documento
Questo documento descrive il processo completo di installazione, avvio e configurazione del modulo Kowal_AiProductFeed in Magento 2. È stato preparato per consentire il passaggio dall implementazione tecnica alla prima esportazione funzionante e alla pubblicazione di llms.txt.
Ambito funzionale del modulo
Il modulo consente di:
- esportare i contenuti del negozio 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 del negozio.
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.
Requisiti preliminari
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 abbia una
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, cioè l indirizzo e-mail del cliente e il token di licenza, ti saranno inviati via e-mail dopo l acquisto. Sono disponibili anche 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 principale 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:compile
bin/magento cache:flush
In ambiente di sviluppo di solito è sufficiente:
bin/magento cache:flush
Se davanti a Magento opera uno strato cache aggiuntivo, 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 il negozio opera in più lingue.
Raccomandazione:
- uno
Store View = una lingua, - uno
Store View = un Vector Store ID, - uno
Store View = uno strato 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 su quegli Store View che devono generare dati AI
OpenAI API Key
Chiave API globale utilizzata per la comunicazione con OpenAI.
Richiesta se:
- vuoi sincronizzare file con
OpenAI Vector Store
Non richiesta se:
- vuoi usare solo esportazioni locali,
- vuoi usare 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 esportazione.
Valore predefinito:
var/ai-feeds
Raccomandazione:
- lasciare la directory in
var/, - non esporre questa directory direttamente tramite 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 negozio i cui contenuti possono essere disponibili pubblicamente.
Importante:
/llms.txt non è un indice globale di tutti i negozi- ogni versione linguistica del negozio restituisce il proprio manifest
/llms.txt da solo non richiede l esistenza di 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à dello strato 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, 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à preparata.
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 controlli successivi 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 usi 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 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
Esportazione reale
Quindi avvia la sincronizzazione effettiva:
bin/magento kowal:ai-export:sync --channel=product --store=1
Controllo 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 il negozio 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 feed/ai-feed/{storeCode}/index.json mostra solo i feed esistenti per il negozio indicato/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 in pratica disattivano la cache, - per
index.json una breve durata della cache e una revalidazione forzata.
Verifica HTML:
- nel sorgente della pagina dovrebbe comparire un link nell
head a /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=product
bin/magento kowal:ai-export:sync --channel=product --store=1
bin/magento kowal:ai-export:sync --channel=product --store=1 --content-type=product.core --identifier=example-sku --dry-run
bin/magento kowal:ai-export:sync --channel=blog --store=1 --source=amasty_blog
bin/magento kowal:ai-export:sync --channel=category --store=1
bin/magento kowal:ai-export:sync --channel=cms_page --store=1
Stato
bin/magento kowal:ai-export:status
bin/magento kowal:ai-export:status --store=1
bin/magento kowal:ai-export:status --channel=blog --store=1
bin/magento kowal:ai-export:status --channel=blog --store=1 --source=amasty_blog
Import delle fonti del 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:generate
bin/magento kowal:ai-feed:generate --store=1 --content-type=product.core --sku=example-sku --dry-run
Cron
Il modulo utilizza tre attività cron:
kowal_ai_blog_source_importkowal_ai_feed_generatekowal_ai_feed_cleanup
Assicurati che il cron Magento funzioni correttamente nell ambiente.
Problemi più comuni
/llms.txt restituisce 404
Verifica:
- che sia implementata 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 static content standard secondo il processo del progetto,
- che tu abbia svuotato la cache,
- che tu abbia eseguito il purge dello strato CDN / reverse proxy,
- che
Enable Public AI Feed sia abilitato.
Se https://twoja-domena.pl/llms.txt?v=123 funziona e 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 esportazione non è ancora stata eseguita,
- mancano contenuti attivi per il canale indicato,
- i flag di sincronizzazione appropriati sono disattivati.
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 della
OpenAI API Key, - la correttezza del
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 uno strato dati pronto per l AI:
- locale,
- multilingue,
- sincronizzabile con
OpenAI, - pronto per la pubblicazione tramite
llms.txt e feed NDJSON, - estensibile per ulteriori integrazioni e moduli AI.
