Afinamento de embeddings
Nesta página
Objetivos
- Compreender quando é necessário afinar embeddings
- Preparar um conjunto de dados de pares para treino
- Implementar o afinamento com adaptadores leves
Quando afinar?
Comecemos pelas más notícias, que na verdade são boas: na maioria dos casos, os modelos de embeddings pré-treinados funcionam perfeitamente e o afinamento é um desperdício de esforço. Apenas três situações justificam verdadeiramente esta prática. A primeira é um domínio com vocabulário altamente especializado — medicina, direito, indústria — onde o modelo genérico não sabe que “IAM” e “enfarte do miocárdio” se referem à mesma coisa. A segunda é atingir um platô: otimizou o fracionamento, adicionou pesquisa híbrida e reranking, e as métricas não evoluem. A terceira é simplesmente ter à mão pares de texto anotados, semelhantes ou dissimilares, parados nos seus registos de pesquisa.
Por outro lado, prescinda do afinamento se tiver menos de mil pares anotados: o treino memorizará os seus exemplos sem generalizar. Prescinda também se o desempenho já for satisfatório — um ganho de dois pontos na revocação não justifica a manutenção de um modelo extra. E, acima de tudo, verifique se um melhor fracionamento ou um melhor prompt não resolverão o problema: é quase sempre mais barato e rápido.
Abordagem 1: Adaptador linear (Matryoshka)
A abordagem mais económica deixa o modelo de embeddings intocado. Permite-lhe produzir os seus vetores e, em seguida, treina uma pequena camada de projeção por cima que deforma o espaço para aproximar o que precisa de estar próximo no seu domínio. O modelo da OpenAI permanece uma caixa negra acedida via API; apenas algumas centenas de milhares de parâmetros são treinados, em CPU, em minutos.
O treino baseia-se em tripletos: uma consulta, um documento que a responde e um documento que cobre o mesmo tópico mas não responde. Observe os exemplos médicos abaixo: o negativo para “efeitos secundários do paracetamol” não é um texto sobre futebol, mas um texto sobre paracetamol vendido em farmácias. Isto chama-se um negativo difícil (hard negative) e é o que ensina algo ao modelo: um negativo óbvio não corrige nada, pois o modelo genérico já o classificou corretamente.
import numpy as np
from openai import OpenAI
from sklearn.model_selection import train_test_split
client = OpenAI()
# Dataset of pairs (query, positive_document, negative_document)
triplets = [
{
"query": "paracetamol side effects",
"positive": "Paracetamol can cause liver disorders...",
"negative": "Paracetamol is available in pharmacies..."
},
{
"query": "children's aspirin dosage",
"positive": "For children aged 6 to 12, the recommended dose...",
"negative": "Aspirin was discovered in the 19th century..."
},
# ... more triplets
]
def prepare_embeddings(triplets: list[dict]) -> dict:
"""Generate embeddings for the triplets."""
all_texts = []
for t in triplets:
all_texts.extend([t["query"], t["positive"], t["negative"]])
response = client.embeddings.create(
input=all_texts,
model="text-embedding-3-large"
)
embs = np.array(
[d.embedding for d in sorted(response.data, key=lambda x: x.index)]
)
n = len(triplets)
return {
"queries": embs[0::3],
"positives": embs[1::3],
"negatives": embs[2::3],
}
O adaptador em si é uma rede de duas camadas que projeta as 3.072 dimensões do modelo para 256, com normalização final para que os vetores de saída permaneçam comparáveis por similaridade de cosseno. A função de perda é uma triplet margin loss: equivale a zero assim que a consulta estiver mais próxima do positivo do que do negativo por uma margem de pelo menos 0,2, e penaliza proporcionalmente caso contrário. Por outras palavras, apenas ensina ao modelo o que este ainda não compreendeu, e o treino estabiliza naturalmente assim que os tripletos estiverem bem separados.
import torch
import torch.nn as nn
import torch.optim as optim
class EmbeddingAdapter(nn.Module):
"""Projection layer to adapt embeddings."""
def __init__(self, input_dim: int = 3072, output_dim: int = 256):
super().__init__()
self.projection = nn.Sequential(
nn.Linear(input_dim, output_dim),
nn.ReLU(),
nn.Linear(output_dim, output_dim),
)
def forward(self, x):
projected = self.projection(x)
return projected / projected.norm(dim=-1, keepdim=True)
def triplet_loss(anchor, positive, negative, margin=0.2):
"""Triplet margin loss."""
dist_pos = 1 - torch.cosine_similarity(anchor, positive)
dist_neg = 1 - torch.cosine_similarity(anchor, negative)
return torch.relu(dist_pos - dist_neg + margin).mean()
def train_adapter(data: dict, epochs: int = 50):
"""Train the adapter on triplets."""
model = EmbeddingAdapter()
optimizer = optim.Adam(model.parameters(), lr=1e-3)
queries = torch.tensor(data["queries"], dtype=torch.float32)
positives = torch.tensor(data["positives"], dtype=torch.float32)
negatives = torch.tensor(data["negatives"], dtype=torch.float32)
for epoch in range(epochs):
optimizer.zero_grad()
q_proj = model(queries)
p_proj = model(positives)
n_proj = model(negatives)
loss = triplet_loss(q_proj, p_proj, n_proj)
loss.backward()
optimizer.step()
if (epoch + 1) % 10 == 0:
print(f"Epoch {epoch + 1}/{epochs}, Loss: {loss.item():.4f}")
return model
# Train
data = prepare_embeddings(triplets)
adapter = train_adapter(data)
# Save
torch.save(adapter.state_dict(), "medical_adapter.pt")
Um ponto operacional que não pode ignorar: no dia em que implementar este adaptador, todos os vetores já armazenados na sua base de dados devem passar novamente pela projeção; caso contrário, estaria a comparar vetores de dois espaços diferentes. Planeie uma reindexação completa do corpus na sua implementação em produção.
Abordagem 2: Afinamento com Sentence Transformers
Quando o adaptador não é suficiente, precisa de modificar o próprio modelo de embeddings, o que requer um modelo aberto que hospede — neste caso BAAI/bge-large-en-v1.5. O Sentence Transformers torna isto acessível: descreve exemplos como pares de texto com um rótulo contínuo, onde 1,0 significa “estes dois textos devem estar próximos” e 0,2 significa “parecem superficialmente semelhantes, afaste-os”. A CosineSimilarityLoss empurra então a similaridade de cosseno calculada em direção ao rótulo fornecido.
Três épocas e cem passos de aquecimento são valores conservadores, e por boa razão: num conjunto de dados modesto, treinar durante demasiado tempo destrói o conhecimento geral do modelo, tornando-o excelente nos seus exemplos e medíocre em todo o resto.
from sentence_transformers import (
SentenceTransformer, InputExample, losses
)
from torch.utils.data import DataLoader
# Load a base model
model = SentenceTransformer("BAAI/bge-large-en-v1.5")
# Prepare training examples
train_examples = [
InputExample(
texts=["paracetamol side effects",
"Paracetamol can cause liver disorders"],
label=1.0
),
InputExample(
texts=["paracetamol side effects",
"Paracetamol is sold in pharmacies"],
label=0.2
),
]
train_dataloader = DataLoader(train_examples, shuffle=True, batch_size=16)
train_loss = losses.CosineSimilarityLoss(model)
# Train
model.fit(
train_objectives=[(train_dataloader, train_loss)],
epochs=3,
warmup_steps=100,
output_path="./finetuned_medical_model"
)
# Use the fine-tuned model
embeddings = model.encode([
"abdominal pain after taking medication",
"adverse drug effects"
])
Preparar um conjunto de dados de qualidade
Aqui reside o verdadeiro obstáculo: ninguém tem mil pares anotados à disposição. A solução alternativa é construí-los a partir do que já possui, nomeadamente os seus documentos. Submete cada documento ao LLM pedindo as perguntas que este responde com precisão e obtém pares pergunta-documento sem qualquer anotação manual. Uma temperatura de 0,7 garante que as três perguntas geradas para o mesmo documento não sejam três variantes da mesma frase, e lstrip limpa a numeração que o modelo adiciona espontaneamente.
def generate_training_pairs(
documents: list[str],
n_per_doc: int = 3
) -> list[dict]:
"""Generate query-document pairs for training."""
pairs = []
for doc in documents:
response = client.chat.completions.create(
model="gpt-5.6-terra",
messages=[{
"role": "user",
"content": (
f"Here is a document:\n\n{doc[:500]}\n\n"
f"Generate {n_per_doc} questions that this document "
f"answers precisely. One question per line."
)
}],
temperature=0.7
)
questions = response.choices[0].message.content.strip().split("\n")
for q in questions[:n_per_doc]:
q = q.strip().lstrip("0123456789.-) ")
if q:
pairs.append({"query": q, "document": doc})
return pairs
Avaliar o afinamento
Treinar com uma perda decrescente não prova nada: a única questão que importa é saber se a pesquisa melhorou. A função abaixo mede a recall@5 no mesmo conjunto de consultas, com e sem o adaptador, simplesmente passando adapter=None para obter a linha de base. Tanto o corpus como as consultas passam pela projeção quando fornecida, o que é a condição para que ambos os vetores vivam no mesmo espaço.
Execute sempre esta comparação antes de implementar. Acontece regularmente que um adaptador treinado com poucos tripletos degrada a revocação e, sem medição, colocaria em produção uma regressão pensando que estava a implementar uma melhoria.
def evaluate_before_after(
queries: list[str],
relevant_docs: list[list[str]],
corpus: list[str],
adapter=None
):
"""Compare performance before and after fine-tuning."""
resp = client.embeddings.create(
input=corpus, model="text-embedding-3-large"
)
corpus_embs = np.array(
[d.embedding for d in sorted(resp.data, key=lambda x: x.index)]
)
if adapter:
corpus_embs_adapted = adapter(
torch.tensor(corpus_embs, dtype=torch.float32)
).detach().numpy()
else:
corpus_embs_adapted = corpus_embs
recall_scores = []
for query, relevants in zip(queries, relevant_docs):
q_resp = client.embeddings.create(
input=query, model="text-embedding-3-large"
)
q_emb = np.array(q_resp.data[0].embedding)
if adapter:
q_emb = adapter(
torch.tensor(q_emb, dtype=torch.float32).unsqueeze(0)
).detach().numpy()[0]
scores = corpus_embs_adapted @ q_emb
top_5 = set(np.argsort(scores)[-5:])
relevant_ids = set(
i for i, d in enumerate(corpus) if d in relevants
)
recall = len(top_5 & relevant_ids) / len(relevant_ids)
recall_scores.append(recall)
return np.mean(recall_scores)
Pontos-chave
- O afinamento de embeddings melhora o desempenho em domínios especializados
- Um adaptador linear é o método mais simples e frequentemente suficiente
- O Sentence Transformers permite um afinamento mais profundo do modelo completo
- Recomenda-se um mínimo de 1.000 pares anotados
- Avalie sempre antes e depois para validar o ganho