Geniusia_v2/EMBEDDING_SYSTEM_README.md

Système d'Embeddings - Documentation Complète

📋 Vue d'Ensemble

Le système d'embeddings de GeniusIA v2 permet de:

• Générer des représentations vectorielles d'images UI
• Rechercher des workflows similaires via FAISS
• S'adapter automatiquement aux workflows utilisateur via fine-tuning
• Améliorer la précision au fil du temps

🚀 Quick Start

Installation

# Installer les dépendances
./installer_dependances_completes.sh

# Ou manuellement
pip install torch torchvision open-clip-torch faiss-cpu

Utilisation Basique

from geniusia2.core.embedders import EmbeddingManager, FAISSIndex
from PIL import Image

# 1. Initialiser
manager = EmbeddingManager(model_name="clip")
index = FAISSIndex(manager.get_dimension())

# 2. Générer un embedding
image = Image.open("screenshot.png")
embedding = manager.embed(image)

# 3. Indexer
index.add(embedding.reshape(1, -1), [{"workflow_id": "submit_form"}])

# 4. Rechercher
results = index.search(embedding, k=5)
print(f"Meilleur match: {results[0]['metadata']}")

📚 Documentation

Guides

• Guide d'Intégration - Comment intégrer dans l'Orchestrator
• Optimisations - Performance et optimisations
• Benchmark Pix2Struct - Comparaison des modèles

Specs

• Requirements - Exigences détaillées
• Design - Architecture et design
• Tasks - Plan d'implémentation

🧪 Tests

Tests Unitaires

# Test du système de base
geniusia2/venv/bin/python test_embedding_system.py

# Test complet avec fine-tuning
geniusia2/venv/bin/python test_complete_embedding_system.py

# Benchmark CLIP vs Pix2Struct
geniusia2/venv/bin/python test_pix2struct_vs_clip.py

Outils de Debug

# Debug un embedding
python debug_embeddings.py embedding screenshot.png

# Debug une recherche FAISS
python debug_embeddings.py search screenshot.png --index data/workflow_embeddings

# Debug le fine-tuning
python debug_embeddings.py finetuning

Visualisation

# Visualiser les embeddings en 2D (t-SNE)
python visualize_embeddings.py --method tsne

# Ou avec UMAP (nécessite: pip install umap-learn)
python visualize_embeddings.py --method umap

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│                  EmbeddingManager                        │
│  - Sélection de modèle (CLIP/Pix2Struct)               │
│  - Cache LRU (1000 entrées)                            │
│  - Fallback automatique                                 │
└────────────────┬────────────────────────────────────────┘
                 │
        ┌────────┴────────┐
        ▼                 ▼
┌──────────────┐  ┌──────────────────┐
│ CLIPEmbedder │  │ LightweightFine  │
│              │  │ Tuner            │
│ - 512D       │  │ - Auto-trigger   │
│ - 20ms/img   │  │ - Non-blocking   │
│ - Fine-tune  │  │ - Checkpoints    │
└──────┬───────┘  └──────────────────┘
       │
       ▼
┌──────────────┐
│  FAISSIndex  │
│ - <10ms      │
│ - Persistence│
└──────────────┘

📊 Performance

Opération	Temps	Notes
Embedding (CPU)	20ms	Batch de 5
Embedding (GPU)	5ms	4x plus rapide
Cache hit	<1ms	20x plus rapide
FAISS search (10k)	<10ms	k=5
Fine-tuning (6 ex)	0.4s	Non-bloquant

🎯 Modèles Disponibles

CLIP ViT-B/32 (Recommandé) ✅

manager = EmbeddingManager(model_name="clip")

Avantages:

• ⚡ Rapide (20ms/image)
• 🎯 Précis pour UI
• 💾 Léger (2GB)
• ✅ Fine-tuning supporté

Inconvénients:

• Généraliste (pas spécialisé UI)

Pix2Struct (Non Recommandé) ❌

manager = EmbeddingManager(model_name="pix2struct")

Avantages:

• Spécialisé pour documents/UI

Inconvénients:

