Patrones: chunks, sincronía y calidad de la recuperación

Insertar vectores y consultarlos es la parte fácil, y quien se queda ahí construye demostraciones que impresionan con veinte documentos y decepcionan con veinte mil. Lo que separa un juguete de un sistema es lo que ocurre alrededor del índice: cómo troceas los documentos antes de embeberlos, cómo mantienes el índice al día cuando la fuente cambia, y cómo sabes —con números, no con impresiones— si lo que recuperas es realmente lo que hacía falta. Estas tres disciplinas no son opcionales ni posteriores: son el diseño mismo del sistema, y de ellas depende que la búsqueda semántica cumpla su promesa.

El chunk es la unidad de recuperación

Un documento entero rara vez debe ser un solo vector. Los modelos tienen un límite de tokens de entrada y truncan en silencio lo que sobra, pero el problema de fondo es otro y más sutil: un embedding es un promedio del significado de lo que se le da: un manual completo produce un vector que no habla de nada en particular, porque cada tema tira de él en una dirección distinta y el resultado queda en un centro difuso que no está cerca de ninguna pregunta concreta.

Trocear resuelve eso y, de paso, define lo que el sistema podrá devolver. Ese es el punto que hay que interiorizar: el fragmento no es solo la unidad que se embebe, es la unidad que se recupera y la que acabará mostrándose o pasándose a un modelo generativo. Si troceas por párrafos, tu sistema responderá con párrafos.

El punto de equilibrio habitual está entre doscientas y ochocientas palabras, con un solapamiento del diez o el quince por ciento entre fragmentos consecutivos para que una idea que cae justo en la frontera aparezca completa en al menos uno. Pero el criterio que más rendimiento da no es el tamaño sino el respeto por la estructura: corta en encabezados, en secciones, en párrafos, nunca a mitad de frase. Un troceado que sigue la arquitectura del documento produce fragmentos que ya eran unidades de sentido antes de que tú los definieras.

Hay una técnica sencilla que mejora la recuperación más que casi cualquier otro ajuste y que casi nadie aplica al principio: enriquecer el texto antes de embeberlo. Un fragmento arrancado de la mitad de un manual pierde el contexto que lo hacía comprensible —de qué documento venía, bajo qué encabezado— y su vector queda flotando sin anclaje. Anteponer ese contexto al texto que embebes coloca el fragmento en la vecindad correcta del espacio.

// lo que se embebe lleva contexto; lo que se guarda y se muestra es el texto limpio
const paraEmbeber = `${documento.titulo} — ${seccion}\n\n${texto}`;
const { data } = await env.AI.run("@cf/google/embeddinggemma-300m", {
  text: [paraEmbeber],
});

Fíjate en la disociación: el texto enriquecido solo existe para generar el vector, mientras que el fragmento que guardas y acabas mostrando sigue siendo el original. Esa separación entre lo que se embebe y lo que se devuelve es una de las libertades más infrautilizadas del oficio.

// el identificador codifica documento y posicion: determinista y reconstruible
const fragmentos = trocear(documento.texto, { palabras: 400, solape: 60 });

const vectores = fragmentos.map((texto, i) => ({
  id: `${documento.id}#${String(i).padStart(4, "0")}`,
  values: embeddings[i],
  namespace: documento.cliente,
  metadata: {
    doc_id: documento.id,
    posicion: i,
    idioma: documento.idioma,
    actualizado_en: documento.actualizadoEn,
  },
}));

Fíjate en el identificador. Al derivarlo del documento y de la posición, obtienes gratis dos propiedades valiosísimas: reindexar el mismo documento sobrescribe exactamente los mismos vectores, y desde cualquier resultado puedes reconstruir a qué documento y a qué parte pertenece sin consultar nada. La metadata repite el doc_id porque un identificador no se puede filtrar, pero un campo indexado sí.

Mantener el índice sincronizado

El índice es una proyección derivada de tus documentos, y toda proyección derivada tiende a divergir de su origen. Cada vez que un documento cambia hay que reembeber sus fragmentos y volver a escribirlos, y esa operación es idempotente gracias a los identificadores deterministas: upsert sobre los mismos identificadores deja el índice exactamente igual sin importar cuántas veces se ejecute.

Lo que no resuelve upsert es el caso incómodo. Si un documento tenía doce fragmentos y tras la edición tiene nueve, los tres últimos siguen en el índice apuntando a texto que ya no existe. Son vectores huérfanos, y contaminan silenciosamente los resultados con contenido obsoleto que parece legítimo. Reindexar bien exige siempre dos pasos: escribir los fragmentos actuales y borrar la cola sobrante.

