Architecture.md 4.9 KB

Architecture de l'application

Documentation du conditionnement et de l'architecture du chatbot RAG (Retrieval-Augmented Generation).


Vue d'ensemble

Application Flask de chatbot documentaire qui répond aux questions à partir du contenu du wiki Intersel. Le flux repose sur :

  1. Indexation : scraping du wiki → découpage en chunks → embeddings → index FAISS
  2. Requête : question utilisateur → recherche hybride (FAISS + BM25 + rerank) → contexte + LLM → réponse

Composants principaux

Composant Rôle Fichiers / modules
Scraping Récupération des pages wiki (Dokuwiki), détection des changements par hash src/agent_ai/scraping.py, src/agent_ai/auth.py
Chunking Découpage sémantique du texte (phrases, overlap) src/agent_ai/chunking.py
Pipeline d'indexation Orchestration : scrape → chunks → embeddings → FAISS src/utils/processing.py
State État global (chunks, index FAISS, modèle d'embedding, mémoire) src/service/state.py
Recherche hybride FAISS + BM25 + MMR (diversité) + cross-encoder (rerank) src/service/embedding_service.py
Mémoire longue durée Stockage des Q/R passées dans un index FAISS dédié src/service/memory_service.py
QA / LLM Vérification sécurité, construction du prompt, appel Mistral (Scaleway) src/service/qa_service.py
API Routes Flask (chat, health, status, trigger-indexation) src/app.py, src/api/*.py

Flux de données

1. Indexation (pipeline)

wiki.intersel.fr (Dokuwiki)
        │
        ▼  scrape_pages() — session authentifiée, crawl limité (voir Choix_techniques.md)
        │
  raw_pages.json / page_hashes.json / urls.json
        │
        ▼  update_chunks() — clean_text + semantic_chunking
        │
  All_chunks.json (chunk_id, text, url, word_count, token_count)
        │
        ▼  build_and_save_index() — SentenceTransformer + FAISS (cosine)
        │
  faiss_index.index
        │
        ▼  pipeline_status.json (last_run, duration, chunk_count, scraping_stats)
  • Première indexation : pas de All_chunks.json ni faiss_index.index → scrape complet, chunking, construction de l’index.
  • Mise à jour incrémentale : fichiers présents → scrape, mise à jour des pages modifiées (hash), reconstruction de l’index.

2. Réponse à une question (QA)

Question utilisateur (POST /qa_chain)
        │
        ▼  quote_keywords() — spaCy, mise entre guillemets des noms/entités
        │
        ▼  detect_topic_smart() — similarité avec l’historique de chat
        │
        ▼  _is_safe_query() — LLM Scaleway (sécurité)
        │
        ▼  hybrid_search() — FAISS + BM25 + MMR + cross-encoder → top N chunks
        │
        ▼  Contexte = mémoire longue durée (topic) + chat récent (topic) + chunks
        │
        ▼  call_scaleway_llama3() — Mistral, réponse factuelle
        │
        ▼  save_memory_entry() — sauvegarde Q/R en mémoire longue durée
        │
  Réponse + sources (chunk_id + URL)

En cas d’erreur (ou contexte vide), fallback SerpAPI (recherche Google + résumé LLM).


Fichiers de données (répertoire src/data/)

Fichier Description
urls.json Liste des URLs wiki connues (crawl)
page_hashes.json Hash MD5 du contenu par URL (détection des modifications)
raw_pages.json Contenu brut des pages (url, text)
All_chunks.json Chunks avec métadonnées (chunk_id, text, url, etc.)
faiss_index.index Index FAISS (vecteurs normalisés, similarité cosinus)
pipeline_status.json Dernier run du pipeline (durée, chunk_count, erreurs, scraping_stats)
memory_chunks.json Entrées de la mémoire longue durée (Q/R)
faiss_memory_index.index Index FAISS pour la mémoire longue durée

Démarrage et santé

  • Démarrage : auto_login() (wiki), init_memory(), puis si ready=False → exécution du pipeline d’indexation et rechargement du state.
  • Scheduler : toutes les 24 h, run_full_update() (pipeline + rechargement du state).
  • Healthcheck : GET /api/health → 200 si chunks et index présents et valides, 503 sinon.
  • Statut : GET /api/status → détails du dernier pipeline (durée, chunks, scraping_stats).
  • Indexation manuelle : POST /api/trigger-indexation → lance le pipeline et recharge le state.

Dépendances externes

  • Wiki : authentification (WIKI_USERNAME, WIKI_PASSWORD) pour le scraping.
  • Scaleway : API Mistral (SCW_API_KEY, SCW_ENDPOINT, SCW_MODEL) pour génération et filtre de sécurité.
  • SerpAPI (optionnel) : fallback en cas d’erreur ou de contexte vide (SERPAPI_API_KEY).

Les choix techniques (limites, modèles, seuils) sont décrits dans Choix_techniques.md.