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 caricate quando si usa un modello in grado di gestire immagini.

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_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.

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 i controlli esistenti sull’account:

• aiFeatures.enabled non deve essere false. Questo campo esistente del database controlla sia la chat sia i suggerimenti per gli errori LaTeX.
• Il valore effettivo di features.aiUsageQuota dell’utente deve corrispondere al livello illimitato configurato (unlimited per impostazione predefinita), oppure deve essere abilitato il permesso legacy esistente features.aiErrorAssistant. Le funzionalità effettive includono le eventuali sostituzioni delle funzionalità applicate all’account.

Selezionare soltanto la casella di controllo non modifica il piano dell’utente. Il campo aiUsageQuota è un livello di permesso, non una quota numerica di token. AI_TOKEN_QUOTA è un limite separato 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. Dopo una modifica dei permessi, aggiorna l’editor per aggiornarne i controlli visibili.

​

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; questi moduli non espongono i file di progetto come server MCP né forniscono un registro di server MCP di uso generale.

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.