linear-coding-agent/generations/library_rag/ANALYSE_ARCHITECTURE_WEAVIATE.md

Analyse Architecture Weaviate - Library RAG

Date: 2026-01-03 Dernier commit: b76e56e - refactor: Suppression tous fonds beiges header section Status: Production (13,829 vecteurs indexés)

---

📋 Table des Matières

1. Vue d'Ensemble de la Base Weaviate
2. Collections et leurs Relations
3. Focus: Œuvre, Document, Chunk - La Hiérarchie Centrale
4. Stratégie de Recherche: Résumés → Chunks
5. Outils Weaviate: Utilisés vs Non-Utilisés
6. Recommandations pour Exploiter Weaviate à 100%
7. Annexes Techniques

---

1. Vue d'Ensemble de la Base Weaviate

1.1 Architecture Générale

Library RAG utilise Weaviate 1.34.4 comme base vectorielle pour indexer et rechercher des textes philosophiques. L'architecture suit un modèle normalisé avec dénormalisation stratégique via nested objects.

┌─────────────────────────────────────────────────────────────┐
│                    WEAVIATE DATABASE                         │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  Work (0 objets)          Document (16 objets)              │
│  └─ Métadonnées œuvre     └─ Métadonnées édition           │
│     (vectorisé)              (non vectorisé)                │
│                                                              │
│  Chunk (5,404 objets) ⭐   Summary (8,425 objets)           │
│  └─ Fragments vectorisés   └─ Résumés vectorisés           │
│     COLLECTION PRINCIPALE     (recherche hiérarchique)      │
│                                                              │
└─────────────────────────────────────────────────────────────┘

1.2 Statistiques Clés

Collection	Objets	Vectorisé	Taille estimée	Utilisation
Chunk	5,404	✅ Oui (text + keywords)	~3 MB	Recherche sémantique principale
Summary	8,425	✅ Oui (text + concepts)	~5 MB	Recherche hiérarchique par chapitres
Document	16	❌ Non	~10 KB	Métadonnées éditions
Work	0	✅ Oui (title + author)*	0 B	Prêt pour migration

Total vecteurs: 13,829 (5,404 chunks + 8,425 summaries) Ratio Summary/Chunk: 1.56 (1.6 résumés par chunk, excellent pour recherche hiérarchique)

* Work est configuré avec vectorisation depuis migration 2026-01 mais actuellement vide

1.3 Modèle de Vectorisation

Modèle: BAAI/bge-m3 Dimensions: 1024 Contexte: 8192 tokens Langues supportées: Grec ancien, Latin, Français, Anglais

Migration Dec 2024: MiniLM-L6 (384-dim) → BGE-M3 (1024-dim)

• Gain: 2.7x plus riche en représentation sémantique
• Performance: Meilleure sur textes philosophiques/académiques
• Multilingue: Support natif grec/latin

---

2. Collections et leurs Relations

2.1 Architecture des Collections

Work (Œuvre philosophique)
  │
  │ Nested in Document.work: {title, author}
  │ Nested in Chunk.work: {title, author}
  ▼
Document (Édition/traduction spécifique)
  │
  │ Nested in Chunk.document: {sourceId, edition}
  │ Nested in Summary.document: {sourceId}
  ▼
  ├─► Chunk (Fragments de texte, 200-800 chars)
  │     └─ Vectorisé: text, keywords
  │     └─ Filtres: sectionPath, unitType, orderIndex
  │
  └─► Summary (Résumés de chapitres/sections)
        └─ Vectorisé: text, concepts
        └─ Hiérarchie: level (1=chapitre, 2=section, 3=subsection)

2.2 Collection Work (Œuvre)

Rôle: Représente une œuvre philosophique canonique (ex: Ménon de Platon)

Propriétés:

title: TEXT (VECTORISÉ)           # "Ménon", "République"
author: TEXT (VECTORISÉ)          # "Platon", "Peirce"
originalTitle: TEXT [skip_vec]    # "Μένων" (grec)
year: INT                         # -380 (avant J.-C.)
language: TEXT [skip_vec]         # "gr", "la", "fr"
genre: TEXT [skip_vec]            # "dialogue", "traité"

