Esencial⏱ 25 minVS Code / Cursor

Construye RAG con citas

Recuperar evidencia y responder con referencia.

scikit-learn

Antes de comenzar

🎯 Qué vas a lograr en esta lección

¿Qué problema vas a resolver?

Aprenderás a recuperar evidencia y responder con referencia. La idea es partir de una necesidad concreta, no de memorizar código.

¿Qué vas a construir?

Cited Rag Assistant: un proyecto pequeño para crear una aplicación que consulta documentos o usa herramientas. El nombre técnico identifica la carpeta del proyecto; no necesitás memorizarlo.

¿Por qué es útil?

Te ayuda a obtener respuestas basadas en información disponible y no solo en memoria del modelo.

¿Qué vas a aprender?

Practicarás fragmentos, búsqueda, fuentes, herramientas y aprobación humana. Cada término nuevo se explica antes de usarlo.

Tu primera acción

No instalés ni ejecutes nada todavía. Primero lee las palabras esenciales y observa el ejemplo pequeño. Después identificarás qué dato entra, qué instrucción trabaja y qué resultado aparece.

Cómo usar esta lección

Avanza una parte a la vez

Aprende

Leé las palabras nuevas y el ejemplo pequeño.

Practica

Cambiá una sola cosa y ejecuta nuevamente.

Comprueba

Respondé las preguntas y usa las pistas cuando las necesites.

Cierra

Marcá el checklist y decide si continuar o tomar una pausa.

No necesitás entender toda la página de una vez. Termina una parte, haz una pausa breve y continúa cuando estés listo.

Parte 1

Aprende las palabras esenciales

Leé definiciones cortas y explica cada palabra con un ejemplo propio.

Base conceptual — léela antes de practicar

🧱 Conceptos esenciales explicados desde cero

Esta sección no es opcional. Presenta las palabras y procesos que necesitás para comprender el ejemplo. Leé una definición, observa el ejemplo y explícalo con una frase propia antes de avanzar.

`rag`

Qué significa: Patrón que recupera información antes de pedir una respuesta a un modelo.

Para qué sirve: Ayuda a responder usando documentos concretos y mostrar fuentes.

Ejemplo: Pregunta → búsqueda → contexto → respuesta con citas.

Confusión frecuente: RAG no elimina las alucinaciones; requiere evaluación y fuentes.

`recuperacion`

Qué significa: Selección de información relevante para una consulta.

Para qué sirve: Proporciona contexto al modelo.

Ejemplo: Buscar chunks.

Confusión frecuente: Mala recuperación limita todo RAG.

`contexto`

Qué significa: Información adicional necesaria para interpretar una tarea.

Para qué sirve: Ayuda a producir respuestas relevantes.

Ejemplo: Audiencia y documento fuente.

Confusión frecuente: Contexto excesivo puede diluir instrucciones.

`cita`

Qué significa: Referencia al fragmento fuente usado.

Para qué sirve: Permite verificar una respuesta.

Ejemplo: Documento A, página 3.

Confusión frecuente: Debe apuntar a contenido que realmente respalda.

`alucinacion`

Qué significa: Contenido generado que parece plausible pero no está respaldado.

Para qué sirve: Es riesgo central de LLM.

Ejemplo: Cita inexistente.

Confusión frecuente: Debe prevenirse con fuentes y evaluación.

Ejemplo mínimo de flujo RAG

Este ejemplo es deliberadamente pequeño. Su objetivo es mostrar las piezas básicas sin mezclar todavía toda la lógica del proyecto.

pregunta = "¿Cómo instalo el proyecto?"
fragmentos = buscar_documentos(pregunta)
respuesta = responder_con_fuentes(pregunta, fragmentos)

Identificá los nombres nuevos: subraya variables, funciones, tipos, herramientas o pasos.
Señala la entrada: qué dato recibe o qué valor ya está escrito.
Señala el proceso: qué instrucción transforma, valida, consulta o calcula.
Señala la salida: qué resultado puede verse o verificarse.
Explícalo: completa “el programa recibe ___, hace ___ y entrega ___”.

