> ## Documentation Index > Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Integrazione AI > Configura la chat AI, i suggerimenti per gli errori LaTeX, l'accesso degli utenti, le quote e i servizi di ricerca facoltativi. > [!NOTE] > > Questa funzionalità è fornita da [ayaka-notes/ayakaleaf-pro](https://github.com/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. ![](https://mintcdn.com/ayakaleaf-pro/UZ_4Jfz7cU6MnXtE/images/on-premises/image-49.png?fit=max\&auto=format\&n=UZ_4Jfz7cU6MnXtE\&q=85\&s=609d6a28104dfb16264790c00123eeb4) ### 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: ```dotenv theme={null} 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. > [!NOTE] > > 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](https://github.com/router-for-me/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: ```sh theme={null} 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: ```dotenv theme={null} 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. ![](https://mintcdn.com/ayakaleaf-pro/x9kfDjtWlyyhG_mR/images/on-premises/img-2f5a5399.png?fit=max\&auto=format\&n=x9kfDjtWlyyhG_mR\&q=85\&s=3c52c12aa1551cda22f218ec2dfda63b) 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: ```dotenv theme={null} 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](https://ayakaleaf-pro.mintlify.site/it/on-premises/configuration/overleaf-toolkit/integrations/mcp-server.md). 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](https://ayakaleaf-pro.mintlify.site/it/on-premises/configuration/overleaf-toolkit/external-url.md). 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 > [accordion] 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. > [accordion] 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: > > ```sh theme={null} > 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. > [accordion] 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.