Al cerrar el módulo 3 dejamos a DocuBot en una situación curiosa: es un sistema robusto, con memoria, económicamente vigilado... y ciego. Responde de maravilla cuando le damos la documentación correcta en la mano, pero hasta ahora esa mano ha sido la nuestra: en cada ejemplo hemos pegado nosotros los fragmentos relevantes en el bloque <documentacion>. La pregunta pendiente era: ¿quién encuentra, entre cientos de páginas de la wiki de Nubelia, los dos fragmentos que responden a cada pregunta? Esta lección construye la primera pieza de la respuesta: los embeddings —que en 01-02 presentamos intuitivamente como "coordenadas de significado"— pasan hoy de intuición a código. Aprenderás a obtenerlos vía API, a medir cuánto se parecen dos textos con la similitud coseno, y a montar una búsqueda semántica funcional (aunque de fuerza bruta) sobre la documentación de Nubelia. Y de regalo, resolveremos la limitación que anunciamos en 03-04: el CacheRespuestas exacto que no reconocía preguntas equivalentes formuladas de otra manera.

1. De "coordenadas de significado" a vectores reales
2. Obtener embeddings vía API
3. Similitud coseno: medir la cercanía entre significados
4. Búsqueda semántica de fuerza bruta sobre la doc de Nubelia
5. Palabras clave vs. significado: por qué gana la búsqueda semántica
6. Elegir un modelo de embeddings
7. Aplicación de regalo: el caché semántico de respuestas

En 01-02 vimos la intuición con el ejemplo perro/gato/factura: un embedding coloca cada texto en un mapa donde los significados parecidos quedan cerca. "Perro" y "gato" son vecinos; "factura" vive en otro barrio. Hoy concretamos esa metáfora:

• Un embedding es una lista de números decimales (un vector) que representa el significado de un texto. Longitudes típicas: entre 256 y 3072 números (sus dimensiones).
• Lo produce un modelo de embeddings, que es un modelo distinto del LLM que genera texto. No conversa: solo convierte texto en coordenadas.
• La propiedad clave: dos textos con significado parecido producen vectores cercanos, aunque no compartan ni una sola palabra. "No puedo entrar en mi cuenta" y "restablecer contraseña" quedan cerca en el mapa; "exportar informe" queda lejos de ambos.

Para DocuBot esto lo cambia todo: si convertimos cada fragmento de la documentación de Nubelia en un vector, y también la pregunta del usuario, encontrar la documentación relevante se reduce a un problema geométrico — buscar los vectores más cercanos al de la pregunta.

Igual que en 03-01 con el LLM, usamos una API gestionada. Todos los proveedores de embeddings siguen el mismo patrón: envías una lista de textos, recibes una lista de vectores. Aquí lo mostramos con el SDK de voyageai como ejemplo, pero el código es deliberadamente genérico — cambiar de proveedor es cambiar tres líneas:

Desglose para quien lo ve por primera vez:

• embed() recibe una lista, no un texto suelto: las APIs de embeddings están pensadas para trabajar por lotes, y embeber 50 textos en una llamada es mucho más barato en latencia que 50 llamadas de un texto. Lo explotaremos en la ingesta (04-03).
• input_type: varios modelos distinguen entre embeber un documento (que será buscado) y una consulta (que busca). Si tu proveedor no lo soporta, ignora el parámetro; si lo soporta, úsalo — mejora la recuperación.
• El resultado es una lista de vectores; cada vector es una list[float] de tantas dimensiones como tenga el modelo (p. ej. 1024).

Un detalle importante: ningún número del vector significa nada por sí solo. El significado está en la posición global del vector respecto a los demás. Por eso la única operación útil es compararlos.

Necesitamos un número que diga "cuánto se parecen" dos vectores. El estándar es la similitud coseno, y la intuición geométrica es simple: imagina cada vector como una flecha que sale del origen del mapa de significados. La similitud coseno mide el ángulo entre las dos flechas:

• Flechas que apuntan en la misma dirección (ángulo 0°) → similitud 1.0: significados casi idénticos.
• Flechas perpendiculares (90°) → similitud 0.0: significados sin relación.
• Flechas opuestas → similitud -1.0 (raro en la práctica con textos reales).

Lo interesante es que mide dirección, no longitud: un párrafo largo y una frase corta sobre el mismo tema apuntan hacia el mismo sitio. La implementación cabe en diez líneas y no necesita más matemática que multiplicar y sumar:

• El producto escalar (sum(x*y)) crece cuando los dos vectores tienen valores grandes en las mismas posiciones — es decir, cuando "apuntan hacia el mismo lado".
• Dividir por las dos normas (longitudes) elimina el efecto del tamaño: solo queda el ángulo.
• En producción usarías numpy por velocidad, pero esta versión pura deja claro que no hay magia.

