Tipi di dati e dimensioni
In questa pagina
Ottimizzazione di dimensioni e qualità
codestral-embed ti offre un controllo preciso su due assi: il numero di dimensioni e il tipo di dato (dtype) dei valori. Questi parametri ti permettono di bilanciare la qualità della ricerca con i costi di archiviazione o di calcolo.
Questo aspetto diventa critico man mano che i volumi crescono. Un indice di due milioni di funzioni a 1536 dimensioni float occupa circa dodici gigabyte e non entra più nella memoria di una macchina standard; lo stesso indice in int8 a 768 dimensioni scende sotto un gigabyte e torna interrogabile in tempo reale. È questa aritmetica, non una preferenza estetica, a dover guidare le tue scelte.
I cinque tipi di output
float (predefinito)
Il tipo float produce valori floating-point a 32 bit. È il formato più preciso, ideale quando la qualità ha la priorità sullo spazio di archiviazione.
from mistralai.client import Mistral
client = Mistral(api_key=api_key)
response = client.embeddings.create(
model="codestral-embed",
output_dtype="float",
inputs=["def hello(): print('world')"],
)
embedding = response.data[0].embedding
print(f"Type: float, Values: {embedding[:5]}")
# [0.0234375, -0.15625, 0.08984375, 0.01171875, -0.046875]
int8
Ogni dimensione è un intero compreso tra -128 e 127. Questo formato utilizza 4 volte meno memoria rispetto a float32 con una perdita di qualità minima. Confronta i valori visualizzati con quelli dell’esempio precedente: si tratta dello stesso vettore, quantizzato su una scala più grossolana, e la classifica dei risultati rimane quasi invariata.
response = client.embeddings.create(
model="codestral-embed",
output_dtype="int8",
inputs=["def hello(): print('world')"],
)
embedding = response.data[0].embedding
print(f"Type: int8, Values: {embedding[:5]}")
# [3, -20, 11, 1, -6]
uint8
Simile a int8, ma con valori compresi tra 0 e 255 (senza segno). Utile per alcuni motori di ricerca vettoriale che accettano solo valori positivi, un vincolo che scopri solitamente durante l’integrazione e non prima.
response = client.embeddings.create(
model="codestral-embed",
output_dtype="uint8",
inputs=["def hello(): print('world')"],
)
embedding = response.data[0].embedding
print(f"Type: uint8, Values: {embedding[:5]}")
# [131, 108, 139, 129, 122]
binary
Il formato più compatto. Ogni dimensione viene quantizzata a 1 bit, quindi i bit sono raggruppati in pacchetti da 8 in valori int8. Il vettore risultante è 32 volte più piccolo di float: la lunghezza di 192 mostrata di seguito corrisponde esattamente alle 1536 dimensioni originali, impacchettate otto per otto.
response = client.embeddings.create(
model="codestral-embed",
output_dtype="binary",
inputs=["def hello(): print('world')"],
)
embedding = response.data[0].embedding
print(f"Type: binary, Length: {len(embedding)}")
# Length: 192 (instead of 1536 in float)
ubinary
Identico a binary, ma con valori uint8 (0-255) invece di int8 (-128 a 127). La scelta tra i due dipende da ciò che il tuo motore di archiviazione a valle accetta, non dalla qualità della ricerca.
Impatto sulla qualità
Le cifre di compressione non ti dicono cosa stai effettivamente perdendo. La funzione seguente lo misura su un esempio concreto: un test per i palindromi, interrogato in francese, codificato successivamente con tre dtype diversi. Le similarità risultanti ti danno l’ordine di grandezza del degrado sui tuoi dati reali.
import numpy as np
from sklearn.metrics.pairwise import cosine_similarity
def compare_dtypes(code_snippet, query):
"""Compare search quality by dtype."""
dtypes = ["float", "int8", "uint8"]
results = {}
for dtype in dtypes:
# Encode code and query with the same dtype
resp_code = client.embeddings.create(
model="codestral-embed",
output_dtype=dtype,
inputs=[code_snippet],
)
resp_query = client.embeddings.create(
model="codestral-embed",
output_dtype=dtype,
inputs=[query],
)
emb_code = np.array(resp_code.data[0].embedding, dtype=np.float32)
emb_query = np.array(resp_query.data[0].embedding, dtype=np.float32)
sim = cosine_similarity([emb_code], [emb_query])[0][0]
results[dtype] = sim
return results
# Test
code = "def is_palindrome(s): return s == s[::-1]"
query = "fonction qui vérifie si un mot est un palindrome"
scores = compare_dtypes(code, query)
for dtype, score in scores.items():
print(f" {dtype:8s}: similarity = {score:.4f}")
Nota che il codice e la query sono sempre codificati con lo stesso dtype all’interno del ciclo. Mescolare i tipi tra l’indice e la query produrrebbe punteggi incoerenti, e l’errore è tanto più insidioso perché non genera alcuna eccezione.
Riduzione delle dimensioni
Il parametro output_dimension controlla il numero di dimensioni nel vettore. Il ciclo seguente iterava su sei valori e visualizza l’impronta di memoria di un singolo vettore per ciascuno, prima in float e poi in int8.
import numpy as np
# Compare different dimensions
dims = [256, 512, 768, 1024, 1536, 3072]
for dim in dims:
response = client.embeddings.create(
model="codestral-embed",
output_dimension=dim,
inputs=["def quicksort(arr): ..."],
)
emb = response.data[0].embedding
# Approximate memory size
size_float32 = dim * 4 # 4 bytes per float32
size_int8 = dim * 1 # 1 byte per int8
print(f" {dim:5d} dims -> {size_float32:6d} bytes (float) | {size_int8:5d} bytes (int8)")
Output:
256 dims -> 1024 bytes (float) | 256 bytes (int8)
512 dims -> 2048 bytes (float) | 512 bytes (int8)
768 dims -> 3072 bytes (float) | 768 bytes (int8)
1024 dims -> 4096 bytes (float) | 1024 bytes (int8)
1536 dims -> 6144 bytes (float) | 1536 bytes (int8)
3072 dims -> 12288 bytes (float) | 3072 bytes (int8)
Moltiplica la colonna di destra per il tuo numero effettivo di vettori e ottieni immediatamente il dimensionamento del tuo server. Tra 3072 dimensioni in float e 768 in int8, il rapporto è sedici: lo stesso indice passa da dodici gigabyte a settecentocinquanta megabyte.
Guida alla selezione
Le configurazioni seguenti coprono gli scenari più frequenti:
| Contesto | Configurazione | Motivo |
|---|---|---|
| Prototipo / sviluppo | float + 1536 dims | predefinito, nessun compromesso |
| Produzione standard | float + 1024 dims | buon equilibrio qualità/costo |
| Alto volume (milioni di vettori) | int8 + 768 dims | 4 volte più compatto |
| Ricerca in tempo reale su larga scala | binary + 1536 dims | pre-filtraggio veloce, poi ri-classifica in float |
| Embedded / edge | int8 + 256 dims | minimo vitale |
La riga “tempo reale” descrive un’architettura a due stadi che vale la pena comprendere: l’indice binary molto leggero serve a recuperare alcune centinaia di candidati in millisecondi; solo questi candidati vengono poi ri-classificati utilizzando i vettori float, che sono più costosi ma molto più fini. Ottieni la velocità del binary e, in cima alla lista, la precisione del float.
Punti chiave
- codestral-embed supporta 5 tipi di output: float, int8, uint8, binary, ubinary
- Il tipo binary è 32 volte più compatto di float, con una perdita di qualità accettabile per il pre-filtraggio
- Le prime dimensioni contengono la maggior parte delle informazioni (rappresentazione Matryoshka)
- Combina dimensioni ridotte + int8 per indici molto compatti
- Testa sempre sui tuoi dati reali prima di scegliere i parametri di produzione