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

Classificação de texto com embeddings

Aula 17 de 22 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Objetivos
  2. Classificação Zero-shot
  3. Classificação Few-shot
  4. Classificador supervisionado ligeiro
  5. Comparação de abordagens
  6. Pontos-chave

Objetivos

  • Classificar texto sem treinar um modelo
  • Implementar classificação zero-shot e few-shot utilizando embeddings
  • Comparar o desempenho com um classificador supervisionado ligeiro

Classificação Zero-shot

A pesquisa semântica encontra documentos semelhantes a uma consulta entre milhares de candidatos. A classificação inverte esta configuração sem alterar a mecânica subjacente: os seus “documentos” são agora as suas categorias (cinco ou dez delas), e a “consulta” é o texto que deseja classificar. O rótulo cujo embedding estiver mais próximo torna-se a previsão. Sem treino, sem dados anotados, apenas uma chamada à API.

Dois detalhes de implementação no código abaixo merecem atenção. Primeiro, o texto e os nomes das categorias são inseridos numa única chamada embeddings.create, o que reduz a latência proporcionalmente ao número de rótulos. Segundo, aplicar softmax às pontuações de similaridade converte valores brutos (tipicamente entre 0,3 e 0,5) em probabilidades que somam 1. Pode exibir estas probabilidades a um utilizador ou compará-las com um limiar de confiança.

from openai import OpenAI
import numpy as np

client = OpenAI()

def classifier_zero_shot(
    texte: str,
    categories: list[str],
    model: str = "text-embedding-3-large"
) -> dict:
    """Classifies text into categories without training."""
    # Embeddings for categories
    all_inputs = [texte] + categories
    response = client.embeddings.create(
        input=all_inputs,
        model=model
    )
    embs = [d.embedding for d in sorted(response.data, key=lambda x: x.index)]
    texte_emb = np.array(embs[0])
    cat_embs = np.array(embs[1:])

    # Similarity with each category
    scores = cat_embs @ texte_emb

    # Softmax to get probabilities
    exp_scores = np.exp(scores - np.max(scores))
    probas = exp_scores / exp_scores.sum()

    resultats = sorted(
        zip(categories, probas),
        key=lambda x: x[1], reverse=True
    )

    return {
        "prediction": resultats[0][0],
        "confiance": float(resultats[0][1]),
        "scores": {cat: float(p) for cat, p in resultats}
    }

# Usage
texte = "Le cours de l'action a chuté de 15% après l'annonce"
categories = ["Finance", "Sport", "Technologie", "Politique", "Santé"]

resultat = classifier_zero_shot(texte, categories)
print(f"Prédiction : {resultat['prediction']} "
      f"({resultat['confiance']:.1%})")
print("Scores :", resultat["scores"])

Neste exemplo, “o preço da ação caiu 15% após o anúncio” vai parar, sem surpresa, à categoria Finanças. Esta abordagem atinge um limite quando as categorias são rótulos internos cujos nomes não revelam nada sobre o seu conteúdo. Um rótulo como “P1” ou “escalamento de nível 2” não carrega nenhum significado semântico explorável, tornando a classificação essencialmente aleatória.

Classificação Few-shot

É exatamente isto que a classificação few-shot resolve. Em vez de representar uma categoria pelo seu nome, representa-a pelo centroide de alguns exemplos reais. A categoria “bug” deixa de ser a palavra “bug” para se tornar a média dos embeddings de “a aplicação falha ao iniciar”, “erro 500 na página de login” e “o botão não funciona no telemóvel”. Três a cinco exemplos por classe são geralmente suficientes, e o custo permanece o de uma única chamada à API, uma vez que todos os textos são enviados em conjunto.

def classifier_few_shot(
    texte: str,
    exemples: dict[str, list[str]],
    model: str = "text-embedding-3-large"
) -> dict:
    """Classifies by similarity to labeled examples.

    Args:
        exemples: {"category": ["example1", "example2", ...]}
    """
    # Prepare all texts
    tous_textes = [texte]
    mapping = []
    for cat, txts in exemples.items():
        for t in txts:
            tous_textes.append(t)
            mapping.append(cat)

    # Embeddings in a single call
    response = client.embeddings.create(
        input=tous_textes, model=model
    )
    embs = [d.embedding for d in sorted(response.data, key=lambda x: x.index)]
    texte_emb = np.array(embs[0])

    # Average embeddings per category
    cat_embeddings = {}
    for i, cat in enumerate(mapping):
        emb = np.array(embs[i + 1])
        if cat not in cat_embeddings:
            cat_embeddings[cat] = []
        cat_embeddings[cat].append(emb)

    cat_moyennes = {
        cat: np.mean(embs_list, axis=0)
        for cat, embs_list in cat_embeddings.items()
    }

    # Similarity
    scores = {
        cat: float(np.dot(texte_emb, emb_moy) /
                    (np.linalg.norm(texte_emb) * np.linalg.norm(emb_moy)))
        for cat, emb_moy in cat_moyennes.items()
    }

    prediction = max(scores, key=scores.get)
    return {"prediction": prediction, "scores": scores}

