Las APIs de embeddings convierten texto en vectores para búsqueda semántica, RAG, agrupamiento, deduplicación y recomendaciones. No generan texto, pero son la base de casi todas las aplicaciones de base de conocimiento.
Esta guía explica cómo llamar a una API de embeddings, cómo elegir un modelo y cómo evaluar el costo y la calidad de recuperación antes de construir un pipeline de producción.
Nota: las interfaces y dimensiones de los modelos de embeddings varían según el proveedor. Este artículo usa la API compatible con OpenAI como ejemplo; consulta la documentación oficial o del sitio para los detalles específicos.
1. Qué pueden hacer los embeddings
- Búsqueda semántica: encontrar contenido por significado en lugar de por coincidencia de palabras clave.
- RAG: dividir documentos en fragmentos, generar embeddings, recuperar las piezas relevantes y pasarlas a un LLM para obtener una respuesta.
- Agrupamiento y clasificación: reunir textos similares.
- Deduplicación: encontrar contenido repetido o casi duplicado.
- Recomendaciones: mostrar artículos o productos similares.
El elemento común es la similitud. Un modelo de embeddings asigna el texto a un punto en un espacio de alta dimensión, y se espera que los puntos cercanos signifiquen cosas similares. Esa propiedad es útil incluso cuando no interviene ningún modelo generativo.
2. Cómo llamarla
El endpoint compatible con OpenAI suele ser:
POST /v1/embeddings
Solicitud:
{
"model": "text-embedding-3-small",
"input": ["First piece of text", "Second piece of text"]
}
La respuesta contiene un vector por cada entrada. Los nombres de modelo y las dimensiones siguen la página de precios de modelos. La mayoría de los proveedores aceptan lotes, lo que resulta más económico y rápido que enviar una solicitud por fragmento, pero cada modelo tiene una longitud máxima de entrada. Trunca o divide el texto largo de forma deliberada en lugar de dejar que el proveedor lo corte en silencio. Si tu base de datos vectorial espera vectores normalizados, aplica la misma normalización a documentos y consultas; mezclar convenciones reduce la calidad de la similitud.
3. Ejemplo en Python
from openai import OpenAI
client = OpenAI(
api_key="sk-your-key",
base_url="https://ai.zhongshangqihang.com/v1",
)
resp = client.embeddings.create(
model="text-embedding-3-small",
input=["What is an API gateway", "What is an API Gateway"],
)
print(len(resp.data[0].embedding))
Las dos entradas anteriores son casi idénticas, así que sus vectores deberían ser cercanos. Ejecutar comprobaciones pequeñas como esta es una forma rápida de confirmar que el endpoint, la clave y el nombre del modelo son correctos antes de generar embeddings de un corpus completo.
4. El flujo básico de RAG
- Limpia los documentos y divídelos en fragmentos por párrafo o encabezado.
- Llama a la API de embeddings para cada fragmento.
- Guarda los vectores en una base de datos vectorial como pgvector, Milvus o Qdrant.
- Cuando un usuario hace una pregunta, genera también el embedding de la pregunta.
- Recupera los fragmentos más similares.
- Envía el contexto recuperado y la pregunta a un LLM.
El tamaño de los fragmentos, el solapamiento y los metadatos afectan el resultado. Guarda la fuente, el título de la sección y los permisos de acceso junto a cada vector; sin ellos, puedes recuperar el texto correcto pero no mostrar de dónde salió ni si el usuario tiene permitido verlo.
5. Cómo elegir un modelo
| Criterio | Qué confirmar |
|---|---|
| Dimensión | Más alta no siempre es mejor; también aumenta el almacenamiento y el costo |
| Idioma | Calidad en chino, inglés y otros idiomas objetivo |
| Entrada máxima | La longitud de un solo fragmento |
| Precio | Facturación por token |
| Coherencia | Los vectores de modelos distintos no se pueden mezclar |
| Despliegue | Si se admite despliegue privado o cumplimiento de datos |
Evalúa con tus propias consultas. Un modelo que rinde bien en benchmarks generales puede fallar con términos del dominio, nombres de productos o abreviaturas que importan a tus usuarios. Si necesitas recuperación multilingüe, prueba cada idioma por separado en lugar de suponer que la puntuación media se aplica en todas partes.
6. Cómo calcular el costo
Costo mensual =
tokens totales de documentos × precio unitario
+ tokens de consultas × precio unitario
+ almacenamiento de vectores y ancho de banda
Generar embeddings de una colección de documentos suele ser un costo único, mientras que las consultas son un costo recurrente. Cambiar el modelo de embeddings implica volver a generar los embeddings de toda la colección, así que incluye ese costo de migración en la decisión. Ten en cuenta también el crecimiento del almacenamiento: los vectores son pequeños individualmente, pero se acumulan cuando conservas varias versiones de un corpus.
7. Errores comunes
- Mezclar vectores antiguos y nuevos después de cambiar el modelo de embeddings, lo que corrompe la recuperación.
- Fragmentos demasiado grandes para recuperar con precisión, o demasiado pequeños para conservar el contexto.
- No guardar metadatos de fuente y permisos, de modo que las respuestas no se pueden rastrear.
- Confiar solo en la búsqueda vectorial sin recuperación híbrida por palabras clave, lo que vuelve inestable el recall.
- Ignorar las diferencias de calidad entre idiomas.
Preguntas frecuentes
¿Cuál es la diferencia entre embeddings y un LLM?
Los embeddings producen vectores para recuperación y agrupamiento. Un modelo de lenguaje grande produce texto para generación y razonamiento.
¿Se pueden desplegar embeddings localmente?
Sí. Los modelos de embeddings de código abierto pueden ejecutarse en tu propia infraestructura, pero requieren capacidad de GPU y operaciones continuas.
¿Puede una misma clave llamar a modelos de embeddings y de chat?
En un gateway, normalmente sí. El modelo se selecciona en los parámetros de la solicitud, así que la misma clave puede servir a ambos endpoints.
Próximos pasos
Si necesitas un endpoint unificado, facturación por uso y acceso a varios modelos, puedes registrarte en ZSQH AI Gateway y hacer una prueba pequeña con modelos de embeddings y de chat. Los nombres de modelo y los precios aparecen en la página de precios de modelos.
Lecturas relacionadas:
