---
title: PolyglotRAG
emoji: 🌍
colorFrom: blue
colorTo: yellow
sdk: docker
app_port: 7860
pinned: false
license: mit
---

# 🌍 PolyglotRAG

Assistant documentaire multilingue et **cross-lingue** : posez une question en
anglais, français, russe, espagnol, arabe ou portugais, et obtenez une réponse
sourcée — même si le document pertinent est rédigé dans une **autre** langue
que la question.

> Exemple : une question posée en **russe** retrouve un règlement rédigé en
> **français** et un rapport en **anglais**, puis PolyglotRAG répond en russe
> en citant les documents originaux — sans jamais traduire le corpus au
> préalable.

Propulsé par **DeepSeek-V4.1-Flash** (génération) et **BAAI/bge-m3**
(embeddings multilingues partagés), les deux via le routeur *Inference
Providers* de Hugging Face — **un seul jeton d'API** suffit pour tout le
projet.

---

## Sommaire

- [Fonctionnalités](#fonctionnalités)
- [Architecture](#architecture)
- [Optimisations de performance](#optimisations-de-performance)
- [Démarrage rapide (local, sans Docker)](#démarrage-rapide-local-sans-docker)
- [Docker](#docker)
- [Déploiement sur Hugging Face Spaces](#déploiement-sur-hugging-face-spaces)
- [Structure du dépôt](#structure-du-dépôt)
- [Configuration](#configuration)
- [Ingestion de vos propres documents](#ingestion-de-vos-propres-documents)
- [Tests](#tests)
- [Choix d'architecture assumés](#choix-darchitecture-assumés)
- [Évolutions possibles](#évolutions-possibles)

## Fonctionnalités

- 🔎 Détection automatique de la langue de la question (hors-ligne, `lingua`).
- 📥 Ingestion PDF, DOCX, Markdown, HTML, CSV, avec langue/fichier/page/titre
  conservés par chunk.
- 🌐 Recherche **cross-lingue** dans un espace sémantique multilingue partagé
  (BGE-M3), avec 3 modes : global, filtré par langue, priorité locale.
- 🧠 Génération strictement source-grounded (mode strict / abstention si le
  score de confiance est trop faible).
- 🈯 Interface **RTL** correcte pour l'arabe.
- 📚 Citations systématiques : fichier, langue, page, score.
- 📊 Page **Admin** : métriques du RAG (volume, latence, langues, taux
  d'abstention, historique des requêtes).
- 🏗️ Page **Architecture** : schéma complet du pipeline.
- 🔐 Stockage vectoriel dans un **dataset privé Hugging Face** (aucun service
  tiers à héberger).
- ⚡ **Cache** réponses + embeddings de requêtes, **recherche approximative
  (ANN / FAISS-HNSW)** et **top-k final limité à 2** — voir
  [Optimisations de performance](#optimisations-de-performance).
- 🐳 **Dockerfile** fourni (image de production, utilisateur non-root,
  healthcheck) — exécution locale ou Space Hugging Face en SDK Docker.

## Architecture

Voir l'onglet **Architecture** de l'application pour le schéma interactif.
Résumé :

```
Documents multilingues (knowledge_base/<lang>/*)
        │
        ▼
Extraction PDF / DOCX / MD / HTML / CSV
        │
        ▼
Détection langue + métadonnées (fichier, page, titre, sens RTL/LTR)
        │
        ▼
Chunking adapté à la langue (découpage par phrases + recouvrement)
        │
        ▼
Embeddings multilingues partagés — BAAI/bge-m3 (HF Inference Providers)
        │
        ▼
Dataset privé Hugging Face (Parquet) ──► chargé en FAISS au démarrage
        │
        ▼
Question utilisateur ──► détection de langue ──► recherche ANN cross-lingue (top-15, FAISS-HNSW)
        │
        ▼
Bonus langue + reranking (top-2 final) ──► mode strict (seuil de confiance)
        │
        ▼
DeepSeek-V4.1-Flash (routeur HF) ──► réponse + citations + score
        │
        ▼
Cache réponse (TTL) ──► une question identique reposée pendant la fenêtre
                         de cache ne refait ni la recherche, ni l'appel LLM
```

## Optimisations de performance

Trois optimisations sont actives par défaut (`config.py` / `.env.example`) :

| Optimisation | Où | Détail |
|---|---|---|
| **Cache** | `core/optimization/cache.py`, `core/pipeline.py` | Cache à expiration (TTL, 10 min par défaut) sur (1) les embeddings de questions déjà posées et (2) les réponses complètes pour une question strictement identique (même langue de réponse, même filtre). Désactivable via `ENABLE_CACHE=false`. |
| **Recherche approximative (ANN)** | `core/retrieval/vector_store.py` | Index `FAISS IndexHNSWFlat` par défaut au lieu d'une recherche exacte (`IndexFlatIP`) : bien plus rapide dès que le corpus grossit, sans étape d'entraînement. Réglable via `ANN_INDEX_TYPE` (`hnsw`/`flat`), `ANN_HNSW_M`, `ANN_EF_SEARCH`. |
| **Top-k final réduit** | `config.py` (`TOP_K_FINAL=2`) | Seuls les **2 meilleurs passages** (après bonus de langue et reranking) sont envoyés au LLM — moins de tokens de contexte, réponse plus rapide et moins coûteuse. `TOP_K_RETRIEVE=15` reste le pool de candidats initial avant ce filtrage final. |

L'onglet **Admin** affiche en direct l'état du cache (taille/capacité) et le
type d'index vectoriel actif, pour vérifier que ces optimisations tournent
bien en production.

## Démarrage rapide (local, sans Docker)

```bash
git clone <votre-fork-ou-dossier> polyglot-rag
cd polyglot-rag
python -m venv .venv && source .venv/bin/activate   # Windows : .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env
# Éditez .env : renseignez HF_TOKEN (https://huggingface.co/settings/tokens)

# 1. Ingestion des documents d'exemple (ou des vôtres) -> index local
python scripts/ingest.py --no-push

# 2. Lancement de l'application
python app.py
```

L'application s'ouvre sur `http://localhost:7860` avec les 3 onglets
Chat / Architecture / Admin.

## Docker

Image de production fournie (utilisateur non-root UID 1000, healthcheck,
compatible Hugging Face Spaces en SDK Docker).

```bash
cp .env.example .env   # renseignez HF_TOKEN au minimum

# Construction + lancement
docker compose up --build
# ou, sans docker compose :
docker build -t polyglot-rag .
docker run --rm -p 7860:7860 --env-file .env -v "$(pwd)/data:/app/data" polyglot-rag
```

Pensez à ingérer vos documents avant (ou après) le premier démarrage :

```bash
docker compose run --rm polyglot-rag python scripts/ingest.py --no-push
```

L'application est alors disponible sur `http://localhost:7860`.

## Déploiement sur Hugging Face Spaces

Le Space est un **Space Docker** : `README.md` déclare `sdk: docker` et
`app_port: 7860`, et Hugging Face construit directement le `Dockerfile`
fourni à la racine — aucune configuration supplémentaire n'est nécessaire
côté Space.

**Option recommandée : notebook Colab fourni**
(`PolyglotRAG_Deploy_HuggingFace.ipynb`). Il automatise tout :

1. Installation des dépendances.
2. Saisie sécurisée de votre `HF_TOKEN` (jamais affiché en clair).
3. Création du dataset privé + ingestion des documents.
4. Publication du dataset privé sur le Hub.
5. Création du Space en **SDK Docker** + injection du token en secret.
6. Publication du code de l'application (dont le `Dockerfile`).
7. Affichage de l'URL finale du Space (build Docker déclenché automatiquement
   par Hugging Face).

**Option manuelle**, en ligne de commande :

```bash
python scripts/ingest.py                       # pousse l'index vers HF_DATASET_REPO
hf repos create <votre-compte>/polyglot-rag --repo-type space --space_sdk docker
huggingface-cli upload <votre-compte>/polyglot-rag . --repo-type space
# Puis, dans les Settings du Space : ajoutez les secrets HF_TOKEN et HF_DATASET_REPO
```

## Structure du dépôt

```
polyglot-rag/
├── app.py                        # Point d'entrée Gradio (Chat / Architecture / Admin)
├── config.py                     # Configuration centralisée (variables d'env)
├── Dockerfile                     # Image de production (Space Docker + usage local)
├── docker-compose.yml             # Confort de développement local
├── .dockerignore
├── requirements.txt
├── .env.example
├── knowledge_base/                # Documents d'exemple (6 langues) — à remplacer par les vôtres
│   ├── en/ fr/ ru/ es/ ar/ pt/
├── core/
│   ├── ingestion/                 # loaders, détection de langue, chunking, indexeur
│   ├── retrieval/                 # embeddings, FAISS (ANN), recherche cross-lingue
│   ├── generation/                 # prompts, appel LLM
│   ├── optimization/               # cache réponses + embeddings (TTL)
│   ├── pipeline.py                 # orchestration retrieval + génération + cache + métriques
│   ├── metrics/                   # journalisation SQLite pour l'Admin
│   ├── ui/                        # onglets Gradio (Chat, Admin, Architecture)
│   └── assets/architecture.svg    # schéma d'architecture
├── scripts/ingest.py               # CLI d'ingestion / publication du dataset
├── tests/                          # pytest (aucun test ne fait d'appel réseau)
├── data/                           # cache local (index, métriques) — gitignored
└── PolyglotRAG_Deploy_HuggingFace.ipynb
```

## Configuration

Toutes les options sont documentées dans `.env.example`. Point clé :
**un seul jeton, `HF_TOKEN`**, avec le scope *"Make calls to Inference
Providers"* (+ *"Write"* si le Space doit aussi pousser/rafraîchir le
dataset). Créez-le sur
[huggingface.co/settings/tokens](https://huggingface.co/settings/tokens).

| Variable | Rôle | Défaut |
|---|---|---|
| `HF_TOKEN` | Authentification unique (LLM, embeddings, dataset) | — (obligatoire) |
| `HF_DATASET_REPO` | Dataset privé contenant l'index | — |
| `LLM_MODEL` | Modèle génératif | `deepseek-ai/DeepSeek-V4.1-Flash:fastest` |
| `EMBEDDING_MODEL` | Modèle d'embeddings | `BAAI/bge-m3` |
| `TOP_K_FINAL` | Passages envoyés au LLM | `2` |
| `ANN_INDEX_TYPE` | `hnsw` (approximatif) ou `flat` (exact) | `hnsw` |
| `ENABLE_CACHE` | Cache réponses + embeddings de requêtes | `true` |
| `CACHE_TTL_SECONDS` | Durée de vie du cache | `600` |
| `MIN_CONFIDENCE_SCORE` | Seuil d'abstention (mode strict) | `0.28` |
| `ADMIN_PASSWORD` | Protège l'onglet Admin | vide (accès libre) |

## Ingestion de vos propres documents

1. Placez vos fichiers dans `knowledge_base/<code_langue>/` (`en`, `fr`, `ru`,
   `es`, `ar`, `pt`) — formats supportés : `.pdf`, `.docx`, `.md`, `.html`,
   `.csv`.
2. Lancez `python scripts/ingest.py` (pousse automatiquement vers
   `HF_DATASET_REPO` si défini).
3. Redémarrez le Space (ou rechargez la page) : l'index est reconstruit au
   démarrage à partir du dataset privé.

⚠️ Les PDF scannés sans couche texte ne sont pas encore océrisés
automatiquement — le loader signale les pages concernées
(`[PAGE SANS TEXTE EXTRACTIBLE — OCR REQUIS]`) plutôt que d'indexer du vide.

## Tests

```bash
pip install pytest
pytest
```

Tous les tests s'exécutent **hors-ligne** (un garde-fou dans
`tests/conftest.py` fait échouer volontairement tout test qui tenterait un
appel réseau réel vers l'API d'embeddings).

## Choix d'architecture assumés

- **Pas de traduction systématique du corpus.** Chaque chunk garde son
  texte et sa langue d'origine ; seule la recherche passe par un espace
  d'embeddings partagé. La traduction n'intervient jamais côté indexation.
- **FAISS en mémoire plutôt qu'un service Qdrant externe.** Le dataset privé
  Hugging Face joue le rôle de stockage persistant (Parquet) ; l'index est
  reconstruit en mémoire au démarrage du Space. Pour un corpus de quelques
  dizaines de milliers de chunks, c'est largement suffisant, et cela évite
  une seconde dépendance opérationnelle (donc une seconde clé d'API) — cohérent
  avec la contrainte « un seul jeton Hugging Face ».
- **DeepSeek-V4.1-Flash via le routeur *Inference Providers*.** Le modèle
  n'est pas déployé/hébergé par ce projet : il est appelé via
  `https://router.huggingface.co`, qui route vers un provider tiers (Novita
  à ce jour) tout en facturant sur votre compte Hugging Face. Le
  qualificatif `:fastest` sur `LLM_MODEL` s'adapte automatiquement si le
  provider change.

## Évolutions possibles

- Reranking cross-encoder dédié (au lieu du bonus de score actuel).
- Snapshot périodique de la base de métriques vers le dataset HF (persistance
  au-delà du cycle de vie du Space).
- Agents spécialisés (routeur de langue, agent de récupération cross-lingue,
  agent terminologie/glossaire métier, agent qualité) pour une architecture
  de type Corrective RAG multi-agent, comme décrit dans le document de
  cadrage du projet.
- OCR automatique pour les PDF scannés.