Clase 12 · Guía de trabajoSe guarda solo

Un sistema que responde con documentos

El código se copia con un botón: no transcriba nada. Lo que sí tiene que llenar son los campos verdes — se guardan solos en este computador, y al final los baja en un archivo para la entrega.

Baje el archivo apenas termine. Lo que se guarda solo vive en este computador y se pierde si lo reinician.

Quién entrega

Parte A · El sistema guiado

Lo construimos juntos. Al final de esta parte usted tiene un buscador que funciona.

1Abrir la carpeta

Baje clase12-rag.zip de los recursos de la clase y descomprímalo en el Escritorio.

Cuidado aquíDescomprímalo de verdad. Windows deja abrir el zip como si fuera una carpeta, pero ahí adentro no se puede guardar nada y después nada le va a funcionar. Clic derecho → Extraer todo.

Ábralo en VS Code con Archivo → Abrir carpeta. Debe verse así:

Lo que debe ver en el Explorador
clase12-rag/
   documentos/
      01-devoluciones.txt
      02-garantias.txt
      03-domicilios.txt
      04-fidelizacion.txt
      05-horarios.txt
      06-reclamos.txt

2La forma de un documento

Abra 02-garantias.txt y léalo. Son ocho líneas.

Esos seis archivos son todo lo que va a saber el sistema que vamos a construir. No hay base de datos ni internet. Café Altamar es una cadena inventada para la clase.

Fíjese en la forma, porque hoy usted va a escribir cinco así. Todos los documentos de esta carpeta siguen el mismo molde:

El molde · 6 a 10 líneas por documento
TITULO EN MAYUSCULAS - NOMBRE DE LA EMPRESA     <- de que trata

Un parrafo de 3 o 4 lineas con la regla principal,
y SIEMPRE con cifras concretas: 8 dias, 9.900 pesos, 30 dias.

Un parrafo con los detalles o las excepciones.

Una linea con lo que NO cubre.
Anótelo · lo va a usar en el taller
Cuidado aquíLas cifras no son adorno. Un documento que dice «le devolvemos el dinero rápido» no sirve: no hay nada que buscar ni nada que responder. Uno que dice «5 días hábiles» sí.

3Crear el buscador

En VS Code: clic derecho sobre la carpeta → New File, y llámelo buscador.py.

Copie todo este código y péguelo adentro. No lo transcriba: use el botón.

buscador.py · péguelo completo
# glob -> busca archivos por patrón: "documentos/*.txt" = todos los .txt de esa carpeta
# re   -> expresiones regulares, aquí solo para partir un texto en palabras
import glob, re

# Palabras que aparecen en TODO y no distinguen nada. Si no las quitamos,
# cualquier documento se parece a cualquier pregunta.
VACIAS = {"de","la","el","en","y","a","los","las","un","una","que","se","con",
          "por","para","del","al","es","su","o","no","si","mi","me","lo","como",
          "cuanto","cuantos","cuanta","cuantas","puedo","tengo","hay","dentro"}

# "días" y "dias" son la misma palabra para usted y dos palabras distintas
# para el computador. El recuperador tiene que igualarlas antes de comparar.
TILDES = str.maketrans("áéíóúüñ", "aeiouun")

def palabras(texto):
    limpio = texto.lower().translate(TILDES)
    sueltas = [p for p in re.findall(r"[a-z]+", limpio) if p not in VACIAS]
    # [:5] = nos quedamos con la raíz, para que "devolver" y "devoluciones"
    # cuenten como la misma. Un buscador de verdad usa stemming; esto es
    # la versión de juguete, y más abajo vamos a ver dónde se rompe.
    return {p[:5] for p in sueltas}

# 1 - EL CORPUS. Cada archivo es un pedazo (un "chunk").
pedazos = []
for ruta in sorted(glob.glob("documentos/*.txt")):
    with open(ruta, encoding="utf-8") as f:
        pedazos.append((ruta, f.read()))

# La misma guarda de la clase pasada: sin esto, responde "no sé" y parece normal.
if not pedazos:
    print("NO ENCONTRE NINGUN DOCUMENTO en documentos/*.txt")
    raise SystemExit(1)

pregunta = input("Pregunta: ")
clave = palabras(pregunta)

