Qué es un embedding: el significado hecho geometría

Cada almacén que has aprendido hasta aquí responde preguntas de identidad. KV te devuelve el valor de una clave exacta, D1 filtra las filas que cumplen un predicado, R2 te entrega el objeto que nombraste. Todos comparten un supuesto invisible —que sabes describir lo que buscas mediante una condición literal— y ese supuesto se derrumba en cuanto la pregunta es “dame lo que hable de lo mismo que esto”. Un embedding es la pieza que rompe ese muro: convierte un texto en un punto de un espacio de cientos de dimensiones, situado de tal modo que las cosas con sentido parecido caen cerca unas de otras. A partir de ahí, buscar por significado deja de ser un problema de lingüística y pasa a ser uno de geometría.

Del texto a un punto en el espacio

Un modelo de embeddings es una función determinista que toma un fragmento de texto y devuelve una lista fija de números en coma flotante. Si el modelo declara 768 dimensiones, cualquier entrada —una palabra suelta o un párrafo entero— sale convertida en exactamente 768 valores. El vector se llama denso porque casi todas sus posiciones cargan información, a diferencia de las representaciones dispersas clásicas, donde la inmensa mayoría de las casillas eran ceros y cada casilla correspondía a una palabra concreta del vocabulario.

// el modelo convierte texto en un vector denso de 768 numeros
const { data } = await env.AI.run("@cf/google/embeddinggemma-300m", {
  text: ["El gato duerme sobre el tejado"],
});
const vector = data[0]; // 768 valores en coma flotante

El campo text acepta un array porque embeber es una operación que se amortiza en lote: pasarle treinta fragmentos de golpe cuesta mucho menos que treinta llamadas sueltas, y por eso toda canalización de indexación seria agrupa antes de invocar. La respuesta llega en data con un vector por cada entrada y en el mismo orden en que los mandaste, correspondencia que conviene no perder si vas a construir identificadores a partir de la posición.

// embeber en lote: un vector por entrada, en el mismo orden
const { data } = await env.AI.run("@cf/google/embeddinggemma-300m", {
  text: fragmentos, // un array de cadenas
});
console.log(data.length === fragmentos.length); // true

Hay un límite silencioso que conviene conocer desde el principio. Cada modelo admite un máximo de tokens de entrada y lo que sobra se descarta sin avisar: si le entregas un documento de veinte páginas a un modelo que acepta unos cientos de tokens, obtendrás un vector perfectamente válido que solo representa el principio. Ese truncado invisible es una de las causas más frecuentes de sistemas que recuperan mal sin dar ninguna señal de error, y la razón de que la siguiente decisión —cómo trocear— pese tanto.

Lo desconcertante, y lo decisivo, es que ninguna de esas 768 posiciones tiene nombre. No existe una dimensión “trata de animales” y otra “tono formal”: el modelo aprendió durante su entrenamiento un sistema de coordenadas propio y distribuido, donde el sentido no reside en ejes aislados sino en la posición conjunta de todos ellos. Por eso un embedding es opaco a la inspección humana y transparente a la comparación. No puedes leerlo, pero puedes medir distancias con él, y esa asimetría es justo lo que lo hace útil.

Esa geografía aprendida tiene una propiedad que sorprende la primera vez y que a ti, trabajando en español, te importa especialmente. Los modelos multilingües sitúan una frase y su traducción prácticamente en el mismo punto, porque durante el entrenamiento aprendieron que expresan el mismo contenido. La consecuencia práctica es notable: con el modelo adecuado puedes preguntar en español y recuperar documentos escritos en inglés sin traducir nada por el camino, algo sencillamente inalcanzable para cualquier buscador basado en palabras. Y a la inversa, un modelo entrenado solo en inglés colocará tu corpus en español en una región empobrecida de su espacio, con resultados mediocres que ningún ajuste posterior arregla.

De ahí se sigue una consecuencia que conviene fijar antes que ninguna otra: el espacio pertenece al modelo. Dos modelos distintos producen dos geografías incompatibles aunque ambos declaren 768 dimensiones, porque cada uno colocó los conceptos donde su entrenamiento decidió. Comparar el vector de un modelo con el de otro no arroja un resultado malo, arroja un resultado sin sentido, como medir la distancia entre una coordenada de Madrid y una latitud marciana.

La similitud es un ángulo

Si el significado es una posición, el parecido es una distancia, y hay más de una forma de medirla. La que domina en texto es la similitud del coseno: mide el ángulo entre dos vectores e ignora por completo su longitud. Esa indiferencia a la magnitud no es un capricho, es lo que quieres cuando comparas un fragmento largo con uno corto y te interesa la dirección del significado, no cuánta tinta se gastó en expresarlo.

La elección no es libre: cada modelo se entrenó optimizando una de estas funciones, y usar otra degrada los resultados sin producir ningún error visible. Lo veremos con detalle al crear el índice, porque esa decisión queda congelada para siempre.

El cálculo no tiene ningún misterio y merece la pena escribirlo una vez a mano, aunque en producción nunca lo hagas tú. Es el producto escalar de los dos vectores dividido por el producto de sus longitudes, y ese denominador es exactamente lo que anula el efecto de la magnitud.

// la similitud del coseno, escrita a mano una sola vez en la vida
function coseno(a: number[], b: number[]): number {
  let punto = 0, normaA = 0, normaB = 0;
  for (let i = 0; i < a.length; i++) {
    punto += a[i] * b[i];
    normaA += a[i] * a[i];
    normaB += b[i] * b[i];
  }
  return punto / (Math.sqrt(normaA) * Math.sqrt(normaB));
}

