Embeddings Learnings — Recherche sémantique via Ollama + FAISS¶

Vue d'ensemble¶

Ce système permet la recherche sémantique dans les 93+ learnings (REX, écarts, patterns) via : - Ollama local (nomic-embed-text) pour les embeddings (768 dimensions) - FAISS pour l'indexation k-NN (vector store local) - Skill /learnings pour l'interrogation interactive

Architecture¶

data/learnings.jsonl (source de vérité, 93 entrées)
    ↓
scripts/index-learnings.py (génération embeddings Ollama + index FAISS)
    ↓
data/
├── learnings-embeddings.npy         # Vecteurs NumPy (93×768)
├── learnings-index.faiss            # Index FAISS k-NN
├── learnings-cache.json             # Learnings structurés (pour recherche)
└── embeddings-meta.json             # Métadonnées (count, model, date)
    ↓
scripts/search-learnings.py (recherche sémantique)
    ↓
.claude/commands/learnings.md (skill /learnings)

Installation¶

1. Dépendances Python¶

pip install -r requirements.txt

2. Ollama et modèle nomic-embed-text¶

# Vérifier qu'Ollama est installé
which ollama

# Télécharger le modèle nomic-embed-text (~274 MB)
ollama pull nomic-embed-text

3. Indexation initiale¶

# Lancer l'indexation (1-2 minutes pour 93 learnings)
python3 scripts/index-learnings.py

Sortie attendue :

📖 Chargement learnings.jsonl...
   93 learnings chargés
🤖 Génération embeddings Ollama (nomic-embed-text)...
   10/93 embeddings générés...
   20/93 embeddings générés...
   ...
   90/93 embeddings générés...
🔍 Construction index FAISS...
💾 Sauvegarde...
✅ Indexation terminée
   Embeddings : data/learnings-embeddings.npy
   Index FAISS : data/learnings-index.faiss
   Métadonnées : data/embeddings-meta.json

Usage¶

Via skill /learnings (recommandé)¶

/learnings "Redis mocks incomplets"
/learnings "Validation Zod manquante"
/learnings "Tests coverage faible"

Via script direct¶

# Top 5 résultats (défaut)
python3 scripts/search-learnings.py "Redis mocks incomplets"

# Top 10 résultats
python3 scripts/search-learnings.py "Validation Zod" --top-k 10

Sortie attendue :

🔍 Recherche : "Redis mocks incomplets"

## 1. PD-103 (Gate 8, NON_CONFORME)
**Tags** : #backend, #test-coverage, #redis
**Learning** : Redis mocks incomplets dans tests d'intégration — reconnexion non testée
**Score** : 0.2341

## 2. PD-087 (Gate 8, RESERVE)
**Tags** : #backend, #test-doubles
**Learning** : Mocks insuffisants pour services externes (Redis, S3)
**Score** : 0.3156

...

Fallback grep¶

Si Ollama est inaccessible (service down, timeout), le script bascule automatiquement en mode grep classique :

⚠️ Erreur Ollama : Connection refused. Fallback grep.

🔍 Recherche : "Redis mocks incomplets"

## 1. PD-103 (Gate 8, NON_CONFORME)
**Tags** : #backend, #test-coverage, #redis
**Learning** : Redis mocks incomplets dans tests d'intégration — reconnexion non testée
**Score** : 0.0000  # (grep n'a pas de score de similarité)

Le skill reste fonctionnel même sans Ollama (recherche textuelle dégradée).

Réindexation¶

Quand réindexer ? : - Après ajout de nouveaux learnings dans data/learnings.jsonl - Changement de modèle Ollama (rare)

Commande :

python3 scripts/index-learnings.py

Fréquence recommandée : Après chaque REX (étape 9) ou batch de learnings.

Cas d'usage¶

1. Éviter répétition erreurs¶

Avant de produire une spec ou un plan, rechercher learnings similaires :

/learnings "validation manquante"
/learnings "tests coverage faible"
/learnings "Redis reconnexion"

2. Identifier patterns récurrents¶

/learnings "ESLint disabled"
/learnings "any TypeScript"
/learnings "code dupliqué"

3. Capitaliser sur expériences passées¶

/learnings "NestJS guards"
/learnings "DTOs validation"
/learnings "error handling"

Limitations et Trade-offs¶

Sécurité¶

• ✅ 100% local (Ollama + FAISS)
• ✅ Pas de données envoyées en externe
• ✅ Pas de clé API requise
• ✅ Learnings sont publics (pas de données sensibles)

Troubleshooting¶

Erreur "Index FAISS non trouvé"¶

Lancer l'indexation initiale :

python3 scripts/index-learnings.py

Erreur "Connection refused" (Ollama)¶

Vérifier qu'Ollama tourne :

ollama list
# Si erreur, relancer Ollama
ollama serve

Erreur "ModuleNotFoundError: No module named 'requests'"¶

Installer les dépendances :

pip install -r requirements.txt

Ollama lent¶

Le premier embedding peut prendre quelques secondes (chargement modèle en mémoire). Les suivants sont instantanés (~50ms/embedding).

Métriques¶

Performance Ollama¶

• Premier embedding : 2-3 secondes (chargement modèle)
• Embeddings suivants : 50-100 ms
• Mémoire : ~500 MB (modèle en RAM)

Évolutions futures¶

• Filtres par tags (/learnings "Redis" --tags backend,cache)
• Recherche par score de gate (--min-score 6.0)
• Clustering des learnings (identifier patterns récurrents automatiquement)
• Embeddings incrémentales (réindexer seulement les nouveaux learnings)
• Support Ollama distant (IA-Server 192.168.1.82)

Ollama distant (optionnel)¶

Pour utiliser Ollama sur IA-Server (2× RTX 5090) au lieu du Mac :

# Modifier OLLAMA_URL dans les scripts
OLLAMA_URL = "http://192.168.1.82:11434/api/embeddings"

Avantages : - ✅ GPU puissant (génération plus rapide) - ✅ Libère ressources Mac - ⚠️ Nécessite accès réseau IA-Server

Auteur : Claude (Governance Workflow Orchestrator) Date : 2026-02-19 Version : 2.0.0 (Ollama local)