Vectorisation: Activée depuis 2026-01

• ✅ title vectorisé → recherche "dialogues socratiques" trouve Ménon
• ✅ author vectorisé → recherche "philosophie analytique" trouve Haugeland

Status actuel: Vide (0 objets), prêt pour migration

2.3 Collection Document (Édition)

Rôle: Représente une édition ou traduction spécifique d'une œuvre

Propriétés:

sourceId: TEXT                    # "platon_menon_cousin"
edition: TEXT                     # "trad. Cousin, 1844"
language: TEXT                    # "fr" (langue de cette édition)
pages: INT                        # 120
chunksCount: INT                  # 338 (nombre de chunks extraits)
toc: TEXT (JSON)                  # Table des matières structurée
hierarchy: TEXT (JSON)            # Hiérarchie complète des sections
createdAt: DATE                   # 2025-12-09T09:20:30

# Nested object
work: {
  title: TEXT                     # "Ménon"
  author: TEXT                    # "Platon"
}

Vectorisation: ❌ Non (métadonnées uniquement)

2.4 Collection Chunk ⭐ (PRINCIPALE)

Rôle: Fragments de texte optimisés pour recherche sémantique (200-800 caractères)

Propriétés vectorisées:

text: TEXT (VECTORISÉ)            # Contenu du fragment
keywords: TEXT_ARRAY (VECTORISÉ)  # ["justice", "vertu", "connaissance"]

Propriétés de filtrage (non vectorisées):

sectionPath: TEXT [skip_vec]      # "Présentation > Qu'est-ce que la vertu?"
sectionLevel: INT                 # 2 (profondeur hiérarchique)
chapterTitle: TEXT [skip_vec]     # "Présentation"
canonicalReference: TEXT [skip_vec] # "Ménon 80a" ou "CP 5.628"
unitType: TEXT [skip_vec]         # "argument", "définition", "exposition"
orderIndex: INT                   # 42 (position séquentielle 0-based)
language: TEXT [skip_vec]         # "fr", "en", "gr"

Nested objects (dénormalisation):

work: {
  title: TEXT                     # "Ménon"
  author: TEXT                    # "Platon"
}
document: {
  sourceId: TEXT                  # "platon_menon_cousin"
  edition: TEXT                   # "trad. Cousin"
}

Exemple d'objet:

{
  "text": "SOCRATE. - Peux-tu me dire, Ménon, si la vertu peut s'enseigner?",
  "keywords": ["vertu", "enseignement", "question socratique"],
  "sectionPath": "Présentation > Qu'est-ce que la vertu?",
  "sectionLevel": 2,
  "chapterTitle": "Présentation",
  "canonicalReference": "Ménon 70a",
  "unitType": "argument",
  "orderIndex": 0,
  "language": "fr",
  "work": {
    "title": "Ménon ou de la vertu",
    "author": "Platon"
  },
  "document": {
    "sourceId": "platon_menon_cousin",
    "edition": "trad. Cousin"
  }
}

2.5 Collection Summary (Résumés)

Rôle: Résumés LLM de chapitres/sections pour recherche hiérarchique

Propriétés vectorisées:

text: TEXT (VECTORISÉ)            # Résumé généré par LLM
concepts: TEXT_ARRAY (VECTORISÉ)  # ["réminiscence", "anamnèse", "connaissance innée"]

Propriétés de filtrage:

sectionPath: TEXT [skip_vec]      # "Livre I > Chapitre 2"
title: TEXT [skip_vec]            # "La réminiscence et la connaissance"
level: INT                        # 1=chapitre, 2=section, 3=subsection
chunksCount: INT                  # 15 (nombre de chunks dans cette section)

---

3. Focus: Œuvre, Document, Chunk - La Hiérarchie Centrale

3.1 Modèle de Données

L'architecture suit un modèle normalisé avec dénormalisation stratégique :

