Back-end19 min de lectura
Qué es RAG: indexación, búsqueda híbrida y un caso real
Qué es RAG (Retrieval-Augmented Generation), explicado con un caso real: crawler, chunking, embeddings, vector store, búsqueda híbrida, re-rank y fuentes citadas.

Si llegaste aquí buscando "qué es RAG", seguro ya viste la sigla en ofertas de trabajo, en posts sobre IA y en todo producto que promete "conversa con tus documentos". La idea es mucho más simple que el nombre.
Construí un RAG desde cero: Nixa AI, un asistente de chat que responde preguntas sobre la documentación pública de NICE CXone, una plataforma de contact center. Preguntas en portugués, busca los fragmentos correctos en la documentación oficial y responde diciendo de dónde los sacó. El código es abierto y está en GitHub.
Este post explica qué es RAG, cómo funciona la indexación (crawler, chunks, embeddings, vector store) y el camino de una pregunta (búsqueda híbrida, re-rank, prompt y fuentes), con los números reales del proyecto.
TL;DR#
- RAG es buscar antes de responder. La app busca fragmentos relevantes en tus documentos y se los entrega al modelo junto con la pregunta.
- Tiene dos mitades: la indexación, que corre antes (descarga, corta, convierte en vector, guarda), y la pregunta, que corre en cada mensaje (busca, ordena, arma el prompt, genera).
- Un embedding es un vector de números que representa el sentido de un texto. Textos parecidos se vuelven vectores cercanos.
- La búsqueda solo por sentido falla con nombres de API. En Nixa, la nota es 75% sentido y 25% palabra, y después un re-rank la ajusta por fuente, tipo de página y antigüedad.
- Un índice, un modelo de embedding. Si cambias el modelo, reindexas todo.
- RAG no le enseña nada al modelo, solo le da contexto. Si la respuesta no está en los documentos, lo correcto es decir que no la encontró.
El problema: el modelo no leyó tu documentación#
Un LLM sabe lo que estaba en sus datos de entrenamiento hasta una fecha de corte. La documentación de tu producto, la release note de la semana pasada, la wiki del equipo: nada de eso lo vio. Si le preguntas igual, hace lo que mejor sabe hacer, que es escribir un texto plausible. A veces acierta, a veces con un endpoint que nunca existió.
La documentación de CXone es grande, está repartida en varios sitios (centro de ayuda, portal de developers, SDKs en GitHub) y casi toda en inglés. Encontrar una respuesta suele significar abrir diez pestañas. Era el escenario perfecto para RAG.
Qué es RAG#
RAG es la sigla de Retrieval-Augmented Generation: generación aumentada por recuperación. El nombre viene de un artículo de 2020 de investigadores de Facebook AI, y la idea cabe en una frase: antes de generar la respuesta, recupera los fragmentos relevantes y ponlos en el prompt.
Es un examen a libro abierto. El modelo sigue siendo quien escribe, pero en vez de responder de memoria, responde con la página abierta delante.
Son tres pasos:
- Retrieval (recuperación): encontrar, en una base de documentos, los fragmentos que tienen que ver con la pregunta.
- Augmentation (aumento): armar el prompt con esos fragmentos y la pregunta.
- Generation (generación): el LLM escribe la respuesta usando ese contexto.
Los pasos 2 y 3 son casi triviales. Casi todo el trabajo (y casi todo bug) vive en el 1. Y para recuperar bien, la base tiene que estar preparada de antes: eso es la indexación.
¿RAG, fine-tuning o pegar todo en el prompt?#
Antes de construir, vale la pena entender por qué no las otras dos opciones obvias.
| Pegar todo en el prompt | Fine-tuning | RAG | |
|---|---|---|---|
| Cómo funciona | Manda los documentos enteros en cada pregunta | Entrena el modelo de nuevo con tus datos | Busca los fragmentos relevantes y manda solo esos |
| Documento nuevo | Solo pegarlo | Entrenar de nuevo | Indexar la página nueva |
| Costo por pregunta | Alto: todos los tokens, cada vez | Bajo | Bajo: solo algunos fragmentos |
| Muestra la fuente | Difícil | No | Sí, cada fragmento sabe de dónde vino |
| Bueno para | Pocos documentos cortos | Enseñar estilo, formato, tarea | Base grande, que cambia y necesita fuente |
Pegar todo funciona cuando el contenido cabe con holgura en la ventana de contexto. No era mi caso: una sola de las páginas de release notes que indexé pasa de 140 mil caracteres. El fine-tuning enseña comportamiento, no es bueno para guardar datos que cambian cada semana y no te dice de dónde sacó la respuesta. RAG resuelve justo las dos cosas que necesitaba: contenido que cambia y fuente en cada respuesta.
Las dos mitades de un RAG#
Todo RAG tiene dos mitades, que corren en momentos distintos:
- Indexación, antes de cualquier pregunta: buscar los documentos, cortarlos en pedazos, convertir cada pedazo en vector y guardarlo.
- Pregunta, en cada mensaje: convertir la pregunta en vector, encontrar los pedazos más cercanos, ordenarlos, armar el prompt y llamar al LLM.
En Nixa, la indexación es una ruta de la API que disparo desde la interfaz y que va mandando el progreso por streaming. La pregunta es la ruta del chat.
Indexación, paso a paso#
1. El crawler: descargar y limpiar#
El crawler empieza por una lista de 154 URLs semilla y solo sigue enlaces dentro de 11 dominios permitidos: el centro de ayuda, el portal de developers y los SDKs oficiales en GitHub y npm. Login, páginas de error, archivos binarios y GitHub de terceros quedan fuera.
Para cada página, descarga el HTML y usa Cheerio para tirar todo lo que no es contenido: menú, pie de página, banner de cookies, "¿te sirvió esta página?". Esa basura parece inofensiva, pero si entra al índice, aparece en todo resultado de búsqueda, porque está en todas las páginas.
import * as cheerio from "cheerio";
export async function crawlPage(url: string) {
const html = await fetch(url).then((res) => res.text());
const $ = cheerio.load(html);
// The same menu on every page means noise in every search result
$("nav, footer, header, script, style, .cookie-banner").remove();
const title = $("h1").first().text().trim();
const content = $("main, article").first().text().trim();
if (content.length < 150) return null; // empty or error page
const pageType = classify(url, title); // api, reference, guide, release
return { url, title, content, breadcrumb: getBreadcrumb($), pageType };
}Además del texto, el crawler guarda metadatos: título, breadcrumb (la ruta tipo "Agente > Copilot > Configurar"), el tipo de página (API, referencia, guía, release note) y un hash SHA-256 del contenido. El hash sirve para ahorrar: en la próxima indexación, si la página no cambió, no pasa por el embedding otra vez. Y una página indexada hace más de dos semanas se descarga de nuevo.
Ten presentes los metadatos, vuelven en el re-rank.
2. Chunking: cortar en pedazos#
No se indexa la página entera. Una página de API puede hablar de autenticación, paginación y límites de uso al mismo tiempo, y el vector de la página entera se vuelve un promedio de todo eso: no queda cerca de ninguna pregunta específica. Entonces la página se corta en chunks (pedazos).
En Nixa, el objetivo es 900 caracteres por chunk, y cada chunk empieza repitiendo las últimas frases del anterior, hasta unos 200 caracteres. Eso es el overlap.
El overlap existe porque la respuesta no respeta la frontera de tu corte. Si la frase que explica el parámetro quedó al final de un chunk y el ejemplo al principio del siguiente, la repetición garantiza que al menos uno de los dos tenga ambas cosas.
Otro detalle: un párrafo corto que parece título ("Configurar el perfil") no se vuelve chunk solo. Se pega al párrafo siguiente, para que el fragmento lleve su tema consigo.
export function chunkText(text: string, maxSize = 900, overlap = 200): string[] {
const chunks: string[] = [];
let current = "";
let pendingHeading = "";
for (const paragraph of text.split(/\n\n+/).map((p) => p.trim()).filter(Boolean)) {
if (looksLikeHeading(paragraph)) {
pendingHeading = paragraph; // glue it to the next paragraph
continue;
}
const section = pendingHeading ? `${pendingHeading}\n${paragraph}` : paragraph;
pendingHeading = "";
if (current && current.length + section.length > maxSize) {
chunks.push(current);
// the next chunk starts with the last sentences of this one
current = `${lastSentences(current, overlap)}\n\n${section}`;
} else {
current = current ? `${current}\n\n${section}` : section;
}
}
if (current.length > 80) chunks.push(current);
return chunks;
}Fíjate que el corte es por párrafo (\n\n). Eso tiene una consecuencia que cuento al final del post.
3. Embeddings: convertir texto en vector#
Un embedding es una lista de números que representa el sentido de un texto. Mandas un texto a un modelo de embedding y recibes un vector, tipo [0.012, -0.341, 0.088, ...]. El truco es que los textos con sentido parecido se vuelven vectores que apuntan en direcciones parecidas, aunque no tengan ninguna palabra en común: "cómo inicio sesión en la API" queda cerca de "authentication with OAuth".
El tamaño del vector depende del modelo. En el índice de Nixa hay vectores de 384 números (all-minilm, que corre local en Ollama) y de 3.072 números (el tamaño que devuelve gemini-embedding-001). La app acepta tres proveedores de embedding: Gemini (el predeterminado), OpenAI (text-embedding-3-small) y Ollama.
Un truco barato que ayudó: antes de generar el vector, el título de la página va delante del chunk. Un fragmento que solo dice "define el valor como true" no significa nada solo. Con [Configurar Copilot] delante, sí. Anthropic describe una versión más elaborada de esta idea, el contextual retrieval.
const input = `[${chunk.title}] ${chunk.content}`.slice(0, 2000);
const { embedding } = await embed(input); // number[]4. El vector store: guardar los vectores#
El vector store es donde viven los chunks, los vectores y los metadatos. Y aquí viene la parte que sorprende a quien espera una base de datos vectorial elegante: en Nixa, es un archivo JSON. El data/vectorstore.json del repositorio tiene 425 chunks de 62 páginas y pesa 11 MB.
Para buscar, la app lee el archivo, calcula la similitud de la pregunta con todos los chunks y ordena. Fuerza bruta. Con 425 chunks, es instantáneo. Con cientos de miles, ahí sí quieres un índice de verdad, como pgvector en Postgres o una base vectorial dedicada. Empieza por lo simple y cambia cuando midas que lo necesitas.
La medida de cercanía más usada es la similitud del coseno: cuánto apuntan dos vectores en la misma dirección, en una escala de -1 a 1.
function cosineSimilarity(a: number[], b: number[]): number {
if (a.length !== b.length) return 0; // vectors from different models
let dot = 0, normA = 0, normB = 0;
for (let i = 0; i < a.length; i++) {
dot += a[i] * b[i];
normA += a[i] * a[i];
normB += b[i] * b[i];
}
return dot / (Math.sqrt(normA) * Math.sqrt(normB));
}Recuerda esa primera línea. Es el motivo de una regla del proyecto.
La pregunta, paso a paso#
1. Expansión de la pregunta: portugués a inglés#
La documentación está casi toda en inglés y la gente pregunta en portugués. El embedding se las arregla bien con eso, pero la búsqueda por palabra no: "relatório" (informe) nunca va a coincidir con "reporting".
Entonces la pregunta se vuelve dos: la semántica es la pregunta original, y la léxica recibe términos en inglés pegados al final. Son 19 reglas, una por tema:
const PT_EN_TERMS = [
{ pattern: /(relat[óo]rio|dashboard|m[ée]tricas)/i, en: "reporting analytics reports dashboard metrics KPI" },
{ pattern: /(fila|filas|roteamento|skill)/i, en: "queue queues skill skillset ACD routing" },
{ pattern: /(autentica[çc][ãa]o|login|oauth)/i, en: "authentication oauth bearer access login" },
// ...
];
function buildQuery(question: string) {
const extra = PT_EN_TERMS.filter((term) => term.pattern.test(question)).map((term) => term.en);
return { semantic: question, lexical: [question, ...extra].join(" ") };
}"Como gerar um relatório de filas?" ("¿cómo genero un informe de colas?") va al embedding tal como la escribiste, y a la búsqueda léxica con "reporting", "queue", "ACD" y compañía.
2. Búsqueda híbrida: sentido y palabra#
La búsqueda solo semántica es excelente para preguntas vagas y mala para nombres exactos. Si alguien pregunta por el agent-sdk, quieres el fragmento que tiene esa palabra, no uno que habla de algo parecido. La búsqueda solo por palabra tiene el problema contrario: no sabe que "iniciar sesión" y "login" son lo mismo.
La búsqueda híbrida suma las dos. En Nixa, la nota de cada chunk es así:
const isShort = question.split(/\s+/).length <= 2;
const semanticWeight = isShort ? 0.5 : 0.75;
const lexicalWeight = isShort ? 0.5 : 0.25;
// lexicalOverlap: share of the query words found in the chunk (0 to 1)
const score =
cosineSimilarity(queryEmbedding, chunk.embedding) * semanticWeight +
lexicalOverlap(lexicalQuery, chunk.content) * lexicalWeight;Pregunta normal: 75% sentido, 25% palabra. Una pregunta de hasta dos palabras pasa a mitad y mitad, porque con tan poco texto el embedding tiene poco sentido que captar, y la palabra exacta pesa más.
La parte léxica es lo más simple posible: la fracción de las palabras de la pregunta que aparecen en el chunk. Se podría cambiar por BM25 y mejorar, pero alcanzó para acertar nombres de API y de SDK.
De esa cuenta salen los 20 mejores candidatos (cuatro veces el número de fragmentos que van al prompt, con un mínimo de 16), que siguen al re-rank.
3. Re-rank: lo que la similitud no sabe#
La similitud solo mira el texto. Pero yo sé cosas que el texto no dice: que la documentación oficial de API vale más que un README cualquiera, que una pregunta técnica quiere una página de referencia, que la release note de ayer vale más que la del año pasado. El re-rank es donde entra eso, sumando bonos y descuentos a la nota:
| Señal | Ajuste |
|---|---|
| Portal oficial de developers | +0,15 |
| Centro de ayuda oficial | +0,12 |
| GitHub que no es de los SDKs oficiales | -0,40 |
| Pregunta técnica y página de API | +0,12 |
| Pregunta técnica y página de referencia | +0,10 |
| Indexada hace hasta 7, 30 o 90 días | +0,06, +0,04 o +0,02 |
| Cada palabra de la pregunta en el título | +0,025 |
| Palabra de la pregunta en el breadcrumb | +0,08 |
| La pregunta entera dentro del título | +0,15 |
Una pregunta "técnica" aquí es la que tiene palabras como api, sdk, webhook o endpoint. Después del ajuste, los chunks repetidos salen, todo lo que queda por debajo de 0,22 se descarta y los 5 mejores van al prompt.
El re-rank por reglas es el más simple que existe. El paso siguiente sería un modelo de re-rank (un cross-encoder), que lee la pregunta y el fragmento juntos y les da la nota. Para el tamaño de esta base, las reglas alcanzaron, y cada una es fácil de explicar cuando un resultado sale raro.
4. Saber cuándo no responder#
Antes de llamar al LLM, Nixa mira la nota del mejor fragmento y clasifica la confianza: alta si pasa de 0,6 y hay al menos dos fragmentos, media por encima de 0,4, baja en el resto. Con confianza baja o sin fragmentos, ni llama al modelo: responde que no encontró eso en la documentación oficial.
Parece poco, pero es la diferencia entre un asistente útil y un generador de suposiciones con fuentes bonitas. Si el contexto es débil, el modelo llena el hueco con lo que suene plausible.
5. El prompt#
Los 5 fragmentos entran al prompt de sistema en XML, agrupados por tipo de página, cada uno con título, URL y breadcrumb, y recortados a 700 caracteres:
<context>
<section type="API">
<document index="1" type="api" url="https://docs.example.com/api/auth">
<title>Authentication</title>
<breadcrumb>Documentation > Getting Started</breadcrumb>
<content>...</content>
</document>
</section>
</context>Y las reglas dicen qué hacer con ellos: responder en el idioma de la pregunta, citar la fuente en el texto con [Título](URL) y, si la información no está en el contexto, decir que no la encontró en la documentación oficial en vez de inventar un endpoint, un campo o una versión. Cuando dos fuentes no coinciden, vale el orden: API, después referencia, después guía, después release note.
El LLM puede ser Gemini, OpenAI u Ollama (100% local). Cambiarlo no cambia nada en el RAG: el prompt es el mismo.
6. Solo las fuentes que se usaron#
Muchos RAG muestran debajo de la respuesta todo lo que devolvió la búsqueda. Pero el modelo pudo haber usado dos de los cinco fragmentos, y entonces tres "fuentes" son adorno.
En Nixa, la respuesta llega por streaming y, cuando termina, el servidor revisa qué URLs aparecen de verdad en el texto y manda solo esas:
export function selectCitedSources(answer: string, candidates: Source[]): Source[] {
return candidates.filter((source) => answer.includes(source.url));
}Una línea. Como el prompt pide citar con el enlace, la fuente que aparece abajo es la que el modelo realmente usó.
Un índice, un modelo de embedding#
Ahora, aquella primera línea del coseno. Los vectores de modelos distintos no se comparan: son espacios distintos, a veces ni del mismo tamaño. Entre un vector de 384 números de all-minilm y uno de 3.072 de Gemini no hay cuenta posible, y por eso la función devuelve 0. Incluso cuando el tamaño coincide, dos modelos organizan el sentido de formas distintas: saldría una nota, pero sería basura.
Por eso la regla de Nixa es embedding fijo por índice. El archivo guarda qué proveedor, qué modelo y qué dimensión generaron los vectores, y la búsqueda siempre usa ese mismo modelo para convertir la pregunta, sin importar qué LLM elegiste para el chat. Puedes conversar con Ollama y buscar con Gemini. Si la dimensión de la pregunta no coincide con la del índice, la búsqueda no finge: pasa a búsqueda solo léxica y avisa en el log que hay que reindexar.
const { embedding: queryEmbedding } = await getEmbedding(question, store.embeddingProvider);
if (store.dims && queryEmbedding.length !== store.dims) {
console.warn("Embedding dimension mismatch, reindex. Falling back to lexical search.");
return lexicalSearch(lexicalQuery);
}Lo aprendí por las malas. El índice que está hoy en el repositorio mezcla los dos: 330 chunks con vectores de 384 números, de una indexación con Ollama local, y 95 con 3.072, de Gemini. Para una pregunta convertida en vector por Gemini, esos 330 tienen similitud cero y solo aparecen por la parte léxica, que vale el 25% de la nota. Más de tres cuartos de la base casi invisibles para la búsqueda semántica, y ningún error en pantalla.
Cambiar el modelo de embedding es cambiar el índice entero. No existe migración parcial.
La misma búsqueda, fuera del chat#
Como la búsqueda no depende de ningún LLM, se volvió una función propia, searchNiceDocs(), que solo devuelve fragmentos. El chat la llama y después genera la respuesta. Pero otros clientes también pueden llamarla: está expuesta como una tool de MCP, search_nice_docs, y como una ruta REST.
Así ChatGPT, Claude o Cursor consultan la misma base, y quien escribe la respuesta es el modelo del propio cliente. Si MCP es nuevo para ti, escribí sobre él en Qué es MCP.
Cuándo RAG no resuelve#
RAG es bueno en una cosa: encontrar el fragmento correcto y responder a partir de él. Fuera de eso:
- Preguntas que necesitan la base entera. "¿Cuántas APIs hay?" o "resume todas las novedades del año" no caben en 5 fragmentos. Eso pide otro camino, como una consulta estructurada o un resumen hecho antes.
- Datos que cambian cada minuto. El índice es una foto. En Nixa, la pregunta "¿cuál es la última versión del agent SDK?" ni pasa por el RAG: la app consulta el registro de npm en el momento y responde con la versión y la fecha de publicación.
- Documentos malos. Si la respuesta no está escrita en ningún lado, o está mal, el RAG recupera fielmente lo incorrecto.
- Cambiar cómo se comporta el modelo. Tono, formato, un tipo de tarea: eso es prompt o fine-tuning, no recuperación.
- Cortes mal hechos. Si el chunking separa la pregunta de la respuesta, ningún re-rank te salva. Que es el siguiente tema.
Lo que aprendí#
Cortar por estructura tiene un precio. El chunker corta por párrafos (\n\n). Cuando una página llega sin ninguna línea en blanco, se vuelve un solo párrafo, y un solo chunk. En el índice actual, 62 chunks pasan de 2 mil caracteres, y el más grande, una página de release notes, tiene 142.273 caracteres. El embedding solo lee los primeros 2 mil. El resto existe en el archivo y no existe para la búsqueda semántica. El arreglo es un corte de seguridad: si el párrafo pasa del límite, se parte por frase.
Los metadatos son la mitad del ranking. El título delante del chunk, el tipo de página, el breadcrumb y el dominio hicieron más diferencia en las respuestas de lo que esperaba. Y cuestan casi nada de guardar en el crawler.
Decir "no sé" es una función, no una falla. La nota mínima y la confianza antes de llamar al LLM cortan la respuesta inventada que más engaña: la que viene con fuente y todo.
Haz que la búsqueda sea observable. Con RAG_DEBUG=true, cada pregunta registra la query expandida, la nota de cada fragmento y la confianza. Cuando una respuesta sale mal, el primer lugar donde mirar es la búsqueda, no el LLM: si el fragmento correcto no llegó al prompt, ningún modelo acierta.
Empieza con un JSON. Vector store en archivo, coseno a mano, búsqueda léxica de diez líneas. Se entiende cada número que sale. La base vectorial es una optimización para cuando la base crezca.
Referencias#
Sigue leyendo

Back-end13 min de lectura
Qué es MCP (Model Context Protocol) y cómo funciona

Front-end17 min de lectura
SEO multilingüe en React: hreflang, prerender y sitemap

Front-end15 min de lectura
Cómo creo videos con IA usando Remotion: un caso real