linear-coding-agent/DIAGNOSTIC_ARCHITECTURE_EMBEDDINGS.md

Diagnostic - Architecture des Embeddings

Date: 2026-01-09 Projet: Library RAG Problème initial: Erreurs de connexion Weaviate

Architecture Actuelle (Système Hybride)

Le projet utilise deux systèmes d'embeddings différents selon le contexte:

1. Pour l'INGESTION (Nouveaux Documents)

Fichiers concernés:

• utils/weaviate_ingest.py (ligne 1004)
• schema.py (lignes 245, 355)

Méthode:

# Dans weaviate_ingest.py:ingest_document()
chunk_collection.data.insert_many(objects=batch)
# ⚠️ Pas de vecteurs manuels = vectorisation automatique par Weaviate

Configuration schéma:

# Dans schema.py:create_chunk_collection()
vectorizer_config=wvc.Configure.Vectorizer.text2vec_transformers(
    vectorize_collection_name=False,
)

Service utilisé:

• Docker container: library_rag-text2vec-transformers-1
• Image: cr.weaviate.io/semitechnologies/transformers-inference:baai-bge-m3-onnx-latest
• Port: 8090 (exposé), 8080 (interne Weaviate)
• Runtime: ONNX CPU-only (pas de CUDA)
• Modèle: BAAI/bge-m3 (1024 dimensions)

Verdict: ✅ Utilise Docker text2vec-transformers (obligatoire)

---

2. Pour les REQUÊTES (Recherche Sémantique)

Fichiers concernés:

• flask_app.py (lignes 92-107, 307-308, 383-384, 669-670, 1056-1057)
• memory/core/embedding_service.py

Méthode:

# Dans flask_app.py (routes /search, /explore_summaries, etc.)
embedder = get_gpu_embedder()
query_vector = embedder.embed_single(query)

result = chunks.query.near_vector(
    near_vector=query_vector.tolist(),
    limit=10,
)

Service utilisé:

• Module Python: GPUEmbeddingService (singleton)
• Framework: PyTorch + sentence-transformers
• Accélération: CUDA (RTX 4070 avec FP16)
• VRAM: ~2.6 GB peak
• Modèle: BAAI/bge-m3 (1024 dimensions)
• Performance: ~17 ms par requête

Verdict: ✅ Utilise Python GPU embedder (pas de dépendance Docker)

---

Compatibilité des Modèles

Composant	Modèle	Dimensions	Runtime
Ingestion (Docker)	BAAI/bge-m3-onnx	1024	ONNX CPU
Requêtes (Python)	BAAI/bge-m3	1024	PyTorch CUDA

Statut: ✅ Compatible (même modèle, même dimensionnalité)

Les vecteurs générés par les deux systèmes sont comparables car:

• Même architecture de modèle (BAAI/bge-m3)
• Même nombre de dimensions (1024)
• Différence ONNX vs PyTorch est seulement une optimisation d'exécution

---

Problème Diagnostiqué

Symptôme Original

Erreur connexion Weaviate: Connection to Weaviate failed.
Details: Error: Server disconnected without sending a response.

Cause Racine

Le service Docker text2vec-transformers n'était pas démarré.

Impact:

• ❌ Ingestion impossible: Nouveaux documents ne peuvent pas être vectorisés
• ✅ Recherche fonctionnelle: Les requêtes utilisent le GPU embedder Python (indépendant)

Pourquoi text2vec-transformers est nécessaire ?

Weaviate est configuré au démarrage pour utiliser ce service:

# docker-compose.yml
environment:
  DEFAULT_VECTORIZER_MODULE: "text2vec-transformers"
  ENABLE_MODULES: "text2vec-transformers"
  TRANSFORMERS_INFERENCE_API: "http://text2vec-transformers:8080"

Si le service n'est pas disponible:

1. Weaviate essaie de se connecter au démarrage
2. Échec DNS: "no such host"
3. Weaviate reste partiellement fonctionnel MAIS:
   • Les connexions peuvent être instables
   • L'ingestion avec vectorisation automatique échoue

---

Solution Appliquée

Fix Immédiat

cd generations/library_rag
docker compose up -d  # Démarre TOUS les services

Résultat:

• ✅ weaviate démarré (port 8080, 50051)
• ✅ text2vec-transformers démarré (port 8090)
• ✅ Connexion Weaviate stable
• ✅ Ingestion opérationnelle

Fix Permanent (docker-compose.yml)

Ajout de healthchecks et depends_on:

services:
  weaviate:
    depends_on:
      text2vec-transformers:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/v1/.well-known/ready"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s

  text2vec-transformers:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/.well-known/ready"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 120s  # BGE-M3 loading time

Bénéfices:

• Docker attend que text2vec-transformers soit prêt avant de démarrer Weaviate
• Pas de "race condition" au démarrage
• Redémarrages automatiques plus fiables

---

Architecture Alternative (Full Python)

L'utilisateur a mentionné que le projet devrait utiliser uniquement Python embedder. Voici comment migrer:

Option 1: Vectorisation Manuelle Complète

