🔬 धडा 05 — Vector DB बनवा: 70 प्रामाणिक ओळी

📍 तुम्ही इथे आहात: 8 पैकी धडा 05 · मागे: lesson-04-nearest-neighbors · पुढे: lesson-06-chunking-metadata

📦 या ब्रँचमध्ये काय आहे

धडे 01–04, आणि vectordb/vectordb.py चे मार्गदर्शित वाचन — आतापर्यंतचा संपूर्ण course, एका ओळ क्रमांकावर सापडेल असा — आणि तुमच्या पहिल्या भरी.

🧒 5 वर्षांच्या मुलाला समजावल्यासारखे

File उघडा. धड्यांशी जुळणारे तीन क्रमांकित भाग:

TEXT → VECTOR 🔢 (धडा 02): _tokens (lowercase शब्द), embed (प्रत्येक शब्द 256 पैकी एका bucket मध्ये hash करा, तो वाढवा, normalize करा). प्रामाणिक सूचना docstring मध्येच आहे: या function च्या जागी embedding-model call ठेवा आणि बाकी सगळे तसेच राहते. ही एका function ची सीमा म्हणजे industry ची architecture छोट्या रूपात: embedder आणि store ही वेगवेगळी कामे आहेत.
SIMILARITY 📐 (धडा 03): cosine — dot product ची एक ओळ, कारण normalization दारातच झालेले असते (_normalize).
THE DATABASE 🗄️ (धडे 04+06): class MiniVectorDB — rows (id, vector, text, metadata), add() embed करून साठवते, search() म्हणजे metadata filter सह brute-force kNN (all(meta.get(k)==v) — रंगीत stickers ची ओळ; ranking च्या आधी filter करणे का महत्त्वाचे ते धडा 06 समजावतो).

खरे product काय जोडते ते पाहा — आणि त्यातले काहीच संकल्पना बदलत नाही: persistence (आपला exit झाल्यावर विसरतो!), updates/deletes, ANN index (L04), concurrency, replication (k8s शाळा हात हलवून नमस्कार करते 👋).

🗺️ आकृती

flowchart TB
    subgraph file["vectordb/vectordb.py — the map"]
        e["1 🔢 embed()<br/>hash words → 256 dims → normalize<br/>← swap for a model call HERE"]
        c["2 📐 cosine()<br/>one line: dot product<br/>(normalize made it cheap)"]
        d["3 🗄️ MiniVectorDB<br/>add: embed + store rows<br/>search: filter 🏷️ → score → sort → top-k"]
    end
    demo["demo.py: 7 chunks · 3 queries ·<br/>1 honest failure 😬"]
    file --> demo

❓ काय (चोरण्यासारखे तपशील)

तुम्ही बनवला तो database आहे, index नाही. MiniVectorDB ही storage/query system आहे: ती embed करते, साठवते, filter करते आणि rank करते. तिचा search प्रत्येक जागा तपासतो (brute force); तो loop HNSW किंवा IVF ने बदलला (धडा 04) तर त्याच database च्या आत एक index जोडला जाईल — API बदलणार नाही.
लिहिताना normalize, वाचताना dot — vector search मधली सर्वोत्तम एकमेव perf युक्ती, आणि इथे ती दोन ओळींची आहे.
Scoring च्या आधी filter — search() आधी stickers लावते, मग उरलेल्यांना rank करते. Toy scale वर हे फक्त बरोबर आहे; ANN scale वर "filtered search" हे खरोखर कठीण feature आहे (धडा 08 मधली products त्याबद्दल उगाच बढाई मारत नाहीत).
Text vector सोबतच साठवा — retrieval ने माणसाला/model ला वाचता येईल असे काहीतरी परत दिले पाहिजे; नुसते vectors म्हणजे मुलांशिवायच्या जागा.
(score, id, text, meta) tuple sort: सर्वात जास्त आधी — scores समान आले तर tuple-ordering च्या सापळ्यांकडे लक्ष द्या (इथे ids बरोबरी सोडवतात).

🤔 का

एकदा तुम्ही एक वाचला की "आपण vector database वापरावा का?" हा शांत engineering प्रश्न होतो: तुम्हाला तीन कामे माहीत असतात (embed, तुलना, आणणे), कोणते भाग सामान्य आहेत (वरचे सगळे) आणि कोणते product आहेत (indexes, scale वर filters, ops) हे माहीत असते. Framework docs धर्मग्रंथ राहत नाहीत, changelogs बनतात.

🧪 करून पाहा — दोन सुधारणा, प्रत्येकी ~10 ओळी

