Intégration de l'IA

Configurez le chat IA, les suggestions de correction d’erreurs LaTeX, l’accès des utilisateurs, les quotas et les services de recherche facultatifs.

Cette fonctionnalité est fournie par ayaka-notes/ayakaleaf-pro et est disponible à partir de la v6.3.0. N’hésitez pas à nous faire part de vos retours si vous rencontrez des problèmes.

​

Assistant IA et assistant d’erreurs LaTeX

Ayakaleaf Pro intègre l’IA à l’éditeur de 2 manières.

• L’assistant IA peut utiliser les documents de votre projet et la sélection en cours comme contexte pour répondre à vos questions et vous proposer des modifications à examiner.
• L’assistant d’erreurs propose une correction ciblée lorsque vous sélectionnez une erreur de compilation LaTeX.

​

Configuration du Toolkit

Ajoutez ce qui suit au fichier config/variables.env de votre déploiement Toolkit, en remplaçant l’URL, la clé et le modèle d’exemple par les valeurs fournies par votre fournisseur :

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

Conservez les vraies clés d’API dans le fichier d’environnement de votre déploiement, hors du contrôle de version. Les valeurs ci-dessus sont des exemples, et non des identifiants fonctionnels.

La qualité des suggestions de l’IA dépend du modèle choisi. Si vous disposez déjà d’un abonnement Codex ou ChatGPT, vous pouvez le connecter via le point de terminaison compatible OpenAI de CLIProxyAPI.

AI_BASE_URL est l’URL de base de l’API compatible OpenAI, incluant le préfixe de version du fournisseur si nécessaire. N’ajoutez pas /chat/completions, car nous l’ajoutons en interne. La passerelle et le modèle doivent prendre en charge les chat completions en streaming et les outils de type fonction. Les deux fonctionnalités envoient le contexte du document à cette passerelle ; le chat peut également envoyer les images et les fichiers PDF téléversés lorsqu’un modèle qui les accepte est utilisé.

Le Toolkit transmet config/variables.env au conteneur de l’application. Conservez les noms de variables indiqués ici ; n’ajoutez pas de préfixe OVERLEAF_. Depuis le répertoire du Toolkit, recréez le conteneur de l’application après avoir modifié ces variables :

bin/up -d

​

Paramètres de la passerelle

Variable	Valeur par défaut	Rôle
AI_ENABLED	false	Définissez exactement true pour activer le chat et les suggestions de correction pour l’instance. Si la variable n’est pas définie ou a une autre valeur, ils restent désactivés. Une configuration de passerelle fonctionnelle est également requise.
AI_BASE_URL	Aucune ; requise	URL de base de l’API compatible OpenAI.
AI_API_KEY	Aucune ; requise	Clé d’API de cette passerelle, utilisée par le serveur.
AI_MODEL	Aucune ; requise	Modèle de texte utilisé par la configuration de chat par défaut et par les suggestions de correction d’erreurs LaTeX.
AI_IMAGE_MODEL	Non définie	Modèle facultatif capable de traiter les images, sur la même passerelle et avec la même clé d’API.
AI_PDF_MODEL	Non définie	Modèle facultatif sur la même passerelle pour les chats contenant des fichiers PDF, avec la même clé d’API. À partir de la v6.4.0.
AI_MAX_STEPS	20	Nombre maximal d’appels d’outils par message utilisateur dans le chat IA, continuations automatiques comprises. Utilisez un entier positif.
AI_PROXY_URL	Non définie	URL facultative d’un proxy HTTP pour les appels à la passerelle IA. Elle ne configure pas les clients de recherche web ou de documentation.
AI_TOKEN_QUOTA	0	Limite de jetons par utilisateur et par période, partagée entre le chat et les suggestions de correction. Non définie ou 0 signifie illimité ; utilisez un entier positif pour fixer une limite.
AI_TOKEN_QUOTA_PERIOD	month	month est réinitialisé le premier jour du mois à 00:00 UTC ; week est réinitialisé le lundi à 00:00 UTC. Toute autre valeur utilise month.

Pour les téléversements d’images, définissez AI_IMAGE_MODEL sur un modèle qui accepte les images en entrée et prend en charge les outils utilisés par le chat. Toute requête de chat dont l’historique contient une image jointe utilise ce modèle, y compris les messages ultérieurs de cette conversation. Sans ce paramètre, les requêtes contenant des images utilisent le modèle de chat habituel, qui doit alors lui-même prendre en charge les images. Les suggestions de correction d’erreurs LaTeX continuent d’utiliser AI_MODEL.

