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

Afinamento de embeddings

Aula 21 de 22 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Objetivos
  2. Quando afinar?
  3. Abordagem 1: Adaptador linear (Matryoshka)
  4. Abordagem 2: Afinamento com Sentence Transformers
  5. Preparar um conjunto de dados de qualidade
  6. Avaliar o afinamento
  7. Pontos-chave

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