No continués todavía si no podés explicar al menos tres términos y el flujo entrada → proceso → salida sin copiar el texto.

Aprende las palabras antes de usarlas

🧠 Conceptos explicados desde cero

No memoricés los nombres. Leé qué significa cada término, observa el ejemplo y trata de explicarlo con tus propias palabras.

`retrieval`

Qué significa: retrieval es un concepto usado al trabajar con sistemas de inteligencia artificial.

Para qué sirve: Controlar la información, instrucciones o evaluación de una respuesta.

Ejemplo pequeño: La lección aplica retrieval en un ejemplo verificable.

Confusión frecuente: Una respuesta convincente no siempre es correcta; debe revisarse con evidencia.

`context`

Qué significa: context es un concepto usado al trabajar con sistemas de inteligencia artificial.

Para qué sirve: Controlar la información, instrucciones o evaluación de una respuesta.

Ejemplo pequeño: La lección aplica context en un ejemplo verificable.

Confusión frecuente: Una respuesta convincente no siempre es correcta; debe revisarse con evidencia.

`citations`

Qué significa: citations es un término técnico utilizado en esta lección.

Para qué sirve: Nombrar una parte específica del proceso de citations.

Ejemplo pequeño: Busca citations en el ejemplo y observa qué recibe y qué produce.

Confusión frecuente: No intentés memorizar el nombre: explicá primero su función con tus propias palabras.

`grounding`

Qué significa: grounding es un concepto usado al trabajar con sistemas de inteligencia artificial.

Para qué sirve: Controlar la información, instrucciones o evaluación de una respuesta.

Ejemplo pequeño: La lección aplica grounding en un ejemplo verificable.

Confusión frecuente: Una respuesta convincente no siempre es correcta; debe revisarse con evidencia.

Parte 2

Mirá un ejemplo pequeño

Primero comprende un ejemplo mínimo. Después observa el código completo.

Ejemplo pequeño antes del proyecto

Relacionar una pregunta con un documento

Observá únicamente tres cosas: qué dato existe, qué instrucción se ejecuta y qué resultado aparece.

document = "Python se usa para automatización."
question = "¿Para qué se usa Python?"
print(document, question)

Resultado explicado: RAG añade después búsqueda y generación; primero comprende documento y pregunta.

Antes de continuar, responde con tus palabras:

¿Qué dato recibe o ya tiene el ejemplo?
¿Qué instrucción realiza el trabajo?
¿Qué resultado podés observar?

⌨️ Código completo

from sklearn.feature_extraction.text import TfidfVectorizer
from sklearn.metrics.pairwise import cosine_similarity

sources = [
    {"id":"lesson-03","text":"pathlib permite trabajar con rutas y archivos."},
    {"id":"lesson-06","text":"FastAPI genera documentación OpenAPI automáticamente."},
]
vectorizer = TfidfVectorizer()
matrix = vectorizer.fit_transform(item["text"] for item in sources)

def retrieve(question: str) -> dict:
    scores = cosine_similarity(vectorizer.transform([question]),matrix)[0]
    return sources[int(scores.argmax())]

source = retrieve("¿Qué ayuda con rutas?")
print(f"{source['text']} [{source['id']}]")

Código README Desafío

Primero entiende el ejemplo

🖼️ Explicación ilustrada: entrada → proceso → resultado

Piensa en una máquina sencilla: colocas algo en la entrada, la máquina aplica un proceso y entrega un resultado.

Situación

Una persona necesita resolver el problema de «construye rag con citas».

Entrada

El programa recibe datos, instrucciones o archivos relacionados con microproyecto.

Proceso

El código valida la entrada, aplica reglas mediante funciones y prepara una respuesta.

Resultado

El usuario recibe un resultado visible que puede comprobar y comparar.

Ejemplo antes y después

Antes

Antes de ejecutar: solo tenemos datos y una necesidad.

Después

Después de ejecutar: tenemos un resultado producido por pasos identificables.

¿Cómo usarás este ejemplo en el mini proyecto?

