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

Gerar embeddings para os seus dados

Aula 3 de 22 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Objetivos
  2. Preparar os seus dados
  3. Gerar embeddings em lotes
  4. Armazenar embeddings
  5. Pipeline completo: de ficheiros de texto a embeddings
  6. Estimar custos
  7. Pontos-chave

Objetivos

  • Preparar os seus dados de texto para a criação de embeddings
  • Gerar embeddings de forma eficiente e em larga escala
  • Armazenar vetores para utilização futura

Preparar os seus dados

A qualidade dos seus embeddings depende diretamente da qualidade dos seus dados. Um texto cheio de espaços em branco desnecessários, caracteres de controlo provenientes de uma exportação mal configurada ou quebras de linha erráticas produz um vetor ligeiramente incorreto. Esse desvio acumula-se em cada pesquisa. A limpeza não é cosmética: é a primeira e mais barata otimização de relevância.

import re

def nettoyer_texte(texte: str) -> str:
    """Prepares text for embedding."""
    # Remove multiple spaces
    texte = re.sub(r"\s+", " ", texte)
    # Remove control characters
    texte = re.sub(r"[\x00-\x08\x0b\x0c\x0e-\x1f]", "", texte)
    # Trim
    texte = texte.strip()
    return texte

# Example
brut = "  Texte   avec   des   espaces\n\n\nen trop  "
propre = nettoyer_texte(brut)
print(propre)  # "Texte avec des espaces en trop"

Enriquecer o contexto

Um excerto de documentação isolado perde parte do seu significado sem o respetivo título. Tome um parágrafo que começa com «Download the package from the official site»: fora de contexto, nada indica que se refere ao PostgreSQL, e o vetor resultante nunca corresponderá a uma consulta sobre PostgreSQL. Ao prefixar o conteúdo com o seu título e secção, reinjeta essa informação no texto que o modelo vê.

def enrichir_document(titre: str, section: str, contenu: str) -> str:
    """Creates enriched text for better embedding."""
    return f"Titre : {titre}\nSection : {section}\n\n{contenu}"

texte_enrichi = enrichir_document(
    titre="Installation de PostgreSQL",
    section="Getting Started Guide",
    contenu="Download the package from the official site..."
)

Gerar embeddings em lotes

Num corpus real de centenas ou milhares de documentos, o processamento deve ser feito em blocos e ser resiliente a falhas de rede. A função abaixo itera sobre os textos em fatias, ordena sistematicamente a resposta por index para garantir que o vetor nº 7 corresponde ao documento nº 7 e tenta novamente uma vez após uma pausa caso ocorra um erro.

from openai import OpenAI
import time
import json

client = OpenAI()

def generer_embeddings(
    textes: list[str],
    model: str = "text-embedding-3-large",
    batch_size: int = 100
) -> list[list[float]]:
    """Generates embeddings in batches with error handling."""
    tous_les_embeddings = []

    for i in range(0, len(textes), batch_size):
        batch = textes[i:i + batch_size]
        print(f"Processing batch {i // batch_size + 1}/"
              f"{(len(textes) - 1) // batch_size + 1}")

        try:
            response = client.embeddings.create(
                input=batch,
                model=model
            )
            # Sort by index to guarantee order
            batch_embeddings = sorted(
                response.data, key=lambda x: x.index
            )
            tous_les_embeddings.extend(
                [item.embedding for item in batch_embeddings]
            )
        except Exception as e:
            print(f"Error on batch {i}: {e}")
            # Retry after a pause
            time.sleep(5)
            response = client.embeddings.create(
                input=batch,
                model=model
            )
            batch_embeddings = sorted(
                response.data, key=lambda x: x.index
            )
            tous_les_embeddings.extend(
                [item.embedding for item in batch_embeddings]
            )

    return tous_les_embeddings

Ordenar por index é uma precaução que nunca deve ignorar. Um simples desvio silencioso de uma linha é suficiente para associar cada documento ao vetor do seu vizinho. O sintoma que observará é «a pesquisa devolve lixo», sem qualquer erro técnico que o oriente na direção certa.

Armazenar embeddings

Para um pequeno corpus de alguns milhares de documentos, um ficheiro JSON simples contendo textos, metadados e vetores funciona perfeitamente. Tem a vantagem de ser legível por humanos quando precisa de depurar um resultado estranho.

