Note tecniche su AI Assistant

Questo documento descrive la funzionalità opzionale AI Assistant, che genera descrizioni dei veicoli orientate alla SEO, testi alternativi per le immagini, metadati SEO ed evidenze degli equipaggiamenti a partire dai dati dei veicoli importati.

Le funzionalità di intelligenza artificiale utilizzano la configurazione gestita di Google Gemini in ADP Car Market Hub. Non è richiesta alcuna selezione del provider, del modello o l'inserimento di chiavi API nel backend di WordPress. L'abilitazione dell'IA specifica per il cliente viene completata da AD Promotion dopo l'installazione.

Quando utilizzare questo documento

Leggi questo documento se hai bisogno di:

• Decidere se abilitare l'AI Assistant per il tuo sito.
• Capire come la coda in background e la generazione per ciascuna importazione interagiscono con WP-Cron.
• Verificare il modello di sicurezza relativo alla configurazione gestita di Gemini e ai trigger di amministrazione.

Panoramica

L'AI Assistant è implementato in AS24CI\Ai_Assistant. Quando abilitato, può:

• Generare automaticamente una descrizione come parte del flusso di importazione (collegato a as24ci_vehicle_imported).
• Elaborare una coda di generazioni in sospeso in background tramite WP-Cron (as24ci_process_ai_queue).
• Consentire ai redattori di generare o rigenerare manualmente una descrizione dalla schermata di modifica del veicolo, sia tramite un'azione AJAX che tramite un'azione admin-post singola.

La funzionalità è di tipo opt-in: non esegue alcuna operazione finché as24ci_ai_assistant_enabled non è impostato su '1' e la configurazione gestita di Gemini non è attiva. Il callback del cron viene registrato in modo incondizionato, così che eventuali processi già pianificati da una configurazione precedente possano comunque essere completati.

Configurazione gestita dell'IA

Il plugin utilizza una singola configurazione gestita dell'IA esposta da AS24CI\Ai_Config. Le costanti relative alla chiave e al modello Gemini precedentemente hard-coded in Ai_Config sono state rimosse; la classe è ora una sottile facciata sopra AS24CI\Ai_Credential_Manager:

• Ai_Config::get_effective_model() — restituisce il modello Gemini fisso per il runtime, sempre Ai_Credential_Manager::PRIMARY_MODEL (attualmente gemini-3.5-flash). Qualsiasi valore di modello fornito dall'API è solo un metadato e non controlla mai la selezione a runtime.
• Ai_Config::get_managed_gemini_api_key() — restituisce la chiave Gemini del cliente estratta dall'involucro crittografato delle credenziali sincronizzato server-to-server dalla piattaforma API. Restituisce una stringa vuota quando l'IA non può essere eseguita (nessuna abilitazione della licenza ai_allowed o nessuna credenziale memorizzata). Non viene mai esposta nell'interfaccia utente di amministrazione, nella diagnostica, nei log o in qualsiasi superficie visibile all'utente.
• Ai_Config::is_configured() — restituisce true solo quando è disponibile una chiave Gemini gestita e utilizzabile.

I metodi helper legacy di Ai_Assistant (get_api_key_for_provider(), get_model(), ecc.) sono mantenuti per compatibilità con le versioni precedenti e fanno riferimento ai valori gestiti di Gemini. Non è presente alcuno switch del provider, nessun campo per la chiave API per singolo provider e nessun selettore di modello nel backend di WordPress.

Le lingue di output disponibili (de, en, fr, it), i toni di scrittura (professional, emotional, technical) e le lunghezze target (short, medium, long) sono definiti come costanti di classe in Ai_Assistant.

Coda in background

• Hook del cron: as24ci_process_ai_queue.
• Pianificazione personalizzata: as24ci_every_5_minutes.
• Dimensione del batch per esecuzione: fino a 3 veicoli.
• Tentativi massimi per veicolo: 3.
• Limite dell'estratto: 160 caratteri.

La coda consente al plugin di distribuire la generazione tramite IA tra le importazioni senza bloccare la richiesta frontend che le ha generate.

Istruzioni passo dopo passo

Per abilitare e configurare l'AI Assistant:

1. Apri la scheda di amministrazione AI Assistant.
2. Attiva l'impostazione Abilita AI Assistant (as24ci_ai_assistant_enabled = '1').
3. Scegli una lingua, un tono, una lunghezza target e un prompt personalizzato (opzionale).
4. Decidi se abilitare la Generazione automatica all'importazione (as24ci_ai_assistant_auto_generate).
5. Salva ed esegui un'importazione o avvia una singola generazione dalla schermata di modifica di un veicolo per verificare la connessione.

