Chatbot Citoyen MJC

Assistant conversationnel d'accueil pour MJC et tiers-lieux — RAG open source, widget web et tablette kiosque.

Prérequis

• Docker et Docker Compose
• Git

Démarrage rapide

# Cloner (si besoin)
git clone <url-du-repo> chatbot-mjc && cd chatbot-mjc

# Copier la configuration
cp .env.example .env
# Éditer .env si besoin (par défaut ça suffit pour le dev)

# Lancer tous les services (frontend, backend, Qdrant, Ollama)
docker compose up -d --build

# Vérifier que tout tourne
curl http://localhost:8008/health

Interface de chat : ouvrir http://localhost:3003 dans le navigateur. Le frontend appelle l’API via le proxy nginx (/api → backend). Aucune clé API : seule la variable d’environnement VITE_API_URL (défaut /api) est utilisée au build.

Première fois : télécharger les modèles Ollama puis indexer le corpus :

# Une fois (environnement Python)
sudo apt install python3.13-venv
python3 -m venv .venv
source .venv/bin/activate   # à activer à chaque session
pip install -r scripts/requirements.txt

# Modèles Ollama (LLM + embeddings)
docker compose exec ollama ollama pull llama3.2:3b   # rédaction de la réponse (recommandé, ~2 Go)
docker compose exec ollama ollama pull nomic-embed-text   # recherche sémantique (vecteurs)

# Indexer le corpus (Qdrant + Ollama doivent tourner)
python scripts/ingest.py --qdrant-host localhost --ollama-host http://localhost:11434 --recreate

Tester le chat :

curl -X POST http://localhost:8008/chat -H "Content-Type: application/json" -d '{"message": "Quels sont les horaires douverture ?"}'

• Interface chat front : http://localhost:3003
• API : http://localhost:8008
• Documentation API : http://localhost:8008/docs
• Qdrant : http://localhost:6333/dashboard (si exposé)

Frontend (dev local sans Docker) : dans frontend/, créer frontend/.env avec VITE_API_URL=http://localhost:8008, puis npm install && npm run dev. L’app sera sur http://localhost:5173 et enverra les requêtes au backend sur le port 8008.

Poids des modèles Ollama (ordre de grandeur) :

Modèle	Taille téléchargée	Rôle	RAM typique (CPU)
nomic-embed-text	~274 Mo	Embeddings (vecteurs)	~500 Mo
llama3.2 (défaut = 3B)	~2 Go	Génération des réponses	~4–6 Go
llama3.2:1b	~1,3 Go	Idem, plus léger	~2–3 Go
tinyllama	~638 Mo	Encore plus léger (1,1B params)	~1–2 Go
smollm2:360m	~726 Mo	Très léger (360M params)	~1 Go
smollm2:135m	~271 Mo	Minimal (135M params)	~500 Mo

Recommandation : utiliser Llama 3.2 3B (OLLAMA_MODEL=llama3.2:3b) pour des réponses RAG correctes. TinyLlama est plus léger mais recopie souvent les instructions au lieu de répondre.

Pour un modèle plus léger (TinyLlama, moins bon en RAG) :

1. docker compose exec ollama ollama pull tinyllama
2. Dans .env : OLLAMA_MODEL=tinyllama
3. Redémarrer : docker compose up -d backend

Au premier lancement, Ollama télécharge ces modèles (environ 2,3 Go au total avec llama3.2). Le backend précharge le modèle au démarrage (~5 s après le start) pour que la première requête utilisateur soit plus rapide ; le modèle reste en mémoire 30 min après chaque utilisation (keep_alive). Pour éviter un timeout : OLLAMA_TIMEOUT_SECONDS=180 dans .env, ou utilisez un modèle plus léger : ollama pull llama3.2:3b puis OLLAMA_MODEL=llama3.2:3b.

Dépannage — « Je n'ai pas cette information » alors que la donnée est dans un Markdown

Vérifiez que l'ingestion a bien été faite et que RAG_TOP_K est au moins 10 (défaut depuis la mise à jour). Réindexer : python scripts/ingest.py --qdrant-host localhost --ollama-host http://localhost:11434 --recreate. Le script affiche la liste des fichiers indexés. Voir aussi corpus/README.md.

Améliorer le temps de réponse (le plus lent = génération Ollama sur CPU) :

• Réduire les tokens générés : OLLAMA_NUM_PREDICT=100 ou 120 dans .env (défaut 150). Réponses courtes = plus rapide.
• Modèle plus léger : OLLAMA_MODEL=llama3.2:1b (au lieu de 3b) ou modèle quantifié llama3.2:3b-q4_0 si disponible.
• Contexte : OLLAMA_NUM_CTX=2048 (défaut) suffit ; le baisser (ex. 1024) peut légèrement accélérer.
• GPU : si vous avez une carte graphique compatible, Ollama l’utilise automatiquement et la génération est beaucoup plus rapide.

Structure du projet

Dossier	Rôle
frontend/	Interface chat React (Vite), servi sur le port 3003
backend/	API FastAPI, logique RAG
scripts/	Ingestion corpus, tests
corpus/	Documents Markdown (contenus)
config/	Prompts, config RAG
docs/	Cahier des charges, roadmap

Documentation

• Cahier des charges technique
• Roadmap et checklist

Licence

À définir (MIT / Apache 2.0).