easy-vecdb: a Datawhale curriculum for vector search, from IVF to Milvus

A curriculum, not a library you pip install

The first thing to settle is what easy-vecdb actually is. It is not a vector database, not a Python client, and not a wrapper around Faiss or Milvus. The README describes it as a systematic learning project for developers and researchers, covering concepts, algorithm principles and production deployment. The repository layout is docs for the learning guide, data for shared example data, src for project code, and tmp for temporary files. The primary language is Jupyter Notebook, which matches the format of a tutorial rather than a package. If you arrive expecting an API to import, you will be disappointed. If you arrive wanting to understand why HNSW behaves differently from IVF-PQ, the table of contents is aimed squarely at you. The intended reader is a developer or student who already writes Python and wants to connect embedding models to retrieval systems without treating the index as a black box.

The six-part structure and what sits at each level

The navigation table splits the material into a Base part and a practice part. Base runs from a project introduction through why vector databases exist, vector embedding fundamentals covering Word2Vec and Transformer embeddings, brute-force search and similarity, ANN algorithms (IVF, PQ, HNSW, LSH, Annoy) with code, and finally a chapter on implementing your own minimal vector database. That last chapter is the one that most distinguishes the curriculum from vendor documentation: it asks you to build the thing before you operate someone else's. The tool-specific parts follow, with three Annoy chapters, five Faiss chapters, and six Milvus chapters. Faiss moves from installation to Flat, IVF, PQ and HNSW indexes, then composite indexes, GPU and batch retrieval, then recall, latency and memory tuning, then engineering structure and service deployment. Milvus moves from architecture and core components to Collection, Partition and Index concepts, PyMilvus API practice, a BM25 hybrid search RAG chapter, an image retrieval chapter, and an elective chapter covering internal architecture, rerankers, Milvus Lite and MinerU deployment. A fifth part holds four projects: Annoy plus DSSM recommendation recall, a Faiss RAG, a Milvus agent, and a Milvus plus ArangoDB RAG system. A sixth part collects supplementary material on vectors, FusionANNS GPU-accelerated retrieval, Meta-Chunking text splitting, theoretical limits of embedding retrieval, RabitQ quantization, and clustering.

Where the theory chapters stop and the code begins

The split between Base and the tool chapters is deliberate, and it maps to a real gap in most vector database learning material. Vendor docs usually start at client construction and end at a query example, leaving the reader unable to reason about recall and latency trade-offs. easy-vecdb inverts that: chapter 5 of Base covers IVF, PQ, HNSW, LSH and Annoy principles with code before any managed service appears, and chapter 6 asks for a minimal implementation. Chapter 4 of the Faiss part then revisits recall, latency and memory as tuning targets rather than as abstract properties. That ordering means the Faiss and Milvus chapters can assume the reader knows what an inverted file list or a product quantizer is doing. It also means the curriculum is front-loaded: a reader who only wants to call Milvus will spend several chapters on material they may not need. The repository does not appear to offer a shortcut track in the README, so the sequence is the product.

Getting the material running: clone, then read, then execute

There is no install command in the README because there is nothing to install. The documented entry points are the online site at https://datawhalechina.github.io/easy-vecdb/ and the source tree on GitHub. The practical workflow is to clone the repository, open the notebook files under docs and src, and run them against the libraries each chapter covers. The README lists the relevant tools as Milvus, Faiss and Annoy, and the topics list adds hnsw, ivfflat, lsh and rag. The data directory is described as the shared example data location, which suggests notebooks reference it by relative path; run them from the repository root rather than from inside a chapter folder if paths fail. Milvus chapters use PyMilvus, and chapter 6 of that part mentions Milvus Lite, which is the lighter local deployment path if you do not want a full server. None of these setup steps are spelled out in the README itself, so expect to follow the per-chapter markdown files under docs for the actual environment instructions. The repository has no releases, so pinning a version means pinning a commit on main.

The licence conflict you should resolve before reuse