Los valores exactos dependen del modelo (cada modelo tiene su "escala" típica), pero el orden relativo es fiable: lo relacionado puntúa más alto que lo no relacionado. Retén esta idea — reaparecerá cuando calibremos umbrales.

Ya tenemos las dos piezas. La búsqueda semántica más simple posible — fuerza bruta — consiste en: embeber todos los fragmentos una vez, embeber la pregunta, calcular la similitud contra todos los fragmentos y quedarse con los k mejores (top-k):

Salida típica:

Fíjate en lo que acaba de pasar: la pregunta "no puedo entrar en mi cuenta" no comparte ninguna palabra clave con "restablecer contraseña" ni con "cuenta bloqueada tras intentos fallidos", y aun así la búsqueda ha encontrado exactamente los dos fragmentos que un humano de soporte habría elegido. Esto es lo que ninguna búsqueda por palabras hace bien.

Dos observaciones antes de seguir:

• El paso 1 (embeber el corpus) se hace una vez y se reutiliza; solo la pregunta se embebe en cada búsqueda. Aun así, mantener los vectores en una lista de Python tiene problemas serios de escala y persistencia — ese es exactamente el tema de la próxima lección (04-02).
• Aquí los "fragmentos" nos los hemos dado hechos. Decidir cómo trocear cientos de páginas reales en fragmentos buenos es un arte con nombre propio, chunking, y tiene su propia lección (04-03).

La alternativa clásica es la búsqueda por palabras clave (la de grep, la de un buscador de wiki básico): encontrar documentos que contengan las mismas palabras que la consulta. Comparemos:

La tabla revela algo importante: la semántica no es estrictamente superior en todo. Para códigos de error exactos o nombres de funciones de la API de Nubelia, la búsqueda literal es difícil de batir. Por eso muchos sistemas maduros usan búsqueda híbrida (combinar ambas) — nos basta con saber que existe; para DocuBot, la semántica pura cubre la gran mayoría de preguntas de soporte, que llegan escritas con las palabras del usuario, no con las de la documentación.

Un error frecuente es asumir que el modelo de embeddings "viene con" el LLM. Son decisiones independientes: DocuBot puede generar respuestas con el modelo medio elegido en 01-03 y embeber con un modelo de otro proveedor. Los criterios de elección:

Y una regla de oro que conviene tatuar: los vectores de modelos distintos no son comparables entre sí. Si mañana cambias de modelo de embeddings, todos los vectores del corpus quedan obsoletos y hay que re-embeber todo. Por eso MODELO_EMBEDDINGS es una constante con env var, y por eso la ingesta de 04-03 será re-ejecutable.

En 03-04 construimos CacheRespuestas: un caché exacto por hash SHA-256 de la pregunta normalizada, con TTL. Y anunciamos su limitación: "¿cómo restablezco mi contraseña?" y "olvidé mi password, ¿qué hago?" generan hashes distintos → dos llamadas al LLM para la misma respuesta. Con lo aprendido hoy, la solución es directa: cachear también el vector de cada pregunta y, antes de llamar al LLM, comprobar si alguna pregunta cacheada es suficientemente parecida:

Puntos de diseño que merecen atención:

• El umbral es la decisión crítica. Con 0.92 exigimos preguntas casi equivalentes. Si lo bajas a 0.80, ahorras más llamadas pero arriesgas servir la respuesta de "¿cómo invito a un miembro?" a quien preguntó "¿cómo elimino a un miembro?" — preguntas temáticamente cercanas pero con respuestas opuestas. Un falso positivo en un caché es peor que cien misses: el usuario recibe una respuesta incorrecta con total confianza. Calíbralo con el conjunto de evaluación de 02-04, empezando conservador.
• Sigue habiendo coste: cada consulta al caché embebe la pregunta (una llamada barata a la API de embeddings). El ahorro neto viene de evitar la llamada cara al LLM. Con los precios relativos de precios.py (03-04), la cuenta sale muy a favor.
• La búsqueda dentro del caché es fuerza bruta — recorre todas las entradas. Para un caché de cientos de preguntas es perfectamente válido; es el mismo patrón de buscar() de esta lección. (Y sí: si el caché creciera a millones de entradas, necesitaría lo mismo que el corpus — una base vectorial. Todo conecta.)
• La invalidación se mantiene: cuando Nubelia publica documentación nueva, el caché se vacía, exactamente como decidimos en 03-04.

