Integrazione AI

Configura la chat AI, i suggerimenti per gli errori LaTeX, l’accesso degli utenti, le quote e i servizi di ricerca facoltativi.

Questa funzionalità è fornita da ayaka-notes/ayakaleaf-pro ed è disponibile a partire dalla v6.3.0. Se riscontri problemi, il tuo feedback è benvenuto.

​

Assistente AI e assistente per gli errori LaTeX

Ayakaleaf Pro porta le funzionalità AI nell’editor in 2 modi.

• L’assistente AI può usare i documenti del progetto e la selezione corrente come contesto per rispondere alle domande e proporti modifiche da rivedere.
• L’assistente per gli errori propone una correzione mirata quando selezioni un errore di compilazione LaTeX.

​

Configurazione del Toolkit

Aggiungi quanto segue a config/variables.env nella tua installazione del Toolkit, sostituendo l’URL, la chiave e il modello di esempio con i valori del tuo provider:

AI_ENABLED=true
AI_BASE_URL=https://ai-gateway.example.com/v1
AI_API_KEY=REPLACE_WITH_YOUR_GATEWAY_API_KEY
AI_MODEL=YOUR_TEXT_MODEL_ID

Conserva le chiavi API reali nel file d’ambiente della tua installazione e tienile fuori dal controllo di versione. I valori sopra sono segnaposto, non credenziali funzionanti.

La qualità dei suggerimenti AI dipende dal modello scelto. Se hai già un abbonamento Codex o ChatGPT, puoi collegarlo tramite l’endpoint compatibile con OpenAI di CLIProxyAPI.

AI_BASE_URL è l’URL di base dell’API compatibile con OpenAI, incluso il prefisso di versione del provider ove richiesto. Non aggiungere /chat/completions, poiché viene aggiunto internamente. Il gateway e il modello devono supportare le chat completion in streaming e i function tool. Entrambe le funzionalità inviano il contesto del documento a questo gateway; la chat può inviare anche le immagini e i file PDF caricati quando si usa un modello che li accetta.

Il Toolkit inoltra config/variables.env al container dell’applicazione. Mantieni i nomi delle variabili indicati qui; non aggiungere il prefisso OVERLEAF_. Dalla directory del Toolkit, ricrea il container dell’applicazione dopo aver modificato queste variabili:

bin/up -d

​

Impostazioni del gateway

Variabile	Predefinito	Scopo
AI_ENABLED	false	Imposta esattamente true per abilitare la chat e i suggerimenti per gli errori sull’istanza. Se non impostata o con qualsiasi altro valore, restano disabilitati. È inoltre necessaria una configurazione del gateway funzionante.
AI_BASE_URL	Nessuno; obbligatorio	URL di base dell’API compatibile con OpenAI.
AI_API_KEY	Nessuno; obbligatorio	Chiave API per quel gateway, usata dal server.
AI_MODEL	Nessuno; obbligatorio	Modello di testo usato dalla configurazione predefinita della chat e dai suggerimenti per gli errori LaTeX.
AI_IMAGE_MODEL	Non impostato	Modello facoltativo in grado di gestire immagini sullo stesso gateway, con la stessa chiave API.
AI_PDF_MODEL	Non impostato	Modello facoltativo sullo stesso gateway per le chat con file PDF, con la stessa chiave API. Da v6.4.0.
AI_MAX_STEPS	20	Numero massimo di chiamate agli strumenti per messaggio utente nella chat AI, incluse le continuazioni automatiche. Usa un intero positivo.
AI_PROXY_URL	Non impostato	URL facoltativo di un proxy HTTP per le chiamate al gateway AI. Non configura i client di ricerca web o della documentazione.
AI_TOKEN_QUOTA	0	Limite di token per utente, condiviso tra chat e suggerimenti per gli errori in ogni periodo. Non impostato o 0 significa illimitato; usa un intero positivo per impostare un limite.
AI_TOKEN_QUOTA_PERIOD	month	month si azzera il primo giorno del mese alle 00:00 UTC; week si azzera il lunedì alle 00:00 UTC. Gli altri valori usano month.

Per il caricamento di immagini, imposta AI_IMAGE_MODEL su un modello che accetti input di immagini e supporti gli strumenti usati dalla chat. Qualsiasi richiesta di chat la cui cronologia contenga un’immagine allegata usa questo modello, compresi i messaggi successivi di quella conversazione. Senza questa impostazione, le richieste con immagini usano il normale modello di chat, che deve quindi supportare le immagini. I suggerimenti per gli errori LaTeX continuano a usare AI_MODEL.

