La API de Embeddings: Modelos y Dimensiones
En esta página
Objetivos
- Dominar la llamada
client.embeddings.create() - Comprender las diferencias entre los modelos de embeddings
- Utilizar la reducción de dimensionalidad
La Llamada Básica
Toda la API de Embeddings de OpenAI se resume en un único método: client.embeddings.create(). Le pasas una cadena de texto y el nombre de un 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]
El objeto devuelto no es el vector en sí, sino un contenedor que alberga múltiples vectores, ya que la API está diseñada para gestionar lotes. En su interior encontrarás data, una lista de objetos donde cada uno tiene un campo embedding (el vector) y un campo index (su posición en el lote enviado); model, que indica el modelo utilizado realmente; y usage.prompt_tokens, el número de tokens facturados. Debes registrar este último campo desde el primer día: es la única medida fiable de lo que te cuesta tu indexación.
Los Dos Modelos Disponibles
text-embedding-3-large es el modelo de alto rendimiento. Sus 3.072 dimensiones capturan los matices semánticos más finos, lo que lo hace ideal para buscar en corpus extensos, canalizaciones RAG exigentes y, en general, cualquier caso en el que la precisión prime sobre el coste. Si un usuario formula preguntas de forma indirecta o tus documentos cubren un dominio técnico denso, notarás la diferencia en cómo se ordenan los resultados.
text-embedding-3-small es más compacto, con 1.536 dimensiones, y ofrece una excelente relación calidad-precio. Es la elección correcta para la clasificación de textos, sistemas de recomendación, prototipado rápido y aplicaciones de alto volumen donde el objetivo no es distinguir entre dos documentos casi idénticos, sino separar temas claramente distintos. Un bucle sencillo verifica qué devuelve cada uno:
# 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 por Lotes
No se indexa un corpus real texto a texto: cada llamada HTTP implica un viaje de ida y vuelta por la red, y procesar mil documentos individualmente significa acumular mil latencias. La API acepta hasta 2.048 textos en una única llamada, y el campo index te permite mapear cada vector de vuelta al documento correcto.
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}")
En la práctica, agrupa tus textos en lotes de entre 100 y 2.048 dependiendo de tu volumen: los lotes más pequeños facilitan la recuperación tras fallos, mientras que los más grandes reducen el número de llamadas. Supervisa usage.prompt_tokens en cada iteración para estimar los costes sobre la marcha en lugar de descubrirlos en la factura, e implementa reintentos con retroceso exponencial: superar el límite de tasa es un error transitorio, no un motivo para interrumpir un trabajo de indexación de tres horas.
Reducción de Dimensionalidad
Los modelos text-embedding-3-* aceptan un parámetro dimensions que devuelve vectores más cortos que su tamaño 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
El mecanismo es sencillo: la reducción trunca el vector y luego lo renormaliza. Dado que las primeras dimensiones contienen la mayor parte de la información, la degradación es muy gradual. La siguiente tabla ofrece puntos de referencia estándar para equilibrar calidad frente a almacenamiento.
| Dimensions | Relative Quality | Storage | Use Case |
|---|---|---|---|
| 3.072 | 100 % | ~24 KB | Búsqueda de alta precisión |
| 1.536 | ~98 % | ~12 KB | Buen compromiso general |
| 512 | ~93 % | ~4 KB | Alto volumen, coste reducido |
| 256 | ~88 % | ~2 KB | Prototipado, clasificación simple |
Recuerda que tu elección de dimensionalidad es vinculante: todos los vectores de un índice dado deben tener el mismo tamaño, y cambiar de opinión obliga a recalcularlo todo.
Gestión de Tokens
Los modelos de embeddings tienen un límite de 8.191 tokens por texto, y la API devuelve un error si lo superas. Es mejor medir antes de enviar que capturar una excepción en mitad de un 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")
El truncamiento es una red de seguridad, no una estrategia: un documento largo truncado pierde su final, y el final suele contener la respuesta que buscas. El tratamiento adecuado de documentos grandes implica fragmentación, algo que veremos más adelante en el curso.
Resumen
client.embeddings.create()acepta un único texto o una lista de textos- Usa
text-embedding-3-large(3.072 dim) para precisión,text-embedding-3-small(1.536 dim) para eficiencia de costes - El parámetro
dimensionspermite reducir el tamaño del vector - Agrupar textos en lotes es más eficiente que hacer llamadas individuales
- Límite de 8.191 tokens por texto