Tipos de Dados e Dimensões
Nesta página
Otimização de Tamanho e Qualidade
O codestral-embed oferece-lhe controlo preciso sobre dois eixos: o número de dimensões e o tipo de dados (dtype) dos valores. Estes parâmetros permitem-lhe ajustar o equilíbrio entre a qualidade da pesquisa e os custos de armazenamento ou de computação.
Isto torna-se crítico à medida que os volumes crescem. Um índice de dois milhões de funções com 1536 dimensões em ponto flutuante pesa cerca de doze gigabytes e já não cabe na memória de uma máquina standard; o mesmo índice em int8 com 768 dimensões desce para abaixo de um gigabyte e volta a ser consultável em tempo real. É esta aritmética, e não uma preferência estética, que deve guiar as suas escolhas.
Os Cinco Tipos de Saída
float (padrão)
O tipo float produz valores de ponto flutuante de 32 bits. Este é o formato mais preciso, ideal quando a qualidade tem prioridade sobre o espaço de armazenamento.
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
Cada dimensão é um inteiro entre -128 e 127. Isto utiliza 4 vezes menos memória do que o float32 com uma perda de qualidade mínima. Compare os valores apresentados com os do exemplo anterior: é o mesmo vetor, quantizado para uma escala mais grosseira, e a classificação dos resultados permanece praticamente inalterada.
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
Semelhante ao int8, mas com valores entre 0 e 255 (sem sinal). Útil para certos motores de pesquisa vetorial que apenas aceitam valores positivos — uma restrição que geralmente descobre durante a integração, e não antes.
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
O formato mais compacto. Cada dimensão é quantizada para 1 bit, sendo depois os bits agrupados em pacotes de 8 em valores int8. O vetor resultante é 32 vezes menor do que o float — o comprimento de 192 apresentado abaixo corresponde exatamente às 1536 dimensões originais, empacotadas de oito em oito.
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
Idêntico ao binary, mas com valores uint8 (0-255) em vez de int8 (-128 a 127). A escolha entre os dois depende do que o seu motor de armazenamento a jusante aceita, e não da qualidade da pesquisa.
Impacto na Qualidade
Os números de compressão não lhe dizem o que está realmente a perder. A função seguinte mede isto num exemplo concreto: um teste de palíndromo, consultado em francês, codificado sucessivamente com três dtypes. As similaridades resultantes dão-lhe a ordem de grandeza da degradação nos seus próprios dados.
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}")
Note que o código e a consulta são sempre codificados com o mesmo dtype dentro do ciclo. Misturar tipos entre o índice e a consulta produziria pontuações inconsistentes, e o erro é tanto mais insidioso quanto não levanta nenhuma exceção.
Redução de Dimensões
O parâmetro output_dimension controla o número de dimensões no vetor. O ciclo abaixo itera sobre seis valores e apresenta a pegada de memória de um único vetor para cada um, primeiro em float e depois em 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)")
Saída:
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)
Multiplique a coluna da direita pelo seu número real de vetores e obtém imediatamente o dimensionamento do seu servidor. Entre 3072 dimensões em float e 768 em int8, a razão é de dezasseis: o mesmo índice passa de doze gigabytes para setecentos e cinquenta megabytes.
Guia de Seleção
As configurações seguintes cobrem os cenários mais frequentes:
| Contexto | Configuração | Motivo |
|---|---|---|
| Protótipo / desenvolvimento | float + 1536 dims | padrão, sem compromissos |
| Produção standard | float + 1024 dims | bom equilíbrio qualidade/custo |
| Alto volume (milhões de vetores) | int8 + 768 dims | 4x mais compacto |
| Pesquisa em tempo real em larga escala | binary + 1536 dims | pré-filtragem rápida, depois reclassificação em float |
| Incorporado / edge | int8 + 256 dims | mínimo viável |
A linha “tempo real” descreve uma arquitetura de duas etapas que vale a pena compreender: o índice binary muito leve serve para recuperar algumas centenas de candidatos em milissegundos; apenas estes candidatos são depois reclassificados utilizando os vetores float, que são mais dispendiosos mas muito mais finos. Obtém a velocidade do binary e, no topo da lista, a precisão do float.
Pontos-chave
- O codestral-embed suporta 5 tipos de saída: float, int8, uint8, binary, ubinary
- O tipo binary é 32 vezes mais compacto que o float, com perda de qualidade aceitável para pré-filtragem
- As primeiras dimensões contêm a maior parte da informação (representação Matryoshka)
- Combine dimensões reduzidas + int8 para índices muito compactos
- Teste sempre nos seus dados reais antes de escolher os parâmetros de produção