Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Tipi di dati e dimensioni

Lezione 7 di 18 Aggiornata il 2 novembre 2026 Sviluppatore
In questa pagina
  1. Ottimizzazione di dimensioni e qualità
  2. I cinque tipi di output
  3. Impatto sulla qualità
  4. Riduzione delle dimensioni
  5. Guida alla selezione
  6. Punti chiave

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:

ContestoConfigurazioneMotivo
Prototipo / sviluppofloat + 1536 dimspredefinito, nessun compromesso
Produzione standardfloat + 1024 dimsbuon equilibrio qualità/costo
Alto volume (milioni di vettori)int8 + 768 dims4 volte più compatto
Ricerca in tempo reale su larga scalabinary + 1536 dimspre-filtraggio veloce, poi ri-classifica in float
Embedded / edgeint8 + 256 dimsminimo 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