The repository metadata supplied here lists Apache-2.0, and the GitHub licence badge in the README links to a LICENSE file. The closing section of the same README states that the work is licensed under Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International, and displays the CC BY-NC-SA 4.0 badge. These two positions are not compatible: Apache-2.0 permits commercial use, CC BY-NC-SA 4.0 does not. This is not a subtle ambiguity, and it matters as soon as you want to reuse the text, notebooks or diagrams in a commercial training programme or an internal onboarding course at a company. I cannot tell from the supplied material which one governs, and I am not giving legal advice. What I can say is that the discrepancy is visible on the repository front page, which suggests it has not been treated as urgent. If your use is non-commercial and personal, the practical risk is low either way. If it is not, ask the maintainers to clarify in an issue before you build on the text.

Coverage gaps and a link that looks broken

The navigation table marks every listed chapter with a completion check, and the README adds a note that the project is continuously updated. That note is the honest signal here: a curriculum with no releases and a moving main branch has no stable snapshot. Two specific things stand out. First, chapter 5 of the Milvus part is listed with the path docs/Milvus/docs/Milvus/chapter5/Milvus的AI应用开发.md, which duplicates the docs/Milvus segment and does not match the pattern of the neighbouring chapters. That is very likely a broken relative link on the rendered site, and it is worth checking before you plan a session around image retrieval. Second, the sixth part is a mixed bag of supplementary topics, from FusionANNS architecture to RabitQ quantization and Meta-Chunking, with no stated prerequisite ordering. Those chapters are useful as reference reading but they do not form a sequence. The absence of releases also means there is no changelog to tell you what changed between the version you read and the version you cloned.

How this differs from reading Faiss and Milvus documentation directly

The obvious alternative is the official documentation for each tool: the Faiss wiki and the Milvus docs. The difference in approach is scope and sequence. Faiss documentation assumes you already know which index family you want and explains the parameters of that family; it does not teach you why IVF and HNSW fail differently at the same recall target. Milvus documentation is organised around the product, its deployment modes and its API, and it will not ask you to implement a minimal vector database first. easy-vecdb sits above both and tries to build the mental model before the API. The cost of that approach is currency. Faiss and Milvus release frequently, and a tutorial repository maintained by volunteers will lag. If you need the current parameter set for a specific index in a specific version, the upstream docs will be more accurate. If you need to understand which index to reach for and why, the ordering here is the more useful starting point. A second alternative is a general ANN algorithms course or textbook, which would go deeper on the mathematics but give you no Milvus deployment or RAG project work at all.

Maintenance, contribution model and what to verify first

The repository is not archived, and the last push recorded in the material is 2026-08-16. The README names a project lead and four contributors, and points contributors at the Datawhale open project guide and a support team for follow-up on issues and pull requests. It also links a 2025 PolarDB database innovation competition, which suggests the material is tied to a teaching and competition cycle rather than to a product roadmap. There are no releases, so upgrade cost is the cost of re-reading changed chapters rather than a migration. For a course, that is a reasonable model. For anything you build on top of the notebooks, treat the code as a starting point and expect to rewrite the parts you depend on. Before committing time, verify three things: which licence actually applies to the material you intend to reuse, whether the Milvus chapter 5 link resolves on the online site, and whether the notebook environments for the Faiss GPU and Milvus chapters match the hardware you have, since the README lists GPU acceleration as a topic without stating requirements.

Editorial conclusion

Adopt easy-vecdb if you are a developer or student who wants a structured path through ANN theory and hands-on Faiss, Annoy and Milvus work, and you can read Chinese. Do not adopt it if you need an installable Python package, an English-language course, or a stable API surface: there are no releases and the repository is a curriculum, not software. Before relying on it, verify the licence question first, since the repository metadata says Apache-2.0 while the README states CC BY-NC-SA 4.0, and confirm the Milvus chapter 5 path, which the navigation table lists as docs/Milvus/docs/Milvus/chapter5/Milvus的AI应用开发.md and which looks like a broken link.

Official sources

1. datawhalechina/easy-vecdb on GitHub
2. Issues
3. License: Apache-2.0
4. Project website
5. README