• Comparar vectores de modelos distintos. Da números sin sentido, sin error visible. Fija el modelo con MODELO_EMBEDDINGS y trátalo como parte del esquema de tus datos.
• Interpretar la similitud como probabilidad universal. Un 0.75 no significa "75% relevante": la escala depende del modelo. Compara siempre dentro del mismo modelo, y calibra umbrales empíricamente con tu conjunto de evaluación.
• Olvidar input_type (en modelos que lo soportan): embeber preguntas como si fueran documentos degrada la recuperación de forma silenciosa.
• Embeber texto a texto en bucle. Las APIs aceptan lotes; embeber uno a uno multiplica la latencia y a veces el coste. Reserva el bucle para la pregunta del usuario (que llega de una en una, inevitablemente).
• Umbral de caché semántico demasiado generoso. Empieza en 0.90+, mide falsos positivos con casos del tipo "preguntas parecidas con respuesta distinta" (los adversariales suaves de 02-04 son buenos candidatos) y baja solo con evidencia.
• Consejo: guarda junto a cada vector el texto que lo originó. Un vector sin su texto es irrecuperable — no hay operación "des-embeber".

1. Top-k con umbral mínimo. Modifica buscar() para que acepte un parámetro umbral_minimo y descarte los fragmentos cuya similitud quede por debajo, aunque eso deje menos de k resultados. Pruébala con la pregunta "¿puedo pagar con criptomonedas?" (que no tiene respuesta en el mini-corpus) y observa qué devuelve.
2. Keyword vs. semántica. Implementa una función buscar_keywords(pregunta, k) que puntúe cada fragmento por número de palabras en común con la pregunta (ignorando mayúsculas y palabras de menos de 4 letras). Compárala con buscar() para las preguntas "no puedo entrar en mi cuenta" y "token de la API": ¿cuál gana en cada caso y por qué?
3. Calibrar el caché semántico. Con CacheSemantico, guarda la respuesta a "¿cómo restablezco mi contraseña?" y prueba a recuperarla con: (a) "olvidé mi password, ¿qué hago?", (b) "¿cómo cambio mi contraseña?", (c) "¿cómo invito a un usuario?". Prueba umbrales 0.80, 0.90 y 0.95 y anota en una tabla qué combinaciones aciertan y cuáles producen falsos positivos.

1. Basta con filtrar antes de cortar:

Con "¿puedo pagar con criptomonedas?" y un umbral razonable (p. ej. 0.5), la lista queda vacía o casi: no hay documentación relevante, y devolver una lista vacía es más honesto que devolver ruido. Guarda esta idea — en 04-04 será la pieza que dispare la frase anti-alucinación de SYSTEM_DOCUBOT ("No encuentro esa información en la documentación disponible.") cuando la recuperación no encuentre nada digno.

2. Una versión mínima:

Resultado esperado: para "no puedo entrar en mi cuenta", buscar_keywords empata casi todo a 0-1 coincidencias (solo "cuenta" ayuda, y aparece en varios fragmentos) mientras la semántica acierta de pleno. Para "token de la API", la keyword gana o empata: "token" y "API" son términos exactos que aparecen literalmente en el fragmento correcto. Conclusión: la semántica domina en lenguaje natural de usuario; la literal sigue siendo fuerte en terminología exacta.

3. Resultados típicos (los tuyos variarán según el modelo):

Con 0.95 el caché apenas ahorra; con 0.80 acierta más pero el margen de seguridad frente a pares "parecidos con respuesta distinta" se estrecha. 0.90 suele ser el compromiso inicial razonable — y la cifra definitiva debe salir de medir sobre el conjunto de evaluación, no de este ejercicio.

Hoy los embeddings han dejado de ser una metáfora de 01-02 para convertirse en tres funciones que caben en una pantalla: embed() convierte texto en coordenadas de significado, similitud_coseno() mide el ángulo entre dos de esas coordenadas, y buscar() encuentra los top-k fragmentos de la documentación de Nubelia más cercanos a cualquier pregunta — incluida "no puedo entrar", que no comparte ni una palabra con la respuesta que necesita. Hemos visto por qué esto supera a la búsqueda por palabras clave (y cuándo no), qué criterios pesan al elegir modelo de embeddings (independiente del LLM, con sus vectores incompatibles entre modelos), y hemos cobrado el regalo prometido en 03-04: CacheSemantico, que reconoce preguntas equivalentes por significado con un umbral calibrado con cuidado. Pero nuestra búsqueda tiene dos vergüenzas que hemos barrido bajo la alfombra: compara la pregunta contra todos los vectores en cada consulta, y esos vectores viven en una lista de Python que desaparece al reiniciar el proceso — con cientos de páginas de documentación real, ninguna de las dos cosas es aceptable. Resolver ambas es el trabajo de las bases de datos vectoriales, y es exactamente lo que construimos en la siguiente lección (04-02).