Crear un índice: dimensiones y métrica

Crear un índice en Vectorize es un comando de una sola línea, y esa brevedad engaña. En esa línea tomas dos decisiones —cuántas dimensiones y qué métrica— que quedan grabadas en el índice de por vida y que no describen tus datos, sino el modelo de embeddings con el que vas a trabajar. Elegirlas mal no produce un error al crear, produce un índice que funciona en apariencia y responde disparates, o que rechaza tus vectores el día que intentas insertarlos. Este es un caso raro y valioso en la plataforma: una configuración inmutable que te obliga a pensar antes de escribir.

El comando y sus dos decisiones

La creación vive en Wrangler, no en el código. Le das un nombre único en tu cuenta, el número de dimensiones y la métrica de distancia, y el índice queda provisionado y vacío, listo para recibir vectores.

# el nombre admite hasta 64 bytes y debe ser unico en la cuenta
npx wrangler vectorize create guia-docs --dimensions=768 --metric=cosine

# comprobar que existe y con que configuracion quedo
npx wrangler vectorize get guia-docs
npx wrangler vectorize info guia-docs

Hay un atajo que evita el error más común. Si vas a usar un modelo conocido, el flag --preset deriva por ti las dimensiones y la métrica correctas a partir del nombre del modelo, de modo que no puedas equivocarte al transcribir un número. Es la vía recomendada siempre que tu modelo figure entre los presets disponibles.

# el preset fija dimensiones y metrica segun el modelo
npx wrangler vectorize create guia-docs --preset="@cf/baai/bge-base-en-v1.5"

Los dos comandos de inspección no son intercambiables. get te devuelve la configuración declarada —dimensiones, métrica, descripción—, mientras que info añade el estado real del índice, como el número de vectores que contiene y cuándo se procesó la última mutación. El primero responde “cómo lo definí”; el segundo, “qué hay dentro ahora mismo”.

El nombre merece más cuidado del que parece. Como no puede cambiarse y va a aparecer en el manifiesto de todos tus entornos, conviene que codifique aquello que de verdad distingue un índice de otro: el corpus y, sobre todo, el modelo con el que se embebió. Un nombre como docs-es-768 te recordará dentro de seis meses por qué existe; uno como indice-2 te obligará a averiguarlo. Y como el día que cambies de modelo tendrás que convivir un tiempo con dos índices en paralelo, agradecerás que sus nombres se distingan solos.

# el inventario de indices de la cuenta, util cuando conviven varias generaciones
npx wrangler vectorize list

Las dimensiones son un contrato

El número de dimensiones no lo eliges tú: lo dicta el modelo de embeddings. Si @cf/google/embeddinggemma-300m produce vectores de 768 valores, tu índice tiene que declarar 768 y ni uno más. No es una sugerencia ni un valor por defecto que el sistema ajuste: es un contrato que Vectorize verifica en cada inserción y que rechaza si no cuadra.

La verificación es estricta y ocurre en cada escritura. Un vector cuya longitud no coincida con las dimensiones declaradas se rechaza con un error, lo cual es una buena noticia: es un fallo ruidoso y temprano, no una degradación silenciosa. El error de verdad peligroso es el otro, el que no se detecta, y es usar un modelo distinto que casualmente produce el mismo número de dimensiones. El índice acepta esos vectores sin protestar porque la forma encaja, pero el espacio es otro, y el sistema empieza a devolver resultados incoherentes sin que nada falle.

// comprobacion defensiva antes de escribir un lote
const { dimensions } = await env.VECTORIZE.describe();
if (embedding.length !== dimensions) {
  throw new Error("el modelo no corresponde a este indice");
}

El techo actual es de 1536 dimensiones con precisión de 32 bits por componente, lo que acomoda a la práctica totalidad de los modelos de texto en circulación. Y conviene no leer más dimensiones como sinónimo de mejor: un vector más largo captura matices más finos, pero ocupa más, consume más ancho de banda en cada consulta y encarece cada comparación. La elección real no es cuántas dimensiones quieres, sino qué modelo se ajusta a tu dominio y a tu idioma, y las dimensiones vienen dadas de propina.