# A) persistence: add save(path)/load(path) using json
#    (vectors are just lists — json.dump(self.rows) and back)
# B) delete(doc_id): rows = [r for r in rows if r[0] != doc_id]
#    then re-run demo.py and delete 'lunch-1' — watch query 1's
#    second hit change!
python3 vectordb/demo.py

किमान सुधारणा A तरी पूर्ण करा — exit झाल्यावर सगळे विसरणारा database हा खूप प्रामाणिक toy आहे, पण फक्त toy. 💾

⏭️ पुढे

कोणत्याही index पेक्षा मोठा दर्जाचा लीव्हर: तुम्ही आत काय टाकता — chunking, overlap, stickers, आणि hybrid search.

git checkout lesson-06-chunking-metadata

🔬 Lesson 05 — Build a vector DB: 70 honest lines

📍 You are here: Lesson 05 of 8 · Previous: lesson-04-nearest-neighbors · Next: lesson-06-chunking-metadata

📦 What's in this branch

Lessons 01–04, plus the guided read of vectordb/vectordb.py — the whole course so far, findable at a line number — and your first extensions.

🧒 Explain like I'm 5

Open the file. Three numbered parts, matching the lessons:

TEXT → VECTOR 🔢 (lesson 02): _tokens (lowercase words), embed (hash each word into one of 256 buckets, bump it, normalize). The honest label sits right in the docstring: replace THIS function with an embedding-model call and everything else stays. That one-function boundary is the industry's architecture in miniature: embedder and store are separate jobs.
SIMILARITY 📐 (lesson 03): cosine — one line of dot product, because normalization already happened at the door (_normalize).
THE DATABASE 🗄️ (lessons 04+06): class MiniVectorDB — rows (id, vector, text, metadata), add() embeds-and-stores, search() is brute-force kNN with a metadata filter (all(meta.get(k)==v) — the colored-stickers line, lesson 06 explains why filtering BEFORE ranking matters).

Notice what a real product adds — and that none of it changes the concepts: persistence (ours forgets on exit!), updates/deletes, an ANN index (L04), concurrency, replication (the k8s school waves hello 👋).

🗺️ Diagram

flowchart TB
    subgraph file["vectordb/vectordb.py — the map"]
        e["1 🔢 embed()<br/>hash words → 256 dims → normalize<br/>← swap for a model call HERE"]
        c["2 📐 cosine()<br/>one line: dot product<br/>(normalize made it cheap)"]
        d["3 🗄️ MiniVectorDB<br/>add: embed + store rows<br/>search: filter 🏷️ → score → sort → top-k"]
    end
    demo["demo.py: 7 chunks · 3 queries ·<br/>1 honest failure 😬"]
    file --> demo

❓ What (details worth stealing)

What you built is the database, not an index. MiniVectorDB is the storage/query system: it embeds, stores, filters and ranks. Its search scans every seat (brute force); swapping that loop for HNSW or IVF (lesson 04) would add an index inside the same database — the API would not change.
Normalize at write time, dot at read time — the single best perf trick in vector search, and it's two lines here.
Filter before scoring — search() applies stickers first, then ranks the survivors. At toy scale it's just correct; at ANN scale "filtered search" is a genuinely hard feature (lesson 08 products brag about it for a reason).
Store the text WITH the vector — retrieval must hand back something a human/model can read; vectors alone are seats without kids.
The (score, id, text, meta) tuple sort: highest first — mind tuple-ordering traps if scores tie (ids break the tie here).

🤔 Why

"Should we use a vector database?" becomes a calm engineering question once you've read one: you know the three jobs (embed, compare, fetch), you know which parts are commodity (all of the above) and which are product (indexes, filters at scale, ops). Framework docs stop being scripture and start being changelogs.

🧪 Try it — two upgrades, ~10 lines each

# A) persistence: add save(path)/load(path) using json
#    (vectors are just lists — json.dump(self.rows) and back)
# B) delete(doc_id): rows = [r for r in rows if r[0] != doc_id]
#    then re-run demo.py and delete 'lunch-1' — watch query 1's
#    second hit change!
python3 vectordb/demo.py

Ship upgrade A at least — a database that forgets everything on exit is a very honest toy, but only a toy. 💾

⏭️ Next

The quality lever bigger than any index: what you put in — chunking, overlap, stickers, and hybrid search.

git checkout lesson-06-chunking-metadata

← Previousnearest neighbors Next →chunking metadata

This page is the lesson's README from the lesson-05-build-a-vector-db branch, shown here so the whole School stays on one site. Code files open on GitHub at the same branch.