linear-coding-agent/generations/library_rag/docs_techniques/analyse_collections.md

Analyse de Cohérence des Collections Weaviate

Date: 2025-12-09 Analysé: 3 collections, 51 objets

---

Résumé Exécutif

Problèmes Critiques Identifiés

1. Désynchronisation schéma défini vs schéma réel - Le schéma dans schema.py ne correspond PAS au schéma actuel dans Weaviate
2. Collection Section manquante - Définie dans schema.py mais inexistante dans Weaviate
3. Collection Work inutilisée - 0 objets, redondante avec les autres collections
4. Duplication massive de données - author/work répétés 50 fois au lieu d'utiliser des références
5. Métadonnées vides - TOC et hiérarchie non exploitées
6. Auto-schema non contrôlé - Propriétés ajoutées automatiquement sans validation

---

1. Collection Document

Configuration Actuelle

• Vectorizer: TEXT2VEC_TRANSFORMERS ⚠️
• Objets: 1
• Auto-generated: OUI (toutes les propriétés)

❌ Problèmes Identifiés

1.1 Schéma Auto-Généré

"This property was generated by Weaviate's auto-schema feature on Fri Dec 5 16:10:30 2025"

• Le schéma réel n'a PAS été créé via schema.py
• Weaviate a auto-généré le schéma lors de l'insertion
• Conséquence: Perte de contrôle sur les types et la configuration

1.2 Vectorizer Incorrect

Attendu (schema.py:21):

vectorizer_config=wvc.Configure.Vectorizer.none()

Réel:

Vectorizer: TEXT2VEC_TRANSFORMERS

Impact: Vectorisation inutile des métadonnées → gaspillage de ressources

1.3 Skip Vectorization Ignoré

Attendu (schema.py:85-86):

skip_vectorization=True  # Pour sectionPath et title

Réel:

Toutes les propriétés: Skip Vectorization = ❌

Impact: Toutes les métadonnées sont vectorisées inutilement

1.4 Données Vides/Invalides

{
  "toc": "[]",              // ❌ Vide alors que le document a une TOC
  "hierarchy": "{}",         // ❌ Vide alors que le document a une hiérarchie
  "pages": 0.0,              // ❌ Devrait être > 0
  "chunksCount": 50.0        // ⚠️ Float au lieu de INT
}

1.5 Type DATE Perdu

Attendu (schema.py:66):

data_type=wvc.DataType.DATE

Réel:

createdAt: TEXT

Impact: Impossible de filtrer par date efficacement

---

2. Collection Passage

Configuration Actuelle

• Vectorizer: TEXT2VEC_TRANSFORMERS ✅
• Objets: 50
• Description: Correcte

⚠️ Problèmes Identifiés

2.1 Propriétés Non-Définies Ajoutées

Le schéma dans schema.py définit 9 propriétés, mais Weaviate en a 12:

Propriétés supplémentaires auto-générées:

• chapterTitle (TEXT)
• chapterConcepts (TEXT_ARRAY)
• sectionLevel (NUMBER)

Problème: Ces propriétés ne sont pas dans le schéma original et ont été ajoutées automatiquement sans validation.

2.2 Skip Vectorization Non Respecté

Selon schema.py, AUCUNE propriété de Passage ne devrait avoir skip_vectorization=True.

Réel: Toutes les propriétés sont vectorisées ✅ (correct)

2.3 Duplication Massive de Données

author répété 50 fois:

"author": "Platon"  // x50 passages

work répété 50 fois:

"work": "Ménon ou de la vertu"  // x50 passages

Impact:

• Gaspillage d'espace (50 × ~20 octets = 1 Ko juste pour author)
• Pas de normalisation
• Impossible de changer l'auteur globalement
• Pas de relation avec la collection Work

2.4 Données Incohérentes

orderIndex:

• Min: 1, Max: 49 (attendu: 0-49 pour 50 chunks)
• ⚠️ Manque l'index 0 OU l'index 50

keywords:

• Parfois vide [] (11 passages)
• Pas de normalisation

chapterConcepts:

• TOUJOURS vide [] pour tous les passages
• Feature non utilisée → propriété inutile

unitType:

