Saltar al contenido

Chatbot RAG con tus documentos: que cite y diga «no sé»

En la práctica/ 14 min de lectura

Cómo montar un chatbot RAG: fragmentos, búsqueda con embeddings, un prompt con reglas y citas del API de Claude. Código en TypeScript con pruebas y guía en PDF.

  • IA
  • Bases de datos
  • JavaScript
En este artículo (9)
  1. Qué es RAG
  2. Partir documentos en fragmentos
  3. Embeddings y búsqueda de los fragmentos
  4. El prompt con reglas: solo con esto, cita la fuente, di que no sabes
  5. Ejemplo mínimo de un chatbot RAG
  6. Cómo evaluar las respuestas del chatbot
  7. Errores comunes
  8. Preguntas frecuentes
  9. Checklist

Un chatbot RAG responde con tus documentos, no con lo que el modelo recuerda. Partes cada documento en fragmentos y guardas su embedding; con cada pregunta buscas los más parecidos y se los das al modelo con tres reglas: responder solo con ellos, citar la fuente y decir «no tengo esa información» cuando no estén.

Abajo tienes el flujo, un ejemplo mínimo en TypeScript con el API de Claude y cómo evaluar las respuestas. En Node probamos el divisor de documentos, la búsqueda y el armado de la petición; la llamada al modelo y la de embeddings las sustituimos por versiones de prueba, así que no medimos la calidad de ningún modelo real. La búsqueda por significado ya la explicamos en búsqueda semántica con embeddings y pgvector; aquí construimos encima.

Qué es RAG

RAG significa generación aumentada por recuperación (retrieval-augmented generation): antes de preguntarle al modelo, tu código busca en tus documentos y pega lo que encontró en el prompt. El modelo no aprende tus políticas; las lee en cada pregunta. Si editas un documento, la siguiente respuesta ya lo refleja, y puedes mostrar de dónde salió cada dato.

Son dos fases. Indexar ocurre una vez, y otra cuando cambia un documento: partir en fragmentos, calcular el embedding de cada uno y guardarlo. Preguntar ocurre en cada mensaje: embedding de la pregunta, los k fragmentos más cercanos, el prompt y la respuesta.

RAG en dos fases: indexar una vez, preguntar cada vez1 · indexar, y de nuevo al cambiar un documentodocumentospolíticas, FAQfragmentoschunkText()embeddingsembed()índicepgvector o memoria2 · preguntar, en cada mensajepreguntaembed() igualbuscar top-kretrieve() · minScoreprompt + reglassearch_result + citasmodeloclaude-opus-5-5«El envío a Monterrey tarda de 2 a 4 días hábiles.» [politica-envios]o, si no está en los documentos: «No tengo esa información.»el modelo lee tus documentos en cada preguntaprobado en local con embeddings simulados: sin llamar a ningún proveedor

Desliza la figura para verla completa

¿Siempre hace falta? No. En septiembre de 2024, Anthropic escribió en Introducing Contextual Retrieval que, si tu base de conocimiento tiene menos de 200,000 tokens (unas 500 páginas), puedes ponerla entera en el prompt, y que el prompt caching lo vuelve más rápido y barato. Unas páginas de políticas de una tienda caben. Prueba las dos opciones con tus preguntas antes de elegir.

Partir documentos en fragmentos

El embedding de una página entera mezcla temas; el de un fragmento con una sola idea se parece mucho a las preguntas sobre esa idea. Según el mismo artículo de Anthropic, el tamaño, los límites y el solapamiento de los fragmentos afectan la recuperación, y los de RAG suelen medir, como mucho, unos cientos de tokens. Nuestro punto de partida: párrafos completos, hasta 800 caracteres y el último párrafo repetido al inicio del siguiente. Este es chunkText:

// Whole paragraphs only; the last `overlap` paragraphs of a chunk open the next one.
// shortcut: a single paragraph longer than maxChars stays one chunk, split it by sentences if your docs have them.
export function chunkText(text: string, maxChars = 800, overlap = 1): string[] {
  const paragraphs = text.split(/\n{2,}/).map((p) => p.trim()).filter(Boolean);
  const chunks: string[] = [];
  let current: string[] = [];
  let fresh = 0; // paragraphs in `current` that are not overlap
  for (const p of paragraphs) {
    if (fresh > 0 && current.join("\n\n").length + p.length > maxChars) {
      chunks.push(current.join("\n\n"));
      current = current.slice(Math.max(0, current.length - overlap));
      fresh = 0;
    }
    current.push(p);
    fresh++;
  }
  if (fresh > 0) chunks.push(current.join("\n\n"));
  return chunks;
}
  1. split(/\n{2,}/) separa por líneas en blanco; trim y filter(Boolean) quitan los vacíos.
  2. current guarda los párrafos del fragmento en curso y fresh cuenta los nuevos, los que no son solape.
  3. Si ya hay párrafos nuevos y el siguiente pasaría de maxChars, cierra el fragmento y abre otro con los últimos overlap párrafos. fresh > 0 evita emitir un fragmento hecho solo de solape.
  4. Emite lo que quede. Un párrafo más largo que maxChars queda como un solo fragmento (el comentario shortcut); divídelo por oraciones si tus documentos los tienen enormes.

Con un documento de tres párrafos y maxChars = 90, solo para que se vea el efecto, la salida real fue:

chunkText(politicaDeEnvios, 90, 1)
[
  'Los pedidos se preparan en 24 horas hábiles.',
  'Los pedidos se preparan en 24 horas hábiles.\n\nEl envío a Monterrey y a Guadalajara tarda de 2 a 4 días hábiles.',
  'El envío a Monterrey y a Guadalajara tarda de 2 a 4 días hábiles.\n\nEl envío es gratis desde 999 pesos de compra.'
]

El segundo fragmento abre con el párrafo que cerró el primero: ese es el solape. Antes de calcular el embedding anteponemos el título del documento, una versión barata de la idea de Anthropic de añadir contexto a cada fragmento. Su técnica completa, que genera ese contexto con un modelo, redujo según sus propias pruebas el fallo de recuperación del top-20 en 35% con embeddings contextuales (de 5.7% a 3.7%), 49% sumando BM25 contextual y 67% con un reranker. Son sus datos, no los medimos.

Embeddings y búsqueda de los fragmentos

Cada fragmento se convierte en un embedding con el modelo de un proveedor de embeddings (Anthropic no ofrece uno propio). Usa el mismo modelo para fragmentos y preguntas, y guarda con cada vector su source, su title y el texto. Buscar es ordenar por distancia y quedarte con los k más cercanos; de 3 a 5 es un buen comienzo. En Postgres con pgvector es un ORDER BY embedding <=> $1 LIMIT 4; en el ejemplo, para no depender de una base de datos, es un recorrido en memoria:

// Embeddings come back with length 1, so the dot product is the cosine similarity.
const dot = (a: number[], b: number[]) => a.reduce((sum, x, i) => sum + x * b[i], 0);

export function retrieve(query: number[], index: Chunk[], k = 4, minScore = 0.3): Hit[] {
  return index
    .map((chunk) => ({ chunk, score: dot(query, chunk.embedding) }))
    .filter((hit) => hit.score >= minScore)
    .sort((a, b) => b.score - a.score)
    .slice(0, k);
}
  1. Los embeddings llegan con longitud 1, así que el producto punto (dot) es la similitud coseno.
  2. map puntúa cada fragmento contra la pregunta y filter descarta lo que no llega a minScore: el umbral.
  3. sort y slice(0, k) dejan los k mejores.

Sin umbral siempre hay cuatro fragmentos «más cercanos», aunque no tengan nada que ver, y el modelo intentará contestar con ellos. El 0.3 de arriba sirve para los embeddings simulados de la prueba; con un modelo real, mira las puntuaciones de unas preguntas que sí tienen respuesta y de otras que no, y pon el corte entre las dos. En nuestra prueba, la pregunta sobre Monterrey sacó 0.52 y 0.40 en dos fragmentos de la política de envíos y la pregunta fuera de los documentos sacó 0 en todos: no hubo fragmentos y no se llamó al modelo.