# 2 - EL RECUPERADOR. Puntaje = qué tanto de la pregunta aparece en el documento.
puntajes = []
for ruta, texto in pedazos:
    comunes = clave & palabras(texto)
    puntajes.append((len(comunes) / max(len(clave), 1), ruta, texto, comunes))

puntajes.sort(key=lambda x: x[0], reverse=True)

print("\nRANKING COMPLETO")
for score, ruta, _, comunes in puntajes:
    print(f"  {score:5.2f}  {ruta:32}  {sorted(comunes)}")

# 3 - EL PROMPT ARMADO. Solo los 2 mejores entran.
print("\n" + "=" * 62)
print("ESTO ES LO UNICO QUE VA A VER EL MODELO")
print("=" * 62)

lineas = []   # aqui vamos armando el prompt, linea por linea
lineas.append("Eres el asistente de servicio al cliente de Cafe Altamar.")
lineas.append("Responde al cliente de forma util y concreta.\n")
for score, ruta, texto, _ in puntajes[:2]:
    lineas.append(f"--- EVIDENCIA ({ruta}) ---")
    lineas.append(texto.strip() + "\n")
lineas.append(f"PREGUNTA: {pregunta}")

print("\n".join(lineas))

# Y lo guardamos tambien en un archivo, porque copiar desde la terminal
# es incomodo. Abra prompt.txt en VS Code y copie con Ctrl+A, Ctrl+C.
with open("prompt.txt", "w", encoding="utf-8") as f:
    f.write("\n".join(lineas))
print("\n(tambien quedo en prompt.txt — abralo en VS Code y copielo de ahi)")

Guarde con Ctrl+S.

El profesor va a explicar qué hace cada parte mientras usted lo tiene en pantalla. Siga la explicación sobre su propio código, no sobre el proyector.

4Primera pregunta

Abra la terminal de VS Code con Ctrl+Ñ (o Terminal → Nueva terminal) y ejecute:

Ejecutar
python buscador.py
Cuidado aquíEspere a que aparezca la palabra Pregunta: antes de escribir. Si escribe antes, la terminal se come la pregunta y le sale command not found.

Cuando aparezca, pegue esta pregunta:

Pregunta 1
¿Cuántos días tengo para devolver un café?
Llene esto · queda en la entrega

Ahora abra el archivo prompt.txt que acabó de aparecer en la carpeta. Selecciónelo todo con Ctrl+A, cópielo con Ctrl+C, y péguelo en su chat de IA.

Llene esto

Ahora voltee a mirar al compañero de al lado. Si usa un chat distinto al suyo, pídale la respuesta que le salió a él y anótela:

El mismo prompt, otro modelo
Esto mismo lo va a repetir en el taller, con su propia pregunta. Por eso lo ensayamos aquí.

5Segunda pregunta

Ejecutar otra vez
python buscador.py

Y cuando aparezca Pregunta:, pegue esta:

Pregunta 2
¿Puedo devolver un molino de café?
Llene esto

Vuelva a abrir prompt.txt, cópielo y péguelo en su chat.

Llene esto · es la respuesta más importante del día
No siga al paso 6 hasta que el profesor lo indique.

6La conversación

Computador a un lado. Esta parte es de hablar y de anotar.

Llene esto

7La segunda versión

No modifique buscador.py. Vamos a trabajar sobre una copia, para poder comparar las dos. En la terminal:

Hacer la copia
cp buscador.py buscador2.py

Abra buscador2.py y haga dos cambios.

Cambio 1 · el umbral. Busque estas tres líneas, que son las que imprimen el ranking:

Búsquelas · el final del ranking
print("\nRANKING COMPLETO")
for score, ruta, _, comunes in puntajes:
    print(f"  {score:5.2f}  {ruta:32}  {sorted(comunes)}")

Y justo debajo de la última, pegue esto:

Cambio 1 · va debajo del ranking
UMBRAL = 0.70
mejor = puntajes[0][0]
if mejor != max(p[0] for p in puntajes):
    print("\nOJO: este bloque quedo ANTES del sort. Muevalo debajo de")
    print("     puntajes.sort(...) o va a bloquear preguntas buenas.")
    raise SystemExit(1)