Muchos modelos entregan sus vectores ya normalizados a longitud unitaria, y ese detalle tiene una consecuencia práctica curiosa: cuando ambas longitudes valen uno, el denominador desaparece y el coseno se reduce al producto escalar. Por eso, con esos modelos, cosine y dot-product ordenan los resultados exactamente igual y la discusión sobre cuál elegir se vuelve puramente formal.

El resultado de comparar dos vectores es un escalar al que llamamos score. Con cosine, ese número se mueve en un rango donde el máximo indica dirección idéntica y los valores intermedios indican parecido decreciente. Interpretarlo exige recordar de dónde sale: es la afinidad geométrica que el modelo aprendió, no un porcentaje de verdad ni una medida de relevancia calibrada para tu dominio.

flowchart LR
T[texto de origen] --> M[modelo de embeddings]
M --> V[vector denso]
V --> I[indice vectorial]
Q[consulta del usuario] --> M2[el mismo modelo]
M2 --> QV[vector de consulta]
QV --> I
I --> R[los k vecinos mas cercanos]
style M fill:#89b4fa,color:#11111b
style I fill:#cba6f7,color:#11111b

Hay un matiz sobre esa simetría que separa a quien entiende el mecanismo de quien lo repite. Documento y consulta no se parecen en nada como textos: uno es un párrafo declarativo y la otra una pregunta breve, con otro registro y otra longitud. Que un modelo de embeddings los coloque cerca cuando tratan del mismo tema no es evidente, es precisamente lo que aprendió a hacer durante su entrenamiento, y por eso su calidad se mide sobre pares de pregunta y pasaje relevante. Elegir un modelo para recuperación es elegir uno entrenado para tender ese puente entre dos formas de decir muy distintas.

Fíjate en la simetría del diagrama, porque es la regla de oro de todo el nivel: el mismo modelo tiene que embeber los documentos y las consultas. En el momento en que indexas con un modelo y preguntas con otro, la geometría se rompe y los resultados dejan de significar nada, aunque el sistema siga devolviendo números con toda la apariencia de normalidad.

Por qué tu base de datos de siempre no sirve

Podrías pensar que esto se resuelve con una tabla y un poco de SQL. Guarda el vector como un blob en D1, recórrelos todos, calcula el coseno contra cada uno y ordena. Con mil documentos funciona; con un millón, cada consulta obliga a leer un millón de filas y hacer un millón de productos escalares de 768 términos. El coste crece linealmente con el corpus, y es exactamente el patrón que una base relacional no puede indexar, porque sus índices —árboles B, tablas hash— presuponen un orden total sobre una clave y en un espacio de 768 dimensiones no existe tal orden.

La solución del sector es, por tanto, renunciar a la exactitud a cambio de velocidad. Las estructuras que lo consiguen agrupan vectores próximos y construyen atajos entre regiones del espacio, de modo que una consulta desciende hacia la vecindad correcta saltando y no recorriendo. Se llaman aproximadas porque ese descenso puede dejarse algún vecino legítimo por el camino, y ese trato —una pizca de recall a cambio de varios órdenes de magnitud en latencia— es lo que hace viable la búsqueda semántica en producción.

Nada de esto convierte la búsqueda literal en una reliquia, y conviene decirlo antes de que el entusiasmo haga estragos. Hay consultas donde la coincidencia exacta es justamente lo que el usuario quiere: un código de producto, un identificador de incidencia, un nombre propio poco frecuente. La similitud semántica es mala en esos casos precisamente porque generaliza, y devolverá cosas parecidas cuando lo que hacía falta era esa y no otra. Los sistemas maduros combinan ambos mundos —una búsqueda por palabras y otra por vectores, fusionando después sus resultados—, y saber cuándo tu problema pide una, otra o las dos es parte del criterio que este nivel pretende darte.

Conviene detenerse un segundo en lo que significa aceptar una respuesta aproximada, porque rompe una expectativa profundamente arraigada. Una consulta de SQL con un índice devuelve exactamente las filas que cumplen el predicado, siempre, y esa exactitud es innegociable. Una consulta vectorial devuelve los que casi con toda seguridad son los más parecidos, y admitir ese “casi” es la condición de entrada a este territorio. No es una debilidad de la implementación, es la única forma conocida de que la pregunta sea respondible en el tiempo que tienes.

Merece la pena ver la alternativa para apreciar lo que se te está dando hecho. Montar esto por tu cuenta significa elegir una estructura de índice, ajustar sus parámetros de construcción y de búsqueda, dimensionar la memoria que ocupa —los índices de este tipo suelen vivir en RAM—, decidir cómo se reconstruye tras una caída y cómo se replica para no tener un punto único de fallo. Es un proyecto de infraestructura completo, con su propio equipo si el corpus crece.

Vectorize es la implementación de esa idea dentro de la plataforma. Es una base de datos vectorial gestionada, accesible desde un Worker mediante un binding como cualquier otro almacén, que en 2026 admite índices de hasta 10 millones de vectores con un máximo de 1536 dimensiones en precisión de 32 bits. No la operas, no la escalas y no eliges su algoritmo: declaras el índice, insertas vectores y consultas por proximidad.

Con eso queda dibujado el mapa del nivel. Sabes qué es un embedding, por qué la similitud es geometría y qué estructura hace falta para buscar vecinos sin recorrer el corpus entero. Lo que viene a continuación son las cuatro decisiones prácticas que convierten esa idea en un sistema: cómo se declara el índice, cómo se escriben y se consultan los vectores, cómo se acota la búsqueda antes de comparar y cómo se mantiene todo ello sincronizado y medido.