Tutoriales de RAG: guías paso a paso

Qué cubre este artículo sobre tutoriales de RAG

• Cuatro tutoriales completos, desde minimalista hasta interactivo, todos con código Python funcional
• Guía de configuración para Python, Ollama y los paquetes necesarios
• Consejos prácticos para adaptar los tutoriales a tus propios documentos
• Errores comunes y cómo evitarlos
• Preguntas frecuentes sobre tutoriales de RAG

Introducción: tutoriales de RAG explicados

La teoría detrás de RAG es simple: buscar documentos, encontrar las secciones relevantes, entregarlas a un modelo de lenguaje. Sin embargo, entre la teoría y el código que funciona hay a menudo un salto importante. Aquí es donde estos tutoriales entran en juego. Recibirás cuatro guías completas que puedes seguir paso a paso. Cada tutorial se construye sobre el anterior y te acerca más a una aplicación RAG real.

Si aún no conoces los fundamentos, lee primero el artículo Fundamentos de RAG. Allí explico los conceptos detrás de Retrieval Augmented Generation. Si tienes dudas generales sobre qué significa IA local, encontrarás respuestas en Qué es la IA local.

Por qué necesito tutoriales

Imagina que acabas de leer los fundamentos de RAG. Entiendes qué son los embeddings, cómo funciona una base de datos vectorial y por qué el chunking es importante. Luego abres tu editor y te preguntas: ¿por dónde empiezo? ¿Qué librería necesito? ¿Cómo conecto Ollama con Chroma? ¿Cómo cargo mi texto en la base de datos?

Muchos desarrolladores se encuentran con este mismo problema. La teoría es clara, pero escribir el primer código funcional requiere trabajo. Un buen tutorial cierra esa brecha. No solo te muestra qué hacer, sino también en qué orden y con qué código. Copias el código, lo ejecutas, ves un resultado y entiendes inmediatamente cómo encajan las piezas.

Tutoriales de RAG en pocas palabras

Este artículo te proporciona cuatro walkthroughs completos. Cada tutorial es independiente y produce un resultado funcional. Comienzas con un RAG minimalista en 30 líneas, haces PDFs buscables, construyes un chat interactivo y finalmente usas LangChain para un pipeline estructurado.

Todos los tutoriales se ejecutan localmente. No necesitas cloud, sin claves de API y sin conexión a internet después de la configuración inicial. El modelo de lenguaje se ejecuta mediante Ollama, la base de datos vectorial es Chroma. Más sobre RAG local lo encuentras en el artículo de descripción general.

Para quién son estos tutoriales

Estos tutoriales están dirigidos a desarrolladores que implementan RAG por primera vez. Necesitas conocimientos básicos de Python: variables, funciones y bucles. No se requiere experiencia previa en Machine Learning. Si alguna vez escribiste un script de Python y lo ejecutaste desde la línea de comandos, es suficiente.

También te ayuda este artículo si ya probaste RAG pero tienes dudas sobre cómo se conectan las piezas. Los tutoriales están estructurados para que puedas hacer cada uno por separado o usarlos como plantilla para tus propios proyectos.

Términos importantes relacionados con tutoriales de RAG

Término	Significado
Tutorial	Guía paso a paso con código explicado
Walkthrough	Recorrido completo de un ejemplo de principio a fin
Pipeline	Secuencia de pasos de procesamiento por los que pasan los datos
Stack	Combinación de herramientas y librerías utilizadas juntas
Ollama	Servidor local para ejecutar modelos de lenguaje
Chroma	Base de datos vectorial local para embeddings
LangChain	Framework que conecta componentes de RAG
Python	Lenguaje de programación en el que están escritos todos los tutoriales
Virtual Environment	Entorno Python aislado para paquetes
Requirements	Lista de paquetes necesarios y sus versiones

Tutorial 1: RAG minimalista en 30 líneas

Este tutorial muestra el RAG más simple posible. Almacenas tres fragmentos de texto en Chroma, haces una pregunta y recibes una respuesta del modelo de lenguaje. Sin frameworks, sin abstracciones, solo la lógica central.

