# Guide FAISS Rebuild Propre

**Auteur :** Dom, Alice Kiro - 22 décembre 2025

## Vue d'ensemble

Le système FAISS Rebuild Propre permet de maintenir un index FAISS propre et cohérent en éliminant la pollution causée par l'accumulation de vecteurs obsolètes.

## Problème résolu

### Avant : Pollution d'index
- Les prototypes mis à jour s'accumulent dans l'index FAISS
- Anciens vecteurs obsolètes restent présents
- Dégradation progressive de la qualité de matching

### Après : Index propre
- Stratégie "1 prototype = 1 entrée"
- Clear complet + reindex depuis source canonique
- Index cohérent reflétant exactement les prototypes actuels

## Utilisation

### Script utilitaire

```bash
# Mode simulation
python3 rebuild_faiss_simple.py --dry-run --verbose

# Rebuild réel
python3 rebuild_faiss_simple.py --verbose

# Index IVF
python3 rebuild_faiss_simple.py --index-type IVF
```

### API programmatique

```python
from core.embedding.faiss_manager import FAISSManager

manager = FAISSManager(dimensions=512)
items = [("id1", vector1, {"meta": "data1"})]
count = manager.reindex(items, force_train_ivf=True)
```

## Formats supportés

- **v1**: `template.embedding_prototype` (liste)
- **v2**: `embedding.vector_id` (fichier)
- **legacy**: `screen_template.embedding_prototype_path`

## Quand déclencher

✅ **Recommandé:**
- Après apprentissage réussi
- Mise à jour de prototypes validée
- Maintenance périodique

❌ **À éviter:**
- Pendant l'exécution
- Mises à jour fréquentes
- Index vide

## Troubleshooting

### Rebuild échoue
```
ERROR - FAISS reindex failed: vector dimensions mismatch
```
**Solution:** Vérifier cohérence des dimensions

### Performance dégradée
**Solutions:**
- Utiliser index IVF pour gros volumes
- Traitement par batch
- Monitoring mémoire

## Configuration

```python
manager = FAISSManager(
    dimensions=512,
    index_type="IVF",
    metric="cosine",
    use_gpu=True
)
```