import json

documents = [
    {"id": 1, "texte": "Premier document...", "metadata": {"source": "faq"}},
    {"id": 2, "texte": "Deuxième document...", "metadata": {"source": "docs"}},
]

# Generate embeddings
textes = [d["texte"] for d in documents]
embeddings = generer_embeddings(textes)

# Add vectors to documents
for doc, emb in zip(documents, embeddings):
    doc["embedding"] = emb

# Save
with open("corpus_embeddings.json", "w") as f:
    json.dump(documents, f)

Além dessa escala, o JSON torna-se um gargalo: cada número é escrito por extenso, inchando o ficheiro e impondo uma análise dispendiosa em cada carregamento. O NumPy armazena os mesmos valores em binário com 4 bytes e recarrega instantaneamente.

import numpy as np

# Convert to NumPy matrix
matrice = np.array(embeddings, dtype=np.float32)
print(f"Shape : {matrice.shape}")  # (n_docs, 3072)

# Save in binary format
np.save("embeddings.npy", matrice)

# Load
matrice_chargee = np.load("embeddings.npy")

Pipeline completo: de ficheiros de texto a embeddings

Vamos reunir estes elementos numa função que lê uma pasta, limpa cada ficheiro, gera vetores e divide o armazenamento em dois: metadados em JSON (legível e editável) e a matriz em NumPy (compacta e rápida).

from openai import OpenAI
from pathlib import Path
import json
import numpy as np

client = OpenAI()

def pipeline_embeddings(dossier: str, model: str = "text-embedding-3-large"):
    """Complete pipeline: files → embeddings → storage."""
    dossier_path = Path(dossier)

    # 1. Read files
    documents = []
    for fichier in sorted(dossier_path.glob("*.txt")):
        contenu = fichier.read_text(encoding="utf-8")
        contenu = nettoyer_texte(contenu)
        if contenu:
            documents.append({
                "id": fichier.stem,
                "fichier": fichier.name,
                "texte": contenu
            })

    print(f"{len(documents)} documents found")

    # 2. Generate embeddings
    textes = [d["texte"] for d in documents]
    embeddings = generer_embeddings(textes, model=model)

    # 3. Save
    # Metadata in JSON
    meta = [{"id": d["id"], "fichier": d["fichier"]} for d in documents]
    with open("metadata.json", "w") as f:
        json.dump(meta, f, ensure_ascii=False, indent=2)

    # Vectors in NumPy
    np.save("embeddings.npy", np.array(embeddings, dtype=np.float32))

    print(f"Embeddings saved: {len(embeddings)} vectors "
          f"of {len(embeddings[0])} dimensions")

    return documents, embeddings

# Usage
documents, embeddings = pipeline_embeddings("./mes_documents/")

Note o sorted() no glob: sem ele, a ordem dos ficheiros depende do sistema de ficheiros, e os seus dois ficheiros de saída correm o risco de ficar dessincronizados após uma simples mudança de máquina.

Estimar custos

Antes de lançar um trabalho massivo, conte os tokens localmente com o tiktoken. A operação demora alguns segundos e evita que descubra tarde demais que um corpus mal filtrado continha dez vezes o volume esperado.

import tiktoken

encoder = tiktoken.get_encoding("cl100k_base")

def estimer_cout(textes: list[str], model: str = "text-embedding-3-large"):
    """Estimates embedding cost for a list of texts."""
    total_tokens = sum(len(encoder.encode(t)) for t in textes)

    # Approximate prices per million tokens (check current rates)
    prix = {
        "text-embedding-3-large": 0.13,
        "text-embedding-3-small": 0.02,
    }

    cout = total_tokens / 1_000_000 * prix.get(model, 0.13)
    print(f"Estimated tokens: {total_tokens:,}")
    print(f"Estimated cost: ${cout:.4f}")
    return total_tokens, cout

Os preços no dicionário são indicativos e envelhecem rapidamente: verifique sempre as tarifas atuais antes de apresentar um orçamento a um cliente.

Pontos-chave

  • Limpe e enriqueça os seus textos antes de gerar embeddings
  • Utilize processamento em lotes para grandes corpora
  • Armazene metadados em JSON e vetores em NumPy
  • Estime os seus custos antes de lançar um trabalho massivo