El prompt con reglas: solo con esto, cita la fuente, di que no sabes

Las reglas van en el system: responde solo con los resultados de búsqueda, cada dato sale de un resultado y se cita, y si la respuesta no está, di exactamente que no tienes la información. Añadimos una cuarta: no inventes plazos ni cantidades. Para las citas usamos los bloques search_result del API de Claude, descritos en su documentación de search results: cada fragmento viaja con source, title, content y citations: { enabled: true }, y Claude responde con bloques de texto cuyas citations son de tipo search_result_location (source, title, cited_text y la posición del bloque). Lo que dice la documentación:

  • Los search_result solo caben en mensajes de usuario, incluidos los resultados de herramientas, y solo con texto. Claude cita bloques completos: para citas más finas, divide el contenido en bloques más pequeños. Todos los resultados de una petición deben usar el mismo valor de citations.enabled.
  • Según la documentación de citations, las citas son punteros válidos a los documentos que enviaste, y cited_text no cuenta como tokens de salida. Que la frase esté bien apoyada por ese fragmento no lo garantiza nadie: eso se evalúa.
  • Las citas no se combinan con structured outputs: activarlas junto con output_config.format da un error 400. Si necesitas datos estructurados, pide una línea por campo y analízala, o lee cómo obtener JSON válido de un modelo.
export const NO_INFO = "No tengo esa información en los documentos. ¿Quieres que te pase con una persona?";

export const RULES = `Eres el asistente de atención de una tienda en línea.
Reglas:
1. Responde SOLO con los resultados de búsqueda que recibes. No uses conocimiento externo.
2. Cada dato (plazo, precio, condición) debe salir de un resultado y citarse.
3. Si la respuesta no está en los resultados, responde exactamente: "No tengo esa información en los documentos. ¿Quieres que te pase con una persona?"
4. No inventes políticas ni cantidades. Responde en español, en tres frases como máximo.`;
  1. NO_INFO es la frase exacta para «no sé». El código la usa también cuando no hay fragmentos, así la respuesta es idéntica en los dos caminos.
  2. RULES son las cuatro reglas; la tercera repite esa frase entre comillas para que el modelo la devuelva tal cual.
export function buildRequest(question: string, hits: Hit[]): Anthropic.MessageCreateParamsNonStreaming {
  const results = hits.map(({ chunk }) => ({
    type: "search_result" as const,
    source: chunk.source,
    title: chunk.title,
    content: [{ type: "text" as const, text: chunk.text }],
    citations: { enabled: true },
  }));
  return {
    model: "claude-opus-5-5",
    max_tokens: 1024,
    system: RULES,
    messages: [{ role: "user", content: [...results, { type: "text" as const, text: question }] }],
  };
}
  1. model es el que usan los ejemplos de la documentación de Claude al 12 de noviembre de 2026; cámbialo por el que uses. system lleva las reglas.
  2. Se crea un bloque search_result por fragmento recuperado, con citations activadas; as const deja los literales como TypeScript los espera.
  3. La pregunta va al final, como bloque de texto, después de los resultados.
cada dato de la respuesta apunta a un fragmento que enviastefragmentos enviados[1] politica-enviosEl envío a Monterrey y aGuadalajara tarda de 2 a 4 días.[2] politica-devolucionesAceptamos devoluciones durante30 días después de la entrega.pregunta y respuestapregunta¿Cuánto tarda el envíoa Monterrey?respuestaDe 2 a 4 días hábiles [1].search_result_locationpregunta fuera de los documentos: «¿Venden botas de montaña?»retrieve() devuelve [] y el modelo ni se llama«No tengo esa información en los documentos.»la cita lleva source, title y cited_textdocumentos de ejemplo inventados para esta figura

Desliza la figura para verla completa

Ejemplo mínimo de un chatbot RAG

