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

A API de Embeddings: Modelos e Dimensões

Aula 2 de 22 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Objetivos
  2. A Chamada Básica
  3. Os Dois Modelos Disponíveis
  4. Embeddings em Lote
  5. Redução de Dimensionalidade
  6. Gestão de Tokens
  7. Pontos-chave

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.

DimensionsRelative QualityStorageUse Case
3,072100%~24 KBHigh-precision search
1,536~98%~12 KBGood general compromise
512~93%~4 KBHigh volume, reduced cost
256~88%~2 KBPrototyping, 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 e text-embedding-3-small (1.536 dim) para eficiência de custos
  • O parâmetro dimensions permite reduzir o tamanho do vetor
  • Processar textos em lote é mais eficiente do que chamadas individuais
  • Limite de 8.191 tokens por texto