Requisito previo: Ollama está ejecutándose y el modelo llama3.2 está descargado. También necesitas el modelo de embedding nomic-embed-text. Más sobre modelos de embedding lo encuentras en Modelos de embedding.

import chromadb
import requests

# Iniciar Chroma y crear colección
client = chromadb.PersistentClient(path="./minrag_db")
collection = client.get_or_create_collection("docs")

# Agregar documentos
texts = [
    "Python es un lenguaje de programación con tipado dinámico.",
    "Ollama ejecuta modelos de lenguaje localmente en tu propia máquina.",
    "Chroma es una base de datos vectorial para embeddings."
]
collection.add(
    documents=texts,
    ids=["1", "2", "3"]
)

# Hacer una pregunta y encontrar secciones relevantes
frage = "¿Qué es Ollama?"
results = collection.query(query_texts=[frage], n_results=2)
kontext = "\n".join(results["documents"][0])

# Construir prompt y enviar a Ollama
prompt = f"Responde brevemente en español. Usa solo este contexto:\n{kontext}\n\nPregunta: {frage}"
response = requests.post(
    "http://localhost:11434/api/generate",
    json={"model": "llama3.2", "prompt": prompt, "stream": False}
)
print(response.json()["response"])

Guarda el código como minrag.py y ejecútalo con python minrag.py. La salida es una respuesta breve basada en el contexto encontrado. Chroma usa internamente un modelo de embedding estándar, así que aquí no necesitas configuración adicional.

El script crea una base de datos en la carpeta minrag_db. Cuando lo ejecutas de nuevo, Chroma carga los datos existentes. Si añades nuevos documentos, llama a collection.add() con nuevos IDs.

Tutorial 2: hacer documentos PDF buscables

En el primer tutorial escribiste textos manualmente. En la práctica, quieres buscar archivos reales, especialmente PDFs. Este tutorial carga un archivo PDF, lo divide en secciones y lo hace buscable.

Necesitas la librería adicional pypdf para leer PDFs. Más sobre cómo preparar documentos lo encuentras en Preparar documentos.

import chromadb
import requests
from pypdf import PdfReader

# Cargar PDF y extraer texto
reader = PdfReader("ejemplo.pdf")
fulltext = ""
for page in reader.pages:
    text = page.extract_text()
    if text:
        fulltext += text + "\n"

# Dividir texto en chunks (división simple por caracteres)
chunk_size = 500
chunk_overlap = 50
chunks = []
start = 0
while start < len(fulltext):
    end = start + chunk_size
    chunks.append(fulltext[start:end])
    start += chunk_size - chunk_overlap

print(f"{len(chunks)} chunks creados")

# Guardar chunks en Chroma
client = chromadb.PersistentClient(path="./pdf_rag_db")
collection = client.get_or_create_collection("pdf_docs")
collection.add(
    documents=chunks,
    ids=[str(i) for i in range(len(chunks))]
)

# Hacer una pregunta
frage = "¿De qué trata este documento?"
results = collection.query(query_texts=[frage], n_results=3)
kontext = "\n\n".join(results["documents"][0])

prompt = f"Responde en español basándote en este contexto:\n{kontext}\n\nPregunta: {frage}"
response = requests.post(
    "http://localhost:11434/api/generate",
    json={"model": "llama3.2", "prompt": prompt, "stream": False}
)
print(response.json()["response"])

Reemplaza ejemplo.pdf con la ruta de un PDF real. El script lee todas las páginas, combina el texto y lo divide en secciones de 500 caracteres con 50 caracteres de superposición. Más sobre estrategias de chunking sensatas las encuentras en Chunking.

Asegúrate de que el PDF contenga texto, no solo imágenes. Para documentos escaneados necesitas OCR. Los detalles también están en el artículo sobre Preparar documentos.

Tutorial 3: Chat con tus documentos

Hasta ahora has formulado preguntas aisladas. En la práctica, necesitas mantener una conversación con historial y seguimiento de preguntas anteriores. Este tutorial amplía el RAG con un bucle de chat que mantiene el contexto conversacional.

import chromadb
import requests
import json

client = chromadb.PersistentClient(path="./chat_rag_db")
collection = client.get_or_create_collection("chat_docs")

