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.