La configurazione gestita di Gemini è già attiva — non vengono presentati campi per provider, modello o chiavi API nell'interfaccia di amministrazione.

Generazione manuale

Esistono due percorsi amministrativi:

• AJAX (as24ci_generate_ai_assistant) — utilizzato dal meta box nella schermata di modifica del veicolo. Richiede la funzionalità manage_as24_imports e il nonce as24ci_ai_generate.
• Admin-post (as24ci_manual_ai_generate) — gestisce il pulsante manuale singolo Genera. Richiede il nonce specifico per il post as24ci_manual_ai_generate_<post_id> e la funzionalità edit_post per lo specifico veicolo.

Entrambi i flussi chiamano infine la routine gestita di Gemini e salvano il risultato nel post.

Trigger in background dell'amministratore

Il plugin espone l'azione AJAX as24ci_trigger_ai_queue_now che elabora immediatamente un batch della coda dell'IA. È protetta da manage_as24_imports e dal nonce as24ci_trigger_ai_queue_now, e restituisce HTTP 400 se l'AI Assistant è disabilitato.

Riferimento di configurazione

Per l'elenco completo delle opzioni del plugin, consulta Salvataggio di opzioni e impostazioni.

Note operative

• Flusso di dati verso terze parti: quando l'AI Assistant è abilitato, i dati del veicolo e il contesto del prompt lasciano il server di WordPress e vengono inviati all'endpoint gestito di Google Gemini. Esamina il trattamento dei dati applicabile e i termini contrattuali per la configurazione gestita dell'IA prima di abilitare le funzionalità IA in produzione.
• Costi e quote: l'utilizzo dell'IA viene conteggiato a valere sulla configurazione gestita di Gemini fornita da AD Promotion. Il plugin non espone i prezzi per singola chiamata.
• Limiti di frequenza (Rate limits): Gemini applica limiti di richieste e di token indipendentemente dal plugin. Le generazioni non riuscite vengono riprovate fino a 3 volte per veicolo; i veicoli che falliscono costantemente vengono abbandonati per evitare cicli infiniti.
• La generazione automatica si attiva solo sulle importazioni quando sia l'interruttore principale che l'opzione Generazione automatica sono abilitati. La generazione manuale funziona sempre (indipendentemente dalla Generazione automatica) quando l'interruttore principale è attivo.
• Gestione della chiave gestita: la chiave gestita di Gemini viene fornita server-to-server dalla piattaforma API ed è conservata in modo crittografato da Ai_Credential_Manager. Non viene mai scritta in chiaro in wp_options, mostrata nell'interfaccia di amministrazione o stampata nella diagnostica o nei log.
• La disattivazione della funzionalità interrompe le nuove generazioni, ma l'hook del cron registrato rimane attivo in modo che i processi già in coda possano essere completati. Verifica che la coda sia vuota prima di considerare la funzionalità completamente disattivata.

Risoluzione dei problemi

• Nessuna descrizione viene generata all'importazione — verifica che as24ci_ai_assistant_enabled sia impostato su '1', che la Generazione automatica sia attiva e che Ai_Config::is_configured() restituisca true (chiave gestita configurata). Controlla il log del plugin per eventuali risposte di errore da parte di Gemini.
• Il pulsante manuale Genera non fa nulla — controlla la scheda di rete del browser. Un codice 403 indica una funzionalità o un nonce mancante, un codice 400 indica che l'AI Assistant è disabilitato.
• La coda non si svuota mai — WP-Cron richiede traffico regolare sul sito per attivare gli eventi pianificati. Configura un cron job esterno o avvia la coda manualmente tramite l'azione di amministrazione Avvia coda IA ora. Vedi Eventi cron e pianificatore.
• Lo stesso veicolo non riceve mai una descrizione dopo diversi tentativi — il contatore dei tentativi per veicolo ha raggiunto 3. Esamina l'errore Gemini sottostante nel log prima di eseguire un ripristino.

Documenti correlati

• Eventi cron e pianificatore
• Azioni AJAX
• Salvataggio di opzioni e impostazioni
• Sicurezza e funzionalità
• Motore di importazione
• Limitazioni note e rischi aperti