┌──────────────────────────────────────────────────────────────┐
│                      MODÈLE NORMALISÉ                        │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  Work (Source de vérité unique)                             │
│    title: "Ménon ou de la vertu"                            │
│    author: "Platon"                                          │
│    year: -380                                                │
│    language: "gr"                                            │
│    genre: "dialogue"                                         │
│                                                              │
│    ├─► Document 1 (trad. Cousin)                            │
│    │     sourceId: "platon_menon_cousin"                    │
│    │     edition: "trad. Cousin, 1844"                      │
│    │     language: "fr"                                      │
│    │     pages: 120                                          │
│    │     chunksCount: 338                                    │
│    │     work: {title, author} ← DÉNORMALISÉ                │
│    │                                                          │
│    │     ├─► Chunk 1                                         │
│    │     │     text: "Peux-tu me dire, Ménon..."            │
│    │     │     work: {title, author} ← DÉNORMALISÉ          │
│    │     │     document: {sourceId, edition} ← DÉNORMALISÉ  │
│    │     │                                                   │
│    │     ├─► Chunk 2...                                      │
│    │     └─► Chunk 338                                       │
│    │                                                          │
│    │     ├─► Summary 1 (chapitre 1)                         │
│    │     │     text: "Cette section explore..."             │
│    │     │     level: 1                                      │
│    │     │     document: {sourceId} ← DÉNORMALISÉ           │
│    │     │                                                   │
│    │     └─► Summary N...                                    │
│    │                                                          │
│    └─► Document 2 (Loeb Classical Library)                  │
│          sourceId: "plato_meno_loeb"                         │
│          edition: "Loeb Classical Library"                   │
│          language: "en"                                       │
│          ... (même structure)                                │
│                                                              │
└──────────────────────────────────────────────────────────────┘

3.2 Pourquoi Nested Objects au lieu de Cross-References ?

Avantages:

1. ✅ Requête unique - Récupération en une seule requête sans joins
2. ✅ Performance - Pas de jointures complexes côté application
3. ✅ Simplicité - Logique de requête plus simple
4. ✅ Cache-friendly - Toutes les métadonnées dans un seul objet

Trade-off:

• Pour 5,404 chunks: ~200 KB de duplication
• Économie de temps: ~50-100ms par requête (évite 2 roundtrips Weaviate)

---

4. Stratégie de Recherche: Résumés → Chunks

4.1 Pourquoi Deux Collections Vectorisées ?

Problème: Chercher directement dans 5,404 chunks peut manquer le contexte global

Solution: Architecture à deux niveaux

┌─────────────────────────────────────────────────────────────┐
│              RECHERCHE À DEUX NIVEAUX                        │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  Niveau 1: MACRO (Summary - 8,425 objets)                   │
│    "Quels chapitres parlent de la réminiscence?"            │
│    └─► Identifie: Chapitre 2, Section 3                     │
│                                                              │
│  Niveau 2: MICRO (Chunk - 5,404 objets)                     │
│    "Quelle est la définition exacte de l'anamnèse?"         │
│    └─► Trouve: Chunk #42 dans la section identifiée         │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Avantages:

1. ✅ Meilleure précision (contexte chapitres + détails chunks)
2. ✅ Performance optimale (filtrer chunks par section identifiée)
3. ✅ Hiérarchie exploitée (level 1=chapitre, 2=section, 3=subsection)

4.2 Stratégies de Recherche Implémentables

Stratégie 1: Sequential Search (Résumés puis Chunks)

Cas d'usage: Recherche approfondie avec contexte

# 1. Chercher dans Summary (macro)
summaries = client.collections.get("Summary")
summary_results = summaries.query.near_text(
    query="théorie de la réminiscence",
    limit=5,
    filters=Filter.by_property("level").equal(1)  # Chapitres uniquement
)

# 2. Extraire sections pertinentes
relevant_sections = [
    s.properties['sectionPath']
    for s in summary_results.objects
]

# 3. Chercher chunks dans ces sections (micro)
chunks = client.collections.get("Chunk")
chunk_results = chunks.query.near_text(
    query="qu'est-ce que l'anamnèse?",
    limit=10,
    filters=Filter.by_property("sectionPath").like(f"{relevant_sections[0]}*")
)

