Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Il modello mistral-embed

Lezione 2 di 18 Aggiornata il 2 novembre 2026 Sviluppatore
In questa pagina
  1. Panoramica di mistral-embed
  2. Configurazione e installazione
  3. Generazione degli embedding
  4. Struttura della risposta API
  5. Esempio completo: Codifica e archiviazione
  6. Limiti e best practice
  7. Punti chiave

Panoramica di mistral-embed

mistral-embed è il modello di text embedding di Mistral AI. Trasforma qualsiasi testo in un vettore a 1024 dimensioni, indipendentemente dalla lunghezza dell’input: che si tratti di una breve frase o di un intero paragrafo, il vettore di output ha sempre la stessa dimensione. Questa dimensionalità fissa non è un dettaglio trascurabile: ti permette di indicizzare sia il titolo di un prodotto che la sua descrizione completa nello stesso spazio vettoriale, per poi confrontarli direttamente senza alcun trattamento speciale per riconciliare formati diversi.

Questo modello è ottimizzato per compiti di ricerca semantica, classificazione e clustering su testi in linguaggio naturale (articoli, documenti, conversazioni e altro). Usalo per indicizzare una base di conoscenza, FAQ, trascrizioni di riunioni o un decennio di ticket di supporto.

Configurazione e installazione

Prima di chiamare l’API, installa l’SDK Python di Mistral e configura la tua chiave API:

# Installation
# pip install mistralai

import os
from mistralai.client import Mistral

# Initialize the client
api_key = os.environ.get("MISTRAL_API_KEY")
client = Mistral(api_key=api_key)

Recupera la tua chiave API dalla console di Mistral. Salvala in una variabile d’ambiente per tenerla fuori dal tuo codice. Leggerla tramite os.environ.get non è solo una questione di igiene teorica: impedisce che la tua chiave finisca in uno snapshot della cronologia Git il giorno in cui il tuo progetto diventa pubblico.

Generazione degli embedding

La chiamata API è semplice: passa una lista di testi e recupera i vettori corrispondenti. Nota che anche per un singolo testo, l’input deve essere una lista: l’API lavora sempre in batch, un vantaggio che si fa sentire non appena il tuo corpus cresce.

from mistralai.client import Mistral

client = Mistral(api_key=api_key)

# Generate embeddings for one or more texts
response = client.embeddings.create(
    model="mistral-embed",
    inputs=[
        "Embeddings capture semantic meaning.",
        "Mistral AI offers high-performance models.",
        "RAG improves response quality."
    ],
)

# Access the vectors
for i, data in enumerate(response.data):
    print(f"Text {i+1}: vector of {len(data.embedding)} dimensions")
    print(f"  First elements: {data.embedding[:5]}")

Output tipico:

Text 1: vector of 1024 dimensions
  First elements: [0.0234, -0.1567, 0.0891, 0.0123, -0.0456]
Text 2: vector of 1024 dimensions
  First elements: [0.0189, -0.1234, 0.0678, 0.0345, -0.0567]
Text 3: vector of 1024 dimensions
  First elements: [0.0312, -0.1456, 0.0789, 0.0234, -0.0345]

Struttura della risposta API

La risposta contiene più dei soli vettori. Ti indica anche quale modello è stato effettivamente utilizzato e quanti token sono stati consumati: due informazioni che vorrai registrare una volta che la codifica gira in produzione e qualcuno dovrà spiegare la fattura. Presta particolare attenzione al campo index: indica la posizione del testo nella lista che hai inviato, permettendoti di mappare ogni vettore al suo documento sorgente.

response = client.embeddings.create(
    model="mistral-embed",
    inputs=["Example text to encode."],
)

# Response object
print(response.model)          # "mistral-embed"
print(response.usage)          # tokens consumed

# Embedding data
embedding_data = response.data[0]
print(embedding_data.index)     # 0 (position in the inputs list)
print(len(embedding_data.embedding))  # 1024
print(type(embedding_data.embedding))  # list[float]

Esempio completo: Codifica e archiviazione

Ecco una pipeline tipica per codificare un corpus di documenti e preparare i vettori per una ricerca successiva. Il passaggio a NumPy è cruciale: finché i tuoi vettori sono liste Python, ogni calcolo di similarità avviene elemento per elemento; una volta costruita una matrice, una singola operazione confronta la query con l’intero corpus.

import numpy as np
from mistralai.client import Mistral

client = Mistral(api_key=api_key)

# Document corpus
documents = [
    "Mistral AI is a French artificial intelligence company.",
    "RAG combines information retrieval and text generation.",
    "Embeddings enable semantic search.",
    "Python is the most widely used language in data science.",
    "FAISS is a vector search library by Meta.",
]

# Encode all documents
response = client.embeddings.create(
    model="mistral-embed",
    inputs=documents,
)

# Convert to a NumPy matrix for calculations
embeddings_matrix = np.array([d.embedding for d in response.data])

print(f"Embeddings matrix: {embeddings_matrix.shape}")
# Embeddings matrix: (5, 1024)

# Save for later use
np.save("document_embeddings.npy", embeddings_matrix)

Salvare come .npy evita di pagare per ricodificare ogni volta che la tua applicazione si riavvia. Su un corpus di diverse migliaia di documenti, questa è la differenza tra un avvio istantaneo e diversi minuti di chiamate API fatturate.

Limiti e best practice

Quattro fattori determinano la qualità dei tuoi risultati. Primo, la lunghezza massima: il modello tronca i testi troppo lunghi e il troncamento è silenzioso: un rapporto di quaranta pagine codificato in un unico blocco rappresenterà effettivamente solo il suo inizio. Preferisci chunk da 512 a 2048 token, come trattato nella lezione sul chunking.

Secondo, a differenza di altre API, mistral-embed non distingue tra query e document: non esiste alcun tipo di input, passi semplicemente il testo. In pratica, le domande degli utenti e i documenti indicizzati passano attraverso la stessa chiamata con gli stessi parametri, semplificando il tuo codice di ricerca.

Il terzo punto è il costo: gli embedding sono fatturati per token. Codificare mille documenti uno per uno costa lo stesso in token che codificarli in batch, ma moltiplica i round trip di rete e i tempi di elaborazione; ottimizzi raggruppando le chiamate, argomento della prossima lezione sul batching. Infine, il determinismo lavora a tuo favore: per lo stesso testo, il modello restituisce sempre lo stesso vettore. Puoi quindi mettere in cache gli embedding per hash del testo e ricodificare solo ciò che è effettivamente cambiato tra due versioni di un documento.

Punti chiave

  • mistral-embed produce vettori a 1024 dimensioni per qualsiasi testo
  • L’API accetta una lista di input e restituisce i vettori corrispondenti
  • I vettori sono liste di float, facilmente convertibili in array NumPy
  • Archivia i tuoi embedding come matrice NumPy per i calcoli di similarità
  • Ricorda di suddividere i testi lunghi prima della codifica