Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Créer des embeddings

Lezione 11 di 18 Aggiornata il 2 novembre 2026 Sviluppatore
In questa pagina
  1. Encoder les chunks en vecteurs
  2. Encodage par lots
  3. Survivre aux erreurs réseau
  4. Sauvegarder l’index sur disque
  5. Vérifier avant de continuer
  6. Punti chiave

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