Ahora practicarás con un mini proyecto. Primero observarás el ejemplo, después cambiarás una sola parte y finalmente explicarás el resultado.

1. ObservarVer el ejemplo

2. EntenderRelacionar datos y resultado

3. CambiarModificar una sola cosa

4. EjecutarComprobar el resultado

5. ExplicarDecir qué aprendiste

Regla: cambia una sola parte, ejecuta de nuevo y explica qué diferencia observaste. No necesitás reconstruir el proyecto completo.

Parte 3

Practica con un mini proyecto

Hacé un cambio pequeño, ejecuta el código y observa qué cambió.

Practica paso a paso

🧩 Mini proyecto guiado: Construye RAG con citas

Completá estos ejercicios pequeños antes del desafío. Podés equivocarte: el sistema te explicará qué repasar y te dará una pista.

En esta lección aparece retrieval. ¿Cuál es la mejor forma de aprenderlo?

Memorizar el nombre sin ver el ejemplo. Explicar qué recibe, para qué sirve y qué resultado produce. Saltarlo y modificar todo el proyecto.

Querés practicar con el código de Construye RAG con citas. ¿Qué cambio es mejor para comenzar?

Borrar varias líneas sin ejecutar primero. Cambiar un texto o dato de ejemplo, ejecutar y comparar el resultado. Copiar una solución diferente sin leerla.

Después de modificar un dato, ¿qué tenés que hacer para saber si aprendiste correctamente?

Suponer que funciona porque no ves errores en el editor. Guardar, ejecutar y comparar la salida anterior con la nueva. Cambiar otras cinco cosas antes de ejecutar.

Tarea: abre el editor del navegador o el archivo completo. Cambiá un solo dato visible, ejecútalo y observa qué parte del resultado cambió.

Cambié un único valor. Ejecuté el programa después del cambio. Puedo explicar qué cambió en el resultado.

Completé los tres pasos y puedo explicarlos. Todavía no ejecuté o no entiendo el resultado.

Progreso del mini proyecto

Completá los cuatro pasos.

🧪 Error controlado

Hacé una pregunta sin relación y detecta score bajo.

🤖 Cursor

Explica este proyecto como tutor.
Describe entrada, procesamiento y salida.
Revisa una función por vez.
No cambies el código sin mi autorización.
Después hazme cinco preguntas.

Antes de ejecutar el proyecto

🖥️ Cómo abrir y ejecutar este proyecto, paso a paso

¿Qué significa “ejecutar”?

Ejecutar un proyecto significa pedirle a Python que lea las instrucciones guardadas en sus archivos y realice el trabajo. No modifica tu computadora completa: trabaja dentro de la carpeta del proyecto.

En estas instrucciones utilizarás la terminal, una ventana donde escribís comandos. Un comando es una instrucción corta para la computadora.

Antes de comenzar, confirma estas cuatro cosas

Descargaste y descomprimiste el proyecto. Un ZIP es una carpeta comprimida. Tenés que abrirlo para obtener una carpeta normal.
Abriste la carpeta del proyecto. Dentro deberían aparecer archivos como main.py, requirements.txt y README.md.
Python está instalado. Esto se prepara en el Nivel 00.
La terminal está ubicada en esa carpeta. Si la terminal está en otra carpeta, Python no encontrará main.py.

Terminal

Ventana donde escribís comandos. En macOS se llama Terminal; en Windows podés usar PowerShell.

Lo aprendés en: Nivel 00 · Qué necesitás para empezar a programar.

Carpeta del proyecto

Carpeta que contiene todos los archivos relacionados. Los comandos deben ejecutarse desde esta ubicación.

Lo aprendés en: Nivel 00 · Qué necesitás para empezar a programar.

Entorno virtual (`.venv`)

Una carpeta privada para las librerías de este proyecto. Evitá mezclar herramientas de proyectos diferentes.

Lo aprendés en: Nivel 00 · Entornos virtuales, debugging y diagnóstico.

`pip`

Herramienta de Python para instalar librerías. Una librería es código preparado por otras personas para resolver tareas comunes.