if mejor < UMBRAL:
    print(f"\nEVIDENCIA INSUFICIENTE (mejor puntaje {mejor:.2f} < {UMBRAL})")
    print("No le pregunto al modelo. Esta pregunta no la cubren los documentos.")
    raise SystemExit(0)
Cuidado aquíDebajo del ranking, no en otro lado. Si lo pega más arriba, el programa mira el documento equivocado y le bloquea todas las preguntas, hasta las buenas. Por eso el bloque trae un chequeo: si lo pegó mal, se lo dice y se detiene.

Cambio 2. Busque esta línea:

Búsquela
lineas.append("Responde al cliente de forma util y concreta.\n")

Reemplácela por estas tres:

Cambio 2 · reemplaza a la anterior
lineas.append("Responde al cliente de forma util y concreta.")
lineas.append("Responde usando UNICAMENTE la evidencia de abajo.")
lineas.append("Si la evidencia no alcanza, responde exactamente: NO ESTA EN LOS DOCUMENTOS.\n")

Guarde, y corra la misma pregunta 2 contra la versión nueva:

Ejecutar la versión 2
python buscador2.py
Llene esto

8Cómo se fabrica una trampa

El molino del paso 5 no salió de la nada: yo lo construí a propósito, y hay una receta. En el taller usted va a tener que fabricar la suya, así que vamos a hacer una aquí primero.

Las tres reglas
LA RECETA, EN TRES REGLAS

  1. Escoja un documento y mire DE QUE habla.
     (01-devoluciones habla de cafe en grano y cafe molido)

  2. Pregunte por un PRIMO de esa cosa que el documento NO menciona.
     (un molino es pariente del cafe... pero no es cafe)

  3. Use las PALABRAS del documento en su pregunta.
     Si no, saca 0.00 y no sirve como trampa.
Cuidado aquíLa regla 3 es la que se les olvida. «¿Abren el 20 de julio?» parece una buena trampa, pero saca 0.00: no comparte ni una palabra con ningún documento. Una trampa con 0.00 no engaña a nadie — el sistema ya sabe que no sabe. La trampa peligrosa es la que saca puntaje ALTO.

Ahora le toca a usted. Escoja otro documento de Café Altamar — no el de devoluciones — y fabrique una trampa siguiendo las tres reglas. Pruébela:

Y escriba su trampa cuando aparezca Pregunta:
python buscador.py
Su primera trampa · con el corpus de Café Altamar
Si le salió por debajo de 0.40, le falló la regla 3: su pregunta no está usando las palabras del documento. Cámbiela y vuelva a probar.

9El banco de pruebas

En la misma carpeta ya viene probar.py. Córralo una sola vez:

Ejecutar el banco
python probar.py

Son 10 preguntas donde ya se sabe cuál debería ser el resultado: 7 sí se pueden responder con los documentos y 3 no. El programa le muestra tres cosas, una debajo de la otra.

Lea bien las dos últimas columnas, porque no son lo mismo. QUE HACE es lo que el sistema hizo de verdad. QUE DEBIA HACER es lo que debió haber hecho. Con el umbral en 0.70, todo lo que saque menos de 0.70 se calla, sin excepción — las filas marcadas MAL también. El error no es que respondieran: es que se callaron teniendo la respuesta en los documentos.
Parte 1 · el detalle con el umbral en 0.70
Parte 2 · la tabla de umbrales

Mire solo las dos últimas columnas, no el total.

Parte 3 · las preguntas empatadas

El programa encuentra varias preguntas con el mismo puntaje.

Y ahora agregue la suya. Abra probar.py y busque la lista que se llama BANCO. Cada línea tiene dos cosas: la pregunta, y el archivo que debería ganar — o None si la respuesta no está en ningún documento.

Agregue su línea justo debajo de la del molino
    ("¿Puedo devolver un molino de café?",           None),
    ("SU PREGUNTA TRAMPA DEL PASO 8 VA AQUI",        None),
Cuidado aquíRespete la coma del final y las comillas. Y fíjese que el molino lleva None porque su respuesta no está en los documentos — la suya también debería llevar None, si de verdad es una trampa.
Vuelva a correrlo, ahora con 11 preguntas
python probar.py
Su pregunta dentro del banco
Acaba de hacer, en una línea, lo que en el taller hará con ocho. Eso es armar un banco de pruebas: escribir la pregunta y declarar cuál es la verdad, usted, leyendo los documentos.

