En tancar el mòdul 3 vam deixar DocuBot en una situació curiosa: és un sistema robust, amb memòria, econòmicament vigilat... i cec. Respon de meravella quan li donem la documentació correcta a la mà, però fins ara aquesta mà ha estat la nostra: a cada exemple hem enganxat nosaltres els fragments rellevants al bloc <documentacio>. La pregunta pendent era: qui troba, entre centenars de pàgines de la wiki de Nubelia, els dos fragments que responen cada pregunta? Aquesta lliçó construeix la primera peça de la resposta: els embeddings —que a 01-02 vam presentar intuïtivament com a "coordenades de significat"— passen avui d'intuïció a codi. Aprendràs a obtenir-los via API, a mesurar com s'assemblen dos textos amb la similitud cosinus, i a muntar una cerca semàntica funcional (encara que de força bruta) sobre la documentació de Nubelia. I de regal, resoldrem la limitació que vam anunciar a 03-04: el CacheRespostes exacte que no reconeixia preguntes equivalents formulades d'una altra manera.

1. De "coordenades de significat" a vectors reals
2. Obtenir embeddings via API
3. Similitud cosinus: mesurar la proximitat entre significats
4. Cerca semàntica de força bruta sobre la doc de Nubelia
5. Paraules clau vs. significat: per què guanya la cerca semàntica
6. Triar un model d'embeddings
7. Aplicació de regal: el cache semàntic de respostes

A 01-02 vam veure la intuïció amb l'exemple gos/gat/factura: un embedding col·loca cada text en un mapa on els significats semblants queden a prop. "Gos" i "gat" són veïns; "factura" viu en un altre barri. Avui concretem aquesta metàfora:

• Un embedding és una llista de números decimals (un vector) que representa el significat d'un text. Longituds típiques: entre 256 i 3072 números (les seves dimensions).
• El produeix un model d'embeddings, que és un model diferent del LLM que genera text. No conversa: només converteix text en coordenades.
• La propietat clau: dos textos amb significat semblant produeixen vectors propers, encara que no comparteixin ni una sola paraula. "No puc entrar al meu compte" i "restablir contrasenya" queden a prop al mapa; "exportar informe" queda lluny de tots dos.

Per a DocuBot això ho canvia tot: si convertim cada fragment de la documentació de Nubelia en un vector, i també la pregunta de l'usuari, trobar la documentació rellevant es redueix a un problema geomètric — buscar els vectors més propers al de la pregunta.

Igual que a 03-01 amb el LLM, fem servir una API gestionada. Tots els proveïdors d'embeddings segueixen el mateix patró: envies una llista de textos, reps una llista de vectors. Aquí ho mostrem amb l'SDK de voyageai com a exemple, però el codi és deliberadament genèric — canviar de proveïdor és canviar tres línies:

Desglossament per a qui ho veu per primera vegada:

• embed() rep una llista, no un text sol: les APIs d'embeddings estan pensades per treballar per lots, i embeddir 50 textos en una crida és molt més barat en latència que 50 crides d'un text. Ho explotarem a la ingesta (04-03).
• input_type: diversos models distingeixen entre embeddir un document (que serà cercat) i una consulta (que cerca). Si el teu proveïdor no ho suporta, ignora el paràmetre; si ho suporta, fes-lo servir — millora la recuperació.
• El resultat és una llista de vectors; cada vector és una list[float] de tantes dimensions com tingui el model (p. ex. 1024).

Un detall important: cap número del vector no significa res per si sol. El significat és a la posició global del vector respecte dels altres. Per això l'única operació útil és comparar-los.

Necessitem un número que digui "com s'assemblen" dos vectors. L'estàndard és la similitud cosinus, i la intuïció geomètrica és simple: imagina cada vector com una fletxa que surt de l'origen del mapa de significats. La similitud cosinus mesura l'angle entre les dues fletxes:

• Fletxes que apunten en la mateixa direcció (angle 0°) → similitud 1.0: significats gairebé idèntics.
• Fletxes perpendiculars (90°) → similitud 0.0: significats sense relació.
• Fletxes oposades → similitud -1.0 (rar a la pràctica amb textos reals).

L'interessant és que mesura direcció, no longitud: un paràgraf llarg i una frase curta sobre el mateix tema apunten cap al mateix lloc. La implementació cap en deu línies i no necessita més matemàtica que multiplicar i sumar:

• El producte escalar (sum(x*y)) creix quan els dos vectors tenen valors grans a les mateixes posicions — és a dir, quan "apunten cap al mateix costat".
• Dividir per les dues normes (longituds) elimina l'efecte de la mida: només queda l'angle.
• En producció faries servir numpy per velocitat, però aquesta versió pura deixa clar que no hi ha màgia.

