O modelo mistral-embed
Nesta página
Visão geral do mistral-embed
O mistral-embed é o modelo de incorporação de texto (text embedding) da Mistral AI. Transforma qualquer texto num vetor de 1024 dimensões, independentemente do comprimento da entrada — seja uma frase curta ou um parágrafo inteiro, o vetor de saída tem sempre o mesmo tamanho. Esta dimensionalidade fixa não é um detalhe menor: permite indexar tanto o título de um produto como a sua descrição completa no mesmo espaço vetorial e compará-los diretamente, sem qualquer processamento especial para reconciliar formatos diferentes.
Este modelo está otimizado para tarefas de pesquisa semântica, classificação e agrupamento (clustering) em texto de linguagem natural (artigos, documentos, conversas, entre outros). Utilize-o para indexar uma base de conhecimento, FAQs, transcrições de reuniões ou uma década de tickets de suporte.
Configuração e instalação
Antes de chamar a API, instale o SDK Python da Mistral e configure a sua chave de 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)
Obtenha a sua chave de API na consola da Mistral. Armazene-a numa variável de ambiente para a manter fora do seu código. A leitura através de os.environ.get não é apenas higiene teórica: impede que a sua chave acabe num snapshot do histórico do Git no dia em que o seu projeto se torna público.
Geração de incorporações (Embeddings)
A chamada à API é direta: passe uma lista de textos e recupere os vetores correspondentes. Note que, mesmo para um único texto, a entrada deve ser uma lista — a API funciona sempre em lotes (batches), o que compensa assim que o seu 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]}")
Saída típica:
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]
Estrutura da resposta da API
A resposta contém mais do que apenas vetores. Indica também qual o modelo que foi efetivamente utilizado e quantos tokens foram consumidos — duas informações que vai querer registar (log) assim que a codificação correr em produção e alguém precisar de explicar a fatura. Preste especial atenção ao campo index: indica a posição do texto na lista que enviou, permitindo mapear cada vetor de volta ao seu documento de origem.
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]
Exemplo completo: Codificar e armazenar
Eis um pipeline típico para codificar um corpus de documentos e preparar vetores para pesquisa futura. A mudança para o NumPy é o passo crítico: enquanto os seus vetores forem listas Python, cada cálculo de similaridade ocorre elemento por elemento; assim que construir uma matriz, uma única operação compara a consulta contra todo o 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)
Guardar como .npy evita pagar para recodificar sempre que a sua aplicação reinicia. Num corpus de vários milhares de documentos, esta é a diferença entre um arranque instantâneo e vários minutos de chamadas à API faturadas.
Limites e boas práticas
Quatro fatores determinam a qualidade dos seus resultados. Primeiro, o comprimento máximo: o modelo trunca textos que são demasiado longos, e o truncamento é silencioso — um relatório de quarenta páginas codificado num único bloco representará efetivamente apenas o seu início. Prefira fragmentos (chunks) de 512 a 2048 tokens, abordados na lição sobre fragmentação.
Segundo, ao contrário de algumas outras APIs, o mistral-embed não distingue entre query e document: não existe tipo de entrada, basta passar o texto. Na prática, as perguntas dos utilizadores e os documentos indexados passam pela mesma chamada com os mesmos parâmetros, simplificando o seu código de pesquisa.
O terceiro ponto é o custo: as incorporações são faturadas por token. Codificar mil documentos um por um custa o mesmo em tokens que codificá-los num lote, mas multiplica as idas e voltas na rede e o tempo de processamento; otimiza agrupando as chamadas, que é o tema da próxima lição sobre lotes (batching). Finalmente, o determinismo joga a seu favor: para o mesmo texto, o modelo devolve sempre o mesmo vetor. Pode, portanto, colocar em cache as incorporações pelo hash do texto e recodificar apenas o que realmente mudou entre duas versões de um documento.
Pontos-chave
- O mistral-embed produz vetores de 1024 dimensões para qualquer texto
- A API aceita uma lista de entradas e devolve os vetores correspondentes
- Os vetores são listas de números de vírgula flutuante, facilmente convertíveis em arrays NumPy
- Armazene as suas incorporações como uma matriz NumPy para cálculos de similaridade
- Lembre-se de dividir textos longos antes da codificação