Les pièces jointes PDF sont disponibles à partir de la v6.4.0. Les utilisateurs peuvent joindre des fichiers PDF jusqu’à 2 Mo, comme pour les images. Le chat envoie chaque fichier PDF tel quel, sous forme de partie file de Chat Completions ; la passerelle et le modèle doivent donc accepter les PDF en entrée : les modèles de vision d’OpenAI les acceptent, tandis que de nombreuses passerelles auto-hébergées, comme vLLM, acceptent les images mais refusent les fichiers PDF. Définissez AI_PDF_MODEL sur un modèle capable de lire les fichiers PDF ; tout chat dont l’historique contient un fichier PDF l’utilise, y compris les messages ultérieurs et les éventuelles images de cette conversation : il doit donc également accepter les images. Sans ce paramètre, les chats contenant des PDF utilisent AI_MODEL. Lorsque le modèle refuse un fichier PDF, le chat invite l’utilisateur à demander à l’administrateur de définir AI_PDF_MODEL.

Par exemple, pour activer un modèle d’images et une allocation IA hebdomadaire :

AI_IMAGE_MODEL=YOUR_IMAGE_CAPABLE_MODEL_ID
AI_TOKEN_QUOTA=100000
AI_TOKEN_QUOTA_PERIOD=week

​

Accès des utilisateurs et consentement

La disponibilité au niveau de l’instance et les permissions des utilisateurs sont distinctes. AI_ENABLED et la configuration de la passerelle contrôlent la disponibilité au niveau de l’instance. Un utilisateur connecté doit en outre satisfaire à la vérification de compte existante : aiFeatures.enabled ne doit pas valoir false. Ce champ de base de données existant contrôle à la fois le chat et les suggestions de correction d’erreurs LaTeX. Lorsqu’il n’est pas défini, les fonctionnalités IA sont activées pour l’utilisateur.

AI_TOKEN_QUOTA est une limite appliquée de manière identique à chaque utilisateur autorisé ; le module actuel ne permet pas de définir une limite numérique individuelle par compte.

Dans la liste des utilisateurs de l’administration, sélectionnez un utilisateur et ouvrez Update account info → AI features. Enable AI features met à jour aiFeatures.enabled lors de l’enregistrement des modifications du compte. Le serveur vérifie les permissions actuelles à chaque nouvelle requête IA, y compris celles provenant d’un éditeur déjà ouvert. Un utilisateur sans permission voit toujours l’assistant IA dans l’éditeur, mais ne peut pas envoyer de messages.

​

Consommation et réinitialisation

L’onglet AI features de l’administration affiche sur une même ligne la consommation (Usage), la limite (Limit) et le bouton de réinitialisation (Reset) pour la période en cours. La consommation est lue à l’ouverture de l’onglet ; elle n’est pas actualisée en continu. Rouvrez l’onglet une fois un chat ou une suggestion de correction terminé pour voir le décompte le plus récent. La réinitialisation prend effet immédiatement et efface uniquement le compteur de la période en cours de cet utilisateur, puis recharge la consommation affichée. Il n’est pas nécessaire d’enregistrer le reste du formulaire du compte.

La consommation du chat et des suggestions de correction partage un même compteur Redis, mis à jour à partir du nombre total de jetons indiqué par le fournisseur du modèle une fois la requête terminée. Ce total inclut les jetons d’entrée et de sortie de toutes les étapes du modèle. L’entrée peut comprendre l’historique de la conversation, le contexte du document et les résultats des outils ; une question de suivi peut donc consommer plus de jetons que le nouveau message seul. La consommation est enregistrée même lorsque la limite est Unlimited. Les requêtes sans total de jetons indiqué n’incrémentent pas le compteur ; le module ne peut pas reconstituer une consommation passée non enregistrée.

Les vérifications de quota ont lieu avant le streaming. Une requête, ou plusieurs requêtes simultanées, peuvent dépasser l’allocation restante avant que les requêtes suivantes ne soient bloquées. Il s’agit donc d’une allocation de consommation plutôt que d’un plafond de dépenses strict auprès du fournisseur. Si la lecture du quota échoue, la requête est autorisée et l’échec est journalisé.

Les deux fonctionnalités utilisent AI_TOKEN_QUOTA ; les suggestions de correction n’ont pas de limite distincte en nombre de requêtes. La réinitialisation du compteur ne modifie ni les permissions, ni le consentement, ni la limite configurée, ni la facturation propre au fournisseur. Les compteurs utilisent des clés de période en UTC et expirent au bout de 40 jours ; conserver les données Redis permet de préserver la consommation en cours lors des redémarrages de l’application.

​

Services de recherche facultatifs

La recherche web utilise une API compatible Tavily. Elle est disponible dès qu’une clé d’API de recherche est configurée. Ces paramètres sont indépendants de la passerelle IA :