Avantages:

• Un seul embedder (GPU Python) pour ingestion ET requêtes
• Pas besoin du service Docker text2vec-transformers
• Meilleure performance avec GPU (vs ONNX CPU)
• Configuration simplifiée

Inconvénients:

• Nécessite modification du code d'ingestion
• Vecteurs doivent être générés manuellement avant insert

Implémentation:

# Dans utils/weaviate_ingest.py
from memory.core import get_embedder

# Lors de l'ingestion
embedder = get_embedder()

# Générer les vecteurs manuellement
for batch in batches:
    texts = [chunk["text"] for chunk in batch]
    vectors = embedder.embed_batch(texts)

    # Insérer avec vecteurs manuels
    for chunk, vector in zip(batch, vectors):
        chunk_collection.data.insert(
            properties=chunk,
            vector=vector.tolist(),
        )

Modification schéma:

# Dans schema.py:create_chunk_collection()
vectorizer_config=wvc.Configure.Vectorizer.none(),  # Désactiver auto-vectorization

Modification docker-compose.yml:

services:
  weaviate:
    # Supprimer text2vec-transformers des modules
    environment:
      DEFAULT_VECTORIZER_MODULE: "none"
      ENABLE_MODULES: ""
      # Supprimer TRANSFORMERS_INFERENCE_API

# Supprimer complètement le service text2vec-transformers

---

Recommandations

Court Terme (Conserver Système Actuel)

✅ Aucun changement nécessaire si:

• L'ingestion de nouveaux documents est rare
• La performance d'ingestion n'est pas critique
• Vous voulez éviter de réécrire le code d'ingestion

Actions:

• S'assurer que docker compose up -d démarre les deux services
• Ajouter healthchecks (déjà fait)
• Documenter dans README.md que les deux services sont obligatoires

Long Terme (Migration Full Python)

✅ Recommandé si:

• Vous avez un GPU disponible (RTX 4070 confirmé)
• Vous voulez simplifier l'architecture
• Performance d'ingestion importante (GPU 10-20x plus rapide que ONNX CPU)

Plan de migration:

1. Phase 1: Préparation

   • Créer utils/gpu_vectorizer.py avec fonctions de vectorisation batch
   • Écrire tests unitaires pour vectorisation manuelle
   • Benchmarker performance GPU vs Docker

2. Phase 2: Modification Code

   • Modifier utils/weaviate_ingest.py pour utiliser vectorisation manuelle
   • Modifier schema.py pour désactiver auto-vectorization
   • Ajouter paramètre --use-gpu-embedder au pipeline

3. Phase 3: Migration Données

   • CRITIQUE: Ré-ingérer TOUS les documents existants (les vecteurs auto-générés par text2vec doivent être regénérés)
   • Valider que les résultats de recherche sont cohérents
   • Comparer qualité des résultats avant/après

4. Phase 4: Cleanup

   • Supprimer service text2vec-transformers du docker-compose.yml
   • Simplifier environnement de déploiement
   • Mettre à jour documentation

Coût de migration: ~2-4 heures de développement + temps de ré-ingestion (dépend du nombre de documents)

---

Vérification du Système Actuel

Commandes de Diagnostic

# 1. Vérifier que les deux services tournent
docker compose ps

# 2. Tester Weaviate
curl http://localhost:8080/v1/.well-known/ready

# 3. Tester text2vec-transformers
curl http://localhost:8090/.well-known/ready

# 4. Tester le GPU embedder Python
python -c "from memory.core import get_embedder; e = get_embedder(); print('GPU OK')"

# 5. Tester une connexion Weaviate Python
python -c "import weaviate; c = weaviate.connect_to_local(); print('Weaviate OK'); c.close()"

Résultats Attendus

✅ text2vec-transformers: Up (port 8090)
✅ weaviate: Up (ports 8080, 50051)
✅ HTTP 204 No Content (Weaviate ready)
✅ HTTP 204 No Content (text2vec ready)
✅ GPU OK (VRAM: 2.60 GB allocated)
✅ Weaviate OK

---

Fichiers Modifiés

Fichier	Changement	Raison
docker-compose.yml	Ajout healthchecks + depends_on	Éviter race condition au démarrage

---

Conclusion

Système actuel: ✅ Fonctionnel après fix Architecture: Hybride (Docker pour ingestion, Python GPU pour requêtes) Compatibilité: ✅ Compatible (même modèle BGE-M3) Recommandation: Migrer vers Full Python pour simplifier et optimiser

Prochaines étapes:

1. Décider si migration Full Python est prioritaire
2. Si oui: Planifier ré-ingestion de tous les documents
3. Si non: Documenter architecture hybride actuelle

---

Références

• Docker Compose: generations/library_rag/docker-compose.yml
• Schéma Weaviate: generations/library_rag/schema.py
• Ingestion: generations/library_rag/utils/weaviate_ingest.py
• GPU Embedder: memory/core/embedding_service.py
• Flask App: generations/library_rag/flask_app.py
• Bug Report: BUG_REPORT_WEAVIATE_CONNECTION.md