10El correo, en una frase

Último paso de la parte guiada, y es el ensayo de lo que más puntos vale en el taller.

Imagine que el gerente de Café Altamar le escribe: «me dicen que el bot a veces no contesta cosas que están en nuestras propias políticas. ¿Por qué?»

Contéstele en una sola frase
Cuidado aquíSi usó la palabra «umbral», bórrela y vuelva a escribir. Ese es justamente el ejercicio: si no lo puede decir sin jerga, todavía no lo entendió del todo.
En el taller va a escribir el correo completo, con cinco frases como esta, pero sobre su propio negocio. Esta era la de práctica.

Parte B · El taller

Por grupos · 60 minutos · De aquí sale la nota de hoy

B.1Los seis movimientos

Cada grupo construye su propio sistema, con su propio negocio. Carpeta nueva, desde cero:

Crear la carpeta del taller
mkdir taller12
mkdir taller12/documentos
Los seis movimientos ya los hizo esta mañana, uno por uno, con Café Altamar. Lo único que cambia es el negocio. La última columna le dice en qué paso lo ensayó: si se atasca, vuelva a ese paso.
#Qué haceYa lo hizo enPts
1Escriben 5 documentos de su negocio en taller12/documentos/, de 6 a 10 líneas, con cifras concretas, usando el moldepaso 2
la forma de un documento
10
2Copian su buscador.py a taller12/ y lo hacen correr contra sus documentospasos 3 y 4
crear y correr
18
3Fabrican su pregunta trampa con las tres reglas: puntaje alto y sin respuesta en sus documentospaso 8
la receta
18
4Pegan ese prompt en dos chats de IA distintos y comparanpaso 4
con el compañero
14
5Arman un banco de 8 preguntas — 5 que sí responden y 3 que no — y prueban tres umbralespaso 9
agregó una al banco
20
6Escriben el correo al jefe, cinco frases sin jergapaso 10
escribió una
20
Total 100 puntos, multiplicados por el factor del sorteo del cierre.

B.2Copiar el buscador al taller

Los tres comandos
cp buscador.py taller12/buscador.py
cd taller12
python buscador.py
Como el buscador lee documentos/*.txt con ruta relativa, basta con pararse dentro de taller12 para que use los documentos de ustedes.

B.3Su negocio y su trampa

Movimientos 1 y 3

B.4Los dos modelos

Peguen el prompt de su pregunta trampa en dos chats distintos.

Movimiento 4

B.5El banco y los umbrales

Armen un banco de 8 preguntas sobre su negocio — 5 que sus documentos sí respondan y 3 que no — y métanlas en su propio probar.py.

Movimiento 5

B.6El correo al jefe

Su sistema a veces se niega a responder. Su jefe se dio cuenta y le escribió preguntando por qué. No es técnico: es el gerente del negocio.

Cuidado aquíEsta es la parte que más puntos vale, y no se puede copiar de otro grupo porque depende de los números de ustedes. Escríbalo como lo escribiría de verdad: corto, en español de oficina, sin una sola palabra técnica.
Movimiento 6 · el correo
Esa última casilla es la que separa un 20 de un 10. La respuesta tiene que ver con lo que encontraron en el paso 8.

B.7La entrega

Cuidado aquíA AVATA hoy, antes de las 11:59 p.m. Un solo envío por grupo, en la actividad «Clase 12 · Buscador con evidencia». No se reciben correos.

Primero, baje sus respuestas con el botón azul de abajo. Le va a quedar un archivo respuestas-clase12.txt.

Después, meta ese archivo dentro de taller12/ y comprima la carpeta. Adentro debe quedar:

El contenido del zip
taller12/
   documentos/              los 5 documentos del negocio
   buscador.py              funcionando contra su corpus
   respuestas-clase12.txt   el que baja de esta guía
Si prefiere entregar en PDF, el botón Guardar como PDF abre el diálogo de impresión: escoja Guardar como PDF como destino.

Arquitectura de Software · Universidad Jorge Tadeo Lozano · 2026-2S