Choix_techniques.md 4.4 KB

Choix techniques et limites

Documentation des décisions implicites, limites et paramètres importants de l’application.


Scraping wiki

Limite d’URLs : 100 max

  • Où : src/agent_ai/scraping.py, constante MAX_URLS_TO_SCRAPE = 100.
  • Effet :
    • Le crawl s’arrête après avoir visité au plus 100 URLs (pages découvertes en suivant les liens depuis la page d’accueil).
    • La liste finale all_urls (anciennes URLs + URLs du crawl) est tronquée à 100 avant d’appeler fetch_all_pages_content.
  • Raison : limiter le temps de scraping, la charge sur le wiki et la taille des données (chunks, index).
  • Modifier : changer la valeur de MAX_URLS_TO_SCRAPE dans scraping.py (et éventuellement documenter ici).

URLs prises en compte

Une URL est valide si (is_valid_wiki_url) :

  • Domaine wiki.intersel.fr
  • Pas de do= dans la query (exclut les pages d’édition)
  • Pas d’extension .jpg, .png, .pdf, .docx, .xlsx
  • Pas de # dans l’URL

Authentification

  • Connexion au wiki via formulaire (token CSRF), session HTTP persistante.
  • Identifiants dans .env : WIKI_USERNAME, WIKI_PASSWORD.

Indexation (chunks, FAISS)

Modèles

  • Embeddings : sentence-transformers/all-mpnet-base-v2 (processing + state).
  • Cross-encoder (rerank) : cross-encoder/ms-marco-MiniLM-L-6-v2 (state).
  • Chunking : découpage sémantique par phrases avec overlap (voir src/agent_ai/chunking.py).

Première indexation vs mise à jour incrémentale

  • Première indexation : aucun fichier All_chunks.json ou faiss_index.index → scrape (limité à 100 URLs), chunking complet, construction de l’index.
  • Mise à jour incrémentale : fichiers présents → scrape, mise à jour uniquement des pages dont le hash a changé, puis reconstruction de l’index.

QA (questions / réponses)

LLM

  • API : Scaleway (compatible OpenAI), modèle par défaut mistral-small-3.2-24b-instruct-2506.
  • Variables : SCW_API_KEY, SCW_ENDPOINT (optionnel), SCW_MODEL.

Recherche hybride

  • FAISS : top 200 candidats (paramètre top_k_candidates).
  • BM25 : pondération selon la longueur de la requête (courte → 0.7, etc.).
  • MMR : diversité des chunks (éviter le doublon), lambda 0.7.
  • Cross-encoder : rerank des passages, score final = 0.4 × hybride + 0.6 × cross-encoder.
  • Top final : 20 chunks envoyés au LLM.

Topic / mémoire

  • Détection de topic : similarité (embedding) avec l’historique de chat ; seuil 0.7 pour réutiliser un topic existant.
  • Mémoire longue durée : Q/R sauvegardées dans un index FAISS séparé ; récupération des plus pertinentes (top_k=20) puis filtrage par topic pour le contexte.

Sécurité

  • Chaque question passe par un filtre de sécurité (LLM) : refus si contenu sensible ou malveillant (mot de passe, carte bancaire, hacking, etc.).

Fallback

  • Si erreur ou contexte vide : recherche SerpAPI (Google) + résumé par le LLM. Nécessite SERPAPI_API_KEY (optionnel).

API et configuration

Routes documentées

  • GET /api/health : santé (chunks + index chargés) → 200 ou 503.
  • GET /api/status : statut détaillé du pipeline (dernier run, durée, chunk_count, scraping_stats).
  • POST /api/trigger-indexation : lancement manuel du pipeline + rechargement du state.

Limites côté app

  • Taille max payload : 16 Mo (MAX_CONTENT_LENGTH).
  • Longueur max message chat : 2000 caractères (CHAT_MAX_CHARS).
  • Anti-spam : message vide, répétition de caractères (≥ 50), trop d’URLs (≥ 5) → rejet.

Scheduler

  • Intervalle : 24 h (APScheduler, run_full_update).
  • Verrou : une seule exécution du pipeline à la fois (update_lock).

Résumé des constantes à connaître

Élément Valeur / emplacement
URLs max à scraper 100 — scraping.py → MAX_URLS_TO_SCRAPE
Workers scraping 2 — ThreadPoolExecutor(max_workers=2)
Top candidats recherche 200 — embedding_service.py → top_k_candidates
Top chunks final 20 — top_k_final
Seuil topic 0.7 — qa_service.py → detect_topic_smart
MMR lambda 0.7 — embedding_service.py → mmr_lambda
Intervalle scheduler 24 h — app.py → scheduler.add_job(..., hours=24)

Pour l’architecture globale et le conditionnement de l’application, voir Architecture.md.