Els valors exactes depenen del model (cada model té la seva "escala" típica), però l'ordre relatiu és fiable: allò relacionat puntua més alt que allò no relacionat. Retén aquesta idea — reapareixerà quan calibrem llindars.

Ja tenim les dues peces. La cerca semàntica més simple possible — força bruta — consisteix a: embeddir tots els fragments una vegada, embeddir la pregunta, calcular la similitud contra tots els fragments i quedar-se amb els k millors (top-k):

Sortida típica:

Fixa't en el que acaba de passar: la pregunta "no puc entrar al meu compte" no comparteix cap paraula clau amb "restablir contrasenya" ni amb "compte bloquejat després d'intents fallits", i tot i així la cerca ha trobat exactament els dos fragments que un humà de suport hauria triat. Això és el que cap cerca per paraules no fa bé.

Dues observacions abans de continuar:

• El pas 1 (embeddir el corpus) es fa una vegada i es reutilitza; només la pregunta s'embedeix a cada cerca. Tot i així, mantenir els vectors en una llista de Python té problemes seriosos d'escala i persistència — aquest és exactament el tema de la propera lliçó (04-02).
• Aquí els "fragments" ens els han donat fets. Decidir com trossejar centenars de pàgines reals en fragments bons és un art amb nom propi, chunking, i té la seva pròpia lliçó (04-03).

L'alternativa clàssica és la cerca per paraules clau (la de grep, la d'un cercador de wiki bàsic): trobar documents que continguin les mateixes paraules que la consulta. Comparem:

La taula revela una cosa important: la semàntica no és estrictament superior en tot. Per a codis d'error exactes o noms de funcions de l'API de Nubelia, la cerca literal és difícil de batre. Per això molts sistemes madurs fan servir cerca híbrida (combinar totes dues) — en tenim prou de saber que existeix; per a DocuBot, la semàntica pura cobreix la gran majoria de preguntes de suport, que arriben escrites amb les paraules de l'usuari, no amb les de la documentació.

Un error freqüent és assumir que el model d'embeddings "ve amb" el LLM. Són decisions independents: DocuBot pot generar respostes amb el model mitjà triat a 01-03 i embeddir amb un model d'un altre proveïdor. Els criteris d'elecció:

I una regla d'or que convé tatuar-se: els vectors de models diferents no són comparables entre si. Si demà canvies de model d'embeddings, tots els vectors del corpus queden obsolets i cal re-embeddir-ho tot. Per això MODEL_EMBEDDINGS és una constant amb env var, i per això la ingesta de 04-03 serà re-executable.

A 03-04 vam construir CacheRespostes: un cache exacte per hash SHA-256 de la pregunta normalitzada, amb TTL. I en vam anunciar la limitació: "com restableixo la contrasenya?" i "he oblidat el meu password, què faig?" generen hashos diferents → dues crides al LLM per a la mateixa resposta. Amb el que hem après avui, la solució és directa: cachejar també el vector de cada pregunta i, abans de cridar el LLM, comprovar si alguna pregunta cachejada és prou semblant:

Punts de disseny que mereixen atenció:

• El llindar és la decisió crítica. Amb 0.92 exigim preguntes gairebé equivalents. Si el baixes a 0.80, estalvies més crides però t'arrisques a servir la resposta de "com convido un membre?" a qui va preguntar "com elimino un membre?" — preguntes temàticament properes però amb respostes oposades. Un fals positiu en un cache és pitjor que cent misses: l'usuari rep una resposta incorrecta amb tota la confiança. Calibra'l amb el conjunt d'avaluació de 02-04, començant conservador.
• Continua havent-hi cost: cada consulta al cache embedeix la pregunta (una crida barata a l'API d'embeddings). L'estalvi net ve d'evitar la crida cara al LLM. Amb els preus relatius de preus.py (03-04), el compte surt molt a favor.
• La cerca dins del cache és força bruta — recorre totes les entrades. Per a un cache de centenars de preguntes és perfectament vàlid; és el mateix patró de cercar() d'aquesta lliçó. (I sí: si el cache creixés a milions d'entrades, necessitaria el mateix que el corpus — una base vectorial. Tot connecta.)
• La invalidació es manté: quan Nubelia publica documentació nova, el cache es buida, exactament com vam decidir a 03-04.

