Gerar embeddings para os seus dados
Nesta página
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