Lo aprendés en: Nivel 00 · Entornos virtuales, debugging y diagnóstico.

`requirements.txt`

Archivo de texto que enumera las librerías necesarias. pip lo lee para instalar las versiones requeridas.

Lo aprendés en: Nivel 00 · Entornos virtuales, debugging y diagnóstico.

`main.py`

Archivo de inicio habitual. El nombre puede cambiar en proyectos avanzados, pero aquí suele contener el flujo principal.

Lo practicas desde: Nivel 01 · Tu primer proyecto con variables.

Escoge únicamente tu sistema operativo

No ejecutés las dos rutas. Usá macOS si trabajás en una Mac o Windows si utilizás PowerShell.

macOS · Terminal zsh

Abrí Terminal dentro de la carpeta del proyecto.
Una forma sencilla es abrir la carpeta en Finder, escribir cd en Terminal, arrastrar la carpeta a la ventana y presionar Enter.
```
pwd
ls
```
Resultado esperado: pwd muestra la ruta de la carpeta y ls muestra main.py.
Creá el entorno virtual.
```
python3 -m venv .venv
```
python3 abre Python. -m venv pide crear un entorno virtual. .venv es el nombre de la nueva carpeta.
Resultado esperado: aparece una carpeta llamada .venv. El comando puede terminar sin mostrar texto.
Activá el entorno.
```
source .venv/bin/activate
```
Activar significa indicar que los siguientes comandos deben utilizar el Python privado del proyecto.
Resultado esperado: la terminal suele mostrar (.venv) al inicio de la línea.
Instalá las librerías del proyecto.
```
python -m pip install -r requirements.txt
```
python -m pip abre el instalador de librerías. -r requirements.txt le indica qué lista debe leer.
Resultado esperado: aparecen mensajes de instalación o se indica que las librerías ya están instaladas.
Ejecutá el archivo principal.
```
python main.py
```
Python abre main.py, lee sus instrucciones de arriba hacia abajo y muestra el resultado.
Resultado esperado: verás el resultado descrito en la sección “Resultado” de esta lección.

Windows · PowerShell

Abrí PowerShell dentro de la carpeta del proyecto.
En el Explorador de archivos, abrí la carpeta, hacé clic en la barra de dirección, escribí powershell y presioná Enter.
```
Get-Location
dir
```
Resultado esperado: Get-Location muestra la carpeta actual y dir muestra main.py.
Creá el entorno virtual.
```
python -m venv .venv
```
python abre Python. -m venv crea el entorno y .venv es el nombre de la carpeta.
Resultado esperado: aparece una carpeta llamada .venv.
Activá el entorno.
```
.venv\Scripts\Activate.ps1
```
PowerShell empieza a utilizar el Python privado de este proyecto.
Resultado esperado: aparece (.venv) al inicio de la línea. Si PowerShell bloquea el archivo, repasa la lección de entornos virtuales antes de cambiar políticas de seguridad.
Instalá las librerías.
```
python -m pip install -r requirements.txt
```
pip lee la lista y prepara las herramientas que utiliza el proyecto.
Resultado esperado: aparecen mensajes de instalación o confirmación.
Ejecutá el archivo principal.
```
python main.py
```
Python abre y ejecuta las instrucciones de main.py.
Resultado esperado: verás el resultado descrito en esta lección.

¿Cómo sé que estoy en la carpeta correcta?

Tenés que poder ver main.py al ejecutar ls en macOS o dir en Windows.

¿Cómo detengo un programa?

Los scripts pequeños terminan solos. Si un servidor continúa funcionando, presiona Control + C.

¿Qué hago si dice que falta un archivo?

Revisá la carpeta actual. El error suele indicar que la terminal no está ubicada donde guardaste el proyecto.

¿Debo repetir todo cada vez?

El entorno se crea e instala una vez. En una sesión nueva normalmente solo activas .venv y ejecutás python main.py.

Términos que aparecerán más adelante

API

Forma organizada para que dos programas intercambien solicitudes y respuestas.