# Cargar documentos de ejemplo
dokumente = [
    "Der Urlaubanspruch betraegt 30 Tage im Jahr.",
    "Ueberstunden werden am Ende des Monats abgebaut oder ausgezahlt.",
    "Die Probezeit dauert sechs Monate.",
    "Homeoffice ist an zwei Tagen pro Woche moeglich."
]
collection.add(documents=dokumente, ids=["1", "2", "3", "4"])

# Historial de conversación
history = []

def rag_chat(frage):
    # Buscar documentos relevantes
    results = collection.query(query_texts=[frage], n_results=2)
    kontext = "\n".join(results["documents"][0])

    # Construir prompt con historial y contexto
    messages = []
    messages.append({
        "role": "system",
        "content": f"Du bist ein Assistent. Nutze diesen Kontext: {kontext}"
    })
    for eintrag in history:
        messages.append(eintrag)
    messages.append({"role": "user", "content": frage})

    # Enviar a Ollama (Chat API)
    response = requests.post(
        "http://localhost:11434/api/chat",
        json={"model": "llama3.2", "messages": messages, "stream": False}
    )
    antwort = response.json()["message"]["content"]

    # Actualizar historial
    history.append({"role": "user", "content": frage})
    history.append({"role": "assistant", "content": antwort})
    return antwort

# Bucle de chat interactivo
print("Chat gestartet. Tippe 'exit' zum Beenden.")
while True:
    frage = input("Du: ")
    if frage.lower() == "exit":
        break
    antwort = rag_chat(frage)
    print(f"KI: {antwort}\n")

Guarda el código como chat_rag.py y ejecútalo. Puedes hacer preguntas como “Wie viel Urlaub habe ich?” o “Kann ich im Homeoffice arbeiten?”. La IA busca en la base de datos con cada pregunta, pero también considera el historial de conversación acumulado.

La Chat API de Ollama acepta una lista de mensajes con roles. El mensaje system contiene el contexto, mientras que los mensajes user y assistant forman el historial. De esta forma, la IA entiende preguntas de seguimiento como “Und wie lange ist die Probezeit?” sin que tengas que repetir el tema.

Tutorial 4: RAG con LangChain

Hasta ahora has implementado cada paso manualmente. LangChain automatiza gran parte del trabajo y proporciona una estructura extensible. Este tutorial muestra la misma pipeline usando LangChain.

from langchain_community.document_loaders import TextLoader
from langchain.text_splitter import RecursiveCharacterTextSplitter
from langchain_community.embeddings import OllamaEmbeddings
from langchain_community.vectorstores import Chroma
from langchain_community.llms import Ollama
from langchain.chains import RetrievalQA

# Cargar documento
loader = TextLoader("notizen.txt")
docs = loader.load()

# Dividir en fragmentos
splitter = RecursiveCharacterTextSplitter(
    chunk_size=500,
    chunk_overlap=50
)
chunks = splitter.split_documents(docs)

# Embeddings y base de datos vectorial
embeddings = OllamaEmbeddings(model="nomic-embed-text")
vectordb = Chroma.from_documents(
    chunks,
    embeddings,
    persist_directory="./langchain_db"
)

# Construir cadena QA
llm = Ollama(model="llama3.2")
qa = RetrievalQA.from_chain_type(
    llm=llm,
    chain_type="stuff",
    retriever=vectordb.as_retriever(search_kwargs={"k": 3})
)

# Hacer pregunta
frage = "Was steht in den Notizen?"
antwort = qa.run(frage)
print(antwort)

LangChain encapsula la carga, división, embedding y consulta en componentes individuales. La cadena RetrievalQA conecta automáticamente el retriever y el LLM. Puedes cambiar componentes sin tocar el resto del código. Si quieres usar una base de datos vectorial diferente en lugar de Chroma, solo tienes que cambiar una línea.

Para flujos más complejos con condiciones y bucles, vale la pena revisar LangGraph. Con él construyes máquinas de estado para pipelines RAG con múltiples pasos, incluyendo reranking automático o transformación de consultas.

Requisitos previos para todos los tutoriales

Antes de ejecutar los tutoriales, necesitas tres cosas: Python, Ollama y algunos paquetes Python.