Performance: 2 requêtes (~50ms chacune) = 100ms total

Stratégie 2: Hybrid Two-Stage avec Score Boosting

Algorithme recommandé pour production:

def hybrid_search(query: str, limit: int = 10) -> List[ChunkResult]:
    """Recherche hybride résumés → chunks avec boosting."""

    # Stage 1: Summary search (macro)
    summaries = client.collections.get("Summary")
    summary_results = summaries.query.near_text(
        query=query,
        limit=3,  # Top 3 chapitres
        filters=Filter.by_property("level").less_or_equal(2),
        return_metadata=wvq.MetadataQuery(distance=True)
    )

    # Stage 2: Chunk search avec boost par section
    chunks = client.collections.get("Chunk")
    all_chunks = []

    for summary in summary_results.objects:
        section_path = summary.properties['sectionPath']
        summary_score = 1 - summary.metadata.distance

        # Chercher chunks dans cette section
        chunk_results = chunks.query.near_text(
            query=query,
            limit=5,
            filters=Filter.by_property("sectionPath").like(f"{section_path}*"),
            return_metadata=wvq.MetadataQuery(distance=True)
        )

        # Booster le score des chunks
        for chunk in chunk_results.objects:
            chunk_score = 1 - chunk.metadata.distance
            boosted_score = (chunk_score * 0.7) + (summary_score * 0.3)

            all_chunks.append({
                'chunk': chunk,
                'score': boosted_score,
                'context_chapter': section_path
            })

    # Trier par score boosted
    all_chunks.sort(key=lambda x: x['score'], reverse=True)
    return all_chunks[:limit]

Impact: +15-20% précision, ~120ms latence

---

5. Outils Weaviate: Utilisés vs Non-Utilisés

5.1 Outils Actuellement Utilisés ✅

1. Semantic Search (near_text) - Recherche sémantique principale
2. Filters (Nested Objects) - Filtrage par author, work, language
3. Fetch Objects - Récupération par ID
4. Batch Insertion - Insertion groupée adaptative (10-100 objets)
5. Delete Many - Suppression en masse

5.2 Outils Weaviate NON Utilisés ❌

1. Hybrid Search (Sémantique + BM25) ⚠️ HAUTE PRIORITÉ

Qu'est-ce que c'est? Combine recherche vectorielle (sémantique) + BM25 (mots-clés exacts)

Exemple d'implémentation:

result = chunks.query.hybrid(
    query="qu'est-ce que la vertu?",
    alpha=0.75,  # 75% vectoriel, 25% BM25
    limit=10,
    filters=filters,
)

Impact attendu: +10-15% précision sur requêtes factuelles

2. Generative Search (RAG natif) 🚨 HAUTE PRIORITÉ

Qu'est-ce que c'est? Weaviate génère directement une réponse synthétique à partir des chunks

Exemple:

result = chunks.generate.near_text(
    query="qu'est-ce que la réminiscence chez Platon?",
    limit=5,
    grouped_task="Réponds à la question en utilisant ces 5 passages",
)

# Résultat contient:
# - result.objects: chunks trouvés
# - result.generated: réponse LLM générée

Impact: Réduction 50% latence end-to-end (RAG complet en une requête)

3. Reranking (Cohere, Voyage AI) ⚠️ MOYENNE PRIORITÉ

Re-score les résultats avec un modèle spécialisé

Impact: +15-20% précision top-3, +50-100ms latence

4. RAG Fusion (Multi-Query Search) ⚠️ MOYENNE PRIORITÉ

Génère N variantes de la requête et fusionne les résultats

Impact: +20-25% recall

5.3 Matrice Priorités

Outil	Priorité	Difficulté	Impact Précision	Impact Latence	Coût
Hybrid Search	🔴 Haute	Faible (1h)	+10-15%	+5ms	Gratuit
Generative Search	🔴 Haute	Moyenne (3h)	+30% (RAG E2E)	-50% E2E	LLM API
Reranking	🟡 Moyenne	Faible (2h)	+15-20% top-3	+50-100ms	$0.001/req
RAG Fusion	🟡 Moyenne	Moyenne (4h)	+20-25% recall	x3 requêtes	Gratuit