Lo vas a aprender en: Nivel 04 · Consume tu primera API.

FastAPI

Librería de Python para crear APIs y servidores web. Sus proyectos se ejecutan con un comando diferente a python main.py.

Lo vas a aprender en: Nivel 06 · Crea tu primera API.

Docker

Herramienta que empaqueta una aplicación junto con su configuración para ejecutarla de forma consistente en otras computadoras.

Lo vas a aprender en: Nivel 10 · Empaqueta una API con Docker.

Notebook

Documento interactivo que combina pequeños bloques de código, resultados y explicaciones. Es común en análisis de datos.

En este curso: es un recurso opcional. No necesitás usar notebooks para completar las lecciones actuales. Consulta la introducción a notebooks cuando aparezca el término.

Herramienta externa

Programa o servicio que no forma parte de Python, por ejemplo una base de datos, navegador, servicio de nube o modelo de IA.

Regla: no la instales ni ejecutes hasta llegar a la lección que la explica y revisar su README.

🧩 Tres niveles de desafío

Esencial: cambia un dato y verifica el resultado.
Práctica: agrega validación y un mensaje de error claro.
Avanzado: separa responsabilidades, añade pruebas y documenta la arquitectura.

Aprende comprobando

🧪 Comprobaciones programando

Ejecutá un caso controlado y deja que el código compruebe condiciones importantes.

1. Caso normalUsá datos comunes.

2. Valor límiteProbá cero, vacío, máximo o mínimo.

3. Error esperadoComprobá que el mensaje ayude a corregirlo.

response = {
    "answer": "Respuesta de ejemplo",
    "sources": ["documento-1"],
}

assert response["answer"].strip()
assert isinstance(response["sources"], list)
assert response["sources"]

print("✅ Estructura válida")

Qué estás aprendiendo: La prueba valida estructura, campos obligatorios y fuentes sin gastar créditos.

Después de ejecutarlo

¿Qué condición comprueba cada assert?
¿Qué cambio hace fallar la comprobación?
¿El mensaje explica qué tenés que corregir?
¿Podés agregar otro caso?

Parte 4

Comprobá lo que entendiste

Respondé una pregunta a la vez. Podés usar pistas y volver a intentarlo.

Evaluación online

❓ Comprueba lo que entendiste

Respondé sobre Construye RAG con citas. Verás una explicación completa y podrás intentarlo nuevamente.

Pregunta 1 de 5 · Selección

¿Cuál describe mejor la entrada principal?

respuesta con citas o aviso de evidencia insuficiente los documentos, pregunta y metadatos el sistema divide, indexa, recupera contexto y genera respuesta

Pregunta 2 de 5 · Selección

¿Qué describe mejor el procesamiento?

los documentos, pregunta y metadatos el sistema divide, indexa, recupera contexto y genera respuesta respuesta con citas o aviso de evidencia insuficiente

Pregunta 3 de 5 · Selección

¿Qué error esperado debería manejarse?

Ninguno; si funciona una vez siempre funcionará. recuperación irrelevante, cita incorrecta o herramienta no autorizada Ocultar cualquier error sin informar.

Pregunta 4 de 5 · Respuesta breve

¿Cómo comprobarías que el resultado es correcto?

Pregunta 5 de 5 · Respuesta breve

¿Qué mejora convertiría este microproyecto en una pieza de portafolio más sólida?

Resultado de la evaluación

Completá las cinco preguntas.

Parte 5

Cerrá la lección

Resume lo aprendido, completa el checklist y decide tu siguiente paso.

📝 Resumen

Ejecutaste una referencia funcional.
Identificaste entrada, procesamiento y salida.
Modificaste un comportamiento.
Provocaste y reparaste un error.
Preparaste una mejora para GitHub.

✅ Checklist

Ejecuté la referencia. Expliqué el flujo. Reparé el error. Reconstruí el proyecto. Preparé GitHub.Puedo definir las palabras nuevas principales y explicar el ejemplo mínimo sin copiarlo.

Cómo podrás mejorar este proyecto

