Bonnes pratiques d'utilisation

Configuration

• Vérifier que MISTRAL_API_KEY et DATABASE_URL sont définis dans .env avant tout lancement.
• Configurer CHAINLIT_AUTH_SECRET si l'authentification Chainlit est activée.
• Adapter les prompts (CHAINLIT_SYSTEM_PROMPT, BOT_SYSTEM_PROMPT) au domaine métier dans .env ou le ConfigMap Kubernetes.

Qualité des données

• Chunks: éviter les doublons et le bruit textuel. Catégoriser (dynamic, static, not an info) dès l'annotation pour faciliter le fine-tuning futur.
• QA pairs: couvrir les questions fréquentes avec des réponses précises. Les QA pairs servent aussi de few-shot examples dans le prompt RAG.
• Tags & Rôles: bien associer les tags aux chunks et aux rôles applicatifs. Un chunk sans tag ne sera dans aucun index per-role (sauf pour les rôles is_super_admin).
• Régénérer l'index FAISS après toute modification significative des chunks, tags ou associations role-tag.

Paramètres RAG

• RAG_K_CHUNKS (défaut: 5) — nombre de chunks injectés en contexte. Augmenter pour des sujets diffus, diminuer pour des sujets focalisés.
• RAG_N_EXAMPLES (défaut: 4) — nombre de few-shot Q&A injectés. Mettre 0 ou FEW_SHOTS_ENABLED=false pour désactiver.
• RAG_TEMP (défaut: 0.2) — température LLM. Plus bas = réponses plus déterministes.

Index FAISS

• Les index sont persistés en DB (indexes table) et chargés en cache mémoire au premier accès par rôle. Pas de recalcul complet au redémarrage.
• Si l'index est vide ou obsolète: déclencher POST /regenerate-index (via bouton admin web ou directement sur l'Index API).
• La régénération est bloquante côté Index API: prévoir un timeout suffisant pour les bases volumineuses.

Mode orchestrateur

• N'activer ENABLE_ORCHESTRATOR=true que si un service externe implémentant POST /assistant (SSE) est disponible à EXTERNAL_AGENT_URL.
• Le mode ALTER est sticky par thread Chainlit: une fois basculé, toutes les questions suivantes vont à l'agent externe.

Sécurité

• Ne jamais commiter .env ni exposer MISTRAL_API_KEY dans le code ou l'historique git.
• Utiliser des Secrets Kubernetes pour les variables sensibles en production.
• Limiter les journaux si des données sensibles peuvent apparaître dans les chunks ou les questions.