Embeddings, magatzems vectorials i interpretació de les puntuacions de similitud
Converteix els fragments en vectors, desa'ls a Chroma i aprèn a interpretar les puntuacions de similitud.
La part 3 t'ha deixat fragments. Els fragments són text, i el text no es pot comparar aritmèticament. Aquesta part fa de pont: converteix aquests fragments en nombres, posa els nombres en algun lloc on els puguis cercar i després —la part en què gairebé tothom s'equivoca la primera vegada— t'ensenya a interpretar els nombres que en tornen.
En el model mental de la part 1, treballes exactament en quatre caselles:
ASCII original
PHASE A — INDEX Load → Split → [Contextualize] → [EMBED] → [STORE + INDEX] PHASE B — QUERY Gate → Cache → [EMBED QUERY] → [RETRIEVE] → Fuse/Filter → …
Dues d'aquestes caselles són a la fase fora de línia i es paguen una sola vegada. Dues són a la fase en línia i es paguen en cada petició. A totes dues hi ha d'haver el mateix model d'embeddings: aquest és l'invariant 2, i és la regla que sosté aquesta part. La resta és mecànica.
Font: capítols 6, 7 i 8 del curs, 00:48:12 – 01:24:32: un capítol teòric amb moltes diapositives, el primer capítol pràctic de tot el curs i un capítol molt breu que en realitat són dues lliçons enganxades.
Un model d'embeddings no és un model de xat
L'instructor obre el capítol 6 destacant «aquesta distinció tan crucial que confon molta gent» 00:48:13, i fa bé de fer-ho. Tots dos es troben darrere del mateix objecte client d'OpenAI, tots dos es facturen per token i tots dos s'anomenen «models». No són intercanviables en cap dels dos sentits.
| Model de xat | Model d'embeddings | |
|---|---|---|
| Entrada | una conversa (messages=[{role, content}]) | una cadena de text simple (input="…") |
| Sortida | text que pots llegir | una llista de nombres de coma flotant |
| Interfície de l'SDK | client.chat.completions.create(...) | client.embeddings.create(...) |
| Model d'exemple | gpt-4o-mini | text-embedding-3-small |
| D'on es llegeix el resultat | response.choices[0].message.content | response.data[0].embedding |
| Es pot substituir més endavant? | Sí, lliurement | No: vegeu «La regla» més avall |
00:49:14 — «Per tant, mateixa empresa, model diferent.»
El recurs didàctic del capítol és deliberadament mínim: escriu la demostració del xat, l'executa, la comenta, descomenta la demostració d'embeddings que té just a sota i l'executa. Canvien tres línies. El tipus de sortida canvia completament.
# Reconstructed from the ch.6 narration [00:49:14]–[00:51:16].
# NOT a checked-in repo file — the instructor types this into a scratch buffer.
from openai import OpenAI
client = OpenAI()
# --- demo 1: CHAT model ---
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "What is the capital of France?"}],
)
print(response.choices[0].message.content) # -> "The capital of France is Paris."
# --- demo 2: EMBEDDING model (the chat block above gets commented out) ---
response = client.embeddings.create(
input="Your text string goes here",
model="text-embedding-3-small",
)
print(response) # full object: vector + metadata
print(response.model) # "text-embedding-3-small"
print(response.object) # "list"
print(response.usage) # prompt_tokens / total_tokens
print(len(response.data[0].embedding)) # 1536
Hi ha tres coses en aquest segon bloc que valen més del que sembla.
len(response.data[0].embedding) → 1536. Aquesta és tota la definició de dimensió, presentada com una mesura pràctica en lloc d'un punt d'una diapositiva 00:51:16. La dimensió de text-embedding-3-small és 1536 perquè la llista que retorna té una longitud de 1536 nombres de coma flotant. No té cap misteri.
response.usage conté prompt_tokens i total_tokens. Les crides d'embeddings es facturen per tokens exactament igual que les de xat 00:50:14. La gent interioritza que «el xat costa diners» i, d'alguna manera, assumeix que els embeddings són gratuïts. No ho són i —com veurem més avall— els pagues dues vegades: una per fragment en el moment de la indexació i una per pregunta per sempre més.
Per què nombres? Perquè els nombres es poden comparar matemàticament i el text no 00:51:16. Pots calcular una distància entre dos vectors. No pots calcular una distància entre dues frases en anglès. Tot el que ve després —cerca per similitud, llindars, reranking, fusió— només existeix perquè la representació s'ha convertit en aritmètica.
00:51:16 — «Perquè els nombres es poden comparar matemàticament amb facilitat.»
Triar la dimensió
Més dimensions vol dir més espai per emmagatzemar trets d'allò de què has generat l'embedding: més significats, més semàntica, més matisos distingibles 00:52:18. Això és l'únic que millora quan la xifra puja. Tres coses empitjoren.
00:54:20 — «Més dimensions equival a captar més matisos semàntics. Però també a més emmagatzematge i una cerca més lenta.»
La taula de referència. Observa que les dimensions provenen de les diapositives 00:52:18–00:53:19 i els preus provenen d'un bloc de comentaris al començament de embeddings.py del repositori: l'instructor no diu mai cap preu en veu alta, de manera que has de considerar que la columna monetària prové del repositori i contrastar-la amb les tarifes actuals del proveïdor abans de citar-la a ningú.
| Model | Dimensions | Cost / 1M de tokens | Més adequat per a |
|---|---|---|---|
text-embedding-3-small | 1536 | $0.02 | Ús general: l'opció predeterminada del curs |
text-embedding-3-large | 3072 | $0.13 | Precisió elevada (6.5× el preu) |
text-embedding-ada-002 | 1536 | $0.10 | Llegat: avui no hi ha cap motiu per triar-lo |
| Model d'embeddings de Gemini | 768 | pla gratuït | «una mica petit, però la bona notícia és que és gratuït» |
| BGE-small | 384 | local / gratuït | Molt petit; hi predominen la velocitat i el baix consum de recursos |
all-MiniLM-L6-v2 (Sentence-Transformers) | 384 | local / gratuït | El representant de la categoria de 384 dimensions al repositori |
Dos advertiments honestos sobre aquesta taula. Primer, l'instructor esmenta BGE-small a la diapositiva de 00:53:19, però el repositori inclou sentence-transformers/all-MiniLM-L6-v2: tots dos tenen 384 dimensions i són models oberts petits habituals, però no són el mateix checkpoint; no deixis que la taula de la mateixa guia doni a entendre que sí. Segon, diu «embeddings de Gemini, 768 dimensions» sense especificar mai una cadena de versió. Google ha publicat tant text-embedding-004 amb 768 com gemini-embedding-001 amb dimensions configurables; per tant, resisteix la temptació d'omplir un identificador de model que la font mai no va donar.
El procediment de decisió, en l'ordre en què realment l'hauries d'aplicar:
- Tria per defecte la franja de 768–1536. Atura't aquí tret que s'apliqui algun dels supòsits següents.
- Necessites la màxima fidelitat semàntica i pots pagar l'emmagatzematge i la latència per consulta indefinidament?
→ 3072 (text-embedding-3-large), a 6.5× el preu per token.
- El cost és la restricció determinant o vols un pla gratuït? → 768 (Gemini).
- Hi predominen el consum de recursos i la velocitat, i la semàntica és senzilla? → 384 (BGE-small,
all-MiniLM-L6-v2 o un altre model local).
- En tots els casos: decideix a partir de la teva càrrega de treball, no d'una classificació. El que es repeteix durant
tot el capítol és «depèn dels casos d'ús».
Aquest és el fitxer real del repositori. És curt, consisteix sobretot en un comentari i el comentari és la part més citable, però també conté tres paranys diferents; per tant, llegeix les anotacions abans de copiar-lo.
# /home/oriol/lab/rag/code/production-course-main-code/embeddings.py (lines 1-17, verbatim)
# Model Dimensions Cost per 1M tokens Best For
# text-embedding-3-small 1536 $0.02 General use
# text-embedding-3-large 3072 $0.13 High accuracy
# text-embedding-ada-002 1536 $0.10 Legacy
from langchain_openai.embeddings import OpenAIEmbeddings
from langchain_community.embeddings import HuggingFaceEmbeddings
from dotenv import load_dotenv
load_dotenv()
embeddings = HuggingFaceEmbeddings(model_name="sentence-transformers/all-MiniLM-L6-v2") # 384 dimensions
# Ollama
from langchain_ollama import OllamaEmbeddings
embeddings = OllamaEmbeddings(model="llama2-7b-embedding-q4_0")
La resta del fitxer —comentada al repositori— és l'API de LangChain de dos mètodes que faràs servir durant la resta d'aquesta guia:
# /home/oriol/lab/rag/code/production-course-main-code/embeddings.py, lines 33-51,
# with one leading "#" stripped from each line. Otherwise unchanged.
embeddings = OpenAIEmbeddings(model="text-embedding-3-small")
# single text
text = "This is a sample text to be embedded."
embedding = embeddings.embed_query(text)
# print(f"Embedding for single text: {embedding}")
print(len(embedding)) # Should print 1536 for text-embedding-3-small
# multiple texts
embeds = embeddings.embed_documents(
["This is the first document.", "This is the second document."]
)
print(f"Embeddings for multiple texts: {embeds}")
print(f"Number of embeddings returned: {len(embeds)}") # Should print 2
print(
f"Length of each embedding: {len(embeds[0])}"
) # Should print 1536 for text-embedding-3-small
embed_query és per a la pregunta individual al camí de lectura. embed_documents rep una llista i retorna un vector per element en un sol intercanvi de xarxa: és el mètode que vols en indexar, i la distinció importa més endavant quan fas servir memòria cau, perquè CacheBackedEmbeddings desa a la memòria cau embed_documents i deixa embed_query sense memòria cau tret que ho demanis (part 9). Observa també que aquest bloc associa el nom embeddings una tercera vegada: si simplement el descomentes al mateix lloc, queda per sota de les dues associacions actives al començament del fitxer i s'imposa silenciosament. Elimina les que no facis servir.
Què et permeten els nombres: ordenar per similitud del cosinus
Abans de lliurar els vectors a una base de dades, val la pena fer la cerca a mà una vegada. Trenta línies de numpy contenen tota la idea de la cerca semàntica, sense cap magatzem, índex ni abstracció entremig.
# /home/oriol/lab/rag/code/production-course-main-code/embeddings_deep.py (lines 35-65)
def similarity_search():
docs = [
"Python is a programming language",
"JavaScript is used for web development",
"Machine learning enables AI applications",
"Deep learning uses neural networks",
"Cats are popular pets",
]
query = "What programming languages exist?"
# embed documents and query
doc_vector = embeddings_model.embed_documents(docs)
query_vector = embeddings_model.embed_query(query)
# compute cosine similarities
def cosine_similarity(vec1, vec2):
return np.dot(vec1, vec2) / (np.linalg.norm(vec1) * np.linalg.norm(vec2))
similarities = [cosine_similarity(query_vector, doc_vec) for doc_vec in doc_vector]
# rank documents by similarity
ranked_docs = sorted(zip(docs, similarities), key=lambda x: x[1], reverse=True)
print(f"Query: {query}\n")
print("Ranked by similarity:")
for doc, score in ranked_docs:
print(f" {score:.4f}: {doc}")
Llegeix què fa realment una base de dades vectorial, en quatre línies: genera els embeddings del corpus, genera el de la consulta, puntua cada parella i ordena de manera descendent. Un magatzem vectorial de producció hi afegeix un índex perquè no hagis de puntuar totes les parelles, a més de persistència, filtratge i concurrència, però la semàntica que implementa és la de més amunt.
Observa la polaritat aquí: aquesta funció ordena amb reverse=True, perquè en la similitud del cosinus com més alt, millor. Retingues aquesta idea; Chroma està a punt de donar-te la convenció contrària.
Hi ha una altra cosa d'aquest fitxer que val la pena adoptar encara que no s'executi. basic_embeddings() mostra tres dades d'un vector acabat d'obtenir: la longitud, els cinc primers valors i np.linalg.norm(...). És la comprovació mínima de «què he rebut realment», i la tercera sortida és la interessant: si la norma retorna ≈1.0000, el proveïdor et lliura vectors de longitud unitària, i en aquest cas la similitud del cosinus i un simple producte escalar són el mateix nombre, i la divisió de cosine_similarity no fa res. No ho donis per fet: mostra-ho. Els proveïdors difereixen, i un proveïdor que no normalitzi farà que la teva drecera del producte escalar sigui incorrecta sense avisar.
Les dues fases, reformulades de manera concreta
Aquest és l'eix del capítol 6 00:54:20–00:56:23, i és el mateix model de dues fases de la part 1 amb les caselles emplenades.
Fase 1 — Indexació. Es fa una vegada per conjunt de documents.
- Carrega els documents.
- Divideix-los: «posem de 500 a 1,000 tokens cadascun» 00:54:20.
- Genera l'embedding de cada fragment amb el model d'embeddings que has triat.
- Emmagatzema el resultat.
El que arriba realment al magatzem no són només els vectors: «tenim els vectors reals, els embeddings, el text original i tot això» 00:55:23. El vector, el text original del fragment i les seves metadades viatgen junts. Això importa perquè el pas 3 de la fase de consulta necessita el text, no els nombres. Al final de la indexació, el magatzem conté milers de vectors, cadascun dels quals representa un fragment.
(L'instructor fa servir «magatzem vectorial» i «base de dades vectorial» indistintament i ho diu explícitament. Aquesta guia fa el mateix.)
Fase 2 — Consulta. Es fa per a cada pregunta, per a totes les preguntes.
- Genera l'embedding de la consulta —«el mateix model d'embeddings: això és important» 00:55:23— per obtenir
un vector de consulta.
- Cerca vectors similars al magatzem.
- Recupera: «el procés d'obtenir els fragments de text originals d'aquests vectors».
- Amplia: combina prompt de sistema + fragments recuperats + consulta de l'usuari 00:55:23.
- Genera: envia el prompt muntat a un model de xat i retorna la resposta.
El pas 4 és l'«A» de RAG, i és més específic del que se sol dir. L'ampliació consisteix exactament en tres ingredients fusionats en un prompt 00:55:23. No hi ha reentrenament, ni fine-tuning, ni actualització de pesos: «ampliem el coneixement del gran model de llenguatge amb els documents que hem recuperat» 00:56:23, en preparar el prompt, per a una sola petició, i després desapareix.
I l'asimetria que es desprèn de posar les dues fases de costat:
La generació d'embeddings durant la indexació és un cost únic per lots que amortitzes. La generació d'embeddings durant la consulta es paga per cada pregunta, per sempre. Per tant, la tria de la dimensió té més impacte en consultar: un model de 3072 dimensions no és «el doble d'emmagatzematge», sinó el doble d'emmagatzematge i un vector més lent al camí crític de cada petició.
La solució per a la meitat recurrent és la memòria cau, que el curs situa a embeddings_deep.py::embedding_caching() —CacheBackedEmbeddings.from_bytes_store sobre un LocalFileStore— i que aquesta guia cobreix degudament a la part 9. Tres coses que has de saber ara per no adquirir un hàbit equivocat:
- A LangChain 1.x, tots dos símbols es troben a
langchain_classic, no alangchain:
from langchain_classic.embeddings.cache import CacheBackedEmbeddings i from langchain_classic.storage import LocalFileStore. Tots els tutorials antics que trobaràs els importen des del paquet de nivell superior langchain i et donaran un ImportError.
CacheBackedEmbeddingsompledocument_embedding_cache, és a dir, desa a la memòria cau
embed_documents i deixa embed_query sense memòria cau tret que també passis query_embedding_cache=. El repositori només passa el primer, de manera que el camí d'indexació té memòria cau i el de consulta, el que realment pagues en cada petició, no.
- L'argument
namespace=hauria de ser l'identificador del model d'embeddings. El repositori passa
namespace="exercise", que és una etiqueta, no una identitat: canvia de model sota un espai de noms compartit i la memòria cau et continuarà servint vectors de l'antic sense cap problema. És exactament la fallada de què tracta la secció següent, amb una memòria cau afegida per amagar-la.
La regla que no pots trencar mai
Tot el que hem vist en aquesta part ens ha conduït fins aquí.
Hi ha dos mecanismes diferents que el fan fallar, i fallen de maneres molt diferents:
| Fallada | Causa | Símptoma |
|---|---|---|
| Incompatibilitat de dimensions | Vector de consulta de 1536 dimensions contra vectors emmagatzemats de 768 dimensions | Evident. Les operacions matemàtiques no es poden aplicar; obtens una excepció. |
| Mateixa dimensió, model diferent | Per exemple, ada-002 (1536) en indexar, 3-small (1536) en consultar | Silenciosa. Res no dona error. Els dos models no comparteixen sistema de coordenades; per tant, les distàncies no tenen sentit i obtens disbarats plausibles. |
La segona fila és la perillosa, i és la que ningú no comprova. Tots dos models produeixen 1536 nombres de coma flotant. Totes dues crides tenen èxit. La cerca retorna els k documents sol·licitats. L'LLM escriu una resposta fluida. L'únic que falla és que la resposta no té res a veure amb la pregunta, i no hi ha cap excepció en tota la traça. És l'invariant 4 —les fallades són silencioses— en la seva forma més pura.
00:57:25 — «Si canvies de model, els vectors no seran comparables. Per tant, aquesta cerca fallarà.»
Aquest advertiment es repeteix tres vegades en un sol capítol de tretze minuts (00:55:23, 00:56:23, 01:00:26). És la frase més repetida de l'hora.
I l'asimetria que ho fa contraintuïtiu: el model de generació es pot substituir completament. «GPT-4, GPT-5, GPT-10, Claude, és igual» 00:56:23. Pots canviar d'LLM un dimarts a la tarda amb una importació i una cadena de model. El model d'embeddings no es pot canviar sense tornar a generar l'embedding de tots els fragments que tens. Els enginyers que han interioritzat que «els models són intercanviables» pel que han après amb el xat traslladen aquest hàbit als embeddings i destrueixen un índex.
La manera de fer complir la regla és una pauta d'estil de codi d'una línia. Tant vector_stores.py com rag_pipeline.py declaren el model exactament una vegada, a nivell de mòdul, i no escriuen mai directament una cadena de model al punt d'una crida:
# /home/oriol/lab/rag/code/production-course-main-code/vector_stores.py:11
# (identical line at rag_pipeline.py:22)
embeddings_model = OpenAIEmbeddings(model="text-embedding-3-small")
Aquesta única assignació es passa després a Chroma.from_documents(...) en indexar i es reutilitza a tots els camins de consulta del mòdul. Si qui escriu vol extreure una sola lliçó de codi del capítol 6, és aquesta: declara el model d'embeddings una sola vegada, com a constant de nivell de mòdul, i no escriguis mai directament la cadena del model al punt d'una crida. En un sistema real, porta-ho més enllà: una variable d'entorn i una asserció a l'arrencada que comprovi que l'identificador de model registrat a la col·lecció coincideix amb el configurat.
Les tres regles de producció que se'n deriven
Directament de la diapositiva de 00:59:26:
- Fes servir el mateix model d'embeddings a tot arreu. Indexació i consulta, models idèntics,
amb la versió inclosa.
- Qualitat dels embeddings > quantitat. «Uns embeddings millors sobre menys documents superen uns embeddings
pitjors sobre més documents.» Un argument directe contra l'impuls de corregir una recuperació dolenta abocant més dades a l'índex.
- Prova la recuperació per separat. Abans de culpar l'LLM, mostra quins documents s'han
retornat.
Aquesta tercera regla ve acompanyada de la xifra que la justifica:
00:59:26 — «El 90% de les fallades de RAG són fallades de recuperació, no de generació.»
Com la xifra de «el 90% dels sistemes RAG fallen en producció» de la part 1, és una afirmació de camp sense citació: no s'aporta cap estudi, conjunt de dades ni metodologia. Considera la xifra retòrica i l'ordre correcte: quan una resposta RAG és incorrecta, inspecciona els fragments recuperats abans de tocar el prompt o el model. I hi ha un sostre al progrés dels models que cap versió futura no elimina:
00:59:26 — «Si recuperes els documents equivocats, ni GPT 100 et pot salvar.»
El camí correcte i l'incorrecte
L'exemple resolt és deliberadament quotidià. Consulta: «Quina és la política de reemborsament?»
El camí correcte 00:58:25: el vector de consulta capta el significat de «política de reemborsament»; la cerca vectorial troba fragments sobre devolucions, reemborsaments, retorn dels diners, inclosos els que no comparteixen cap terme amb la consulta, perquè «tot gira al voltant del significat real, no només de la paraula clau»; es recupera el text rellevant; l'LLM rep context real; l'usuari obté una resposta precisa. Aquesta correspondència «retorn dels diners» ↔ «política de reemborsament» és tota la proposta de valor de la cerca semàntica respecte de la cerca per paraules clau.
El camí incorrecte 00:58:25–00:59:26: el vector de consulta no capta bé el significat; la cerca retorna fragments aleatoris; l'LLM rep context irrellevant; l'usuari obté una resposta incorrecta o una al·lucinació.
Observa també què fa aquesta reformulació amb l'al·lucinació. Al capítol 6 no és un defecte del model, sinó el símptoma posterior d'una recuperació dolenta. «L'LLM només pot treballar amb el que li dones» 00:59:26. Això és el que fa aplicable la regla 3: l'al·lucinació es converteix en un error de recuperació que pots reproduir i mesurar, en lloc d'una propietat misteriosa del model.
I la cadena causal que connecta aquesta part amb la part 3 (invariant 1: la qualitat s'hereta cap endavant i mai no es recupera en les etapes posteriors):
00:57:25 — «Un chunking dolent portarà a embeddings dolents, i això portarà a un RAG que no funciona.»
00:59:26 — «Embeddings inútils equival a recuperació inútil, que equival a respostes inútils.»
El model d'embeddings no té criteri. Codifica fidelment tot allò que li lliures. Si li lliures mitja secció d'OAuth, obtens un vector perfecte, segur i ben format de mitja secció d'OAuth.
El diagrama del flux de treball de Chroma: el model de referència per a qualsevol base de dades vectorial
El capítol 7 dedica els primers set minuts 01:01:06–01:08:15 a un sol diagrama, i l'instructor és explícit que aquesta és la part que cal recordar:
01:07:13 — «aquesta és la lliçó… a la qual sempre hauríeu de tornar… per entendre qualsevol base de dades»
No hi ha captures de pantalla d'aquest capítol (l'índex del curs inclou 01:01:05 a «capítols sense captura de pantalla»), de manera que aquí en tens l'estructura en text.
Dues capes. La capa d'aplicació superior conté exactament tres coses visibles: la consulta entrant, la finestra de context de l'LLM i la resposta que surt 01:02:08. Aquí dalt no hi ha res relacionat amb vectors. La capa de Chroma DB inferior «emmagatzema i gestiona embeddings»: documents, ja fragmentats, al costat dels seus vectors.
El pas obligatori de traducció al mig. Entre totes dues hi ha «gen embedding». No pots interactuar de cap manera amb una base de dades vectorial fins que la consulta s'ha transformat en un vector, perquè l'embedding és «el format, el llenguatge que necessita» la base de dades 01:03:08. La consulta no s'envia mai com a text.
La resta d'afirmacions del diagrama, que convé tenir en una sola llista:
- L'emmagatzematge és un mitjà, mai l'objectiu. 01:02:08 — «No deses dades només pel
fet de desar-les.» El material emmagatzemat existeix per passar-lo per la finestra de context d'un LLM amb la consulta de l'usuari.
- «Documents» representa qualsevol tipus de dades 01:02:08, incloses les dades no estructurades.
Es fa servir text pla perquè permet fer una demostració clara.
- Les consultes solen ser text, però la modalitat no és fixa: «simplement text, veu o
el que sigui» 01:03:08. En qualsevol cas, tot acaba convertit en un vector.
contingut d'aquell document en forma de vector.
- La recuperació es basa en la distància entre vectors, no en la coincidència de paraules clau 01:04:09.
- Un registre emmagatzemat conté més que el vector. Els documents es troben al magatzem «en forma
d'embeddings, que són vectors que poden contenir una mica més d'informació que els vectors en si» 01:01:06. Concretament: {id, embedding, document text, metadata}. La demostració pràctica ho confirma: el resultat de la consulta retorna identificadors, documents i distàncies.
- L'LLM fa tres coses amb el material recuperat 01:04:09: obté informació
relacionada, interpreta la intenció de la consulta i genera text nou a partir de patrons apresos. No es limita a donar format: pot ampliar el context recuperat, i precisament per això el patró de prompt contra les al·lucinacions de la part 1 no és opcional.
- La resposta és context *més* coneixement paramètric, no només context. 01:07:13 —
el model, «perquè té el seu coneixement», és qui sap com processar el material recuperat. Aquest és el mecanisme que hi ha darrere del punt anterior, i és el motiu pel qual un fragment incorrecte no produeix una resposta òbviament incorrecta: el model té prou coneixements previs propis per dissimular el buit i lliurar-te una cosa fluida.
algun context proporcionat per la base de dades Chroma». Es planteja com un requisit innegociable.
- Dos camins possibles després de generar l'embedding de la consulta 01:05:12: comparar-lo amb els embeddings
emmagatzemats per trobar documents rellevants (RAG normal) o bé anar directament a l'LLM (el cas degenerat sense recuperació, que convé anomenar perquè el mecanisme de decisió de la part 12 fa que aquest camí sigui deliberat en lloc d'accidental).
- Per què això supera la cerca per paraules clau 01:06:12: el sistema pot «entendre i processar
consultes complexes amb més precisió que els sistemes tradicionals de cerca per paraules clau», produint respostes rellevants en el context i semànticament riques. Pren aquesta afirmació amb prudència: la part 6 mostra exactament on la cerca vectorial pura perd davant de la cerca per paraules clau (codis de producte, identificadors, cadenes exactes), i per això existeix la recuperació híbrida.
La generalització és l'objectiu: «en aquest cas només fem servir Chroma, però qualsevol base de dades vectorial, al capdavall, necessita interactuar amb el món real» 01:07:13. Substitueix Chroma per pgvector, Pinecone, Qdrant o FAISS i el diagrama no canvia. Només canvia l'API del client.
Construeix-ho una vegada a mà: el client directe de chromadb
Ara, la mecànica, sense cap framework entremig. El capítol 7 és el primer capítol pràctic del curs: carpeta buida, un sol fitxer, app.py.
Versions, perquè en quedi constància, ja que no se'n diu cap en veu alta: el repositori del curs fixa requires-python = ">=3.12", inclou chromadb 1.4.1 al fitxer de bloqueig i declara langchain-chroma>=1.1.0, que és l'embolcall del qual depèn el capítol 8 i els següents, i que la part 2 ja t'havia advertit que instal·lessis en lloc de langchain-community per al magatzem vectorial.
Entorn, en totes dues plataformes, exactament com es narra 01:09:16–01:10:18:
# macOS / Linux
python3 -m venv venv
source venv/bin/activate # confirm the venv is ACTIVE before continuing
pip install chromadb
# Windows
python -m venv myenv # or: py -m venv myenv
myenv\Scripts\activate
pip install chromadbS'adona a mitja ordre que està a punt d'instal·lar a l'entorn global —«abans de fer això… he de crear un entorn virtual» 01:09:16— pel motiu evident:
01:09:16 — «perquè no instal·lis totes aquestes dependències i paquets diferents pertot arreu»
Després, el fitxer mateix. Aquesta és la reconstrucció de la narració (app.py, ~15 línies):
# app.py — reconstructed from the ch.7 narration [01:11:18]–[01:16:27].
# NOT a checked-in repo file. Raw chromadb client — no LangChain, no API key.
import chromadb
chroma_client = chromadb.Client()
collection_name = "test_collection"
collection = chroma_client.get_or_create_collection(name=collection_name)
documents = [
{"id": "doc1", "text": "hello world"},
{"id": "doc2", "text": "how are you today"},
{"id": "doc3", "text": "..."}, # third doc's text is never read aloud
]
query_text = "hello world"
for doc in documents:
collection.upsert(ids=[doc["id"]], documents=[doc["text"]])
results = collection.query(query_texts=[query_text], n_results=3)
print(results)
Fitxer petit, cinc lliçons reals.
1. Una col·lecció és una taula. 01:13:22: l'analogia més clara del capítol. test_collection és el contenidor amb nom que guarda documents, identificadors i embeddings. Si coneixes SQL, la correspondència mental és: client → connexió, col·lecció → taula, document → fila, identificador → clau primària.
2. get_or_create_collection, no create_collection. La documentació del proveïdor ensenya create_collection; ell el substitueix deliberadament 01:11:18–01:12:18 perquè els scripts es tornen a executar constantment durant el desenvolupament i create_collection genera un conflicte quan el nom ja existeix. *(Una correcció de la narració: diu que get-or-create «ho reescriurà tot», cosa que indueix a error. No esborra ni sobreescriu res: retorna la col·lecció existent. La seguretat en sobreescriure prové d'upsert, no d'aquesta crida.)*
3. upsert, mai add. Aquest és l'advertiment principal del capítol 01:13:22. collection.add() no té protecció contra col·lisions d'identificadors, de manera que cada nova execució de l'script afegeix silenciosament una altra còpia de tot el corpus. upsert insereix o actualitza per identificador.
4. L'API de Chroma fa servir llistes a tot arreu. documents=[...], ids=[...], query_texts=[...]: les operacions que semblen singulars també volen llistes. Ho aprèn en directe: l'execució falla amb «got an unexpected keyword argument text» perquè ha escrit text=…; el paràmetre és documents i rep una llista 01:16:27.
La pràctica generalitzable, que val més que la correcció concreta: quan un SDK de Python rebutja un argument amb nom, no n'endevinis el nom; obre la referència de l'API d'aquell mètode exacte i copia'n els noms dels paràmetres.
I un cop has observat que els paràmetres són llistes, observa què fa el bucle: crida upsert una vegada per document amb una llista d'un sol element cada vegada. Tres documents, tres intercanvis de xarxa, tres lots d'embeddings. La mateixa crida accepta tot el corpus —collection.upsert(ids=[d["id"] for d in documents], documents=[d["text"] for d in documents])— d'un sol cop. Amb tres documents és innocu; amb deu mil és la diferència entre una ingesta que triga un minut i una que triga una tarda. Agrupa les escriptures en lots.
5. Les dades del resultat són un diccionari de llistes paral·leles. collection.query(query_texts=[q], n_results=3) retorna identificadors, documents i distàncies com tres matrius alineades 01:16:27, no com una llista d'objectes de registre. n_results és el nombre de resultats que vols rebre («en volem obtenir tres. Podem dir 2, 1, 3, etcètera»). També hi ha un paràmetre query_embeddings per passar vectors precalculats en lloc de text; s'esmenta una vegada i no es fa servir mai enlloc del curs.
I després, l'observació cap a la qual es construeix tota aquesta part. La consulta és "hello world" i el text de doc1 és "hello world", de manera que doc1 es retorna amb una distància de 0:
01:17:29 — «Per tant, com més a prop de zero és, més similars són tots dos.»
Les altres distàncies que llegeix de la sortida són d'aproximadament 0.01 en amunt. Cal assenyalar-ho amb honestedat: aquest 0.01 és ambigu a la transcripció generada automàticament; podria ser 0.0 llegit dígit a dígit i seguit d'un altre nombre independent. No el citis com a exacte. El 0 de la coincidència exacta és inequívoc.
Petits detalls del capítol pràctic que encara fan perdre una hora a molta gent
- **Un subratllat ondulat a
import chromadbdesprés d'una instal·lació correcta = intèrpret equivocat, no un paquet
espatllat.** 01:11:18 Configura VS Code perquè faci servir el Python del teu entorn virtual. No reinstal·lis.
- Llegeix primer la documentació del proveïdor i coneix-ne l'estructura. 01:08:15 Obre expressament
la pàgina «Getting Started» de Chroma i en copia fragments; després en modifica dos (create_collection → get_or_create_collection, add → upsert) perquè la documentació optimitza per a la primera execució i tu optimitzes per a la centèsima.
- Disciplina d'abast. 01:08:15 — «Òbviament, això no és un curs de Chroma DB.» El
diagrama del flux de treball és el que es transfereix entre bases de dades vectorials; els noms dels mètodes, no.
en lloc de python3) i activació (Scripts\activate en lloc de bin/activate).
- Un buit en el material enregistrat. El capítol 8 diu que el magatzem es construeix amb un directori temporal
«com hem fet abans», però persist_directory no apareix mai en pantalla al capítol 7, que feia servir el simple Client() en memòria. Si segueixes els passos i tens la sensació que te n'has perdut un, no és així: aquest pas no es va enregistrar mai.
Torna-ho a construir amb LangChain
El capítol 8 comença amb la mateixa base de dades, una capa d'abstracció més amunt:
01:17:50 — «podeu veure que és molt fàcil quan fem servir l'embolcall de Chroma i LangChain.»
No deixis que la continuïtat et faci pensar que les API són iguals. No ho són:
| Concepte | chromadb directe (cap. 7) | langchain_chroma (cap. 8+) |
|---|---|---|
| Crear + omplir | collection.upsert(ids=[…], documents=[…]) | Chroma.from_documents(documents=…, embedding=…, persist_directory=…) |
| La unitat de dades | diccionari {"id": …, "text": …} | Document(page_content=…, metadata={…}) |
| Cerca | collection.query(query_texts=[q], n_results=N) | vectorstore.similarity_search(q, k=N) |
| Cerca amb puntuacions | distàncies al diccionari del resultat | similarity_search_with_score(q, k=N) → tuples |
| Qui genera els embeddings | El model predeterminat inclòs a Chroma | l'objecte embedding= que passes |
Aquesta última fila és la important. Amb LangChain proporciones el model d'embeddings explícitament, i això és el que et torna a fer complir la regla.
El corpus de totes les demostracions restants d'aquesta part és un conjunt de prova de 8 documents. Val la pena copiar-lo literalment a les teves pròpies proves, perquè els valors de topic estan dissenyats perquè la demostració de filtratge produeixi un resultat interessant.
SAMPLE_DOCS — el conjunt de prova de 8 documents (vector_stores.py:14-47)
# /home/oriol/lab/rag/code/production-course-main-code/vector_stores.py, lines 1-47, verbatim
from langchain_openai.embeddings import OpenAIEmbeddings
from langchain_chroma import Chroma
from langchain_core.documents import Document
from langchain_text_splitters import RecursiveCharacterTextSplitter
import tempfile
import shutil
from dotenv import load_dotenv
load_dotenv()
embeddings_model = OpenAIEmbeddings(model="text-embedding-3-small")
# Sample documents
SAMPLE_DOCS = [
Document(
page_content="LangChain is a framework for developing applications powered by language models.",
metadata={"source": "langchain_docs", "topic": "overview"},
),
Document(
page_content="LangGraph is a library for building stateful, multi-actor applications with LLMs.",
metadata={"source": "langgraph_docs", "topic": "overview"},
),
Document(
page_content="Vector stores are databases optimized for storing and searching embeddings.",
metadata={"source": "vector_guide", "topic": "database"},
),
Document(
page_content="RAG combines retrieval with generation for more accurate LLM responses.",
metadata={"source": "rag_guide", "topic": "architecture"},
),
Document(
page_content="Embeddings convert text into numerical vectors for semantic similarity.",
metadata={"source": "embeddings_guide", "topic": "fundamentals"},
),
Document(
page_content="Chroma is an open-source embedding database for AI applications.",
metadata={"source": "chroma_docs", "topic": "database"},
),
Document(
page_content="FAISS is a library for efficient similarity search developed by Facebook.",
metadata={"source": "faiss_docs", "topic": "database"},
),
Document(
page_content="Pinecone is a managed vector database service for production workloads.",
metadata={"source": "pinecone_docs", "topic": "database"},
),
]
Distribució de temes: memoritza-la, totes les xifres posteriors en depenen: 4 × database (vector_guide, chroma_docs, faiss_docs, pinecone_docs) · 2 × overview · 1 × architecture · 1 × fundamentals.
Tres notes sobre aquestes nou primeres línies. La importació és langchain_chroma, no langchain_community: la part 2 ho assenyalava com un parany de la instal·lació, i aquest és el fitxer que fa fallar. load_dotenv() s'executa a la línia 9, abans que la línia 11 construeixi el client d'embeddings, que és l'únic ordre que funciona perquè l'SDK llegeix OPENAI_API_KEY de l'entorn del procés en el moment de la construcció. I shutil, a la línia 6, s'importa i no es fa servir mai: és pes mort, no una pista que alguna cosa es netegi automàticament.
La construcció i consulta bàsiques són tres línies de feina real:
# /home/oriol/lab/rag/code/production-course-main-code/vector_stores.py:50-68
def chroma_basics():
with tempfile.TemporaryDirectory() as tmpdir:
# create vector store from documents
vectorstore = Chroma.from_documents(
documents=SAMPLE_DOCS, embedding=embeddings_model, persist_directory=tmpdir
)
print(
f"Vector store created {vectorstore._collection.count()} documents and persisted."
)
# perform similarity search
query = "What is LangChain?"
results = vectorstore.similarity_search(query, k=2)
print(f"Top 2 results for query '{query}':")
for i, doc in enumerate(results):
print(
f"Result {i+1}: {doc.page_content} (Source: {doc.metadata['source']})"
)
Observa l'hàbit de mostrar informació, que es repeteix en totes i cadascuna de les funcions de demostració del fitxer: les metadades source s'afegeixen a cada resultat. No ho comenta mai. Adopta'l igualment.
Tres advertiments sobre la infraestructura auxiliar que el capítol tracta com a codi rutinari: «aquí no hi ha res de nou» 01:17:50:
tempfile.TemporaryDirectory()implica que cada execució torna a generar els embeddings de tot el corpus. Vuit documents
de joguina, de manera que aquí és invisible. Amb un corpus de mida real és una factura d'API i un obstacle de latència en cada execució. Fes servir un persist_directory estable tan bon punt el corpus deixi de ser de joguina.
vectorstore._collection.count()accedeix a un atribut privat. Funciona amb
langchain-chroma 1.1.0, però no és API pública. Prioritza len(vectorstore.get()["ids"]) en el codi que vulguis conservar.
- El bloc
__main__es distribueix amb totes les crides comentades. Aquest és tot el model
d'execució del curs per a aquests fitxers de proves: descomentar una funció, executar i tornar a comentar 01:18:52. Si clones el repositori i no passa res, aquest és el motiu.
La persistència, quan estiguis preparat per fer-la servir, és el mateix objecte amb una ruta real i una inconsistència de noms especialment molesta:
# /home/oriol/lab/rag/code/production-course-main-code/vector_stores.py, lines 153-179.
# Two print statements (lines 164 and 179) elided; everything else is verbatim.
def persist_chroma():
persist_dir = "./chroma_db/"
vectorstore = Chroma.from_documents(
documents=SAMPLE_DOCS,
embedding=embeddings_model,
persist_directory=persist_dir,
)
original_count = vectorstore._collection.count()
print(f"Persisted vector store with {original_count} documents.")
# simulate restart - load from disk
del vectorstore
reloaded = Chroma(
embedding_function=embeddings_model,
persist_directory=persist_dir,
)
reloaded_count = reloaded._collection.count()
print(f"Reloaded vector store with {reloaded_count} documents.")
# verify search still works
results = reloaded.similarity_search("LangChain", k=2)
Les tres últimes línies són tot el sentit de la funció: en reobrir no es passen documents, només el mateix directori i el mateix model d'embeddings, i similarity_search continua funcionant. Això és el que et proporciona «persistent»: els vectors eren al disc, no al procés.
Interpretar les puntuacions: el parany de distància contra similitud
El capítol 8 dura sis minuts i existeix gairebé íntegrament per fer aquesta correcció.
La variant de cerca amb puntuacions rep els mateixos arguments i retorna un tipus diferent:
# /home/oriol/lab/rag/code/production-course-main-code/vector_stores.py:71-87
def similarity_search_with_scores():
with tempfile.TemporaryDirectory() as tmpdir:
# create vector store from documents
vectorstore = Chroma.from_documents(
documents=SAMPLE_DOCS, embedding=embeddings_model, persist_directory=tmpdir
)
# perform similarity search with scores
query = "Explain vector stores."
results_with_scores = vectorstore.similarity_search_with_score(query, k=3)
print(f"Top 3 results with scores for query '{query}':")
for i, (doc, score) in enumerate(results_with_scores):
final_score = 1 / (1 + score) # Convert distance to similarity
print(
f"Result {i+1}: {doc.page_content} (Score: {final_score:.4f}, Source: {doc.metadata['source']})"
)
similarity_search retorna List[Document]. similarity_search_with_score retorna List[Tuple[Document, float]]. Per això la capçalera del bucle canvia de for i, doc in enumerate(results) a for i, (doc, score) in enumerate(results_with_scores). Reutilitzar el cos del bucle sense puntuacions sobre els resultats amb puntuacions llança un AttributeError en una tupla: és la manera més habitual com aquesta API falla als usuaris. (Observa que el nom del mètode és en singular, ..._with_score, mentre que la funció de demostració que l'embolcalla és en plural, ..._with_scores. És fàcil equivocar-s'hi.) El mètode també accepta un argument amb nom where_document= juntament amb filter=: la mateixa idea aplicada al contingut dels fragments en lloc de les metadades, per exemple {"$contains": "OAuth"}. El curs no el fa servir mai; de vegades és la manera més barata d'imposar una restricció de cadena exacta que la cerca vectorial tota sola no respectarà.
Ara, les xifres. Consulta "Explain vector stores.", k=3, i l'execució produeix:
| Posició | Document | Distància original | Després de 1/(1+d) |
|---|---|---|---|
| 1 (millor) | el document de magatzems vectorials (vector_guide) | 0.6612 | ≈ 0.6019 |
| 2 | Pinecone (pinecone_docs) | no es diu en veu alta | — |
| 3 (pitjor) | el document d'embeddings (embeddings_guide) | 1.34 | ≈ 0.4274 |
I l'objecció que l'instructor formula en nom de l'estudiant 01:18:52: per què 0.66 és una puntuació millor que una de superior a 1?
Distància i similitud són dues polaritats oposades sobre la mateixa geometria:
| Distància | Similitud | |
|---|---|---|
| Coincidència perfecta | 0 | 1 |
| Direcció de «millor» | cap avall | cap amunt |
| Interval | 0 → sense límit superior | aproximadament (0, 1] |
| Forma del llindar | if score < T | if score > T |
| Ordenació | ascendent | reverse=True |
01:19:53 — «Si fossin puntuacions de similitud, els uns serien molt similars, oi?»
La conversió. Si vols un nombre normalitzat en què com més alt, millor, una línia ho resol 01:20:55:
final_score = 1 / (1 + score) # distance -> similarity, vector_stores.py:84
Transforma la distància 0 → 1.0, és monòtonament decreixent, acosta les distàncies grans a 0 i conserva exactament l'ordre. Distància 0.6612 → ≈0.6019; distància 1.34 → ≈0.4274.
La polaritat depèn del magatzem i els llindars no es poden traslladar. «Alguns magatzems vectorials sí que calculen la distància de similitud» 01:19:53: és a dir, alguns motors et donen directament una similitud. Passar de Chroma a pgvector, Pinecone o FAISS pot invertir l'operador de comparació que necessites. Per tant, aquest és el procediment pràctic per a qualsevol puntuació que no hagis vist mai:
- Mira el nombre associat al resultat de la primera posició.
- El nombre més petit és a dalt → tens distàncies; com més baix, millor.
- El nombre més gran és a dalt i tendeix a 1 → tens similituds; com més alt, millor.
- Confirma-ho amb la mateixa docstring del mètode, que acostuma a ser explícita. El
Chroma.similarity_search_with_score de LangChain diu, literalment, «distància en coma flotant per a cadascun. Una puntuació més baixa representa més similitud».
- Necessites una rellevància normalitzada entre 0–1? Aplica
1/(1+distance), o estableix l'espai de la col·lecció i
fes servir similarity_search_with_relevance_scores.
- Repeteix els passos 1–4 cada vegada que canviïs de magatzem vectorial. La resposta no és transferible.
És el mateix problema amb què topa a escala industrial la cerca híbrida de la part 6: les puntuacions de BM25 i les vectorials viuen en escales incomparables, i precisament per això la fusió recíproca de rangs descarta les puntuacions i fusiona les posicions.
La variant amb puntuacions també és un instrument de mesura, no només una crida de recuperació. Aquest és l'ús de més valor que té i el capítol no l'esmenta mai. Com que la puntuació és un nombre, pots mantenir fixa la consulta, construir dos magatzems que difereixin exactament en una cosa —segmentador, dimensió, estratègia de contextualització— i comparar-hi les puntuacions amb k=1. Així és precisament com s'avalua el codi de recuperació avançada més endavant al curs: fcc-production-rag-part-6/02_contextual_retrieval.py crida similarity_search_with_score(query, k=1) contra un magatzem original i un de contextualitzat i mostra totes dues puntuacions de costat. La regla 3 («prova la recuperació per separat») deixa de ser un eslògan tan bon punt tens aquest entorn de proves.
Filtratge de metadades: precisió de franc
A 01:20:55, el capítol canvia de tema: «anem a veure el filtratge de metadades, perquè és un altre concepte important que hem de tenir al nostre arsenal». Tracta'l com la segona meitat del capítol, amb la mateixa importància, no com un apèndix. És la manera més barata de millorar la precisió de tota la guia: cap crida addicional a un model, cap latència addicional significativa, un sol argument amb nom més.
La demostració es planteja com una prova A/B controlada: consulta idèntica, k idèntic, una sola variable modificada:
# /home/oriol/lab/rag/code/production-course-main-code/vector_stores.py:90-116
def metadata_filtering():
with tempfile.TemporaryDirectory() as tmpdir:
# create vector store from documents
vectorstore = Chroma.from_documents(
documents=SAMPLE_DOCS, embedding=embeddings_model, persist_directory=tmpdir
)
query = "What databases are available?"
# without metadata filtering
results = vectorstore.similarity_search(query, k=5)
print(f"Results without metadata filtering for query '{query}':")
for i, doc in enumerate(results):
print(
f"Result {i+1}: {doc.page_content} (Source: {doc.metadata['source']})"
)
# with metadata filtering
filter_criteria = {"topic": "database"}
filtered_results = vectorstore.similarity_search(
query, k=5, filter=filter_criteria
)
print(f"\nResults with metadata filtering for query '{query}':")
for i, doc in enumerate(filtered_results):
print(
f"Result {i+1}: {doc.page_content} (Source: {doc.metadata['source']})"
)
El mateix mètode, un argument amb nom addicional. No crides una funció diferent 01:21:56: continua sent similarity_search, amb filter= afegit. Els criteris de filtre són «un objecte o un diccionari»: les claus són noms de camps de metadades adjuntats durant la ingesta, i els valors són la coincidència requerida.
El resultat i la troballa principal:
| Execució | k sol·licitat | Resultats retornats | Què s'ha retornat |
|---|---|---|---|
| Sense filtre | 5 | 5 | 4 documents de database + el document de RAG (topic: architecture) |
filter={"topic": "database"} | 5 | 4 | vector_guide, chroma_docs, faiss_docs, pinecone_docs |
Quatre, perquè exactament quatre dels vuit SAMPLE_DOCS porten topic: "database" 01:22:58. El filtre és un predicat per document que s'avalua com a condició d'admissió al conjunt de candidats: recorre la llista en veu alta a 01:23:59: aquest és database, s'afegeix; aquest és database, s'afegeix; aquest és fundamentals, s'omet; aquest és architecture, s'omet.
El que ha eliminat el filtre és tota la lliçó. Sense filtre, la posició #5 ha anat al document de RAG —«RAG combina recuperació i generació per obtenir respostes més precises dels LLM»—, etiquetat amb topic: architecture. És semànticament proper a «Quines bases de dades hi ha disponibles?»: tracta de la mateixa pila tecnològica, comparteix vocabulari, i la similitud vectorial pura l'ha fet aflorar sense problemes. No respon la pregunta.
La proximitat semàntica no és correcció temàtica. L'embedding diu «proper». L'usuari ha preguntat «quines». Són preguntes diferents i el magatzem vectorial no les pot distingir.
Aquest desajust és la llavor de tot el que hi ha a la part 6: el reranking, la recuperació híbrida i la reescriptura de consultes existeixen perquè el veí més proper a l'espai d'embeddings sovint no és la resposta correcta. El filtratge de metadades és la solució més barata i la primera a què cal recórrer, però només si abans has fet la feina.
Una capa més amunt: el recuperador
vector_stores.py conté una altra funció que el capítol 8 no narra, però que és el pont cap a la part 5; considera-la, doncs, una referència al que vindrà més endavant, no una lliçó:
# /home/oriol/lab/rag/code/production-course-main-code/vector_stores.py — the two retriever
# constructions from as_retriever(), lines 129-133 and 141-145. Print loops elided.
# plain similarity retriever
retriever = vectorstore.as_retriever(
search_type="similarity", search_kwargs={"k": 3}
)
docs = retriever.invoke("How do I build AI applications?")
# MMR retriever — diversity instead of pure proximity
mmr_retriever = vectorstore.as_retriever(
search_type="mmr",
search_kwargs={"k": 3, "fetch_k": 5}, # fetch 5 docs and return 3 diverse
)
mmr_docs = mmr_retriever.invoke("vector databases and embeddings")
as_retriever() embolcalla el magatzem amb la façana lleugera que es va anomenar a la part 1: l'objecte amb què es compon una cadena LCEL. k i filter reapareixen dins de search_kwargs. search_type="mmr" (rellevància marginal màxima) obté fetch_k candidats i retorna k resultats diversos, que és la resposta estàndard a «els meus 5 primers resultats són cinc gairebé còpies del mateix paràgraf». Un ajust realista és fetch_k ≈ 4–10× k; fetch_k=5 sobre un corpus de 8 documents deixa molt poc marge per a la diversitat, de manera que la demostració distribuïda no pot mostrar realment l'efecte.
Llista de comprovació i decisions que cal prendre
Decisions que has de prendre abans de generar cap embedding
| Decisió | Valor predeterminat | Quan cal canviar-lo |
|---|---|---|
| Model d'embeddings | text-embedding-3-small | la qualitat de recuperació mesurada indica el contrari |
| Dimensions | 1536 (franja: 768–1536) | 3072 per precisió a 6.5× el preu; 384 per reduir el consum de recursos |
| On es troba la cadena del model | una constant de nivell de mòdul | mai: això no és negociable |
| Magatzem | Chroma amb un persist_directory real | La part 10 cobreix pgvector/Supabase a escala |
| Esquema de metadades | source + topic com a mínim | afegeix organització client/accés/data/versió abans de la ingesta |
| Espai de distàncies | El l2 predeterminat de Chroma | tria cosine en el moment de crear la col·lecció o mai |
| Polaritat de la puntuació | verifica-la empíricament per a cada magatzem | cada vegada que canviïs de motor |
| Idempotència | ids= explícits / upsert | no confiïs mai que add/from_documents eliminin els duplicats |
Dues d'aquestes files són irreversibles sense tornar a indexar: el model d'embeddings i l'espai de distàncies. Una altra és irreversible sense tornar a fer la ingesta: l'esquema de metadades. Dedica-hi el temps de reflexió i tracta la resta com a ajustable.
Llista de comprovació prèvia
- El model d'embeddings es declara una sola vegada, a nivell de mòdul, i el llegeixen tant el camí d'indexació
com el de consulta. No hi ha cadenes de model escrites directament a les crides enlloc.
- L'identificador i la versió del model es registren dins de la col·lecció, i en arrencar es comprova que
el model configurat coincideixi amb el que es va fer servir per construir la col·lecció. langchain-chroma et proporciona el lloc on desar-ho de franc —collection_metadata= s'escriu a la col·lecció en crear-la—, de manera que no hi ha excusa per tenir un índex de procedència desconeguda:
EMBEDDING_MODEL = "text-embedding-3-small"
vectorstore = Chroma.from_documents(
documents=chunks,
embedding=OpenAIEmbeddings(model=EMBEDDING_MODEL),
persist_directory=PERSIST_DIR,
collection_metadata={"embedding_model": EMBEDDING_MODEL},
)
Cada vegada que la reobris, torna a llegir aquesta clau —vectorstore._collection.metadata["embedding_model"], privada però l'únic accés disponible— i falla de manera evident si no concorda amb EMBEDDING_MODEL. Una fallada a l'arrencada és la versió més barata possible d'aquest error; l'alternativa és descobrir-lo sis mesos després a partir d'una incidència de suport sobre «respostes estranyes».
- La dimensió és dins de la franja de 768–1536, tret que tinguis una mesura que justifiqui el contrari.
- Saps si el magatzem retorna distància o similitud perquè has executat una
consulta i has mirat la xifra del resultat de la primera posició, no perquè ho hagis suposat. Fes-ho una vegada en una prova i deixa que la prova falli si una actualització d'una dependència ho inverteix.
- Cap llindar del codi compara una puntuació sense un comentari que n'indiqui la polaritat i
el magatzem respecte del qual es va calibrar.
- Cada vegada que es mostra un resultat s'inclou
doc.metadata['source']. - Cada document porta tots els camps de metadades pels quals algú podria voler filtrar, inclosos els
de seguretat. No els pots afegir més endavant sense tornar a indexar.
- El codi posterior gestiona
0 ≤ len(results) ≤ k, mai== k. - La ingesta és idempotent: identificadors explícits, semàntica d'
upserti una nova execució que no
duplica el corpus.
- El magatzem és persistent. Cap
TemporaryDirectoryen cap camí que executis més d'una vegada. - Les escriptures s'agrupen en lots. Una crida a
upsert/add_documentsper porció del corpus, no una per
document.
- S'entén que el cost de generar embeddings en consultar és per petició i recurrent, i hi ha un
pla (part 9) per desar-los a la memòria cau, amb l'identificador del model com a espai de noms de la memòria cau.
- Abans de tocar el prompt o canviar l'LLM, has mostrat els fragments recuperats. Regla
3, cada vegada.
01:00:26 — «Qualitat dels embeddings equival a qualitat de RAG. Fes-ho bé o res més no importa.»
La part 5 agafa el magatzem que acabes de construir, l'embolcalla en un recuperador, hi connecta una cadena LCEL i n'obté una resposta real; després t'ensenya a esbrinar per què aquesta resposta és incorrecta.