Con el import y los tipos arriba del archivo, answer recibe el cliente de la API, la función de embeddings de tu proveedor, el índice y la pregunta:

import Anthropic from "@anthropic-ai/sdk";

export interface Chunk { source: string; title: string; text: string; embedding: number[] }
export interface Hit { chunk: Chunk; score: number }
export async function answer(
  client: Pick<Anthropic, "messages">,
  embed: (text: string) => Promise<number[]>,
  index: Chunk[],
  question: string,
) {
  const hits = retrieve(await embed(question), index);
  if (hits.length === 0) return { text: NO_INFO, sources: [] as string[] }; // no model call
  const res = await client.messages.create(buildRequest(question, hits));
  if (res.stop_reason === "refusal") return { text: NO_INFO, sources: [] as string[] };
  const text = res.content.map((b) => (b.type === "text" ? b.text : "")).join("");
  const sources = new Set<string>();
  for (const b of res.content) {
    if (b.type !== "text") continue;
    for (const c of b.citations ?? []) if (c.type === "search_result_location") sources.add(c.source);
  }
  return { text, sources: [...sources] };
}
  1. retrieve(await embed(question), index) busca con el embedding de la pregunta. Si ningún fragmento llega al umbral, devuelve NO_INFO sin llamar al modelo: más barato, y sin nada que inventar.
  2. buildRequest arma la petición y client.messages.create la envía. Si termina con stop_reason igual a refusal, también devuelve NO_INFO.
  3. text une los bloques de texto y sources junta los source de las citas, sin repetir.

Así se arma el índice y se hace una pregunta (el mismo bucle de la prueba, con el embedding simulado):

const docs = [
  { source: "politica-envios", title: "Política de envíos", text: "…el texto del documento…" },
];

const index: Chunk[] = [];
for (const doc of docs) {
  for (const text of chunkText(doc.text)) {
    // embed(): the call to your embeddings provider
    index.push({ source: doc.source, title: doc.title, text, embedding: await embed(`${doc.title}\n${text}`) });
  }
}

const reply = await answer(new Anthropic(), embed, index, "¿Cuánto tarda el envío a Monterrey?");
console.log(reply.text, reply.sources);

Ejecutamos con Node 22.22.3 (node --test) 8 pruebas, 4 en español y 4 en inglés, y las 8 pasaron: chunkText no pierde ni duplica párrafos y repite el solape; la búsqueda pone primero la fuente correcta y no devuelve nada fuera de los documentos; la petición lleva los search_result con citas, la pregunta al final y el modelo claude-opus-5-5; y answer lee las fuentes de las citas, no llama al modelo fuera de los documentos y devuelve NO_INFO ante un refusal. El código pasa tsc en modo estricto contra @anthropic-ai/sdk 1.8.0. No ejecutamos ninguna llamada real al modelo ni a un proveedor de embeddings: ambas están sustituidas, así que las pruebas no dicen nada sobre la calidad de las respuestas. Tampoco hay reintentos, streaming ni historial.

Cómo evaluar las respuestas del chatbot

No necesitas herramientas: una hoja con 20 a 30 preguntas reales de tus clientes (de correos o chats), la fuente que debería responder cada una y unas cinco que tus documentos no contestan. Córrela cada vez que cambies algo, y cambia una cosa por vez: el tamaño del fragmento, k, minScore, el modelo o las reglas. Mide la búsqueda y la respuesta por separado: si el fragmento correcto no llega al modelo, ninguna regla lo arregla. Anthropic mide la recuperación igual, como la fracción de casos en que el fragmento correcto no está entre los 20 primeros.