Variable	Valeur par défaut	Rôle
TAVILY_API_KEY	Non définie	Clé d’API de recherche. Prioritaire sur WEB_SEARCH_API_KEY.
WEB_SEARCH_API_KEY	Non définie	Autre nom possible pour la clé d’API de recherche.
WEB_SEARCH_URL	https://api.tavily.com/search	Point de terminaison de recherche ; les points de terminaison personnalisés doivent accepter le format de requête et de réponse de Tavily.
WEB_SEARCH_MAX_RESULTS	5	Nombre de résultats demandés par recherche ; utilisez un entier positif pris en charge par le service.
WEB_SEARCH_DEPTH	basic	Profondeur de recherche, généralement basic ou advanced.
WEB_SEARCH_PROVIDER	tavily	L’implémentation actuelle ne prend en charge que le protocole compatible Tavily ; modifier cette valeur ne sélectionne pas un autre adaptateur.
DOCS_MCP_URL	https://docs.overleaf.com/~gitbook/mcp	Point de terminaison de recherche dans la documentation. Définissez une chaîne vide pour désactiver la recherche dans la documentation.

Par exemple :

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 recherche dans la documentation appelle l’outil searchDocumentation du point de terminaison GitBook MCP configuré et accepte les réponses JSON ou SSE. Il s’agit d’un client MCP destiné à la recherche dans la documentation. Pour permettre à des clients d’IA extérieurs à Ayakaleaf de travailler sur un projet, consultez Serveur MCP.

La lecture de pages web est disponible à partir de la v6.4.0. Le chat peut lire une page à partir de son URL, par exemple un lien fourni par l’utilisateur ou un résultat de recherche. Il récupère la page via le proxy d’URL liées, le même service que celui qui récupère les fichiers depuis des URL externes ; les restrictions réseau décrites dans URL externe s’y appliquent donc également. Aucun autre paramètre n’est nécessaire.

Les requêtes de recherche sont envoyées au service de recherche configuré. Les résultats peuvent ensuite être inclus dans les requêtes envoyées à la passerelle IA. Le menu Tools du chat permet aux utilisateurs d’activer ou de désactiver Web et Documentation pour leurs requêtes ; un outil doit également être configuré sur le serveur pour être disponible pour le modèle.

​

Questions/réponses

L'assistant IA n'apparaît pas dans l'éditeur

Réponse : L’assistant IA n’apparaît dans la barre latérale gauche de l’éditeur que lorsque AI_ENABLED=true et que AI_BASE_URL, AI_API_KEY et AI_MODEL sont tous définis. Si l’un d’eux manque, l’assistant IA est masqué pour tous les utilisateurs.

Après avoir modifié config/variables.env, recréez le conteneur avec bin/up -d. Actualiser simplement le navigateur n’applique pas les nouvelles variables. Le commutateur Enable AI features du panneau d’administration n’affiche ni ne masque l’assistant IA ; il détermine seulement si l’utilisateur peut envoyer des messages.

J'envoie un message, mais l'assistant IA ne répond pas

Réponse : Vérifiez d’abord que l’utilisateur a accepté la carte de consentement IA affichée dans l’assistant IA. Aucun message ne peut être envoyé avant cela.

Recherchez ensuite des erreurs dans le journal du service web :

bin/logs web

Message du journal	Signification
workbench AI chat requested but no AI gateway is configured	L’une des variables AI_ENABLED, AI_BASE_URL, AI_API_KEY ou AI_MODEL manque dans le conteneur en cours d’exécution. Recréez-le avec bin/up -d.
workbench chat stream error	La passerelle a renvoyé une erreur. L’utilisateur voit « The AI service returned an error ». L’erreur journalisée indique le code d’état et le message de la passerelle.
workbench chat failed	La requête a échoué avant ou pendant le streaming, par exemple parce que la passerelle est injoignable.

Si le tableau de bord de votre fournisseur n’affiche aucune consommation, la requête n’a pas atteint le fournisseur. Causes fréquentes :

• AI_BASE_URL est incorrecte, par exemple un /v1 manquant ou en trop, ou /chat/completions ajouté à la fin.
• Le serveur ne peut pas joindre la passerelle. Si le trafic sortant doit passer par un proxy, définissez AI_PROXY_URL.
• AI_MODEL n’est pas un identifiant de modèle connu de la passerelle.

Si le fournisseur affiche des requêtes mais que le chat échoue toujours, vérifiez que le modèle prend en charge les chat completions en streaming et les outils de type fonction.

L'historique du chat est-il conservé ?

Réponse : Non. Un chat n’est conservé que dans l’onglet de navigateur ouvert. Actualiser ou fermer la page l’efface, et Start new chat remplace le chat en cours. Il n’existe pas de liste des chats précédents, et chaque projet affiche un seul chat à la fois.