• 5 valeurs: exposition, main_content, argument, transition, définition
• Pas de validation (pourrait contenir n'importe quoi)

section:

• 13 valeurs uniques pour 50 passages
• Très variable: "SOCRATE", "MENON", "Qu'est-ce que la vertu?", etc.
• Pas de format standard

---

3. Collection Work

Configuration Actuelle

• Vectorizer: NONE ✅
• Objets: 0 ❌
• Schéma: Correct

🚨 Problèmes Critiques

3.1 Collection Complètement Inutilisée

Nombre d'objets: 0

Pourquoi existe-t-elle?

• Définie dans schema.py
• Jamais utilisée par weaviate_ingest.py

3.2 Redondance Totale

Les informations de Work sont dupliquées dans:

1. Document.author + Document.title
2. Passage.author + Passage.work (x50)

Solution attendue: Utiliser Work comme source unique avec des références croisées.

3.3 Propriétés Inutiles

year: INT              # Jamais renseigné
edition: TEXT          # Jamais renseigné
referenceSystem: TEXT  # Jamais renseigné

---

4. Collection Section (Manquante!)

🚨 Définie mais Inexistante

Dans schema.py (lignes 74-120):

client.collections.create(
    name="Section",
    description="A section/chapter with its summary and key concepts...",
    ...
)

Dans Weaviate:

Collections: Document, Passage, Work

Section est ABSENTE!

Impact

• Impossible de faire des résumés de chapitres vectorisés
• Perte de la hiérarchie structurée
• Feature complète non implémentée

---

5. Problèmes de Conception Architecturale

5.1 Absence de Relations Croisées

Attendu (architecture normalisée):

Work (1) ──< Document (N) ──< Passage (N)
           └──< Section (N) ──< Passage (N)

Réel:

Document (1)  [pas de lien]
Passage (50)  [pas de lien]
Work (0)      [vide]
Section       [manquant]

Conséquence: Impossible de naviguer entre collections

5.2 Pas de Cross-References

Weaviate v4 supporte les références croisées, mais elles ne sont pas utilisées:

# Ce qu'on devrait avoir dans Passage:
wvc.Property(
    name="document",
    data_type=wvc.DataType.REFERENCE,
    references="Document"
)

5.3 Duplication vs Normalisation

Taille actuelle (estimée):

• Document: 1 × ~500 octets = 500 B
• Passage: 50 × ~600 octets = 30 Ko
• Total dupliqué: author (50×) + work (50×) ≈ 2 Ko de redondance

Avec normalisation:

• Work: 1 objet avec author + title
• Passage: Référence UUID vers Work
• Économie: ~1.5 Ko + meilleure intégrité

---

6. Analyse des Données

6.1 Document "Platon_-_Menon_trad._Cousin"

{
  "title": "Ménon ou de la vertu",
  "author": "Platon",
  "sourceId": "Platon_-_Menon_trad._Cousin",
  "language": "fr",
  "pages": 0.0,           // ❌ Invalide
  "chunksCount": 50.0,    // ✅ Mais devrait être INT
  "toc": "[]",            // ❌ Vide
  "hierarchy": "{}",      // ❌ Vide
  "createdAt": "2025-12-09T09:20:30.970580"
}

Problèmes:

1. pages: 0 → Le PDF avait forcément des pages
2. toc: "[]" → Le système extrait une TOC (voir llm_toc.py), pourquoi est-elle vide?
3. hierarchy: "{}" → Idem, la hiérarchie devrait être remplie

6.2 Distribution des Passages

Par unitType:

• main_content: ~25
• argument: ~15
• exposition: ~5
• transition: ~3
• définition: ~2

Par section (top 5):

• "SOCRATE": 8 passages
• "MENON": 7 passages
• "Qu'est-ce que la vertu?": 6 passages
• "Vérification de la réminiscence": 5 passages
• "La vertu s'enseigne-t-elle?": 8 passages

Par chapterTitle (top 3):

• "Ménon ou de la vertu": 7 passages
• "Présentation": 6 passages
• "La vertu s'enseigne-t-elle?": 8 passages

⚠️ Confusion: section et chapterTitle se chevauchent sans logique claire

---

7. Écart Schema.py vs Weaviate Réel

Aspect	schema.py	Weaviate Réel	État
Collections	4 (Document, Section, Passage, Work)	3 (Document, Passage, Work)	❌ Section manquante
Document.vectorizer	NONE	TEXT2VEC_TRANSFORMERS	❌ Incorrect
Document.createdAt	DATE	TEXT	❌ Type perdu
Document.skip_vectorization	Défini	Ignoré	❌ Non appliqué
Passage propriétés	9	12	⚠️ 3 ajoutées automatiquement
Section	Définie	Absente	❌ Non créée
Work objets	N/A	0	⚠️ Inutilisée

Cause probable: Le schéma n'a jamais été appliqué correctement. Les collections ont été créées par auto-schema lors de la première insertion.

---

8. Recommandations

8.1 Actions Immédiates (Critiques)

1. Supprimer et recréer le schéma

   python schema.py  # Recréer proprement
   

2. Vérifier que Section est créée

   • Ajouter des logs dans schema.py
   • Vérifier avec client.collections.list_all()

3. Réparer les métadonnées du Document

   • Remplir toc avec les vraies données
   • Remplir hierarchy avec la structure
   • Corriger pages (nombre réel de pages du PDF)

4. Nettoyer les propriétés orphelines

   • Soit définir chapterTitle, chapterConcepts, sectionLevel dans le schéma
   • Soit les supprimer des données

8.2 Améliorations Architecturales

1. Normaliser avec Work

   # Dans Passage, remplacer author/work par:
   wvc.Property(
       name="work_ref",
       data_type=wvc.DataType.REFERENCE,
       references="Work"
   )
   

2. Ajouter Document → Passage reference

   wvc.Property(
       name="document_ref",
       data_type=wvc.DataType.REFERENCE,
       references="Document"
   )
   

3. Implémenter Section

   • Créer des objets Section pour chaque chapitre
   • Lier Section ← Passage via référence
   • Ajouter des résumés LLM aux sections

8.3 Validation des Données

1. Ajouter des contraintes

   • unitType → Enum validé
   • orderIndex → Doit aller de 0 à chunksCount-1
   • pages > 0

2. Normaliser keywords

   • Éviter les doublons
   • Normaliser la casse
   • Supprimer les arrays vides si non utilisés

3. Standardiser section/chapterTitle

   • Décider d'un format unique
   • Séparer titre de chapitre vs nom de locuteur

8.4 Pipeline d'Ingestion

Modifier weaviate_ingest.py:

1. Créer un objet Work d'abord
2. Créer un objet Document avec référence à Work
3. Créer des objets Section avec références
4. Créer des Passages avec références vers Document + Section
5. Valider les données avant insertion

---

9. Impact Business

Problèmes Actuels

Problème	Impact Utilisateur	Gravité
Section manquante	Pas de navigation par chapitre	🔴 Haute
TOC vide	Impossible de voir la structure	🔴 Haute
Work inutilisée	Duplication, pas de filtre par œuvre	🟡 Moyenne
Auto-schema	Schéma imprévisible, bugs futurs	🔴 Haute
orderIndex incorrect	Ordre des passages peut être faux	🟡 Moyenne

Bénéfices de la Correction

1. Navigation structurée via Section
2. Recherche optimisée avec références croisées
3. Métadonnées riches (TOC, hiérarchie)
4. Intégrité des données avec schéma strict
5. Performance (moins de duplication)

---

10. Plan d'Action Proposé

Phase 1: Diagnostic Complet (1h)

• Vérifier pourquoi schema.py n'a pas été appliqué
• Examiner les logs d'insertion dans weaviate_ingest.py
• Identifier quand l'auto-schema s'est déclenché

Phase 2: Correction du Schéma (2h)

• Supprimer toutes les collections
• Ré-exécuter schema.py avec logs
• Vérifier que les 4 collections existent avec le bon schéma
• Tester l'insertion d'un document de test

Phase 3: Migration des Données (3h)

• Exporter les 50 passages actuels
• Créer un objet Work pour "Ménon"
• Créer un Document avec TOC/hierarchy remplis
• Créer des Sections par chapitre
• Ré-insérer les Passages avec références

Phase 4: Validation (1h)

• Tester les requêtes avec références
• Vérifier l'intégrité des données
• Documenter le nouveau schéma
• Mettre à jour README.md

Temps total estimé: ~7 heures

---

Conclusion

Le système actuel souffre d'une désynchronisation majeure entre le schéma défini et la réalité dans Weaviate. Les collections ont été créées par auto-schema au lieu d'utiliser le schéma explicite, ce qui a conduit à:

1. ❌ Perte de contrôle sur les types et la vectorisation
2. ❌ Collection Section complètement absente
3. ❌ Duplication massive de données
4. ❌ Métadonnées vides et invalides
5. ❌ Pas de relations entre collections

Priorité: Recréer proprement le schéma et migrer les données pour exploiter tout le potentiel de l'architecture vectorielle.