Qué medirCómoEstá mal si…
Recuperación¿La fuente esperada está entre los k fragmentos?Falta en preguntas que sí tienen respuesta
Fidelidad¿Cada dato aparece en el fragmento citado? Revísalo a mano al principioHay plazos, precios o condiciones que no están
RechazoLas preguntas fuera de los documentos devuelven NO_INFOContesta algo en lugar de decir que no sabe
CitaEl source citado es el del fragmento que contiene el datoCita otro documento o no cita
errores típicos de un chatbot RAG y dónde mirarsíntomacausa probablequé revisarinventa un plazosin umbral, k muy altominScore y la regla 3dice no sé y sí estabafragmento partido a mediastamaño y solapecita otro documentotítulos casi igualessource y title únicosdatos desactualizadosíndice sin reindexarreindexar al editarmezcla clientesíndice sin permisosfiltrar antes de buscarprimero mide la búsqueda, luego el promptsi el fragmento correcto no llega al modelo, las reglas no lo arreglan

Desliza la figura para verla completa

Errores comunes

  • Mezclar modelos de embeddings. Si los fragmentos se indexaron con un modelo y la pregunta se calcula con otro, los vectores no son comparables. Si cambias de modelo, reindexa todo.
  • No poner umbral. Siempre hay un «más parecido». Sin minScore, el modelo recibe fragmentos irrelevantes e intenta contestar.
  • Confiar solo en el prompt. Las reglas ayudan, no garantizan: comprueba con tu hoja de preguntas que el chatbot rechaza lo que no sabe.
  • Dejar documentos viejos. Si editas una política y no reindexas, el chatbot responde con la anterior.
  • Indexar lo que el cliente no debe ver. Si el índice mezcla datos de varios clientes, filtra por permisos antes de buscar, no después de responder.
  • Tratar los documentos como instrucciones. El texto recuperado es contenido, no órdenes. Si alguien más edita los documentos, un fragmento podría pedir que se ignoren las reglas: no le des al modelo herramientas con efectos sin confirmación.

Preguntas frecuentes

¿RAG o ajuste fino?

Si lo que cambia son los datos, como plazos, precios o políticas, RAG: editas el documento y la siguiente respuesta ya lo usa, con fuente citada. El ajuste fino sirve para cambiar el estilo o el formato de las respuestas; no lo evaluamos aquí.

¿Necesito una base de datos vectorial?

No necesariamente. Para un puñado de documentos basta el recorrido en memoria del ejemplo. Cuando crezca, guarda los vectores en tu Postgres con pgvector, como en el artículo de búsqueda semántica.

¿Con qué genero los embeddings?

Con el modelo de un proveedor de embeddings: Anthropic no ofrece uno propio. Elige uno, pruébalo con tu hoja de preguntas y usa el mismo para fragmentos y preguntas. El código no depende del proveedor: embed es una función que tú pasas.

¿Qué pasa si preguntan algo que no está en mis documentos?

Hay dos protecciones: el umbral, que evita llamar al modelo si ningún fragmento se parece, y la tercera regla, que le pide la frase exacta de NO_INFO si el fragmento no contesta. Ofrece siempre pasar con una persona.

Checklist

  • Los documentos están en fragmentos de una idea, con título y fuente guardados junto a cada vector.
  • Fragmentos y preguntas usan el mismo modelo de embeddings.
  • minScore se calibró con preguntas que sí tienen respuesta y con otras que no.
  • Cada fragmento viaja como search_result con citations.enabled en true.
  • El system pide responder solo con los resultados, citar y decir que no sabe.
  • Sin fragmentos sobre el umbral, el código responde NO_INFO sin llamar al modelo.
  • Hay una hoja de 20 a 30 preguntas, cinco sin respuesta, y se corre en cada cambio.
  • Los documentos se reindexan al editarse y el índice respeta los permisos de cada cliente.

Si todavía no tienes los vectores, empieza por la búsqueda semántica con embeddings y pgvector. Y si el chatbot debe devolver datos y no texto, mira cómo conseguir respuestas JSON válidas de un modelo, recordando que citas y structured outputs no se pueden usar juntos.

¿Viste esto en Instagram? Comenta RAG en el Reel y te mando la guía.

Escrito por

Luis Morales

Luis Morales

Desarrollador frontend y Shopify, EcomLabs

@luismoralesdev en Instagram

Publicado el 12 de noviembre de 2026 · actualizado el 18 de noviembre de 2026

← Blog