A API de Embeddings: Modelos e Dimensões
Nesta página
Objetivos
- Dominar a chamada
client.embeddings.create() - Compreender as diferenças entre os modelos de embeddings
- Utilizar a redução de dimensionalidade
A Chamada Básica
Toda a API de Embeddings da OpenAI resume-se a um único método: client.embeddings.create(). Basta passar-lhe uma cadeia de texto e o nome de um modelo:
from openai import OpenAI
client = OpenAI()
response = client.embeddings.create(
input="Hello, how are you?",
model="text-embedding-3-large"
)
embedding = response.data[0].embedding
print(f"Type: {type(embedding)}") # list
print(f"Length: {len(embedding)}") # 3072
print(f"Snippet: {embedding[:3]}") # [0.023, -0.041, 0.012]
O objeto devolvido não é o vetor em si, mas um contentor que inclui vários vetores, pois a API foi concebida para processar lotes. No seu interior, encontrará data, uma lista de objetos onde cada um possui um campo embedding (o vetor) e um campo index (a sua posição no lote enviado); model, que indica o modelo efetivamente utilizado; e usage.prompt_tokens, o número de tokens faturados. Deve registar este último campo desde o primeiro dia: é a única medida fiável do custo da sua indexação.
Os Dois Modelos Disponíveis
O text-embedding-3-large é o modelo de alto desempenho. As suas 3.072 dimensões captam as nuances semânticas mais subtis, tornando-o ideal para pesquisar em grandes corpora, para pipelines de RAG exigentes e, de modo geral, para qualquer cenário em que a precisão prevaleça sobre o custo. Se um utilizador formular perguntas de forma indireta ou os seus documentos cobrirem um domínio técnico denso, notará a diferença na classificação dos resultados.
O text-embedding-3-small é mais compacto, com 1.536 dimensões, e oferece uma excelente relação preço-desempenho. É a escolha certa para classificação de texto, sistemas de recomendação, prototipagem rápida e aplicações de grande volume onde o objetivo não seja distinguir entre dois documentos quase idênticos, mas separar temas claramente distintos. Um simples ciclo permite verificar o que cada um devolve:
# Compare the two models
for model_name in ["text-embedding-3-small", "text-embedding-3-large"]:
resp = client.embeddings.create(
input="Artificial intelligence",
model=model_name
)
vec = resp.data[0].embedding
print(f"{model_name}: {len(vec)} dimensions")
Embeddings em Lote
Não se indexa um corpus real texto a texto: cada chamada HTTP implica uma ida e volta à rede, e processar mil documentos individualmente significa acumular mil latências. A API aceita até 2.048 textos numa única chamada, e o campo index permite mapear cada vetor para o documento correto.
texts = [
"Machine learning is advancing rapidly",
"Deep learning is revolutionizing computer vision",
"Vector databases store embeddings",
"Python is the preferred language for data scientists"
]
response = client.embeddings.create(
input=textes,
model="text-embedding-3-large"
)
for item in response.data:
print(f"Text {item.index}: vector of {len(item.embedding)} dimensions")
print(f"Tokens consumed: {response.usage.prompt_tokens}")
Na prática, agrupe os seus textos em lotes de 100 a 2.048, consoante o seu volume: lotes menores facilitam a recuperação após falhas, enquanto lotes maiores reduzem o número de chamadas. Monitore usage.prompt_tokens em cada iteração para estimar custos à medida que avança, em vez de os descobrir apenas na fatura, e implemente novas tentativas com espera exponencial (exponential backoff): o excedente do limite de taxa é um erro transitório, não um motivo para interromper um trabalho de indexação de três horas.
Redução de Dimensionalidade
Os modelos text-embedding-3-* aceitam um parâmetro dimensions que devolve vetores mais curtos do que o seu tamanho nativo:
# Full vector: 3072 dimensions
full = client.embeddings.create(
input="Reduction test",
model="text-embedding-3-large"
)
# Reduced vector: 256 dimensions
reduced = client.embeddings.create(
input="Reduction test",
model="text-embedding-3-large",
dimensions=256
)
print(f"Full: {len(full.data[0].embedding)} dim") # 3072
print(f"Reduced: {len(reduced.data[0].embedding)} dim") # 256
O mecanismo é simples: a redução trunca o vetor e, em seguida, renormaliza-o. Como as primeiras dimensões transportam a maior parte da informação, a degradação mantém-se muito gradual. A tabela abaixo apresenta benchmarks padrão para equilibrar qualidade e armazenamento.
| Dimensions | Relative Quality | Storage | Use Case |
|---|---|---|---|
| 3,072 | 100% | ~24 KB | High-precision search |
| 1,536 | ~98% | ~12 KB | Good general compromise |
| 512 | ~93% | ~4 KB | High volume, reduced cost |
| 256 | ~88% | ~2 KB | Prototyping, simple classification |
Lembre-se de que a escolha da dimensão é um compromisso definitivo: todos os vetores num determinado índice devem ter o mesmo tamanho, e mudar de ideias obriga a recalcular tudo.
Gestão de Tokens
Os modelos de embeddings têm um limite de 8.191 tokens por texto, e a API devolve um erro se esse limite for excedido. É preferível medir antes de enviar do que tratar uma exceção a meio de um lote:
import tiktoken
encoder = tiktoken.get_encoding("cl100k_base")
text = "A potentially long text..."
tokens = encoder.encode(text)
if len(tokens) > 8191:
# Truncate
truncated_text = encoder.decode(tokens[:8191])
print(f"Text truncated from {len(tokens)} to 8191 tokens")
A truncatura é uma rede de segurança, não uma estratégia: um documento longo truncado perde o seu final, e é frequentemente no final que se encontra a resposta que procura. O tratamento adequado de documentos de grandes dimensões envolve a fragmentação (chunking), tema que abordaremos mais adiante neste curso.
Pontos-chave
client.embeddings.create()aceita um único texto ou uma lista de textos- Utilize
text-embedding-3-large(3.072 dim) para precisão etext-embedding-3-small(1.536 dim) para eficiência de custos - O parâmetro
dimensionspermite reduzir o tamanho do vetor - Processar textos em lote é mais eficiente do que chamadas individuais
- Limite de 8.191 tokens por texto