Instalar Python

Python 3.10 o superior es suficiente. Verifica la versión con python --version. Crea un entorno virtual para los tutoriales, así los paquetes no afectarán tu sistema:

python -m venv rag-env
source rag-env/bin/activate

En Windows utiliza rag-env\Scripts\activate en lugar de source.

Configurar Ollama

Descarga Ollama del sitio oficial e instálalo. Luego inicia el servidor de Ollama y descarga los modelos:

ollama pull llama3.2
ollama pull nomic-embed-text

llama3.2 es el modelo de lenguaje, nomic-embed-text genera embeddings. Ollama se ejecuta por defecto en el puerto 11434. Encontrarás más detalles en Ollama.

Instalar paquetes

Crea un archivo requirements.txt con las siguientes entradas:

chromadb
requests
pypdf
langchain
langchain-community

Instala todos los paquetes con un único comando:

pip install -r requirements.txt

Después puedes ejecutar cada tutorial directamente.

Consejos para tus propios proyectos

Los tutoriales usan documentos de ejemplo. Para proyectos reales, necesitas adaptar algunos puntos:

• Documentos: Reemplaza los textos hardcodeados con archivos reales. Usa TextLoader, PdfReader o DirectoryLoader para directorios completos.
• Tamaño de fragmento: Prueba diferentes tamaños entre 300 y 800 caracteres. Con documentos técnicos, fragmentos más pequeños suelen ser más precisos. Lee más en Chunking.
• Modelo: llama3.2 es un buen punto de partida. Para mejores respuestas prueba mistral o qwen2.5. Los modelos más grandes ofrecen resultados superiores pero requieren más RAM.
• Número de resultados: El parámetro n_results o k controla cuántos fragmentos recibe el modelo. Tres a cinco es un buen valor inicial.
• Persistencia: Chroma almacena en disco con PersistentClient. Tus datos se conservan entre ejecuciones. Para pruebas usa EphemeralClient, que guarda todo en RAM.
• Metadatos: Añade metadatos a cada fragmento como nombre de archivo, página o fecha. Así puedes filtrar después, por ejemplo buscar solo en documentos específicos.

Problemas comunes en tutoriales RAG

1. Ollama no se ejecuta: Comprueba con curl http://localhost:11434/api/tags si Ollama es accesible. Si no, inicia el servidor con ollama serve.
2. Modelo incorrecto: Si usas nomic-embed-text en LangChain, ese modelo debe estar descargado en Ollama. ollama list muestra todos los modelos instalados.
3. IDs duplicados en Chroma: Cada ID debe aparecer solo una vez. Si ejecutas el script varias veces, usa collection.upsert() en lugar de collection.add(), o borra la base de datos antes.
4. PDF sin texto: Los PDF escaneados contienen solo imágenes. pypdf extrae entonces una cadena vacía. Usa bibliotecas OCR como pytesseract para esos archivos.
5. Problemas de encoding: Los caracteres especiales alemanes pueden perderse con encoding incorrecto. Abre archivos siempre con encoding="utf-8".
6. Demasiado contexto: Si estableces n_results muy alto, el modelo recibe fragmentos irrelevantes. La respuesta se vuelve menos precisa. Comienza con tres resultados y aumenta solo si es necesario.
7. API de LangChain anticuada: LangChain cambia su API frecuentemente. Si un import falla, verifica la versión instalada con pip show langchain y consulta la documentación actual.
8. Sin almacenamiento persistente: Si usas chromadb.Client() sin PersistentClient, los datos desaparecen al finalizar el script. Usa siempre una ruta para proyectos reales.

Hardware, costes y seguridad en tutoriales RAG

Todos los tutoriales funcionan en un portátil estándar. El modelo de lenguaje llama3.2 necesita unos 4 GB de RAM, nomic-embed-text menos de 1 GB. Chroma requiere espacio en disco, pero para algunos cientos de documentos bastan pocos megabytes.

Los costes son nulos, ya que todas las herramientas son Open Source. No necesitas servicios en la nube ni API keys de pago.

