¿Buscas la API de embeddings de Open AI? El endpoint de embeddings de OpenAI convierte texto en vectores numéricos para que una aplicación pueda recuperar pasajes relacionados. La solicitud es solo el primer paso: una función de búsqueda útil también necesita ID de documentos estables, un espacio vectorial coherente y una prueba que indique si la recuperación mejoró.
Esta guía crea un pequeño ejemplo de búsqueda en Python, muestra qué almacenar junto a cada vector y te ofrece una lista de verificación para llevar el experimento a un producto. Usa OpenAI directamente. La compatibilidad con gateways y la disponibilidad de modelos deben verificarse por separado para cada proveedor.
API de embeddings de Open AI: la solicitud que necesitas
Envía texto a POST https://api.openai.com/v1/embeddings con un modelo de embeddings y una clave de API. Elige encoding_format="float" cuando tu aplicación espere matrices numéricas. Para un lote, usa el index de cada elemento de respuesta para volver a conectar el vector con su entrada. La respuesta también incluye el uso de tokens. La opción dimensions es compatible con los modelos de embeddings de tercera generación. Referencia de la API de OpenAI.
Un embedding no es una respuesta generada. En una aplicación con recuperación aumentada, la búsqueda primero selecciona pasajes fuente; una llamada de generación independiente puede entonces responder usando esos pasajes. Mantener las etapas separadas te permite diagnosticar un mal resultado: ¿la búsqueda recuperó la evidencia equivocada o el modelo de respuesta utilizó mal evidencia válida?
Elige un modelo y mantén fija su configuración
Las longitudes de vector predeterminadas documentadas son 1.536 para text-embedding-3-small y 3.072 para text-embedding-3-large. Estos modelos admiten vectores de salida más cortos mediante dimensions. Un vector más corto cambia las compensaciones entre almacenamiento y recuperación; no es motivo para omitir la evaluación. Guía de embeddings de OpenAI.
Comienza con una configuración y un conjunto pequeño de consultas representativas. Registra el modelo, el número de dimensiones solicitado y la versión de procesamiento de texto con el índice. Que dos vectores tengan la misma longitud no demuestra que procedan de un modelo compatible. Al cambiar modelos o reglas de procesamiento, crea un índice independiente y compáralo antes de cambiar el tráfico de producción.
Un ejemplo mínimo de búsqueda semántica en Python
Instala openai en tu entorno de Python y pon OPENAI_API_KEY a disposición mediante tu gestor de secretos habitual o la configuración del entorno. Mantén la clave fuera del control de código fuente y del código del navegador. El SDK oficial de Python lee esa variable al construir OpenAI().
Guarda lo siguiente como search_demo.py. Usa tres documentos de soporte inventados, genera embeddings para el corpus y una consulta, y clasifica los documentos con similitud de coseno. Al ejecutarlo se realizan solicitudes facturables a la API. La salida depende de la respuesta del servicio; el ejemplo no promete una puntuación ni una clasificación concretas.
import math
from openai import OpenAI
client = OpenAI(timeout=30.0, max_retries=2)
model = "text-embedding-3-small"
dimensions = 1536
documents = [
{"id": "key-rotation", "text": "Replace an exposed API key and revoke the old credential."},
{"id": "invoice-export", "text": "Download a monthly invoice from the billing workspace."},
{"id": "request-timeout", "text": "Record the request ID and retry temporary upstream timeouts."},
]
query = "What should I do after accidentally sharing a secret key?"
def embed(texts):
response = client.embeddings.create(
model=model, input=texts,
dimensions=dimensions, encoding_format="float",
)
ordered = sorted(response.data, key=lambda item: item.index)
if [item.index for item in ordered] != list(range(len(texts))):
raise ValueError("Unexpected embedding response indices")
vectors = [item.embedding for item in ordered]
if any(len(vector) != dimensions for vector in vectors):
raise ValueError("Unexpected vector dimensions")
print("Input tokens:", response.usage.prompt_tokens)
return vectors
def cosine(a, b):
if len(a) != len(b):
raise ValueError("Vector dimensions do not match")
denominator = math.sqrt(sum(x*x for x in a) * sum(y*y for y in b))
if not denominator:
raise ValueError("Cannot compare a zero vector")
return sum(x*y for x, y in zip(a, b)) / denominator
vectors = embed([document["text"] for document in documents])
query_vector = embed([query])[0]
ranked = sorted(
((cosine(query_vector, vector), document["id"])
for document, vector in zip(documents, vectors)),
reverse=True,
)
for score, document_id in ranked:
print(document_id, round(score, 4))
Ejecuta python search_demo.py. Confirma que los tres ID aparezcan una vez y que cada embedding tenga la longitud configurada. Después, cambia la consulta para preguntar sobre facturas. Esto es una prueba básica del flujo de datos, no una demostración de que el sistema esté listo para tráfico real de soporte. El ejemplo vuelve a generar embeddings para el corpus en cada ejecución por claridad; un servicio desplegado normalmente debería conservar los vectores de los documentos y generar embeddings solo para contenido nuevo o modificado.
Convierte la demostración en un índice de documentos confiable
El siguiente diseño de registro es un punto de partida práctico. Es un ejemplo de diseño de aplicación, no un esquema de campos requerido por OpenAI.
| Almacenar con cada fragmento | Por qué es importante |
|---|---|
document_id y chunk_id | Actualizar o eliminar el contenido correcto sin depender del orden del arreglo. |
| URL de origen, título de la sección y revisión de origen | Mostrar una cita útil y rastrear respuestas desactualizadas. |
| Hash del contenido y versión de procesamiento | Identificar qué fragmentos realmente necesitan volver a convertirse en embeddings. |
| Modelo y número de dimensiones | Evitar una mezcla accidental de configuraciones de vectores incompatibles. |
| Metadatos de tenant y control de acceso | Filtrar la recuperación a documentos a los que el usuario solicitante puede acceder. |
| Texto y embedding | Devolver el pasaje de origen después de seleccionar su vector. |
Divide los documentos en límites significativos y, después, comprueba la longitud de los tokens. Una sección que contiene la respuesta a la pregunta debe seguir siendo comprensible cuando se recupera por sí sola. Evalúa la superposición deliberadamente: una superposición excesiva puede llenar el conjunto de resultados con versiones repetidas del mismo pasaje.
Para el primer experimento, el bucle en memoria anterior es suficiente. A medida que crezca el corpus, usa un índice o almacén de vectores que admita el comportamiento de filtrado, eliminación y recuperación que necesitas. Prueba esas operaciones antes de confiar en las puntuaciones de similitud. Un pasaje muy similar del cliente equivocado nunca debe devolverse solo porque ocupa el primer lugar.
Comprueba por separado los límites de entrada y de lote
La referencia actual del endpoint de OpenAI especifica un máximo de 8.192 tokens por entrada y un máximo agregado de 300.000 tokens entre las entradas de una solicitud; también documenta un máximo de 2.048 entradas por lote. El texto vacío no es válido. Cuenta tokens en lugar de caracteres y deja margen por debajo de los límites al construir lotes. Restricciones del endpoint.
Si usas Azure OpenAI, la configuración del endpoint, la autenticación y los nombres de implementación tienen su propia configuración. Sigue las instrucciones de embeddings de Azure para ese servicio en lugar de asumir que una solicitud directa a OpenAI se puede copiar sin cambios. Aplica la misma separación al usar una puerta de enlace: comprueba primero su endpoint, acceso al modelo, parámetros admitidos y cuenta de facturación.
Estima el coste sin ocultar las reconstrucciones del índice
El coste de los embeddings depende de los tokens de entrada, así que cuenta por separado la ingesta de documentos, los fragmentos modificados y los embeddings de consultas. Usa el precio actual de la página del modelo correspondiente, como text-embedding-3-small, y confirma si la tarifa indicada se aplica a tu modo de solicitud.
Para un ejemplo de planificación, sea P el precio verificado por millón de tokens de entrada:
Ingesta inicial: 50,000 fragmentos × 400 tokens = 20 millones de tokens
Cambios mensuales: 5,000 fragmentos × 400 tokens = 2 millones de tokens
Consultas mensuales: 200,000 consultas × 20 tokens = 4 millones de tokens
Coste inicial de embeddings = 20 × P
Coste recurrente de embeddings = (2 + 4) × P = 6 × P
Estas son suposiciones ilustrativas de carga de trabajo, no precios de Flatkey ni de OpenAI. Añade por separado el almacenamiento vectorial, la infraestructura de búsqueda y cualquier llamada de generación de respuestas. Si cambias el modelo de embeddings, incluye una pasada completa de regeneración de embeddings en el presupuesto de migración. Una canalización que vuelve a generar embeddings para documentos sin cambios puede gastar más que la misma carga de trabajo con un modelo más grande pero almacenado correctamente en caché.
Diagnostica los errores antes de añadir reintentos
| Síntoma | Primera comprobación útil |
|---|---|
| Error de autenticación | Confirma que la clave sea válida para el endpoint y la cuenta que estás llamando. |
| Solicitud no válida | Inspecciona el cuerpo del error, las cadenas vacías, los recuentos de tokens y los parámetros admitidos. |
| Error de límite de tasa o cuota | Distingue la presión por la tasa de solicitudes de la cuota de cuenta agotada. |
| Error temporal del servidor o tiempo de espera agotado | Conserva los identificadores de solicitud y usa un comportamiento de reintento limitado. |
| Error de dimensión del almacén de vectores | Compara la configuración de la colección con la longitud real del vector devuelto. |
| Resultados plausibles pero irrelevantes | Comprueba el texto de los fragmentos, la coherencia del modelo y los ejemplos de consultas antes de culpar a la red. |
Las primeras cuatro comprobaciones siguen la guía de errores de OpenAI. Las dos últimas se refieren a tu aplicación e índice. Respeta las indicaciones de reintento del servidor y ten en cuenta los reintentos del SDK antes de añadir otro bucle de reintentos. Registra metadatos operativos sin almacenar credenciales ni texto privado innecesario de los documentos.
Evalúa la recuperación antes de elegir un modelo de respuesta
Crea un pequeño conjunto etiquetado a partir de preguntas reales de usuarios, incluidas paráfrasis, nombres exactos de productos, preguntas ambiguas y preguntas que tu corpus no puede responder. Anota el documento de origen esperado para cada consulta respondible antes de ajustar el sistema.
Para cada configuración candidata, registra si una fuente aceptable aparece en los primeros resultados, cuánto material duplicado se devuelve, la latencia de recuperación y el coste por consulta. Revisa los fallos individualmente. Si una consulta solicita un código de error exacto, una coincidencia por palabra clave puede complementar la similitud semántica. Si falta la fuente, cambiar las dimensiones de los embeddings no puede inventarla.
Mantén una parte reservada de las preguntas para la comparación final. No elijas un umbral de similitud a partir de la demostración de tres documentos y lo trates como una puntuación de confianza universal. Una prueba de aceptación útil refleja las consecuencias de una recuperación incorrecta en tu propia aplicación.
Dónde encaja Flatkey en la aplicación
Flatkey ofrece un enrutador de modelos compatible con OpenAI y un directorio actual de modelos. Utiliza la documentación de integración de Flatkey para evaluar el aspecto de generación de modelos de tu aplicación. Los ejemplos anteriores llaman a OpenAI directamente; no establecen que un modelo de embeddings o todos los parámetros de embeddings estén disponibles a través de Flatkey.
Para una aplicación con varios proveedores, mantén la configuración de recuperación independiente de la configuración de tu modelo de respuesta. Esto te permite comparar modelos de respuesta sin reconstruir el índice de documentos para cada experimento. Revisa las guías de arquitectura de API de Flatkey al planificar el enrutamiento, los controles de cuentas y las comprobaciones operativas.
Preguntas frecuentes
¿La API de embeddings responde preguntas por sí sola?
Devuelve vectores. Tu aplicación los utiliza para seleccionar contenido relacionado; un modelo de respuesta es un componente independiente si necesitas una respuesta escrita.
¿Puedo comparar vectores de diferentes modelos de embeddings?
No supongas que comparten un espacio de coordenadas significativo, incluso si sus dimensiones coinciden. Mantén índices específicos para cada modelo y evalúa las migraciones utilizando las mismas preguntas y documentos de origen.
¿Debo elegir inmediatamente el modelo de embeddings más grande?
Parte de una configuración que puedas medir. Compara la calidad de la recuperación, la latencia, el almacenamiento y el coste con tus propias consultas antes de aceptar un índice más grande o un modelo diferente.
¿Qué debo crear primero?
Utiliza la API de embeddings de Open AI para generar embeddings de un corpus pequeño y seguro en cuanto a permisos, verifica la asignación de documento a vector y prueba la recuperación con preguntas etiquetadas. Amplía el corpus después de que ese ciclo produzca evidencia fiable.
