Configuration IA
BeePass integre plusieurs composants d'intelligence artificielle : un assistant conversationnel, un generateur de brouillons pour le support, un analyseur de securite, un assistant d'import et un generateur de rapports. Chacun de ces composants a ses propres reglages (quel modele utiliser, a quel point etre creatif, combien de contexte inclure...). Plutot que de modifier du code a chaque ajustement, cette page centralise tous les parametres dans une interface visuelle.
La page de configuration IA (/backoffice/ai-config) est organisee en 5 onglets couvrant le support RAG, l'assistant conversationnel, les audits de securite, l'import intelligent et les rapports de dependances. Depuis EMAIL v2.8.0+, la page integre egalement un lien vers le Template editor pour l'edition des templates email Brevo.
L'ancienne URL /backoffice/rag-config redirige automatiquement vers /backoffice/ai-config.
Stockage unifie
Tous les reglages IA sont stockes au meme endroit pour simplifier la gestion : la table site_settings sous la cle ai_agents_config (format JSONB, c'est-a-dire un objet JSON flexible stocke dans PostgreSQL). Chaque agent a sa sous-cle : rag, assistant, security_audit, import_mapper, deps_report.
Le systeme est retrocompatible avec l'ancienne cle rag_config : le chargeur verifie d'abord ai_agents_config, puis tente un fallback sur l'ancienne cle pour la migration automatique.
Cache
Pour eviter d'interroger la base de donnees a chaque requete, la configuration est cachee en memoire pendant 5 minutes cote serveur (src/lib/ai-config.ts). Apres une sauvegarde via l'interface admin, le cache est immediatement invalide pour que les changements prennent effet sans attendre. Le cache RAG legacy (rag.ts) delegue desormais a ai-config.ts.
La configuration IA est chargee via ai-config.ts avec un cache memoire de 5 minutes. Le cache est invalide immediatement apres chaque sauvegarde. En cas de migration depuis l'ancienne cle rag_config, les valeurs sont automatiquement fusionnees dans la nouvelle structure.
Onglet 1 : Support RAG
Le RAG (Retrieval-Augmented Generation --- litteralement "generation augmentee par la recherche") est le mecanisme qui permet a l'IA de repondre aux tickets de support en s'appuyant sur votre documentation reelle, plutot que sur ses connaissances generales. C'est la difference entre un collegue qui repond de memoire et un collegue qui consulte le manuel avant de repondre.
Voici comment le flux fonctionne concretement :
- Un utilisateur ouvre un ticket de support
- Le systeme recherche dans la documentation Docusaurus les passages les plus pertinents (via des embeddings --- des representations mathematiques du sens des mots --- generes par Ollama
nomic-embed-text) - Les passages trouves sont envoyes a Claude Haiku avec le contenu du ticket
- Claude genere un brouillon de reponse qui apparait comme commentaire
[ai:BeePass IA]dans le ticket
Cette page permet d'ajuster chaque etape de ce processus sans modifier le code.
Section 1 --- Recherche & Scoring
Ces parametres controlent comment le systeme cherche les passages pertinents dans votre documentation. C'est un equilibre entre trop de resultats (bruit) et pas assez (silence).
Seuil de similarite (similarity_threshold)
| Propriete | Valeur |
|---|---|
| Defaut | 0.55 |
| Plage | 0.00 -- 1.00 |
| Recommandation | 0.50 -- 0.60 |
Ce seuil est la barre minimale de pertinence. Quand le systeme compare la question du ticket avec les passages de documentation, chaque passage recoit un score de similarite (de 0 a 1). Si le meilleur score est au-dessus du seuil, la reponse IA est publiee en tant que brouillon validable. Si en dessous, la reponse indique que la documentation ne contient pas la reponse et recommande une intervention manuelle.
Le modele d'embeddings nomic-embed-text produit des scores dans une bande etroite (0.58-0.70) pour le contenu francais. Un seuil trop eleve (> 0.70) bloquera presque tous les resultats. Un seuil trop bas (< 0.40) laissera passer des resultats non pertinents.
Score minimum chunk (min_chunk_score)
| Propriete | Valeur |
|---|---|
| Defaut | 0.40 |
| Plage | 0.00 -- 1.00 |
| Recommandation | 0.30 -- 0.50 |
Un "chunk" est un morceau de documentation (un paragraphe, une section). Ce parametre filtre les chunks individuels avant de les envoyer a Claude. Meme si un chunk est dans le top-K (les K meilleurs resultats), il sera exclu si son score est inferieur a cette valeur. C'est un filtre de qualite supplementaire.
Nombre de chunks (top_k)
| Propriete | Valeur |
|---|---|
| Defaut | 8 |
| Plage | 1 -- 20 |
| Recommandation | 5 -- 10 |
Nombre maximum de passages de documentation envoyes a Claude pour generer sa reponse. Plus de chunks = plus de contexte, mais aussi plus de tokens consommes (et donc un cout plus eleve). Au-dela de 10, Claude peut etre noye par trop d'information et perdre en precision.
Boost max keywords (max_keyword_boost)
| Propriete | Valeur |
|---|---|
| Defaut | 0.40 |
| Plage | 0.00 -- 1.00 |
| Recommandation | 0.30 -- 0.50 |
En plus de la similarite semantique (le sens global), le systeme accorde un bonus aux passages qui contiennent les mots-cles exacts de la question. Ce parametre plafonne ce bonus. Le systeme utilise un poids IDF (Inverse Document Frequency --- un mot rare dans la documentation recoit un bonus plus fort qu'un mot courant).
Exemple : si l'utilisateur demande "comment fonctionne le BLUP", le mot "BLUP" (rare) recoit un boost eleve, tandis que "comment" et "fonctionne" (courants) recoivent peu ou pas de boost.
Bonus chemin source (source_path_bonus)
| Propriete | Valeur |
|---|---|
| Defaut | 0.15 |
| Plage | 0.00 -- 0.50 |
| Recommandation | 0.10 -- 0.20 |
Bonus ajoute quand un mot-cle de la requete apparait dans le nom du fichier source. C'est le signal de pertinence le plus fort --- un document dont le titre contient le terme recherche a de grandes chances d'etre exactement ce qu'on cherche. Une question sur "BLUP" favorisera les chunks provenant de docs/genetics/blup-overview.md.
Section 2 --- Generation IA
Ces parametres controlent comment la documentation est decoupee et comment Claude genere sa reponse.
Taille des chunks (chunk_size)
| Propriete | Valeur |
|---|---|
| Defaut | 2000 caracteres (~500 tokens) |
| Plage | 500 -- 5000 |
| Recommandation | 1500 -- 2500 |
La documentation est decoupee en morceaux (chunks) pour la recherche. Ce parametre definit la taille de chaque morceau. Des chunks plus grands contiennent plus de contexte mais sont moins precis dans la recherche. Des chunks plus petits sont plus precis mais peuvent couper des idees en plein milieu.
Ce parametre n'affecte que les futures reindexations. Il faut cliquer "Reindexer la documentation" apres modification pour appliquer le changement.
Chevauchement des chunks (chunk_overlap)
| Propriete | Valeur |
|---|---|
| Defaut | 200 caracteres |
| Plage | 0 -- 500 |
| Recommandation | 100 -- 300 |
Quand la documentation est decoupee, les morceaux se chevauchent legerement pour eviter de couper des phrases importantes entre deux chunks. Pensez-y comme des tuiles sur un toit : elles se superposent pour ne laisser aucun trou. Necessite une reindexation pour prendre effet.
Max tokens reponse (max_tokens)
| Propriete | Valeur |
|---|---|
| Defaut | 2048 |
| Plage | 256 -- 4096 |
| Recommandation | 1024 -- 3072 |
Limite le nombre de tokens (unites de texte, environ 1 token = 3/4 d'un mot francais) dans la reponse generee par Claude Haiku. En dessous de 1024, les reponses risquent d'etre tronquees.
Prompt systeme --- Brouillon (system_prompt_draft)
Les instructions donnees a Claude pour generer le premier brouillon de reponse a un nouveau ticket. C'est ici que vous definissez le ton, le format et les regles que l'IA doit suivre. Le placeholder {{language}} est remplace automatiquement par la langue detectee du ticket (French, English, German, Spanish, Italian, Russian).
Prompt systeme --- Suivi (system_prompt_followup)
Instructions donnees a Claude pour repondre aux messages de suivi d'un utilisateur (apres le brouillon initial). Ce prompt inclut l'historique de la conversation (10 derniers messages) pour assurer la continuite --- l'IA se souvient de ce qui a deja ete dit.
Section 3 --- Index & Reindexation
L'index est la "bibliotheque" que le systeme consulte pour trouver les passages pertinents. Il contient tous les morceaux de documentation avec leurs embeddings (representations mathematiques du sens).
| Statistique | Description |
|---|---|
| Chunks indexes | Nombre total de passages dans l'index. Typiquement 200-300 pour la documentation BeePass complete |
| Statut | Badge vert "Index charge" si l'index est en memoire, orange "Index non charge" sinon |
| Derniere indexation | Date et heure de la derniere reindexation. "Jamais indexe" si aucun fichier rag-index.json n'existe |
Bouton "Reindexer la documentation" : relit tous les fichiers .md et .mdx de docs/site/docs/, les decoupe en chunks, genere les embeddings via Ollama (nomic-embed-text), et sauvegarde l'index sur disque. Duree : 30-60 secondes.
- Apres avoir modifie la documentation Docusaurus
- Apres avoir change
chunk_sizeouchunk_overlap - Apres un deploiement avec de nouveaux fichiers docs
Onglet 2 : Assistant IA
Cet onglet controle le comportement de l'Assistant IA, la console de conversation admin. C'est ici que vous definissez quel modele Claude utiliser et a quel point il doit etre creatif ou factuel.
| Parametre | Defaut | Plage | Description |
|---|---|---|---|
| Modele | claude-sonnet-4-20250514 | Selecteur Claude (Sonnet/Haiku/Opus) | Modele utilise pour le raisonnement complexe et tool_use |
| Temperature | 0.3 | 0.0 -- 1.0 (slider) | Controle la creativite des reponses. A 0, l'IA donne toujours la meme reponse a la meme question (deterministe). A 1, les reponses sont plus variees et creatives. Pour un usage admin factuel, une valeur basse (0.2-0.4) est recommandee. |
| Max tokens | 4096 | Champ numerique | Longueur maximale par reponse |
| Tool rounds max | 8 | Champ numerique | Nombre maximum d'iterations tool_use par reponse |
| Timeout boucle | 300 secondes | Champ numerique | Duree maximale avant interruption forcee d'une boucle tool_use |
| Prompt systeme | Template metier apicole | Textarea monospace | Instructions systeme avec placeholder {{adminContext}} (remplace dynamiquement par les stats DB) |
Le loop timeout est un mecanisme de securite critique. Sans cette limite, une sequence d'appels d'outils defaillante pourrait boucler indefiniment et consommer des tokens inutilement. La valeur par defaut (300s) est generalement suffisante. Ne la modifiez que si vous constatez des interruptions prematurees sur des requetes legitimes.
Onglet 3 : Audit Securite
Les outils d'audit de securite (Nuclei, Trivy, ZAP, SSL Labs) produisent des rapports techniques bruts. Ce modele IA analyse ces rapports et produit des resumes comprehensibles pour le Centre de securite.
| Parametre | Defaut | Description |
|---|---|---|
| Modele | claude-sonnet-4-20250514 | Selecteur Claude --- modele pour l'analyse des resultats de scan |
| Temperature | 0.2 | Slider 0.0--1.0 --- plus basse que l'assistant pour des analyses plus factuelles et reproductibles |
| Max tokens | 4096 | Nombre max de tokens pour le rapport d'analyse |
| Timeout outils | 30 secondes | Timeout par outil de scan (les outils Nuclei/Trivy necessitent 120s, ZAP/SSL Labs 90s) |
| Max findings | 50 | Nombre max de findings par audit (dedupliques par fingerprint SHA-256 pour eviter les doublons) |
| Prompt systeme | Prompt d'analyse | Instructions pour l'analyse structuree des resultats de scan |
Les outils Nuclei et Trivy effectuent des analyses exhaustives qui prennent naturellement plus de temps. Ne reduisez pas leurs timeouts en dessous de 90 secondes sous peine d'obtenir des resultats incomplets.
Onglet 4 : Import Mapper
Quand un eleveur importe un fichier CSV ou Excel, les noms de colonnes ne correspondent pas forcement aux champs de la base BeePass. L'Import Mapper utilise un modele IA local (qui tourne sur le serveur, sans appel externe) pour proposer automatiquement une correspondance intelligente.
| Parametre | Defaut | Description |
|---|---|---|
| Modele | llama3.2:3b | Champ texte libre --- modele Ollama local pour l'analyse des en-tetes de colonnes |
| Temperature | 0.1 | Slider --- tres basse pour des suggestions deterministes (toujours la meme suggestion pour les memes en-tetes) |
| Timeout | 180 secondes | Timeout serveur pour l'appel Ollama |
| Prompt systeme | Instructions mapping | Instructions pour le mapping colonnes CSV vers schema BeePass |
L'import mapper analyse les noms de colonnes du fichier source (CSV/Excel) et propose automatiquement une correspondance avec les champs de la base de donnees BeePass. L'administrateur valide ou corrige chaque suggestion avant l'import --- l'IA propose, l'humain dispose.
Onglet 5 : Rapport Deps
Cet onglet est different des autres : il n'utilise pas de modele IA. Le rapport de dependances est un document deterministe (toujours le meme resultat pour les memes entrees) genere par /api/admin/dependencies/report. L'onglet gere les contraintes d'architecture --- les regles qui definissent quelles versions de bibliotheques sont autorisees, epinglees ou obsoletes.
| Element | Description |
|---|---|
| Table CRUD | Contraintes d'architecture : package, priorite (P0/P1/P2), type (PINNED/LOCKED/CARET/DEPRECATED/LEGACY/OVERRIDE), raison, action |
| Badges colores | Par priorite et type |
| Formulaire inline | Ajout/edition de contraintes, suppression avec confirmation AlertDialog |
Boutons d'action
Sauvegarder
- Enregistre la configuration de l'onglet actif uniquement dans la base de donnees (
site_settings, cleai_agents_config) - Le bouton est grise si aucune modification n'a ete apportee
- Les changements prennent effet immediatement (cache invalide a la sauvegarde, TTL 5 minutes)
- Exception RAG : les parametres
chunk_sizeetchunk_overlapnecessitent en plus une reindexation
Reinitialiser par defaut
- Remet les parametres de l'onglet actif a leurs valeurs d'usine dans le formulaire
- Ne sauvegarde pas automatiquement : il faut ensuite cliquer "Sauvegarder" pour appliquer la reinitialisation
- Une confirmation est demandee avant la reinitialisation (AlertDialog)
Historique des modifications
Quand plusieurs personnes gerent la plateforme, ou simplement pour retrouver ce qui a change quand les performances de l'IA se degradent, un historique complet de toutes les modifications est disponible en bas de page (section collapsible).
Chaque modification de la configuration IA est enregistree dans site_settings (cle ai_config_history). L'historique conserve les 50 dernieres modifications avec :
| Champ | Description |
|---|---|
| Date | Horodatage de la modification |
| Auteur | ID de l'admin ayant effectue le changement |
| Diff | Comparaison avant/apres des valeurs modifiees |
L'historique est affiche sous forme de timeline dans l'interface, permettant de suivre l'evolution de la configuration et de revenir a un etat anterieur si necessaire.
L'historique est stocke dans site_settings sous la cle ai_config_history (JSONB array). Maximum 50 entrees (les plus anciennes sont supprimees automatiquement).
En cas de degradation des performances IA (qualite des reponses support, precision des mappings), consultez l'historique pour identifier les changements recents susceptibles d'en etre la cause.
Workflow recommande
Premiere utilisation
- Ouvrir
/backoffice/ai-config-> onglet RAG Support - Verifier que l'index est charge (badge vert) et que le nombre de chunks est > 0
- Si l'index n'est pas charge, cliquer "Reindexer la documentation"
- Les parametres par defaut sont optimises pour la documentation BeePass en francais
Ajuster la qualite des reponses
Si les brouillons de reponse support ne sont pas satisfaisants, voici comment affiner les reglages :
- Tester en ouvrant un ticket de support
- Si l'IA ne trouve pas les bons documents : baisser
similarity_threshold(ex: 0.50) et/ou augmentertop_k(ex: 10) - Si l'IA inclut des documents non pertinents : augmenter
min_chunk_score(ex: 0.50) - Si les reponses sont trop courtes : augmenter
max_tokens(ex: 3072) - Sauvegarder et retester
Apres mise a jour de la documentation
Chaque fois que la documentation Docusaurus evolue, l'index doit etre reconstruit pour que l'IA puisse exploiter les nouveaux contenus :
- Modifier les fichiers dans
docs/site/docs/ - Se rendre sur
/backoffice/ai-config-> onglet RAG Support - Cliquer "Reindexer la documentation"
- Verifier que le nombre de chunks a change
Modifier le ton des reponses IA
- Editer le "Prompt systeme (brouillon)" et/ou "Prompt systeme (suivi)"
- Exemples de modifications :
- Ajouter "Sois concis et utilise des listes a puces" pour des reponses plus courtes
- Ajouter "Commence toujours par 'Bonjour'" pour un ton plus chaleureux
- Ajouter "Inclus toujours un lien vers la FAQ" pour promouvoir la FAQ
- Toujours garder
{{language}}dans le prompt pour le support multilingue - Sauvegarder et tester sur un nouveau ticket
Depannage
| Probleme | Cause probable | Solution |
|---|---|---|
| "Index non charge" persistant | Fichier rag-index.json absent ou corrompu | Cliquer "Reindexer la documentation" |
| 0 chunks apres reindexation | Ollama non accessible ou modele non charge | Verifier que beepass-ollama est actif et que nomic-embed-text est telecharge |
| Reponses IA toujours "documentation non trouvee" | Seuil de similarite trop eleve | Baisser similarity_threshold a 0.50 ou 0.45 |
| Reponses IA hors sujet | Chunks non pertinents inclus | Augmenter min_chunk_score a 0.50+ |
| Erreur "Reindex failed" | Ollama sature ou timeout | Reessayer apres quelques minutes, verifier les logs Docker de beepass-ollama |
| Modifications non prises en compte | Cache serveur de 5 min | Attendre 5 min ou sauvegarder la config (invalide le cache) |
Prompts avec {{language}} non interpoles | Placeholder mal ecrit | Verifier que le placeholder est exactement {{language}} (double accolades) |
Architecture technique
API routes
| Route | Methode | Description |
|---|---|---|
/api/admin/ai-config | GET | Lire la config des 5 agents + valeurs par defaut |
/api/admin/ai-config | PUT | Sauvegarder la config d'un agent ({ agent, config }) |
/api/admin/rag/reindex | POST | Declencher la reindexation RAG (30-60s) |
/api/admin/rag/stats | GET | Stats de l'index RAG (chunks, statut, date) |
Fichiers sources
| Fichier | Role |
|---|---|
src/lib/ai-config.ts | Module unifie : types, defaults, cache 5min, loader par agent |
src/lib/rag.ts | Service RAG (indexation, recherche, generation) --- charge config via ai-config.ts |
src/app/components/admin/ai-config/AIConfigPanel.tsx | Panel principal 5 onglets |
src/app/components/admin/ai-config/RagTab.tsx | Onglet RAG |
src/app/components/admin/ai-config/AssistantTab.tsx | Onglet Assistant IA |
src/app/components/admin/ai-config/SecurityAuditTab.tsx | Onglet Audit Securite |
src/app/components/admin/ai-config/ImportMapperTab.tsx | Onglet Import Mapper |
src/app/components/admin/ai-config/DepsReportTab.tsx | Onglet Rapport Deps |
src/app/components/admin/ai-config/shared.tsx | Sous-composants partages (SliderRow, NumberRow, PromptEditor, ModelSelect) |
src/app/api/admin/ai-config/route.ts | API config GET/PUT (validation par agent) |
src/app/api/admin/rag/reindex/route.ts | API reindexation |
src/app/api/admin/rag/stats/route.ts | API statistiques |
data/rag-index.json | Index pre-calcule (embeddings) |