Embeddings & Similaridade

Embeddings convertem texto em vetores de tamanho fixo onde a similaridade semântica corresponde à proximidade geométrica. Eles potencializam a busca semântica, clustering e recuperação RAG.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

from openai import OpenAI
import numpy as np
 
client = OpenAI()
emb = client.embeddings.create(model="text-embedding-3-small", input=["texto da consulta"])
vec = np.array(emb.data[0].embedding)
 
# similaridade de cosseno
def cosine(a, b):
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

Quando usar isso:

• Busca semântica sobre documentos, código ou artigos de suporte.
• Agrupamento ou desduplicação de conteúdo de texto.
• Etapa de recuperação RAG antes da geração de LLM.
• Sistemas de recomendação baseados em similaridade de texto.

Exemplo de Trabalho

"""embeddings_similarity.py - incorporar, indexar e pesquisar documentos."""
from __future__ import annotations
 
import numpy as np
from openai import OpenAI
 
client = OpenAI()
MODEL = "text-embedding-3-small"
 
documents = [
    "FastAPI é um framework web moderno em Python para construir APIs.",
    "PyTorch é um framework de deep learning com grafos de computação dinâmicos.",
    "pandas 2.2 fornece operações de DataFrame para análise de dados tabulares.",
    "pytest é o framework padrão de testes para projetos Python.",
]
 
def embed_texts(texts: list[str]) -> np.ndarray:
    response = client.embeddings.create(model=MODEL, input=texts)
    vectors = [item.embedding for item in response.data]
    arr = np.array(vectors, dtype=np.float32)
    norms = np.linalg.norm(arr, axis=1, keepdims=True)
    return arr / norms  # Normalização L2 para cosseno via produto escalar
 
doc_embeddings = embed_texts(documents)
 
query = "Como eu testo meu código Python?"
query_vec = embed_texts([query])[0]
 
scores = doc_embeddings @ query_vec  # similaridade de cosseno (normalizada)
ranked = sorted(zip(scores, documents), reverse=True)
for score, doc in ranked:
    print(f"{score:.3f}  {doc}")

O que isso demonstra:

• Embedding em lote com OpenAI text-embedding-3-small.
• Normalização L2 para que o produto escalar seja igual à similaridade de cosseno.
• Classificação de documentos por relevância a uma consulta em linguagem natural.
• Correspondência semântica: "testar código Python" classifica pytest em primeiro lugar.

Mergulho Profundo

Como Funciona

• Modelo de embedding codifica texto em um vetor de dimensão fixa (por exemplo, 1536).
• Textos similares produzem vetores com alta similaridade de cosseno.
• Normalização (L2) torna o produto escalar equivalente à similaridade de cosseno.
• Índice vetorial (FAISS, pgvector) permite busca rápida de vizinhos mais próximos em escala.
• O mesmo modelo deve ser usado para indexação e consulta.

Modelos de Embedding

Notas Python

# Embeddings locais com sentence-transformers
from sentence_transformers import SentenceTransformer
model = SentenceTransformer("all-MiniLM-L6-v2")
vectors = model.encode(documents, normalize_embeddings=True)

Armadilhas

• Misturar modelos de embedding - modelos diferentes produzem espaços vetoriais incompatíveis. Correção: um modelo por índice; re-incorporar todos os documentos ao mudar de modelo.
• Não normalizar vetores - produto escalar sem normalização não é similaridade de cosseno. Correção: normalizar L2 antes da indexação e busca.
• Incorporar textos muito longos - modelos têm limites de tokens; documentos longos são truncados. Correção: dividir documentos em pedaços antes de incorporar.
• Comparar entre dimensões diferentes - vetores de 384 dimensões vs 1536 dimensões não podem ser comparados. Correção: modelo e dimensão consistentes.
• Ignorar custo de embedding em escala - incorporar milhões de documentos tem um custo. Correção: armazenar embeddings em cache; agrupar requisições; usar modelos menores.
• Expectativa de busca por palavra-chave - embeddings perdem correspondências exatas de palavras-chave. Correção: busca híbrida (embeddings + BM25).

Alternativas

FAQs

client.embeddings.create(model="text-embedding-3-small", input=texts, dimensions=512)

Relacionados

• Noções Básicas de RAG - pipeline de recuperação
• Bancos de Dados Vetoriais - armazenamento e busca
• Chunking & Ingestão - divisão de documentos
• SDKs da OpenAI e Outros - API de embedding
• Recuperação & Re-ranking - busca híbrida

Versões da Stack: Esta página foi escrita para Python 3.14.0 (estável 3.14, manutenção 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, e uv 0.6+.