🚀 Mejoras futuras y dónde las aprenderás

No son obligatorias ahora. Son mejoras que aplicarás cuando aprendas las herramientas correspondientes.

Separar la configuración del código

Qué mejora: Evita editar el programa cuando cambia una ruta, clave o preferencia.

Dónde lo aprenderás: en la lección «Protege tokens con .env», del nivel APIs y servicios externos.

Añadir pruebas automatizadas

Qué mejora: Comprueba que una modificación no rompa lo existente.

Dónde lo aprenderás: en la lección «Escribe pruebas unitarias», del nivel Testing y despliegue.

Registrar la ejecución

Qué mejora: Ayuda a entender fallos sin imprimir datos sensibles.

Dónde lo aprenderás: en la lección «Configura observabilidad», del nivel Testing y despliegue.

Mejorar mensajes y validación

Qué mejora: Explica qué dato falta y cómo corregirlo.

Dónde lo aprenderás: en la lección «Entrada de datos segura», del nivel Fundamentos de Python.

Documentar decisiones y limitaciones

Qué mejora: Permite que otra persona comprenda y evalúe el proyecto.

Dónde lo aprenderás: en la lección «Construye casos de estudio», del nivel Portafolio profesional.

Crear una demostración

Qué mejora: Muestra el problema, funcionamiento y evidencia.

Dónde lo aprenderás: en la lección «Crea un índice HTML», del nivel Portafolio profesional.

Construye RAG con citas

🎯 Qué vas a lograr en esta lección

¿Qué problema vas a resolver?

¿Qué vas a construir?

¿Por qué es útil?

¿Qué vas a aprender?

Tu primera acción

Avanza una parte a la vez

Aprende las palabras esenciales

🧱 Conceptos esenciales explicados desde cero

rag

recuperacion

contexto

cita

alucinacion

Ejemplo mínimo de flujo RAG

🧠 Conceptos explicados desde cero

retrieval

context

citations

grounding

Mirá un ejemplo pequeño

Relacionar una pregunta con un documento

⌨️ Código completo

🖼️ Explicación ilustrada: entrada → proceso → resultado

Situación

Entrada

Proceso

Resultado

Ejemplo antes y después

¿Cómo usarás este ejemplo en el mini proyecto?

Practica con un mini proyecto

🧩 Mini proyecto guiado: Construye RAG con citas

Reconoce una palabra nueva

Hacé un cambio seguro

Comprobá lo que ocurrió

Tu mini proyecto

Progreso del mini proyecto

🎉 ¡Mini proyecto completado!

🧪 Error controlado

🤖 Cursor

🖥️ Cómo abrir y ejecutar este proyecto, paso a paso

¿Qué significa “ejecutar”?

Antes de comenzar, confirma estas cuatro cosas

Terminal

Carpeta del proyecto

Entorno virtual (.venv)

pip

requirements.txt

main.py

Escoge únicamente tu sistema operativo

macOS · Terminal zsh

Windows · PowerShell

¿Cómo sé que estoy en la carpeta correcta?

¿Cómo detengo un programa?

¿Qué hago si dice que falta un archivo?

¿Debo repetir todo cada vez?

API

FastAPI

Docker

Notebook

Herramienta externa

🧩 Tres niveles de desafío

🧪 Comprobaciones programando

Después de ejecutarlo

Comprobá lo que entendiste

❓ Comprueba lo que entendiste

¿Cuál describe mejor la entrada principal?

¿Qué describe mejor el procesamiento?

¿Qué error esperado debería manejarse?

Resultado de la evaluación

Cerrá la lección

📝 Resumen

✅ Checklist

🚀 Mejoras futuras y dónde las aprenderás

Separar la configuración del código

Añadir pruebas automatizadas

Registrar la ejecución

Mejorar mensajes y validación

Documentar decisiones y limitaciones

`rag`

`recuperacion`

`contexto`

`cita`

`alucinacion`

`retrieval`

`context`

`citations`

`grounding`

Entorno virtual (`.venv`)

`pip`

`requirements.txt`

`main.py`