---

6. Recommandations pour Exploiter Weaviate à 100%

6.1 Quick Wins (1-2 jours d'implémentation)

Quick Win #1: Activer Hybrid Search

Fichier à modifier: schema.py

# Ajouter index BM25
wvc.Property(
    name="text",
    data_type=wvc.DataType.TEXT,
    index_searchable=True,  # ← Active BM25
)

Fichier à modifier: mcp_tools/retrieval_tools.py

# Remplacer near_text par hybrid
result = chunks.query.hybrid(
    query=input_data.query,
    alpha=0.75,  # 75% vectoriel, 25% BM25
    limit=input_data.limit,
    filters=filters,
)

Impact: +10% précision, <5ms surcoût

Quick Win #2: Implémenter Two-Stage Search

Créer utils/two_stage_search.py avec l'algorithme hybrid boosting (voir section 4.2)

Impact: +15-20% précision, ~120ms latence

6.2 High-Impact Features (1 semaine d'implémentation)

Feature #1: Generative Search (RAG Natif)

Étape 1: Activer module dans docker-compose.yml

services:
  weaviate:
    environment:
      GENERATIVE_ANTHROPIC_APIKEY: ${ANTHROPIC_API_KEY}

Étape 2: Endpoint Flask

@app.route("/search/generative", methods=["GET"])
def search_generative():
    query = request.args.get("q", "")

    chunks = client.collections.get("Chunk")
    result = chunks.generate.near_text(
        query=query,
        limit=5,
        grouped_task=f"Réponds à: {query}. Utilise les passages fournis.",
    )

    return jsonify({
        "answer": result.generated,
        "sources": [...]
    })

Impact: RAG complet en une requête, -50% latence E2E

---

7. Annexes Techniques

7.1 Exemple de Requête Complète

import weaviate
from weaviate.classes.query import Filter

client = weaviate.connect_to_local()
chunks = client.collections.get("Chunk")

# Recherche: "vertu" chez Platon en français
result = chunks.query.near_text(
    query="qu'est-ce que la vertu?",
    limit=10,
    filters=(
        Filter.by_property("work").by_property("author").equal("Platon") &
        Filter.by_property("language").equal("fr")
    ),
    return_metadata=wvq.MetadataQuery(distance=True)
)

for obj in result.objects:
    props = obj.properties
    similarity = 1 - obj.metadata.distance

    print(f"Similarité: {similarity:.3f}")
    print(f"Texte: {props['text'][:100]}...")
    print(f"Œuvre: {props['work']['title']}")
    print(f"Référence: {props['canonicalReference']}")
    print("---")

client.close()

7.2 Glossaire Weaviate

Terme	Définition
Collection	Équivalent d'une "table" en SQL
Object	Une entrée dans une collection
Vector	Représentation numérique (1024-dim pour BGE-M3)
near_text	Recherche sémantique par similarité
hybrid	Recherche combinée (vectorielle + BM25)
Nested Object	Objet imbriqué (ex: work: {title, author})
HNSW	Index vectoriel performant
RQ	Rotational Quantization (-75% RAM)

---

Conclusion

Points Clés

1. Architecture solide - 4 collections avec nested objects
2. 13,829 vecteurs - Base de production opérationnelle
3. Ratio 1.56 Summary/Chunk - Excellent pour recherche hiérarchique
4. Utilisation 30% - Beaucoup de potentiel non exploité

Roadmap Recommandée

Q1 2026 (Quick Wins):

1. Hybrid Search (1 jour)
2. Two-Stage Search (3 jours)
3. Métriques/monitoring (2 jours)

Q2 2026 (High Impact):

1. Generative Search (1 semaine)
2. Reranking (3 jours)
3. Semantic caching (3 jours)

---

Dernière mise à jour: 2026-01-03 Version: 1.0