La seguridad es una ventaja central. Tus documentos, embeddings y respuestas generadas permanecen en tu máquina. Nada se envía a servidores externos. Esto es especialmente importante con datos sensibles como contratos, notas internas o información de clientes. Encontrarás más detalles sobre seguridad en IA local.

Aprender a programar: tutoriales RAG en Python

Enlaces relacionados e información adicional sobre tutoriales RAG

• RAG local - Descripción general de todos los temas RAG
• Fundamentos de RAG - Conceptos explicados con claridad
• Chunking - Dividir textos de forma significativa
• Modelos de embedding - Vectores para búsqueda
• Bases de datos vectoriales - Almacenamiento de embeddings
• Chroma - Base de datos vectorial local en detalle
• Preparación de documentos - PDFs, OCR y formatos
• Reranking - Mejorar resultados de búsqueda
• Ollama - Ejecutar modelos de lenguaje localmente
• LangGraph - Pipelines RAG complejos como máquina de estados

FAQ: tutoriales RAG - preguntas frecuentes

¿Necesito una GPU para estos tutoriales?

No. Todos los tutoriales funcionan en CPU. Una GPU acelera la generación de respuestas, pero no es obligatoria. Para llama3.2 es suficiente un procesador estándar de portátil.

¿Puedo ejecutar los tutoriales sin Ollama?

Los tutoriales están diseñados para Ollama. Puedes reemplazar las llamadas a Ollama con otros servidores locales como LM Studio, pero tendrás que adaptar las llamadas API.

¿Qué modelo de lenguaje es mejor para RAG?

llama3.2 es una buena opción para comenzar. Para respuestas más complejas, prueba mistral o qwen2.5. Si necesitas optimización específica para español, qwen2.5 suele ofrecer mejores resultados.

¿Cuántos documentos soporta Chroma?

Chroma maneja sin problemas decenas de miles de chunks en un ordenador estándar. Para volúmenes aún mayores o configuraciones distribuidas, Qdrant o Weaviate son alternativas.

¿Tengo que usar LangChain?

No. Los tutoriales 1 a 3 funcionan sin LangChain. LangChain es útil si quieres cambiar componentes rápidamente o construir cadenas complejas. Para aplicaciones sencillas, el código directo es suficiente.

¿Cómo mejoro la calidad de las respuestas?

Hay tres elementos clave: chunking más efectivo, más resultados relevantes y un modelo más potente. También puedes utilizar reranking para ordenar los fragmentos encontrados por relevancia. Consulta la sección de Reranking para más detalles.

¿Puedo implementar los tutoriales en un lenguaje diferente a Python?

Sí. Chroma ofrece clientes para JavaScript, Go y Ruby. Ollama expone una API HTTP que cualquier lenguaje puede invocar. Los conceptos son idénticos, solo el código varía.

¿Cómo mantengo la base de datos actualizada?

Elimina entradas antiguas con collection.delete() y añade nuevas con collection.add(). Para cambios frecuentes, un script que detecte archivos modificados y reindexe solo esos es la solución.

¿Son estos tutoriales adecuados para producción?

Los tutoriales son material educativo. En producción necesitarás manejo de errores, logging, una interfaz y probablemente una base de datos como PostgreSQL en lugar de Chroma. Los conceptos fundamentales se mantienen.

¿Cuál es la diferencia entre RAG y Fine-Tuning?

RAG añade documentos en tiempo de ejecución sin modificar el modelo. Fine-Tuning entrena el modelo con datos nuevos. RAG es más rápido de implementar y flexible con documentos cambiantes. Fine-Tuning es mejor cuando el modelo debe aprender un estilo o jerga específica.

¿Puedo buscar en múltiples tipos de archivo a la vez?

Sí. Carga PDFs con pypdf, archivos de texto con open(), Markdown con TextLoader y páginas web con WebBaseLoader. Añade todos los chunks a la misma colección de Chroma. Los metadatos ayudan a distinguir la fuente después.

Fuentes y lecturas complementarias

• Chroma Documentation, chromadb.com
• Ollama Documentation, ollama.com
• LangChain Documentation, python.langchain.com
• LangGraph Documentation, langchain-ai.github.io/langgraph
• Hugging Face Embedding-Modelle, huggingface.co