Gli allegati PDF sono disponibili a partire dalla v6.4.0. Gli utenti possono allegare file PDF fino a 2 MB, come le immagini. La chat invia ogni file PDF così com’è, come parte file di Chat Completions, quindi il gateway e il modello devono accettare input PDF: i modelli vision di OpenAI lo fanno, mentre molti gateway self-hosted, come vLLM, accettano immagini ma rifiutano i file PDF. Imposta AI_PDF_MODEL su un modello in grado di leggere file PDF; qualsiasi chat la cui cronologia contenga un file PDF lo usa, compresi i messaggi successivi e le eventuali immagini di quella conversazione, quindi dovrebbe accettare anche le immagini. Senza questa impostazione, le chat con PDF usano AI_MODEL. Quando il modello rifiuta un file PDF, la chat invita l’utente a chiedere all’amministratore di impostare AI_PDF_MODEL.

Ad esempio, per abilitare un modello per immagini e una quota AI settimanale:

AI_IMAGE_MODEL=YOUR_IMAGE_CAPABLE_MODEL_ID
AI_TOKEN_QUOTA=100000
AI_TOKEN_QUOTA_PERIOD=week

​

Accesso degli utenti e consenso

La disponibilità sull’istanza e i permessi degli utenti sono separati. AI_ENABLED e la configurazione del gateway controllano la disponibilità sull’istanza. Un utente che ha effettuato l’accesso deve inoltre superare il controllo esistente sull’account: aiFeatures.enabled non deve essere false. Questo campo esistente del database controlla sia la chat sia i suggerimenti per gli errori LaTeX. Se non è impostato, le funzionalità AI sono abilitate per l’utente.

AI_TOKEN_QUOTA è un limite applicato in modo uguale a ogni utente autorizzato; il modulo attuale non prevede un limite numerico individuale per account.

Nell’elenco utenti dell’amministrazione, seleziona un utente e apri Update account info → AI features. Enable AI features aggiorna aiFeatures.enabled quando le modifiche all’account vengono salvate. Il server verifica i permessi correnti sulle nuove richieste AI, comprese quelle provenienti da un editor già aperto. Un utente senza permesso vede comunque l’assistente AI nell’editor, ma non può inviare messaggi.

​

Utilizzo e azzeramento

La scheda AI features dell’amministrazione mostra su una sola riga l’Usage del periodo corrente, il Limit e il pulsante Reset. L’utilizzo viene letto all’apertura della scheda e non viene aggiornato in modo continuo. Riapri la scheda al termine di una chat o di un suggerimento per gli errori per vedere il conteggio più recente. L’azzeramento ha effetto immediato e cancella solo il contatore del periodo corrente di quell’utente, quindi ricarica l’utilizzo visualizzato. Non è necessario salvare il resto del modulo dell’account.

L’utilizzo della chat e dei suggerimenti per gli errori condivide un unico contatore Redis, aggiornato in base ai token totali riportati dal provider del modello al termine di una richiesta. Sono inclusi i token di input e di output in tutti i passaggi del modello. L’input può includere la cronologia della conversazione, il contesto del documento e i risultati degli strumenti, per cui un messaggio successivo può consumare più token del solo nuovo messaggio. L’utilizzo viene registrato anche quando il limite è Unlimited. Le richieste senza un totale di token riportato non incrementano il contatore; il modulo non può ricostruire l’utilizzo storico non registrato.

I controlli sulla quota avvengono prima dello streaming. Una richiesta, o più richieste concorrenti, possono superare la quota residua prima che le richieste successive vengano bloccate. Si tratta di una quota di utilizzo, non di un tetto di spesa rigido presso il provider. Se la lettura della quota non riesce, la richiesta viene consentita e l’errore viene registrato nei log.

Entrambe le funzionalità usano AI_TOKEN_QUOTA; i suggerimenti per gli errori non hanno un limite separato sul numero di richieste. L’azzeramento del contatore non modifica i permessi, il consenso, il limite configurato né i registri di fatturazione del provider. I contatori usano chiavi di periodo in UTC e scadono dopo 40 giorni; conservando i dati Redis, l’utilizzo corrente viene mantenuto anche dopo il riavvio dell’applicazione.

​

Servizi di ricerca facoltativi

La ricerca web usa un’API compatibile con Tavily. È disponibile quando è configurata una chiave API di ricerca. Queste impostazioni sono indipendenti dal gateway AI:

