docs: Reorganize documentation and rewrite README for Library RAG

Major documentation cleanup and restructuring: 1. Documentation reorganization: - Created docs/migration-gpu/ directory - Moved 6 migration-related MD files to docs/migration-gpu/ - Moved project_progress.md to docs/ 2. Complete README.md rewrite: - Comprehensive explanation of dual RAG system - Clear documentation of 5 Weaviate collections: * Library Philosophique: Work, Chunk_v2, Summary_v2 * Memory Ikario: Thought, Conversation - GPU embedder architecture (BAAI/bge-m3, RTX 4070, 1024-dim) - Quick start guide with installation steps - Usage examples for all features (search, chat, memories, upload) - Performance metrics (30-70x faster ingestion) - Troubleshooting section - Project structure overview 3. Benefits: - Reduced root-level clutter (7 MD files → organized structure) - Clear separation: migration docs vs project docs - User-friendly README focused on usage, not implementation - Easier navigation for new users Files moved: - BUG_REPORT_WEAVIATE_CONNECTION.md → docs/migration-gpu/ - DIAGNOSTIC_ARCHITECTURE_EMBEDDINGS.md → docs/migration-gpu/ - MIGRATION_GPU_EMBEDDER_SUCCESS.md → docs/migration-gpu/ - TEST_CHAT_GPU_EMBEDDER.md → docs/migration-gpu/ - TEST_FINAL_GPU_EMBEDDER.md → docs/migration-gpu/ - TESTS_COMPLETS_GPU_EMBEDDER.md → docs/migration-gpu/ - project_progress.md → docs/ Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-09 12:49:42 +01:00
parent eb2bf45281
commit 7cbcdeb476
8 changed files with 384 additions and 475 deletions
--- a/docs/migration-gpu/BUG_REPORT_WEAVIATE_CONNECTION.md
+++ b/docs/migration-gpu/BUG_REPORT_WEAVIATE_CONNECTION.md
@@ -0,0 +1,249 @@
+# Rapport de Bug - Erreur de Connexion Weaviate
+
+**Date:** 2026-01-09
+**Statut:** ✅ RÉSOLU
+
+## Symptômes
+
+L'application Flask affichait des erreurs de connexion Weaviate lors de l'accès aux routes:
+
+```
+Erreur connexion Weaviate: Connection to Weaviate failed.
+Details: Error: Server disconnected without sending a response..
+Is Weaviate running and reachable at http://localhost:8080?
+```
+
+Les requêtes HTTP pour les images fonctionnaient (200 OK), mais toutes les requêtes nécessitant Weaviate échouaient.
+
+## Cause Racine
+
+Le service Docker **`text2vec-transformers`** n'était pas démarré, alors que Weaviate en a besoin pour la vectorisation.
+
+### Architecture Docker
+
+Le `docker-compose.yml` définit **deux services** interdépendants:
+
+1. **`weaviate`** - Serveur Weaviate principal (port 8080, 50051)
+2. **`text2vec-transformers`** - Service de vectorisation BGE-M3 (port 8090)
+
+Weaviate est configuré pour communiquer avec le service de vectorisation:
+```yaml
+environment:
+  DEFAULT_VECTORIZER_MODULE: "text2vec-transformers"
+  ENABLE_MODULES: "text2vec-transformers"
+  TRANSFORMERS_INFERENCE_API: "http://text2vec-transformers:8080"
+```
+
+### Séquence d'Erreur
+
+1. Seul le service `weaviate` était démarré
+2. Weaviate tentait de se connecter à `text2vec-transformers` au démarrage
+3. Résolution DNS échouait: "no such host"
+4. Weaviate timeout: "context deadline exceeded"
+5. Les connexions des clients Python échouaient avec "Server disconnected without sending a response"
+
+### Logs Weaviate (Diagnostic)
+
+```
+{"action":"transformer_remote_wait_for_startup",
+ "error":"Get \"http://text2vec-transformers:8080/.well-known/ready\":
+          dial tcp: lookup text2vec-transformers on 127.0.0.11:53: no such host",
+ "level":"warning",
+ "msg":"transformer remote inference service not ready"}
+```
+
+## Solution
+
+### Démarrage Correct
+
+```bash
+cd generations/library_rag
+
+# Démarrer TOUS les services (pas seulement weaviate)
+docker compose up -d
+
+# Vérifier que les deux services tournent
+docker compose ps
+
+# Tester la connexion
+python -c "import weaviate; client = weaviate.connect_to_local(); print('OK'); client.close()"
+```
+
+### Vérification
+
+```bash
+# Les deux services doivent apparaître
+$ docker compose ps
+NAME                                  STATUS
+library_rag-text2vec-transformers-1   Up
+library_rag-weaviate-1                Up
+
+# Weaviate doit être ready
+$ curl http://localhost:8080/v1/.well-known/ready
+# Retourne: HTTP 204 No Content (succès)
+
+# text2vec-transformers doit être ready
+$ curl http://localhost:8090/.well-known/ready
+# Retourne: HTTP 204 No Content (succès)
+```
+
+## Prévention
+
+### 1. Scripts de Démarrage
+
+Le fichier `init.sh` (ou `init.bat`) devrait déjà contenir:
+
+```bash
+# Démarrer Weaviate ET text2vec-transformers
+docker compose up -d
+```
+
+⚠️ **NE PAS utiliser**: `docker compose up -d weaviate` (démarre seulement un service)
+
+### 2. Health Check
+
+Ajouter une vérification dans les scripts Python critiques:
+
+```python
+import weaviate
+import sys
+
+def check_weaviate_health():
+    """Vérifie que Weaviate et le vectorizer sont opérationnels."""
+    try:
+        with weaviate.connect_to_local() as client:
+            if not client.is_ready():
+                print("❌ Weaviate n'est pas prêt")
+                print("Démarrez les services: docker compose up -d")
+                sys.exit(1)
+        print("✓ Connexion Weaviate OK")
+    except Exception as e:
+        print(f"❌ Erreur connexion Weaviate: {e}")
+        print("Vérifiez que les services Docker tournent:")
+        print("  docker compose ps")
+        print("  docker compose up -d")
+        sys.exit(1)
+```
+
+### 3. Monitoring
+
+Ajouter un healthcheck dans `docker-compose.yml`:
+
+```yaml
+services:
+  weaviate:
+    # ... config existante ...
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8080/v1/.well-known/ready"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 60s
+    depends_on:
+      text2vec-transformers:
+        condition: service_healthy
+
+  text2vec-transformers:
+    # ... config existante ...
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8080/.well-known/ready"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 120s  # Le modèle BGE-M3 prend du temps à charger
+```
+
+## Commandes de Dépannage
+
+### Diagnostic
+
+```bash
+# 1. Vérifier l'état des services
+docker compose ps
+
+# 2. Vérifier les logs Weaviate
+docker compose logs weaviate --tail=50
+
+# 3. Vérifier les logs text2vec-transformers
+docker compose logs text2vec-transformers --tail=50
+
+# 4. Tester la connectivité réseau entre les services
+docker compose exec weaviate ping text2vec-transformers
+```
+
+### Redémarrage Propre
+
+```bash
+# Arrêter tous les services
+docker compose down
+
+# Redémarrer
+docker compose up -d
+
+# Attendre ~30 secondes que text2vec-transformers charge le modèle BGE-M3
+sleep 30
+
+# Vérifier
+docker compose ps
+curl http://localhost:8080/v1/.well-known/ready
+curl http://localhost:8090/.well-known/ready
+```
+
+### Problèmes de Mémoire
+
+Si `text2vec-transformers` crash (OOM - Out of Memory):
+
+```yaml
+# Dans docker-compose.yml, augmenter les limites:
+text2vec-transformers:
+  mem_limit: 12g      # Actuellement 10g
+  memswap_limit: 14g  # Actuellement 12g
+```
+
+Le modèle BGE-M3 (1024 dimensions) nécessite ~6-8 GB de RAM au minimum.
+
+## Tests de Non-Régression
+
+Ajouter ce test dans `tests/integration/test_weaviate_startup.py`:
+
+```python
+import pytest
+import weaviate
+from weaviate.exceptions import WeaviateStartUpError
+
+def test_weaviate_connection():
+    """Test que Weaviate est accessible et prêt."""
+    with weaviate.connect_to_local() as client:
+        assert client.is_ready()
+
+def test_text2vec_transformers_available():
+    """Test que le module text2vec-transformers est chargé."""
+    with weaviate.connect_to_local() as client:
+        meta = client.get_meta()
+        modules = meta.get("modules", {})
+        assert "text2vec-transformers" in modules
+
+        # Vérifier la configuration BGE-M3
+        t2v_config = modules["text2vec-transformers"]
+        assert "BAAI/bge-m3" in str(t2v_config).lower()
+```
+
+## Leçons Apprises
+
+1. **Dépendances implicites**: Weaviate ne peut pas démarrer correctement sans `text2vec-transformers` quand configuré avec `DEFAULT_VECTORIZER_MODULE`
+2. **Messages d'erreur trompeurs**: "Server disconnected" ne pointe pas directement vers le service manquant
+3. **Importance de `depends_on`**: Docker Compose ne garantit pas l'ordre de démarrage sans `depends_on` et `healthcheck`
+4. **Logs critiques**: Les logs Weaviate contenaient l'information clé ("no such host"), mais nécessitaient investigation
+
+## Impact
+
+- **Sévérité**: Critique (application non fonctionnelle)
+- **Fréquence**: Se produit après redémarrage système ou `docker compose down`
+- **Utilisateurs affectés**: Tous les développeurs/utilisateurs locaux
+- **Temps de résolution**: 5 minutes (une fois diagnostiqué)
+
+## Références
+
+- Documentation Weaviate: https://weaviate.io/developers/weaviate/installation/docker-compose
+- BGE-M3 Model: https://huggingface.co/BAAI/bge-m3
+- Configuration actuelle: `generations/library_rag/docker-compose.yml`