Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Criar Embeddings

Aula 11 de 18 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. Codificar Fragmentos em Vetores
  2. Codificação em Lotes
  3. Sobreviver a Erros de Rede
  4. Guardar o Índice no Disco
  5. Verificar Antes de Continuar
  6. Pontos-chave

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