Beginners course module 1#2494
Conversation
Module 1-3 pages don't exist yet, so the syllabus links to them were 404ing the lychee internal link checker.
✅ Deploy Preview for condescending-goldwasser-91acf0 ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
kanungle
left a comment
There was a problem hiding this comment.
This is a good start. Left some comments. Not sure why Module 0 changes are in this PR
|
|
||
| # Let's Understand Search | ||
|
|
||
| Understand why traditional search fails, how semantic (vector) search solves it. |
There was a problem hiding this comment.
I think this is misleading. I think it should be something like:
Understand why traditional search struggles and how modern semantic search improves it.
| |-------|----------------------|--------| | ||
| | car repair | automobile maintenance guide | ❌ Missed | | ||
| | cheap flights NYC | affordable airfare to New York | ❌ Missed | | ||
| | Apple stock | fruit company disambiguation? | ✔ Match | |
There was a problem hiding this comment.
This line doesn't make sense to me
| | cheap flights NYC | affordable airfare to New York | ❌ Missed | | ||
| | Apple stock | fruit company disambiguation? | ✔ Match | | ||
|
|
||
| ### The Three Core Failure Modes |
|
|
||
| Over time, search systems became more diverse. However, they all shared the same fundamental ceiling: they work on words, not meaning. | ||
|
|
||
| ### Evolution of Search Techniques |
There was a problem hiding this comment.
is this actually a chronological evolution? I didn't look it up
| "Does this document contain the same words?" | ||
|
|
||
| **Semantic search asks:** | ||
| "Does this document mean the same thing?" |
| | Cosine | Text similarity, NLP models | Robust to different vector magnitudes. Most common default. | | ||
| | Dot product | When embeddings are normalized | Faster than cosine if vectors are unit-normalized at index time. | | ||
| | Euclidean (L2) | Image embeddings, spatial data | Sensitive to magnitude - works best with models trained for it. | | ||
|
|
| # SKU-48291 (score: 0.89) ← only correct result returned | ||
| ``` | ||
|
|
||
| ### Key insight |
|
|
||
| - **Dense**: Semantic / vector - Intent, vibe, meaning | ||
| - **Sparse**: BM25 / keyword - Exact terms, rare tokens | ||
| - **Filters (Optional)**: Payload constraints - Hard rules, access control |
There was a problem hiding this comment.
I'm not aware of any of our content that mentions "filtering" as a component of Hybrid Search
| - **Agentic AI systems** - multi-step agents that query different data sources sequentially | ||
| - **E-commerce** - find semantically similar products, then filter by price, brand, and availability | ||
| - **Knowledge bases** - semantic over documents, keyword for exact references and code snippets | ||
|
|
|
|
||
| ## 8. References & Further Reading | ||
|
|
||
| - **Qdrant Documentation** - [Qdrant Overview](https://qdrant.tech/documentation/concepts/) |
There was a problem hiding this comment.
Name it "Qdrant Concepts"
| - **Qdrant Concepts** - [Qdrant Overview](https://qdrant.tech/documentation/concepts/) | ||
| - Overview of Qdrant's vector search engine - collections, points, payloads, and APIs. | ||
|
|
||
| - **Distance Metrics Deep Dive** - [Distance Metrics - Qdrant](https://qdrant.tech/documentation/concepts/#distance-metrics) | ||
| - Cosine, dot product, Euclidean, and Manhattan - when to use each. | ||
|
|
||
| - **Filtering & Hybrid Search** - [Filtering - Qdrant](https://qdrant.tech/documentation/concepts/filtering/) | ||
| - Payload filter syntax, indexed fields, and combining filters with vector queries. | ||
|
|
||
| - **RAG Tutorials** - [RAG Tutorials - Qdrant](https://qdrant.tech/rag) | ||
| - End-to-end retrieval-augmented generation tutorials using Qdrant as the retriever. |
There was a problem hiding this comment.
These links need to be href'd on the text itself, instead of beside it.
Example, just:
[Filtering & Hybrid Search]((https://qdrant.tech/documentation/concepts/filtering/)
| - How similarity really works under the hood - and when it fails. | ||
| - Your first Qdrant collection: points, payloads, and your first query. | ||
|
|
||
| End of Module 1. Continue to Module 2: First Principles of Vector Search. |
There was a problem hiding this comment.
This needs to be a button link, like in the essentials course
There was a problem hiding this comment.
make this change on all modules
There was a problem hiding this comment.
I didn't add it intentionally because it might lead to PR runs failure because of disjoint modules, will add once everything is approved
There was a problem hiding this comment.
Added a button, although now its a 404. The merge order is important here after the corrections to avoid conflicts:
--> Merge Module 0 first
--> Module 1 to 5 chronologically next
kanungle
left a comment
There was a problem hiding this comment.
Progress since last round is real (formula, Manhattan row, concepts naming, intro line all fixed), but several items from my previous reviews are still open, so requesting changes again.
Still open from my last reviews:
- Module 0 files are still in this PR. Please remove
course/beginners/_index.mdand themodule-0/files so this PR only adds module 1; those shared files belong to #2492. Same request going out on every module PR. - Line 202:
- and more...Cut it or name a real use case. - Lines 213–226: reference links. Href the text itself:
[Qdrant Concepts](https://qdrant.tech/documentation/concepts/), drop the link-beside-text pattern for all four. - Title Case on headings throughout: "Today's Path", "Core Limitation", "What You'll Learn", and so on.
- Syllabus still says "Hybrid Search: Dense + Sparse + Filters" in
_index.md. Same point I made on the module body: filters aren't a hybrid-search component. "Dense + Sparse". (Moves to #2492 once the shared files come out of this PR.)
New items:
6. Line 141 is a broken sentence: "A score of 0.0 means on the other hand can be interpreted as…". Suggest: "A score of 1.0 means the vectors point in the same direction. A score near 0.0 means the texts are semantically unrelated." Also drop "(identical meaning)"; cosine 1.0 is same direction, not identical meaning.
7. Line 149: "around 0.847". Did you run this? Three decimals plus "around" don't mix, and the score depends on the model version. Run it and quote the real number, or say "around 0.85".
8. Line 83 table row is mislabeled and the example is broken: typo tolerance is fuzzy matching, not "keyword matching", and "(receive → receive)" is the same word twice. → "Fuzzy matching | Tolerance for typos (recieve → receive)".
9. Line 71: SPLADE doesn't belong in the pre-semantic evolution list. It's a learned sparse model that came after dense retrieval. Drop it here; it's covered properly in Module 3. (This answers my earlier chronology question: no, it wasn't chronological.)
10. Diagrams are off-brand. The colors aren't from the Qdrant color palette and the shapes aren't from our diagram system. Rebuild them from the Docs/Diagrams Figma component library using the Qdrant palette.
11. No exercise. The module is all reading. Add one small task: embed three query/document pairs with the section 4 snippet and compare cosine scores.
12. "Best of both worlds" (line 211) → say what it does: "Covers both exact terms and intent".
13. _index.md: "vector databases" → "vector search engines" (hard rule), and "Duration: Multiple modules" is vague, this course has 6. The Path and syllabus should list all six modules.
Noting for launch, not blocking: the module video placeholder at the top will need the real video before the course goes live.
Updated headings for consistency, improved clarity in descriptions, and corrected terminology related to fuzzy matching. Adjusted similarity score representation for better precision.
Added a section to compare cosine scores with examples and instructions for users to try it themselves.
There was a problem hiding this comment.
Must fix (blocks shipping)
- No video at the top of the module page. Every course module page needs one — see the Essentials course pages for the embed pattern. Outro bumper yes, Intro bumper no.
- Diagrams are off-brand. In
cosine-similarity.png(and the pattern holds across the set): colors are outside the Qdrant palette (olive/dark yellow labels, non-ramp greens), and headings are set in mono instead of Mona Sans. Please rebuild from the Docs/Diagrams Figma library (https://www.figma.com/design/dlnrdaJ6pGlKyXoZquVhtZ/Docs---Diagrams?node-id=8137-14624) using palette tokens (Violet 50#8547FF, Teal 50#038585, P50#DC244C, neutrals), Mona Sans headings, and Geist Mono values. - Dead/outdated doc links. The docs were restructured; these targets no longer exist:
/documentation/concepts/and#distance-metrics,/documentation/concepts/filtering/, andqdrant.tech/rag. Use: filtering →/documentation/search/filtering/, RAG → an existing article such as/articles/what-is-rag-in-ai/. Also use relative paths (/documentation/...), not absolutehttps://qdrant.tech/..., matching the rest of the repo. - Hand-rolled next button. The closing
<a>with inline styles (background:#dc244c) is off-system and targets/course/beginners/module-2/, which 404s until #2495 merges. Drop it and rely on the course layout's built-in next navigation (thecontent.nextButton/nextDayfrontmatter pattern Essentials uses). - Broken markdown:
3. **TF-IDF / BM25— unclosed bold, renders as literal asterisks.
Should fix
- Unmeasured numbers presented as measurements. "yields a similarity score around 0.85" for "car repair" vs. "automobile maintenance" on all-MiniLM-L6-v2 is asserted, not measured (expect meaningfully lower). Same question for the diagram's 0.96 / 0.62 / -0.28. Run the snippet in the lesson, use the actual printed scores in both prose and diagram. Also: the text says "a score near 0.0 means unrelated" while the diagram shows -0.28 — add one sentence that cosine can go negative.
- Nonsense table row.
Apple stock | fruit company disambiguation? | ❌ Missed— the middle cell isn't a document, and polysemy is a wrong-match failure, not a miss. Suggest: document = "apple harvest season guide", result = "wrong sense matched". - Vague closing paragraph in §4. "Vector embeddings aren't limited by these models, however. They are theoretically capable of capturing any data into a transformed structured format." says nothing concrete. Suggest: "Embeddings aren't text-only: the same idea works for images, audio, and code, which is how multimodal search in Module 4 works."
- Style sweep. Spaced hyphens used as em-dash substitutes throughout ("no matter how closely related the meaning is", "Recency, popularity, personalization - payload values…") — replace with commas, colons, or two sentences. Heading case: "Today's Path" here vs. "Today's path" in Modules 0/2 and Essentials — match Essentials. Several images have label-only alt text ("Cheap Flights Example") — write descriptive alt text.
Nice to have
- "(see Module 4)" appears twice — fine if Module 4's scope is locked, otherwise soften to "later in this course".
- The PR description says images will be added soon, but they're already in the diff — please update it to reflect the actual state.
PREVIEW
This PR is still work in progress. Formatting and images will be added soon