// 1. reescribir los fragmentos vigentes
await env.VECTORIZE.upsert(vectores);

// 2. eliminar la cola que quedo huerfana tras acortarse el documento
const sobrantes = [];
for (let i = fragmentos.length; i < conteoAnterior; i++) {
  sobrantes.push(`${documento.id}#${String(i).padStart(4, "0")}`);
}
if (sobrantes.length) await env.VECTORIZE.deleteByIds(sobrantes);

flowchart LR
SRC[documento en D1 o R2] --> EV[evento de cambio]
EV --> Q[cola o workflow]
Q --> CH[trocear]
CH --> EM[embeber por lotes]
EM --> UP[upsert de fragmentos]
UP --> DEL[borrar huerfanos]
style Q fill:#f9e2af,color:#11111b
style UP fill:#cba6f7,color:#11111b

La forma correcta de ejecutar esa canalización no es dentro de la petición que edita el documento. Embeber y escribir son operaciones lentas, susceptibles de fallar y sujetas a límites de lote, así que el patrón es publicar un evento de cambio en una cola o arrancar un workflow, y dejar que el proceso de indexación avance por su cuenta con reintentos. La asincronía de Vectorize encaja de forma natural con ese desacople: nadie está esperando el resultado.

El borrado de un documento completo plantea el mismo problema en su versión extrema: hay que eliminar todos sus fragmentos, y el índice no ofrece un borrado por prefijo de identificador. La solución es guardar en tu fuente de verdad cuántos fragmentos generó cada documento, o llevar la lista de sus identificadores, de modo que el borrado sea una operación determinista y no una búsqueda a ciegas. Ese pequeño contador es una de esas piezas de contabilidad que parecen redundantes hasta que un día no la tienes.

Para auditar la deriva tienes list-vectors, que pagina los identificadores del índice en páginas de hasta mil con consistencia de instantánea. Cruzar esa lista contra los identificadores que tu fuente de verdad debería tener es la única forma fiable de detectar huérfanos acumulados por ejecuciones fallidas, y merece la pena como tarea periódica en un cron.

Medir la calidad de la recuperación

Lo más habitual en sistemas de este tipo es que nadie mida nada. Se prueban cuatro preguntas a mano, los resultados parecen razonables y el sistema se da por bueno; meses después alguien nota que responde mal a un tipo de consulta y no hay forma de saber si eso empeoró o siempre fue así. La cura es barata: un conjunto de referencia con preguntas reales y, para cada una, los fragmentos que deberían recuperarse.

Cincuenta preguntas bien elegidas bastan para empezar. Lo caro no es construirlo sino mantenerlo, y la disciplina consiste en añadir cada consulta que alguien reporta como fallida, de modo que el conjunto crezca justo donde el sistema flaquea.

// recall en k sobre un conjunto de referencia, en una docena de lineas
let aciertos = 0;
for (const caso of referencia) {
  const { data } = await env.AI.run(MODELO, { text: [caso.pregunta] });
  const { matches } = await env.VECTORIZE.query(data[0], { topK: 5 });
  const ids = matches.map((m) => m.id);
  if (caso.esperados.some((id) => ids.includes(id))) aciertos++;
}
const recall = aciertos / referencia.length;

Ese bucle, ejecutado como una tarea programada o como un paso previo a cada despliegue, es toda la infraestructura de evaluación que necesitas para empezar. Lo importante no es la sofisticación de la métrica sino que el número exista, quede registrado y pueda compararse con el de la semana pasada.

Con esos números en la mano, cada decisión de diseño se vuelve comprobable en lugar de opinable. Cambiar el tamaño de fragmento, subir el solapamiento, probar otro modelo de embeddings, ajustar el topK o introducir un umbral de score: todo pasa a ser un experimento con un resultado, y el conjunto de referencia es el árbitro. Vigila además la distribución de los score, porque un corpus sano muestra una separación clara entre los buenos resultados y el resto; cuando esa separación se aplana, suele ser síntoma de fragmentos demasiado largos o de un modelo que no entiende tu dominio.

Y no midas solo la media. Un promedio saludable puede esconder que el sistema falla sistemáticamente en una familia entera de preguntas —las muy cortas, las que usan jerga interna, las de un idioma minoritario en tu corpus—, y ese patrón solo aparece si agrupas los casos del conjunto de referencia por tipo y miras cada grupo por separado.

Una última advertencia sobre dónde poner el foco. Cuando el índice alimenta a un modelo generativo, la tentación es evaluar solo la respuesta final, y es un error de método: si la recuperación falla, ninguna cantidad de habilidad del generador lo arregla, porque el contexto correcto sencillamente no llegó. Mide la recuperación por separado y hazlo primero.