• Comparar vectors de models diferents. Dona números sense sentit, sense error visible. Fixa el model amb MODEL_EMBEDDINGS i tracta'l com a part de l'esquema de les teves dades.
• Interpretar la similitud com a probabilitat universal. Un 0.75 no vol dir "75% rellevant": l'escala depèn del model. Compara sempre dins del mateix model, i calibra llindars empíricament amb el teu conjunt d'avaluació.
• Oblidar input_type (en models que ho suporten): embeddir preguntes com si fossin documents degrada la recuperació de manera silenciosa.
• Embeddir text a text en bucle. Les APIs accepten lots; embeddir d'un en un multiplica la latència i de vegades el cost. Reserva el bucle per a la pregunta de l'usuari (que arriba d'una en una, inevitablement).
• Llindar de cache semàntic massa generós. Comença en 0.90+, mesura falsos positius amb casos del tipus "preguntes semblants amb resposta diferent" (els adversarials suaus de 02-04 són bons candidats) i baixa només amb evidència.
• Consell: desa al costat de cada vector el text que el va originar. Un vector sense el seu text és irrecuperable — no hi ha operació "des-embeddir".

1. Top-k amb llindar mínim. Modifica cercar() perquè accepti un paràmetre llindar_minim i descarti els fragments amb similitud per sota, encara que això deixi menys de k resultats. Prova-la amb la pregunta "puc pagar amb criptomonedes?" (que no té resposta al mini-corpus) i observa què retorna.
2. Keyword vs. semàntica. Implementa una funció cercar_keywords(pregunta, k) que puntuï cada fragment per nombre de paraules en comú amb la pregunta (ignorant majúscules i paraules de menys de 4 lletres). Compara-la amb cercar() per a les preguntes "no puc entrar al meu compte" i "token de l'API": quina guanya en cada cas i per què?
3. Calibrar el cache semàntic. Amb CacheSemantic, desa la resposta a "com restableixo la contrasenya?" i prova de recuperar-la amb: (a) "he oblidat el meu password, què faig?", (b) "com canvio la contrasenya?", (c) "com convido un usuari?". Prova llindars 0.80, 0.90 i 0.95 i anota en una taula quines combinacions encerten i quines produeixen falsos positius.

1. N'hi ha prou de filtrar abans de tallar:

Amb "puc pagar amb criptomonedes?" i un llindar raonable (p. ex. 0.5), la llista queda buida o gairebé: no hi ha documentació rellevant, i retornar una llista buida és més honest que retornar soroll. Guarda't aquesta idea — a 04-04 serà la peça que dispararà la frase anti-al·lucinació de SYSTEM_DOCUBOT ("No trobo aquesta informació a la documentació disponible.") quan la recuperació no trobi res digne.

2. Una versió mínima:

Resultat esperat: per a "no puc entrar al meu compte", cercar_keywords empata gairebé tot a 0-1 coincidències (només "compte" ajuda, i apareix en diversos fragments) mentre que la semàntica encerta de ple. Per a "token de l'API", la keyword guanya o empata: "token" i "API" són termes exactes que apareixen literalment al fragment correcte. Conclusió: la semàntica domina en llenguatge natural d'usuari; la literal continua sent forta en terminologia exacta.

3. Resultats típics (els teus variaran segons el model):

Amb 0.95 el cache gairebé no estalvia; amb 0.80 encerta més però el marge de seguretat davant de parells "semblants amb resposta diferent" s'estreny. 0.90 sol ser el compromís inicial raonable — i la xifra definitiva ha de sortir de mesurar sobre el conjunt d'avaluació, no d'aquest exercici.

Avui els embeddings han deixat de ser una metàfora de 01-02 per convertir-se en tres funcions que caben en una pantalla: embed() converteix text en coordenades de significat, similitud_cosinus() mesura l'angle entre dues d'aquestes coordenades, i cercar() troba els top-k fragments de la documentació de Nubelia més propers a qualsevol pregunta — inclosa "no puc entrar", que no comparteix ni una paraula amb la resposta que necessita. Hem vist per què això supera la cerca per paraules clau (i quan no), quins criteris pesen en triar model d'embeddings (independent del LLM, amb els seus vectors incompatibles entre models), i hem cobrat el regal promès a 03-04: CacheSemantic, que reconeix preguntes equivalents per significat amb un llindar calibrat amb cura. Però la nostra cerca té dues vergonyes que hem escombrat sota la catifa: compara la pregunta contra tots els vectors a cada consulta, i aquests vectors viuen en una llista de Python que desapareix en reiniciar el procés — amb centenars de pàgines de documentació real, cap de les dues coses no és acceptable. Resoldre totes dues és la feina de les bases de dades vectorials, i és exactament el que construïm a la lliçó següent (04-02).