Criar Embeddings
Nesta página
Codificar Fragmentos em Vetores
Os seus documentos estão agora divididos em fragmentos limpos. O passo seguinte é transformá-los em embeddings através da API mistral-embed e, de seguida, armazenar esses vetores numa base de dados vetorial que funcionará como o seu motor de pesquisa. É neste momento que o seu corpus deixa de ser texto simples para se tornar geometria consultável. Algumas precauções de engenharia — loteamento, novas tentativas e persistência — fazem a diferença entre um protótipo frágil e um índice fiável.
Para um corpus pequeno, digamos menos de cem fragmentos, uma única chamada direta é suficiente. Extraia o texto dos seus dicionários de fragmentos, passe-os tal como estão para a API e recupere a matriz completa. A forma (87, 1024) apresentada no final da execução é a sua primeira verificação de sanidade: tantas linhas quantos os fragmentos e 1024 colunas, pois essa é a dimensão do mistral-embed. Se a contagem de linhas não corresponder, algum fragmento vazio slipped into the batch (entrou no lote).
import numpy as np
from mistralai.client import Mistral
client = Mistral(api_key=api_key)
# Assume chunks is the list of our prepared chunks
chunk_texts = [c["text"] for c in chunks]
# Encode in a single call
response = client.embeddings.create(
model="mistral-embed",
inputs=chunk_texts,
)
embeddings = np.array([d.embedding for d in response.data])
print(f"Embeddings: {embeddings.shape}")
# Embeddings: (87, 1024) for example
Codificação em Lotes
Para além de algumas dezenas de fragmentos, uma única chamada atinge os limites da API. A solução consiste em dividir a lista em lotes e concatenar os resultados. A função abaixo processa fatias de 25 e mostra o progresso. Isto não é cosmético: num corpus de vários milhares de fragmentos, a codificação demora vários minutos e vai querer saber onde o processo está, em vez de ficar a olhar para um terminal silencioso. A ordem é preservada, pelo que cada vetor permanece alinhado com o seu fragmento correspondente na sua lista original.
def encode_chunks(chunks, batch_size=25, model="mistral-embed"):
"""Encode a list of chunks in batches."""
texts = [c["text"] for c in chunks]
all_embeddings = []
for i in range(0, len(texts), batch_size):
batch = texts[i:i + batch_size]
print(f" Encoding batch {i // batch_size + 1}/{(len(texts) - 1) // batch_size + 1} "
f"({len(batch)} chunks)...")
response = client.embeddings.create(
model=model,
inputs=batch,
)
all_embeddings.extend([d.embedding for d in response.data])
return np.array(all_embeddings)
# Encode all chunks
embeddings = encode_chunks(chunks, batch_size=25)
print(f"Total: {embeddings.shape[0]} vectors of {embeddings.shape[1]} dimensions")
Sobreviver a Erros de Rede
Em produção, uma chamada à API acabará por falhar: queda de rede, limite de taxa atingido ou indisponibilidade temporária. Sem proteção, a sua indexação para no lote 180 de 400 e fica novamente no início. A versão robusta envolve cada lote num ciclo de novas tentativas com backoff exponencial — um segundo, depois dois, depois quatro. Este espaçamento crescente é importante: tentar novamente imediatamente após uma rejeição de quota só piora as coisas. Após três falhas consecutivas, a função lança uma exceção explícita que identifica o lote defeituoso, em vez de devolver uma matriz truncada onde só descobriria a lacuna durante a pesquisa.
import time
def encode_chunks_robust(chunks, batch_size=25, max_retries=3):
"""Robust encoding with error handling."""
texts = [c["text"] for c in chunks]
all_embeddings = []
for i in range(0, len(texts), batch_size):
batch = texts[i:i + batch_size]
for attempt in range(max_retries):
try:
response = client.embeddings.create(
model="mistral-embed",
inputs=batch,
)
all_embeddings.extend([d.embedding for d in response.data])
break # Success, exit retry loop
except Exception as e:
wait_time = 2 ** attempt # Exponential backoff: 1s, 2s, 4s
print(f" Error in batch {i // batch_size + 1}, "
f"attempt {attempt + 1}/{max_retries}: {e}")
if attempt < max_retries - 1:
print(f" Waiting {wait_time}s before retry...")
time.sleep(wait_time)
else:
raise RuntimeError(
f"Failed after {max_retries} attempts for batch {i // batch_size + 1}"
)
return np.array(all_embeddings)
Guardar o Índice no Disco
Cada execução de codificação custa tempo e chamadas à API faturadas. Recalcular vetores sempre que a sua aplicação inicia é um desperdício puro, especialmente porque o próprio corpus não mudou. A gravação ocorre em dois ficheiros complementares: os vetores vão para o NumPy, um formato binário compacto que carrega instantaneamente, enquanto os metadados — texto, origem, posição — vão para um JSON legível que pode abrir para inspecionar um fragmento suspeito. Os dois ficheiros são interdependentes, ligados pela ordem das linhas: nunca regenere um sem o outro, ou os seus resultados de pesquisa apontarão para os textos errados.
import json
def save_index(chunks, embeddings, filepath="rag_index"):
"""Save chunks and embeddings."""
# Save embeddings (NumPy)
np.save(f"{filepath}_embeddings.npy", embeddings)
# Save metadata (JSON)
metadata = []
for c in chunks:
metadata.append({
"text": c["text"],
"source": c.get("source", ""),
"chunk_index": c.get("chunk_index", 0),
})
with open(f"{filepath}_metadata.json", "w", encoding="utf-8") as f:
json.dump(metadata, f, ensure_ascii=False, indent=2)
print(f"Index saved: {len(chunks)} chunks, {embeddings.shape}")
def load_index(filepath="rag_index"):
"""Load chunks and embeddings from disk."""
embeddings = np.load(f"{filepath}_embeddings.npy")
with open(f"{filepath}_metadata.json", "r", encoding="utf-8") as f:
metadata = json.load(f)
print(f"Index loaded: {len(metadata)} chunks, {embeddings.shape}")
return metadata, embeddings
# Save
save_index(chunks, embeddings)
# Load (on next startup)
chunks_loaded, embeddings_loaded = load_index()
Verificar Antes de Continuar
Um índice corrompido silenciosamente manifesta-se tarde, geralmente quando um utilizador reporta uma resposta absurda. Algumas verificações offline demoram trinta segundos e poupam-no a essa descoberta. A função de verificação apresenta primeiro métricas básicas — número de fragmentos, dimensão, norma média — e depois mede a similaridade entre fragmentos vizinhos: como provêm do mesmo documento, devem apresentar valores significativamente mais altos do que duas passagens aleatórias. O último teste é o mais simples e revelador: um fragmento comparado consigo mesmo deve resultar exatamente em 1,0. Qualquer outro valor sinaliza um problema de alinhamento ou de conversão numérica.
from sklearn.metrics.pairwise import cosine_similarity
def verify_embeddings(chunks, embeddings, n_tests=5):
"""Verify embedding quality with simple tests."""
print("=== Verifying embeddings ===")
print(f"Number of chunks: {len(chunks)}")
print(f"Dimensions: {embeddings.shape[1]}")
print(f"Average norm: {np.linalg.norm(embeddings, axis=1).mean():.4f}")
# Test: chunks from the same document should be closer
for i in range(min(n_tests, len(chunks) - 1)):
sim = cosine_similarity([embeddings[i]], [embeddings[i + 1]])[0][0]
print(f" Similarity chunk {i} <-> {i+1}: {sim:.4f}")
# Test: a chunk compared to itself = 1.0
self_sim = cosine_similarity([embeddings[0]], [embeddings[0]])[0][0]
print(f" Self-similarity (must be 1.0): {self_sim:.6f}")
verify_embeddings(chunks, embeddings)
No seu conjunto, o fluxo de trabalho resume-se a quatro linhas úteis. Prepara os fragmentos com o pipeline da lição anterior, codifica no modo robusto, verifica e guarda. Este é o script que voltará a executar sempre que o corpus for atualizado.
# 1. Prepare chunks (previous lesson)
chunks = prepare_documents(raw_docs)
# 2. Encode
embeddings = encode_chunks_robust(chunks, batch_size=25)
# 3. Verify
verify_embeddings(chunks, embeddings)
# 4. Save
save_index(chunks, embeddings)
print("Index ready for search!")
Pontos-chave
- Utilize o loteamento para codificar grandes corpora (lotes de 25–50 fragmentos)
- Adicione lógica de novas tentativas com backoff exponencial para robustez
- Guarde os embeddings no disco (NumPy) para evitar recálculos
- Mantenha os metadados (texto, origem, posição) num ficheiro JSON separado
- Verifique a qualidade dos embeddings antes de os utilizar em produção