La métrica decide qué significa parecido

La métrica define la función con la que se compara tu vector de consulta contra los vectores almacenados, y por tanto define qué entiende el índice por parecido. Las tres opciones responden a geometrías distintas y no son cuestión de gusto: cada modelo se entrena optimizando una de ellas, y usar otra degrada la calidad de la recuperación de forma silenciosa.

La métrica no solo cambia el orden de los resultados, cambia la escala del número que los acompaña. Un score de coseno y una distancia euclídea no viven en el mismo rango ni se leen en el mismo sentido —en una, más alto es mejor; en la otra, más bajo—, así que cualquier umbral que introduzcas en tu código está atado a la métrica del índice. Es otra razón para no tratar estos valores como magnitudes universales trasladables de un sistema a otro.

La regla práctica es sencilla y aburrida: consulta la ficha de tu modelo y usa la métrica que declara. Cuando el modelo normaliza sus salidas a longitud unitaria —lo que hacen casi todos los de la familia BGE— cosine y dot-product producen el mismo orden de resultados, así que el debate se vuelve académico. El error de verdad es elegir euclidean para un modelo pensado para coseno y descubrir meses después que las respuestas son mediocres sin saber por qué.

Enlazar el índice al Worker

Un índice creado es infraestructura inerte hasta que un Worker lo alcanza, y eso ocurre con un binding declarado en el manifiesto, igual que con KV, D1 o R2. El nombre del binding es el que verás en env; el index_name es el que le diste a Wrangler al crearlo.

{
  "vectorize": [
    {
      "binding": "VECTORIZE",
      "index_name": "guia-docs"
    }
  ]
}

Nada impide declarar varios bindings a la vez, y precisamente esa posibilidad es la que hace llevadera una migración de modelo: durante el trasvase, el Worker ve el índice viejo y el nuevo al mismo tiempo, escribes en ambos, comparas resultados y solo al final retiras el que sobra.

Hay un detalle de desarrollo local que ahorra confusión. A diferencia de KV o D1, que ofrecen una emulación local completa, un índice de Vectorize no se simula en tu máquina: las operaciones se dirigen al índice real de tu cuenta. Eso significa que conviene tener un índice separado para desarrollo, declarado en un entorno propio del manifiesto, para no ensuciar el de producción con vectores de prueba que después habrá que localizar y borrar.

Tras tocar el manifiesto, ejecuta wrangler types para que env.VECTORIZE quede tipado y el editor conozca los métodos disponibles. Desde el Worker puedes pedirle al propio índice que te recuerde su configuración, algo especialmente útil como comprobación defensiva al arrancar un proceso de indexación.

// describe devuelve la configuracion real del indice
const detalles = await env.VECTORIZE.describe();
console.log(detalles.dimensions, detalles.processedUpToMutation);

flowchart LR
MOD[modelo de embeddings] --> DIM[dimensiones fijas]
MOD --> MET[metrica recomendada]
DIM --> IDX[wrangler vectorize create]
MET --> IDX
IDX --> BIND[binding en el manifiesto]
BIND --> W[env.VECTORIZE en el Worker]
style MOD fill:#89b4fa,color:#11111b
style IDX fill:#cba6f7,color:#11111b

Un apunte de capacidad para cerrar el cuadro. Una cuenta de pago admite decenas de miles de índices y cada índice hasta diez millones de vectores, cifras que en la práctica sacan la escala de la lista de preocupaciones. Eso libera una decisión de diseño que de otro modo estaría constreñida: puedes permitirte índices separados por corpus, por idioma o por generación de modelo en lugar de amontonarlo todo en uno, y esa separación suele simplificar mucho más de lo que cuesta.

Lee el diagrama de izquierda a derecha y verás que la cadena entera nace en el modelo. No eliges dimensiones y luego buscas un modelo que encaje: eliges el modelo por su calidad en tu idioma y tu dominio, y él te dicta el resto. Invertir ese orden es la fuente más habitual de índices mal configurados.