Créer des embeddings
In questa pagina
Encoder les chunks en vecteurs
Tes documents sont désormais découpés en chunks propres. L’étape suivante consiste à les transformer en embeddings via l’API mistral-embed, puis à stocker ces vecteurs dans une base vectorielle qui servira de moteur de recherche. C’est l’instant où ton corpus cesse d’être du texte brut pour devenir une géométrie interrogeable. Quelques précautions d’ingénierie—mise par lots, nouvelles tentatives et persistance—font la différence entre un prototype fragile et un index fiable.
Pour un petit corpus, disons moins d’une centaine de chunks, un seul appel direct suffit. Extrais le texte de tes dictionnaires de chunks, passe-les tels quels à l’API et récupère la matrice complète. La forme (87, 1024) affichée à la fin de l’exécution est ton premier contrôle de cohérence : autant de lignes que de chunks, et 1024 colonnes car c’est la dimension de mistral-embed. Si le nombre de lignes ne correspond pas, un chunk vide s’est glissé dans le lot.
import numpy as np
from mistralai.client import Mistral
client = Mistral(api_key=api_key)
# Assume chunks is the list of our prepared chunks
chunk_texts = [c["text"] for c in chunks]
# Encode in a single call
response = client.embeddings.create(
model="mistral-embed",
inputs=chunk_texts,
)
embeddings = np.array([d.embedding for d in response.data])
print(f"Embeddings: {embeddings.shape}")
# Embeddings: (87, 1024) for example
Encodage par lots
Au-delà de quelques dizaines de chunks, un appel unique atteint les limites de l’API. La solution consiste à diviser la liste en lots et à concaténer les résultats. La fonction ci-dessous traite des tranches de 25 éléments et affiche la progression. Ce n’est pas cosmétique : sur un corpus de plusieurs milliers de chunks, l’encodage prend plusieurs minutes, et tu voudras savoir où en est le processus plutôt que de fixer un terminal silencieux. L’ordre est préservé, donc chaque vecteur reste aligné avec son chunk correspondant dans ta liste d’origine.
def encode_chunks(chunks, batch_size=25, model="mistral-embed"):
"""Encode a list of chunks in batches."""
texts = [c["text"] for c in chunks]
all_embeddings = []
for i in range(0, len(texts), batch_size):
batch = texts[i:i + batch_size]
print(f" Encoding batch {i // batch_size + 1}/{(len(texts) - 1) // batch_size + 1} "
f"({len(batch)} chunks)...")
response = client.embeddings.create(
model=model,
inputs=batch,
)
all_embeddings.extend([d.embedding for d in response.data])
return np.array(all_embeddings)
# Encode all chunks
embeddings = encode_chunks(chunks, batch_size=25)
print(f"Total: {embeddings.shape[0]} vectors of {embeddings.shape[1]} dimensions")
Survivre aux erreurs réseau
En production, un appel API finira par échouer : coupure réseau, limite de débit atteinte ou panne temporaire. Sans protection, ton indexation s’arrête au lot 180 sur 400, et tu repars de zéro. La version robuste enveloppe chaque lot dans une boucle de nouvelle tentative avec un backoff exponentiel—une seconde, puis deux, puis quatre. Cet espacement croissant compte : retenter immédiatement après un rejet de quota ne fait qu’aggraver les choses. Après trois échecs consécutifs, la fonction lève une exception explicite nommant le lot fautif, plutôt que de renvoyer une matrice tronquée où tu ne découvriras le trou que lors de la recherche.
import time
def encode_chunks_robust(chunks, batch_size=25, max_retries=3):
"""Robust encoding with error handling."""
texts = [c["text"] for c in chunks]
all_embeddings = []
for i in range(0, len(texts), batch_size):
batch = texts[i:i + batch_size]
for attempt in range(max_retries):
try:
response = client.embeddings.create(
model="mistral-embed",
inputs=batch,
)
all_embeddings.extend([d.embedding for d in response.data])
break # Success, exit retry loop
except Exception as e:
wait_time = 2 ** attempt # Exponential backoff: 1s, 2s, 4s
print(f" Error in batch {i // batch_size + 1}, "
f"attempt {attempt + 1}/{max_retries}: {e}")
if attempt < max_retries - 1:
print(f" Waiting {wait_time}s before retry...")
time.sleep(wait_time)
else:
raise RuntimeError(
f"Failed after {max_retries} attempts for batch {i // batch_size + 1}"
)
return np.array(all_embeddings)
Sauvegarder l’index sur disque
Chaque exécution d’encodage coûte du temps et des appels API facturés. Recalculer les vecteurs à chaque démarrage de ton application est un pur gaspillage, surtout puisque le corpus lui-même n’a pas changé. La sauvegarde se fait en deux fichiers complémentaires : les vecteurs vont dans NumPy, un format binaire compact qui se charge instantanément, tandis que les métadonnées—texte, source, position—vont dans un JSON lisible que tu peux ouvrir pour inspecter un chunk suspect. Les deux fichiers sont interdépendants, liés par l’ordre des lignes : ne régénère jamais l’un sans l’autre, sinon tes résultats de recherche pointeront vers les mauvais textes.
import json
def save_index(chunks, embeddings, filepath="rag_index"):
"""Save chunks and embeddings."""
# Save embeddings (NumPy)
np.save(f"{filepath}_embeddings.npy", embeddings)
# Save metadata (JSON)
metadata = []
for c in chunks:
metadata.append({
"text": c["text"],
"source": c.get("source", ""),
"chunk_index": c.get("chunk_index", 0),
})
with open(f"{filepath}_metadata.json", "w", encoding="utf-8") as f:
json.dump(metadata, f, ensure_ascii=False, indent=2)
print(f"Index saved: {len(chunks)} chunks, {embeddings.shape}")
def load_index(filepath="rag_index"):
"""Load chunks and embeddings from disk."""
embeddings = np.load(f"{filepath}_embeddings.npy")
with open(f"{filepath}_metadata.json", "r", encoding="utf-8") as f:
metadata = json.load(f)
print(f"Index loaded: {len(metadata)} chunks, {embeddings.shape}")
return metadata, embeddings
# Save
save_index(chunks, embeddings)
# Load (on next startup)
chunks_loaded, embeddings_loaded = load_index()
Vérifier avant de continuer
Un index corrompu silencieusement se révèle tard, généralement lorsqu’un utilisateur signale une réponse absurde. Quelques vérifications hors ligne prennent trente secondes et t’évitent cette découverte. La fonction de vérification affiche d’abord des métriques de base—nombre de chunks, dimension, norme moyenne—puis mesure la similarité entre les chunks voisins : comme ils proviennent du même document, ils devraient afficher des valeurs significativement plus élevées que deux passages aléatoires. Le dernier test est le plus simple et le plus révélateur : un chunk comparé à lui-même doit donner exactement 1,0. Toute autre valeur signale un problème d’alignement ou de conversion numérique.
from sklearn.metrics.pairwise import cosine_similarity
def verify_embeddings(chunks, embeddings, n_tests=5):
"""Verify embedding quality with simple tests."""
print("=== Verifying embeddings ===")
print(f"Number of chunks: {len(chunks)}")
print(f"Dimensions: {embeddings.shape[1]}")
print(f"Average norm: {np.linalg.norm(embeddings, axis=1).mean():.4f}")
# Test: chunks from the same document should be closer
for i in range(min(n_tests, len(chunks) - 1)):
sim = cosine_similarity([embeddings[i]], [embeddings[i + 1]])[0][0]
print(f" Similarity chunk {i} <-> {i+1}: {sim:.4f}")
# Test: a chunk compared to itself = 1.0
self_sim = cosine_similarity([embeddings[0]], [embeddings[0]])[0][0]
print(f" Self-similarity (must be 1.0): {self_sim:.6f}")
verify_embeddings(chunks, embeddings)
Assemblées, les étapes du flux de travail se résument à quatre lignes utiles. Tu prépares les chunks avec le pipeline de la leçon précédente, encodes en mode robuste, vérifies et sauvegardes. Voici le script que tu relanceras à chaque mise à jour du corpus.
# 1. Prepare chunks (previous lesson)
chunks = prepare_documents(raw_docs)
# 2. Encode
embeddings = encode_chunks_robust(chunks, batch_size=25)
# 3. Verify
verify_embeddings(chunks, embeddings)
# 4. Save
save_index(chunks, embeddings)
print("Index ready for search!")
Punti chiave
- Utilise la mise par lots pour encoder les grands corpus (lots de 25 à 50 chunks)
- Ajoute une logique de nouvelle tentative avec backoff exponentiel pour la robustesse
- Sauvegarde les embeddings sur disque (NumPy) pour éviter le recalcul
- Conserve les métadonnées (texte, source, position) dans un fichier JSON séparé
- Vérifie la qualité des embeddings avant de les utiliser en production