• 🐌 Très lent (2900ms/image, 146x plus lent)
• 😕 Moins précis (9x moins de discrimination)
• 💾 Lourd (4GB)

Verdict: Utiliser CLIP

🔧 Configuration

Recommandée (Production)

config = {
    "embedding": {
        "model": "clip",
        "cache_size": 1000,
        "device": "cpu",  # ou "cuda" si GPU disponible
        "fallback_enabled": True
    },
    "fine_tuning": {
        "enabled": True,
        "trigger_threshold": 10,
        "max_examples": 1000
    },
    "faiss": {
        "index_path": "data/workflow_embeddings"
    }
}

Haute Performance (GPU)

config = {
    "embedding": {
        "model": "clip",
        "cache_size": 5000,  # Plus de cache
        "device": "cuda",     # GPU
        "fallback_enabled": True
    },
    "fine_tuning": {
        "enabled": True,
        "trigger_threshold": 5,  # Plus fréquent
        "max_examples": 2000
    }
}

🐛 Troubleshooting

Problème: Dimension mismatch dans FAISS

# L'index se rebuild automatiquement
if index.rebuild_if_needed(new_dimension):
    logger.warning("Index rebuilt")

Problème: Cache hit rate faible

stats = manager.get_stats()
if stats['cache_hit_rate'] < 0.3:
    # Augmenter la taille du cache
    manager = EmbeddingManager(cache_size=5000)

Problème: Fine-tuning lent

# Vérifier qu'il tourne en thread séparé
assert fine_tuner.training_thread.daemon == True

# Réduire le nombre d'exemples
fine_tuner = LightweightFineTuner(trigger_threshold=5)

Problème: Mémoire insuffisante

# Réduire le cache
manager = EmbeddingManager(cache_size=100)

# Ou utiliser GPU pour libérer RAM
manager = EmbeddingManager(device="cuda")

📈 Monitoring

Statistiques du Cache

stats = manager.get_stats()
print(f"Hit rate: {stats['cache_hit_rate']:.1%}")
print(f"Size: {stats['cache_size']}/{stats['cache_capacity']}")

Statistiques du Fine-tuning

stats = fine_tuner.get_stats()
print(f"Trainings: {stats['training_count']}")
print(f"Examples: {stats['total_examples']}")

for metrics in stats['metrics_history']:
    print(f"Loss: {metrics['loss']:.4f}")

Statistiques FAISS

stats = index.get_stats()
print(f"Embeddings: {stats['num_embeddings']}")
print(f"Dimension: {stats['dimension']}")

🔄 Migration depuis l'Ancien Système

Avant

from .embeddings_manager import EmbeddingsManager

embeddings = EmbeddingsManager()
embedding = embeddings.encode_image(numpy_bgr_image)

Après

from .embedders import EmbeddingManager
from PIL import Image
import cv2

manager = EmbeddingManager(model_name="clip")

# Convertir numpy BGR → PIL RGB
image_rgb = cv2.cvtColor(numpy_bgr_image, cv2.COLOR_BGR2RGB)
pil_image = Image.fromarray(image_rgb)

embedding = manager.embed(pil_image)

📝 Changelog

v2.0.0 (2024-11-19)

Ajouté:

• ✅ Système d'embeddings modulaire (EmbedderBase)
• ✅ CLIPEmbedder avec batch support
• ✅ FAISSIndex corrigé (dimensions + persistence)
• ✅ EmbeddingManager avec cache LRU
• ✅ LightweightFineTuner (auto-trigger, non-bloquant)
• ✅ Pix2StructEmbedder (optionnel)
• ✅ Tests complets (100% passed)
• ✅ Outils de debug et visualisation
• ✅ Documentation complète

Corrigé:

• ✅ Erreurs de dimension FAISS
• ✅ Persistence FAISS
• ✅ Performance (cache, batch)

Déprécié:

• ⚠️ Ancien EmbeddingsManager (toujours supporté)

🤝 Support

Pour toute question:

1. Consulter cette documentation
2. Lire les guides dans le dossier racine
3. Exécuter les tests de debug
4. Vérifier les specs dans .kiro/specs/embedding-improvement/

📄 Licence

Propriétaire - GeniusIA v2