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)
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.
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;
}
split(/\n{2,}/)separa por líneas en blanco;trimyfilter(Boolean)quitan los vacíos.currentguarda los párrafos del fragmento en curso yfreshcuenta los nuevos, los que no son solape.- Si ya hay párrafos nuevos y el siguiente pasaría de
maxChars, cierra el fragmento y abre otro con los últimosoverlappárrafos.fresh > 0evita emitir un fragmento hecho solo de solape. - Emite lo que quede. Un párrafo más largo que
maxCharsqueda como un solo fragmento (el comentarioshortcut); 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);
}
- Los embeddings llegan con longitud 1, así que el producto punto (
dot) es la similitud coseno. mappuntúa cada fragmento contra la pregunta yfilterdescarta lo que no llega aminScore: el umbral.sortyslice(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_resultsolo 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 decitations.enabled. - Según la documentación de citations, las citas son punteros válidos a los documentos que enviaste, y
cited_textno 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.formatda 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.`;
NO_INFOes 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.RULESson 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 }] }],
};
}
modeles el que usan los ejemplos de la documentación de Claude al 12 de noviembre de 2026; cámbialo por el que uses.systemlleva las reglas.- Se crea un bloque
search_resultpor fragmento recuperado, concitationsactivadas;as constdeja los literales como TypeScript los espera. - La pregunta va al final, como bloque de texto, después de los resultados.
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] };
}
retrieve(await embed(question), index)busca con el embedding de la pregunta. Si ningún fragmento llega al umbral, devuelveNO_INFOsin llamar al modelo: más barato, y sin nada que inventar.buildRequestarma la petición yclient.messages.createla envía. Si termina constop_reasonigual arefusal, también devuelveNO_INFO.textune los bloques de texto ysourcesjunta lossourcede 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é medir | Cómo | Está 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 principio | Hay plazos, precios o condiciones que no están |
| Rechazo | Las preguntas fuera de los documentos devuelven NO_INFO | Contesta algo en lugar de decir que no sabe |
| Cita | El source citado es el del fragmento que contiene el dato | Cita otro documento o no cita |
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.
minScorese calibró con preguntas que sí tienen respuesta y con otras que no.- Cada fragmento viaja como
search_resultconcitations.enabledentrue. - El
systempide responder solo con los resultados, citar y decir que no sabe. - Sin fragmentos sobre el umbral, el código responde
NO_INFOsin 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

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