vectordb源码解析(一)__class_getitem__如何让向量数据库设计更优雅类型化Python向量数据库完整指南【免费下载链接】vectordbA Python vector database you just need - no more, no less.项目地址: https://gitcode.com/gh_mirrors/vect/vectordbvectordb是一个 Python 向量数据库Python vector database提供完整的增删改查CRUD能力可本地运行、可服务化部署、可上云。用过它的人都知道那句just need - no more, no less。但你是否好奇过为什么HNSWVectorDBMyDoc这行类名后面跟个方括号的代码能直接跑起来本文带你从源码层面拆解 vectordb 背后的__class_getitem__魔法看懂这套类型化向量数据库的优雅设计。一、先用 30 秒看懂 vectordb 的核心用法vectordb 的使用分两步先定义一个文档结构基于 DocArray 的BaseDoc再选一种数据库套上这个结构db InMemoryExactNNVectorDBToyDoc # 或者用 HNSW 近似搜索 db HNSWVectorDBToyDoc看到HNSWVectorDB[ToyDoc]这个写法了吗在 Python 里方括号作用于一个类而不是实例这并不常见。它背后正是__class_getitem__这个类级别的下标运算符在起作用。二、问题为什么向量数据库需要类型参数普通向量数据库通常只存向量 元数据这种无模式数据。而 vectordb 希望你用一个结构化的 Document 类比如带text和embedding字段的ToyDoc来描述数据。这样一来建索引时知道该对哪个字段建索引如embedding搜索返回时自动把命中文档 相似度分数挂到结果上服务化部署gRPC/HTTP时能自动生成分布式请求/响应的数据契约难点在于HNSWVectorDB这个类在定义时并不知道你将来会塞什么类型的 Document。解决方案就是——在使用类的那一刻HNSWVectorDB[ToyDoc]动态生成一个知道了类型的新类。这就是__class_getitem__的登场时机。三、核心魔法VectorDB.class_getitem逐行拆解整个魔法的核心在基类 vectordb/db/base.py源码只有不到 20 行注释里作者自己写着Behind-the-scenes magicdef __class_getitem__(cls, item: Type[TSchema]): from docarray import BaseDoc if not isinstance(item, type): # 静态上下文如类型注解交给 Generic 处理 return Generic.__class_getitem__.__func__(cls, item) if not issubclass(item, BaseDoc): raise ValueError( f{cls.__name__}[item] item should be a Document not a {item} ) class VectorDBTyped(cls): # 动态生成一个知道类型的子类 _input_schema: Type[TSchema] item _executor_cls: Type[TypedExecutor] cls._executor_type[item] VectorDBTyped.__name__ f{cls.__name__}[{item.__name__}] return VectorDBTyped四个关键设计点新手也能看懂参数校验先行。item必须是BaseDoc的子类否则直接抛ValueError。错误信息里还贴心地告诉你传了什么降低排错成本。动态生成新类而非修改原类。class VectorDBTyped(cls)每次调用都会创建一个新的派生类把输入模式item绑定到_input_schema再把执行器类型类型化cls._executor_type[item]——注意执行器自己也实现了同样的魔法见下文。伪装类名。把新类命名成HNSWVectorDB[MyDoc]这样你在日志、异常、调试器里看到的名字和实际用法完全一致体验极其原生。兼容类型注解场景。如果方括号里传的不是类比如类型变量就原样转交给标准库的Generic.__class_getitem__保证VectorDB[T]这种写法也能作为注解使用——这是很多自造轮子容易忽略的细节。四、分层设计VectorDB 与 TypedExecutor 的双重类型化vectordb 的类结构非常清晰每一层都独立实现了自己的__class_getitem__层级类类型化时机源码位置用户入口VectorDB及其子类HNSWVectorDB[MyDoc]vectordb/db/base.py服务执行器TypedExecutor及其子类HNSWLibIndexer[MyDoc]vectordb/db/executors/typed_executor.py远程客户端ClientClient[MyDoc]vectordb/client/client.py以 vectordb/db/hnsw_vectordb.py 为例整个产品级的 HNSW 向量数据库子类只有 3 行class HNSWVectorDB(VectorDB): _executor_type HNSWLibIndexer reverse_score_order False剩下的全部继承自基类。__class_getitem__被调用时会顺手把_executor_type也做一次类型化cls._executor_type[item]于是执行器层 vectordb/db/executors/typed_executor.py 里的__class_getitem__被触发生成带_input_schema和_output_schema的执行器类并命名为HNSWLibIndexer[MyDoc][MyDocWithMatchesAndScores]。这种一层类型化驱动下一层类型化的设计让新增一种搜索算法比如换掉 HNSW时只需实现一个新的 Indexer 并声明_executor_typeCRUD、服务化、排序等逻辑全部复用——这正是 vectordb 宣称不过度设计的底气。五、隐藏彩蛋输出类型也是运行时长出来的搜索要返回什么是命中文档列表 分数列表。vectordb 不会让你手动定义输出结构而是在 vectordb/utils/create_doc_type.py 里用 pydantic 的create_model动态生成return create_model( input_doc_type.__name__ WithMatchesAndScores, __base__input_doc_type, matches(DocList[input_doc_type], []), scores(List[float], []))也就是说输入是MyDoc输出就自动是MyDocWithMatchesAndScores——继承自MyDoc的所有字段都还在只是多了matches和scores两个字段。配合 vectordb/utils/sort_matches_by_score.py 里的排序装饰器按分数排序返回和 vectordb/utils/unify_input_output.py 的统一输入输出装饰器传单个文档也按列表处理、返回时还原单条用户侧的 API 始终干净一致。六、Client 端同款魔法本地与远程 API 完全一致vectordb 本地库和远程服务共享同一套 API。远程客户端 vectordb/client/client.py 同样实现了__class_getitem__client ClientMyDoc results client.search(inputsDocListMyDoc, limit10)Client[MyDoc]同样会动态生成输出类型保证search的结果能被正确反序列化成带 matches 和 scores 的文档。服务化部署的完整流程可在 vectordb/db/service.py 中查看整体架构如下图服务模式下应用与向量数据库双向通信七、小结这套设计教给我们的 3 件事__class_getitem__不只属于 typing标准库里它主要用于List[int]这类泛型注解而 vectordb 把它用在了运行时类工厂上一个钩子函数换来整个类型化体系性价比极高。动态生成子类 伪装类名既保持了类型信息的运行时可访问性_input_schema又不破坏用户的调试体验HNSWVectorDB[MyDoc]。分层复用拒绝过度设计入口层、执行器层、客户端层各管一段新产品子类仅 3 行代码这正是 vectordb you just need - no more, no less 理念的源码级体现。想动手验证可以直接运行仓库根目录的 example.py里面演示了内存数据库建索引 HNSW 服务化搜索的完整最小流程。下一篇预告vectordb 源码解析(二)——serve()背后的 Jina 分片与副本机制敬请期待。【免费下载链接】vectordbA Python vector database you just need - no more, no less.项目地址: https://gitcode.com/gh_mirrors/vect/vectordb创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考