# Usage
exemples = {
    "bug": [
        "L'application crash au démarrage",
        "Erreur 500 sur la page de connexion",
        "Le bouton ne fonctionne pas sur mobile",
    ],
    "feature": [
        "Pourriez-vous ajouter un mode sombre ?",
        "Il serait utile d'exporter en PDF",
        "Suggestion : intégrer un calendrier",
    ],
    "question": [
        "Comment changer mon mot de passe ?",
        "Où trouver les paramètres de notification ?",
        "Quelle est la limite de stockage ?",
    ],
}

texte = "L'export CSV ne contient pas toutes les colonnes"
resultat = classifier_few_shot(texte, exemples)
print(f"Catégorie : {resultat['prediction']}")

O ticket de teste — “a exportação CSV não contém todas as colunas” — não inclui nem a palavra “bug” nem “erro”, mas assemelha-se aos três exemplos de mau funcionamento fornecidos, pelo que é aí que acaba por ser classificado. Note que fazer a média dos embeddings pressupõe uma categoria homogénea. Se os seus exemplos de “pergunta” misturarem consultas de faturação com questões sobre a API, o seu centroide cairá numa terra de ninguém semântica. Nesse caso, é melhor dividir a categoria.

Classificador supervisionado ligeiro

Quando dispõe de várias dezenas de exemplos por classe, fazer a média torna-se um desperdício de informação: achata a forma da nuvem de pontos. Um classificador linear treinado nos mesmos embeddings aprende, em vez disso, um limite de decisão. O embedding trata da compreensão da linguagem, enquanto o LogisticRegression simplesmente traça uma linha geométrica nesse espaço. Isto resulta em tempos de treino de alguns segundos num CPU standard, ao passo que o ajuste fino (fine-tuning) de um modelo de linguagem exigiria uma GPU.

A validação cruzada de cinco dobras (five-fold cross-validation) não é apenas para inglês ver. Fornece-lhe o desvio padrão da precisão, dando uma ideia da fiabilidade da sua estimativa. Uma pontuação de 0,91 ± 0,02 é utilizável; 0,91 ± 0,15 sinaliza um conjunto de dados demasiado pequeno ou desequilibrado.

from sklearn.linear_model import LogisticRegression
from sklearn.model_selection import cross_val_score
import numpy as np

def entrainer_classifieur(
    textes: list[str],
    labels: list[str],
    model: str = "text-embedding-3-large"
) -> LogisticRegression:
    """Trains a classifier on embeddings."""
    # Generate embeddings
    response = client.embeddings.create(
        input=textes, model=model
    )
    X = np.array([d.embedding for d in sorted(response.data, key=lambda x: x.index)])

    # Train a classifier
    clf = LogisticRegression(max_iter=1000)
    
    # Cross-validation
    scores = cross_val_score(clf, X, labels, cv=5)
    print(f"Accuracy (5-fold CV) : {scores.mean():.3f} ± {scores.std():.3f}")

    # Train on the full dataset
    clf.fit(X, labels)
    return clf

def predire(clf, texte: str, model: str = "text-embedding-3-large") -> str:
    """Predicts the category of a text."""
    emb = client.embeddings.create(
        input=texte, model=model
    ).data[0].embedding
    return clf.predict([emb])[0]

Comparação de abordagens

AbordagemExemplos necessáriosPrecisãoLatência
Zero-shot0~70-80%1 chamada à API
Few-shot (3-5/classe)15-25~80-90%1 chamada à API
Supervisionado (50+/classe)250+~90-95%1 chamada à API + inferência

Lidas pela ordem, estas três linhas descrevem uma progressão que pode seguir ao longo do ciclo de vida do produto. Comece com zero-shot no primeiro dia, sem quaisquer dados. Assim que tiver corrigido manualmente cerca de vinte previsões, recicle-as como exemplos few-shot. Quando o volume de anotações exceder cinquenta por classe, treine o classificador supervisionado. Tenha em mente que a linha “latência” lembra que mesmo o modelo supervisionado permanece rápido; a inferência local adiciona uma sobrecarga negligenciável em comparação com a chamada à API de embeddings.

Pontos-chave

  • A classificação zero-shot compara o texto com os rótulos através de embeddings
  • O método few-shot utiliza exemplos para definir cada categoria
  • Um classificador supervisionado (LogisticRegression) alcança o melhor desempenho
  • Comece com zero-shot e adicione exemplos se a precisão for insuficiente