Variabile	Predefinito	Scopo
TAVILY_API_KEY	Non impostato	Chiave API di ricerca. Ha la precedenza su WEB_SEARCH_API_KEY.
WEB_SEARCH_API_KEY	Non impostato	Nome alternativo per la chiave API di ricerca.
WEB_SEARCH_URL	https://api.tavily.com/search	Endpoint di ricerca; gli endpoint personalizzati devono accettare il formato di richiesta e risposta di Tavily.
WEB_SEARCH_MAX_RESULTS	5	Risultati richiesti per ogni ricerca; usa un intero positivo supportato dal servizio.
WEB_SEARCH_DEPTH	basic	Profondità di ricerca, normalmente basic o advanced.
WEB_SEARCH_PROVIDER	tavily	L’implementazione attuale supporta solo il protocollo compatibile con Tavily; modificare questo valore non seleziona un altro adattatore.
DOCS_MCP_URL	https://docs.overleaf.com/~gitbook/mcp	Endpoint di ricerca nella documentazione. Impostalo su una stringa vuota per disabilitare la ricerca nella documentazione.

Ad esempio:

TAVILY_API_KEY=REPLACE_WITH_YOUR_SEARCH_API_KEY
WEB_SEARCH_MAX_RESULTS=5
WEB_SEARCH_DEPTH=basic
DOCS_MCP_URL=https://docs.overleaf.com/~gitbook/mcp

La ricerca nella documentazione richiama lo strumento searchDocumentation dell’endpoint GitBook MCP configurato e accetta risposte JSON o SSE. Si tratta di un client MCP per la ricerca nella documentazione. Per consentire a client AI esterni ad Ayakaleaf di lavorare su un progetto, vedi Server MCP.

La lettura di pagine web è disponibile a partire dalla v6.4.0. La chat può leggere una pagina tramite il suo URL, ad esempio un link fornito dall’utente o un risultato di ricerca. Recupera la pagina tramite il proxy degli URL collegati, lo stesso servizio che recupera i file da URL esterni, per cui si applicano anche qui le restrizioni di rete descritte in URL esterni. Non è necessaria alcuna ulteriore impostazione.

Le query di ricerca vengono inviate al servizio di ricerca configurato. I risultati della ricerca possono poi essere inclusi nelle richieste al gateway AI. Il menu Tools della chat consente agli utenti di abilitare o disabilitare Web e Documentation per le proprie richieste; affinché uno strumento sia disponibile per il modello, deve essere configurato anche sul server.

​

Domande e risposte

L'assistente AI non compare nell'editor

Risposta: L’assistente AI compare nella barra laterale sinistra dell’editor solo quando AI_ENABLED=true e AI_BASE_URL, AI_API_KEY e AI_MODEL sono tutti impostati. Se uno di essi manca, l’assistente AI è nascosto per tutti gli utenti.

Dopo aver modificato config/variables.env, ricrea il container con bin/up -d. Il solo aggiornamento del browser non applica le nuove variabili. L’interruttore Enable AI features nel pannello di amministrazione non mostra né nasconde l’assistente AI; stabilisce solo se l’utente può inviare messaggi.

Invio un messaggio, ma l'assistente AI non risponde

Risposta: Per prima cosa, verifica che l’utente abbia accettato la scheda di consenso AI mostrata nell’assistente AI. Prima di allora non è possibile inviare messaggi.

Quindi cerca eventuali errori nel log del servizio web:

bin/logs web

Messaggio di log	Significato
workbench AI chat requested but no AI gateway is configured	Nel container in esecuzione manca una tra AI_ENABLED, AI_BASE_URL, AI_API_KEY o AI_MODEL. Ricrealo con bin/up -d.
workbench chat stream error	Il gateway ha restituito un errore. L’utente vede “The AI service returned an error”. L’errore registrato mostra il codice di stato e il messaggio del gateway.
workbench chat failed	La richiesta non è riuscita prima o durante lo streaming, ad esempio perché il gateway non è raggiungibile.

Se la dashboard del tuo provider non mostra alcun utilizzo, la richiesta non ha raggiunto il provider. Le cause più comuni sono:

• AI_BASE_URL è errato, ad esempio manca o è di troppo un /v1, oppure vi è stato aggiunto /chat/completions.
• Il server non riesce a raggiungere il gateway. Se il traffico in uscita deve passare da un proxy, imposta AI_PROXY_URL.
• AI_MODEL non è un ID di modello noto al gateway.

Se il provider mostra le richieste ma la chat continua a non funzionare, verifica che il modello supporti le chat completion in streaming e i function tool.

La cronologia della chat viene conservata?

Risposta: No. Una chat viene conservata solo nella scheda del browser aperta. Aggiornando o chiudendo la pagina viene cancellata, e Start new chat sostituisce la chat corrente. Non esiste un elenco delle chat precedenti e ogni progetto mostra una chat alla volta.