Add Library RAG project and cleanup root directory
- Add complete Library RAG application (Flask + MCP server) - PDF processing pipeline with OCR and LLM extraction - Weaviate vector database integration (BGE-M3 embeddings) - Flask web interface with search and document management - MCP server for Claude Desktop integration - Comprehensive test suite (134 tests) - Clean up root directory - Remove obsolete documentation files - Remove backup and temporary files - Update autonomous agent configuration - Update prompts - Enhance initializer bis prompt with better instructions 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
465
generations/library_rag/docs_techniques/analyse_collections.md
Normal file
465
generations/library_rag/docs_techniques/analyse_collections.md
Normal file
@@ -0,0 +1,465 @@
|
||||
# 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):
|
||||
```python
|
||||
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):
|
||||
```python
|
||||
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
|
||||
```json
|
||||
{
|
||||
"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):
|
||||
```python
|
||||
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:
|
||||
```json
|
||||
"author": "Platon" // x50 passages
|
||||
```
|
||||
|
||||
**work** répété 50 fois:
|
||||
```json
|
||||
"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
|
||||
```python
|
||||
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):
|
||||
```python
|
||||
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**:
|
||||
|
||||
```python
|
||||
# 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"
|
||||
|
||||
```json
|
||||
{
|
||||
"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**
|
||||
```bash
|
||||
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**
|
||||
```python
|
||||
# Dans Passage, remplacer author/work par:
|
||||
wvc.Property(
|
||||
name="work_ref",
|
||||
data_type=wvc.DataType.REFERENCE,
|
||||
references="Work"
|
||||
)
|
||||
```
|
||||
|
||||
2. **Ajouter Document → Passage reference**
|
||||
```python
|
||||
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.
|
||||
Reference in New Issue
Block a user