turbovec LlamaIndex 集成实战基于 TurboQuantVectorStore 构建量化向量检索管线【免费下载链接】turbovecA vector index built on TurboQuant, written in Rust with Python bindings项目地址: https://gitcode.com/GitHub_Trending/tu/turbovec导读本文讲解 turbovec 官方提供的 LlamaIndex 向量存储适配器 ——turbovec.llama_index.TurboQuantVectorStore。它是一个继承自 LlamaIndexBasePydanticVectorStore的向量存储实现底层由IdMapIndexRust 核心 Python 绑定支撑向量被量化为 2~4 bit/维。它的公共接口与llama_index.core.vector_stores.simple.SimpleVectorStore完全一致可作为纯内存简单向量存储的零改动替换品适用于希望在 RAG 管线中大幅压缩 embedding 内存占用的场景。读完本文你将掌握该存储的安装、构造方式、相似度模式、双删除入口、过滤查询、异步调用、持久化与线程安全契约并理解其背后的源码实现细节。安装TurboQuantVectorStore是 turbovec 的可选集成模块需要连同llama-index-core一起安装pip install turbovec[llama-index]在 turbovec-python/pyproject.toml 中可以看到该 extra 的依赖声明llama-index [llama-index-core0.12.1]。如果直接 importturbovec.llama_index而环境中没有安装llama-index-coreturbovec-python/python/turbovec/llama_index.py 会抛出带安装提示的ImportError不会留下费解的运行时错误。基础用法将TurboQuantVectorStore接入标准的 LlamaIndex 构建流程只需把它作为StorageContext的vector_store传入from llama_index.core import VectorStoreIndex, StorageContext from turbovec.llama_index import TurboQuantVectorStore vector_store TurboQuantVectorStore() storage_context StorageContext.from_defaults(vector_storevector_store) index VectorStoreIndex.from_documents(documents, storage_contextstorage_context) retriever index.as_retriever(similarity_top_k5)向量维度dim不需要你手动指定首次add()时从 embedding 模型输出的维度自动推断并锁定。这一惰性构造设计在 turbovec-python/python/turbovec/llama_index.py 的构造函数中实现——未传入index时创建一个惰性IdMapIndextest_lazy_dim_locked_on_first_add等测试在 turbovec-python/tests/test_llama_index.py 中验证了该行为首次 add 后dim被锁定为 64。构造方式TurboQuantVectorStore支持三种构造路径分别适用于完全惰性显式量化位宽加载既有索引三种场景# No-arg: lazy. dim is inferred from the first add. vector_store TurboQuantVectorStore() # from_params: same lazy behaviour, plus an explicit bit_width. vector_store TurboQuantVectorStore.from_params(bit_width4) # Pre-built index: bring your own IdMapIndex (e.g. one you loaded from disk). from turbovec import IdMapIndex vector_store TurboQuantVectorStore(indexIdMapIndex(1536, 4))bit_width取值限定为{2, 3, 4}索引创建后不可变更clear()之后依然保持该值见下文清空小节。from_params(dimNone, bit_width4, similaritycosine)在传入dim时立即构造非惰性索引后续 add 的 embedding 维度必须匹配否则在 llama_index.py 抛出带维度说明的ValueError省略dim时与无参构造等价。bit_width3同样受支持test_bit_width_3_round_trip 验证了 3-bit 下的写入与查询闭环。相似度模式similarity关键字构造函数与from_params均支持决定query返回的similarities如何计算并在 store 生命周期内固定cosine默认。节点 embedding 在 add 时做 L2 归一化查询 embedding 在查询时做 L2 归一化因此result.similarities是落在[-1, 1]区间的真余弦相似度排序结果不受 embedding 量级影响、与SimpleVectorStore一致可以安全地喂给基于相似度阈值截断的后处理逻辑。零向量无法归一化原样保留对所有查询都打 0 分。dot_product。向量原样存储与查询result.similarities是原始内积排序结果对 embedding 量级敏感适用于量级本身携带语义信息的场景。vector_store TurboQuantVectorStore(similaritydot_product)similarity是 turbovec 的扩展参数参考实现SimpleVectorStore无条件计算余弦因此在默认参数下按参考实现编写的代码行为完全不变。底层实现位于 turbovec-python/python/turbovec/_similarity.py其中l2_normalize_rows用归一化因子替换技巧保证零向量行原样通过cosine 模式下归一化在写锁之外完成纯计算不会阻塞并发读。两个 delete 入口LlamaIndex 的向量存储协议定义了两种语义不同的删除入口TurboQuantVectorStore均按参考实现对齐实现delete(ref_doc_id: str)—— 删除整个源文档删除ref_doc_id匹配的每一个节点一个父文档及其所有切块一次调用搞定vector_store.delete(my-source-document-123)不存在的ref_doc_id被静默忽略。注意一个与参考实现对齐的边界语义见 test_delete_none_is_a_noop_matching_reference无父节点的节点会被登记到字面字符串None下node.ref_doc_id or None因此delete(None)是 no-op 而非清空所有无父节点要定向删除无父节点请调用delete(None)。delete_nodes(node_ids, filters)—— 删除指定切块按node_ids、filters或两者求交的结果删除节点。缺失的node_id静默忽略# By node_id vector_store.delete_nodes(node_ids[abc-123, def-456]) # By metadata filter from llama_index.core.vector_stores.types import ( MetadataFilter, MetadataFilters, FilterOperator, ) filters MetadataFilters( filters[MetadataFilter(keytier, valuearchived, operatorFilterOperator.EQ)], ) vector_store.delete_nodes(filtersfilters) # Both: intersect — delete only nodes in this list that ALSO match the filter vector_store.delete_nodes(node_ids[abc-123], filtersfilters)与参考实现有两处刻意的差异源码注释见 llama_index.py两个参数均为None时是no-op。参考实现此时会删除全部节点其build_metadata_filter_fn(None)恒真而协议本身并未规定 delete-all且库已提供专门的clear()因此 no-op 是更安全的解读避免误删。filters中包含嵌套MetadataFilters组时本实现会递归求值而参考实现直接抛ValueError这是 turbovec 的超集扩展见 test_query_nested_filter_groups_are_supported_superset。clear()—— 全部清空vector_store.clear()重置整个 store同时保留配置的bit_width。清空后的 store 立即可用dim由下一批 add 重新推断test_clear_resets_store 验证了bit_width保留、dim回到惰性状态。查询LlamaIndex 内部调用query(VectorStoreQuery)。如果你走VectorStoreIndex.from_documents(...)流程通常不会直接调用它——由 retriever 代劳。直接使用示例from llama_index.core.vector_stores.types import VectorStoreQuery result vector_store.query(VectorStoreQuery( query_embedding[...], similarity_top_k5, )) # result.nodes, result.similarities, result.idsquery_embedding是必填项。turbovec 不负责对查询文本做 embedding那是 retriever / query engine 的职责。此外query.mode只支持VectorStoreQueryMode.DEFAULTMMR / SVM / hybrid 等模式需要全精度向量而 turbovec 量化后即丢弃全精度因此 query() 会显式抛出NotImplementedError而不是旧实现那样静默按 DEFAULT 处理。过滤查询VectorStoreQuery接受filters、node_ids、doc_ids三个过滤维度同时提供多个时全部取交from llama_index.core.vector_stores.types import ( MetadataFilter, MetadataFilters, FilterCondition, FilterOperator, VectorStoreQuery, ) filters MetadataFilters( filters[ MetadataFilter(keytier, valuepro, operatorFilterOperator.EQ), MetadataFilter(keyyear, value2024, operatorFilterOperator.GTE), ], conditionFilterCondition.AND, ) result vector_store.query(VectorStoreQuery( query_embedding[...], similarity_top_k5, filtersfilters, node_ids[chunk-1, chunk-2, chunk-3], # restrict to these chunks doc_ids[src-doc-42], # restrict to chunks of this source doc ))支持的MetadataFilter操作符EQ、NE、GT、LT、GTE、LTE、IN、NIN、TEXT_MATCH、TEXT_MATCH_INSENSITIVE、CONTAINS、ANY、ALL、IS_EMPTY。条件AND、OR、NOT。嵌套MetadataFilters可用递归求值参考实现不支持。过滤语义与SimpleVectorStore参考实现保持一致几个关键细节实现见 llama_index.py缺失 key 的语义除IS_EMPTY外所有正操作符在 metadata 缺失该 key 时返回False而负操作符NE/NIN对缺失 key真空满足没有颜色自然是颜色不是红——这与 llama-index-core ≥ 0.14 的现行行为一致见 test_query_ne_filter_keeps_nodes_missing_the_key。TEXT_MATCH是区分大小写的子串匹配TEXT_MATCH_INSENSITIVE才做两边lower()的大小写折叠非字符串操作数会抛TypeError。过滤在打分之前解析为内部 handle 白名单。过滤查询从过滤后的集合中返回最多similarity_top_k条——即使高分候选恰好被过滤排除你也不会少拿到结果见 test_query_filter_selective_returns_top_k_from_matches。空node_ids/doc_ids列表不构成任何限制等价于省略该参数。这是框架自身调用约定的结果VectorStoreIndex.as_retriever会传入node_idslist(index_struct.nodes_dict.values())而stores_textTrue的 store 该列表恒为空——它表达的是不限制若按匹配空集处理则每个 retriever 查询都会返回空结果issue #130 的维护者裁定。与此相反get_nodes/delete_nodes中node_ids就是选择集显式空列表选择的是无。过滤条件的组合逻辑AND/OR/NOT、嵌套组、同一 key 多条件均有对应测试覆盖如 test_query_contradictive_same_key_and_returns_empty 验证了同 key 两个 EQ 条件 AND 后结果为空。Get nodesnodes vector_store.get_nodes(node_ids[chunk-1, chunk-2]) nodes vector_store.get_nodes(filtersfilters) nodes vector_store.get_nodes(node_ids[chunk-1, chunk-2], filtersfilters) # intersect从 side-car见下文持久化小节重建并返回List[BaseNode]缺失的node_id静默跳过。与SimpleVectorStore不同参考实现此处直接抛NotImplementedError因为它不存节点turbovec 在 side-car 中保存节点文本与元数据因此能直接返回内容完整的TextNode。node_ids是显式选择集空列表选择无并返回[]delete_nodes同理空列表是 no-op传入node_ids时结果按请求顺序返回否则按存储顺序test_get_nodes_returns_requested_id_order。节点保真度side-car 存储的是node_to_metadata_dict(node, remove_textFalse, flat_metadataFalse)的完整序列化字典因此query/get_nodes/ persist 往返都能还原出完整的BaseNode子类TextNode/ImageNode/IndexNode包括PREVIOUS/NEXT/PARENT/CHILD等全部关系、excluded_*_metadata_keys、模板字段、start/end_char_idx、mimetype等见 test_query_returns_node_with_full_field_fidelity。Upsert 语义对已存在node_id调用add()会替换既有条目符合用户在重新索引同一批切块时的预期node TextNode(textv1, embedding[...]) vector_store.add([node]) # Same node_id, different text/embedding → replaces. updated TextNode(textv2, id_node.node_id, embedding[...]) vector_store.add([updated]) assert len(vector_store._index) 1同一add()批次内重复node_id会抛ValueError需先自行去重。这与 LangChain / Haystack 适配器静默保留最后一条的行为不同这里是硬错误避免意外重复静默丢弃节点。实现上通过 turbovec-python/python/turbovec/_dedup.py 的resolve_duplicates(ids, DuplicatePolicy.REJECT)在写入前拦截并在失败时回滚已插入的 map 条目保证 store 不被写坏见 test_add_raises_on_intra_batch_duplicate_node_id。此外upsert 时若新 embedding 维度校验失败旧条目会被完整保留test_add_upsert_dim_mismatch_preserves_existing_node。异步接口每个公开方法都有异步对应版本可直接用于 LlamaIndex 的异步 retriever / query engine 路径await vector_store.async_add(nodes) result await vector_store.aquery(VectorStoreQuery(...)) fetched await vector_store.aget_nodes(node_ids[...]) await vector_store.adelete(ref-doc-id) await vector_store.adelete_nodes(node_ids[...]) await vector_store.aclear()实现上每个方法都通过一次asyncio.to_thread把同步体丢到工作线程执行llama_index.py事件循环在大型 add / 查询期间保持响应——而BasePydanticVectorStore的默认异步实现是直接内联调用同步体会阻塞事件循环整个操作时长。取消语义是部分的这个区别很重要asyncio.wait_for、task.cancel()或客户端断开连接会立即把控制权交还调用方旧实现协程会跑完超时永远不会触发。但它不决定 add 的结局若工作线程已开始执行调用会完整跑完Rust 核心内的工作不可中断add 整体提交若执行器已饱和、调用尚未开始就被取消则什么都没有写入。因此被取消的async_add结局未知可能已完整提交也可能从未开始。由于重加同一node_id是覆盖写无论如何重试都是安全的。唯一确定的是全有或全无store 永远不会处于撕裂状态。超时不代表工作消失事件循环关闭asyncio.run收尾或loop.shutdown_default_executor()会等待工作线程因此超时后立即退出进程仍可能阻塞在未完成调用的剩余时长上。持久化与加载直接文件 stem接口vector_store.persist(./store/vectors.json) # ... later ... vector_store TurboQuantVectorStore.from_persist_path(./store/vectors.json)persist_path被当作路径stem二进制索引与 JSON side-car 以{stem}.tvim和{stem}.nodes.json两个文件并排落盘。persist_path上的扩展名如 StorageContext 默认的.json会被替换。节点元数据必须是 JSON 可序列化的。若{stem}.nodes.json与{stem}.tvim索引失步部分拷贝、过期备份、篡改from_persist_path会立即抛ValueError而不是等查询时深埋一个KeyError——这由 _persist.py 中的check_persisted_handlesside-car handle 集与索引双射校验、check_sidecar_keysets两个同 key 结构的一致性校验与check_schema_versionschema 版本门禁共同保证失步、重复 handle、回卷的next_u64水位、遍历性 namespace 等损坏场景均有对应测试覆盖见 turbovec-python/tests/test_llama_index.py。persist对目标是原子的两个文件都先写入同目录的临时文件再os.replace移入到位Windows 上对瞬态共享冲突做了指数退避重试因此一次失败的 persist例如元数据不可 JSON 序列化不会破坏同一 stem 下此前持久化的 store也不会残留临时文件。相似度模式会被记录在{stem}.nodes.json中并由from_persist_path恢复。在模式字段出现之前持久化的 store保存的是原始未归一化向量加载时进入dot_product模式——这正是它写入时的打分方式无需迁移。通过StorageContext该 store 与SimpleVectorStore一样兼容StorageContext.from_defaults(persist_dir...)# Persist storage_context.persist(persist_dir./store) # Load vector_store TurboQuantVectorStore.from_persist_dir(persist_dir./store) storage_context StorageContext.from_defaults( vector_storevector_store, persist_dir./store, )from_persist_dir(persist_dir, namespacedefault, fsNone)构造带命名空间的文件名{persist_dir}/{namespace}__vector_store.json并委托给from_persist_path。多个命名空间的 store 可以共享同一持久化目录——包括点分命名空间v1.2、v1.3它们映射到不同的文件对v1.2__vector_store.tvim/v1.2__vector_store.nodes.json等。namespace命名的是persist_dir内部的一个 store因此必须非空且不得包含路径分隔符、..或:形如C:foo的 Windows 盘符相对名会逃逸persist_dir违反即抛ValueError校验见 llama_index.py 的_validate_namespace逃逸测试见 test_from_persist_dir_traversal_does_not_read_outside。其余字符串字母数字、连字符、下划线、点均接受。旧版兼容早期 turbovec 在点分命名空间下持久化的 store 以截断文件名落盘namespacev1.2对应v1.tvim加载时仅在正确文件名缺失时走旧文件名回退下一次persist会写回正确文件名test_from_persist_dir_loads_legacy_mangled_dotted_store。仅配置的往返config vector_store.to_dict() # {bit_width: 4, dim: 1536, similarity: cosine} fresh TurboQuantVectorStore.from_dict(config) # empty store with the same configto_dict/from_dict只序列化 store 的配置bit_width、dim、similarity节点数据通过persist/from_persist_path往返。该 store 还支持带完整数据保真度的pickle例如用于multiprocessingworker与copy.copy/copy.deepcopy——两者都返回完全独立的 store不存在共享底层索引的浅拷贝。这是通过自定义__getstate__/__setstate__索引经IdMapIndex.to_bytes()/from_bytes()走内存.tvim字节格式实现的避免了默认实现静默丢弃 Rust 索引导致反序列化出空 store 的坑llama_index.py。线程安全该 store 对并发多线程使用是安全的契约如下读并发且可扩展。query和get_nodes不取锁底层索引在打分期间释放 GIL因此多个线程的独立查询可以真正重叠并扩展。写串行化。add、delete、delete_nodes、clear、persist在 per-store 锁上串行。async_add/a*变体委托给同一套加锁体因此并发 add 会签发唯一 handle——任何批次都不会因 handle 冲突被拒绝或丢失锁还保证_next_u64 1的原子性见 llama_index.py。读与写重叠时看到的是写前或写后状态绝无撕裂态。在高并发 churn 下查询可能瞬时返回少于similarity_top_k条结果查询中途被删除的命中会被跳过。契约不覆盖的部分无跨调用原子性。调用侧的先检查后执行序列如get_nodes后delete_nodes可能与其他写者交错。批量写对读者也不是原子的与对既有node_id的重新add重叠的查询可能短暂看到该 id 同时挂在新旧两个条目下。persist与写串行化因此总能拍到一致快照persist 期间读可以继续。两个 store 写同一路径是安全的。多个线程对同一目的地并发persist各自原子发布最后写入者胜出调用方永远不会看到撕裂文件也不会看到仅由另一写者造成的错误。谁胜出不定义。多进程访问不支持。已知限制不支持 MMR。最大边际相关max-marginal-relevance检索需要每个候选的全精度 embedding 来计算两两多样性turbovec 在量化后即丢弃全精度向量。get(text_id)会抛异常而非返回向量——同理全精度 embedding 不可恢复。需要原始 embedding 请自行维护并行 docstore。不支持fsspec文件系统。persist、from_persist_path、from_persist_dir均接受本地路径请保持fsNone默认值传入非 None 的fs会显式抛NotImplementedError。仅支持 JSON 可序列化元数据。节点元数据以 JSON 存入 side-car不可序列化的值会在 persist 时报错——与SimpleVectorStore.persist的约束一致且 turbovec 在 add 时即做 JSON 强制转换过滤所依据的元数据视图与返回给调用方的视图严格一致、持久化前后不变见 test_filters_operate_on_the_metadata_that_is_returned。stores_text True。与SimpleVectorStore不同turbovec 在 side-car 中保存节点文本使查询结果直接返回内容完整的TextNode无需依赖独立 docstore。若你的管线原本期望文本存于别处这个差异是无害的——框架仅将stores_text视为信息性字段。进一步阅读完整集成源码turbovec-python/python/turbovec/llama_index.py共享工具模块相似度模式 _similarity.py、持久化一致性检查 _persist.py、批内去重 _dedup.py测试套件turbovec-python/tests/test_llama_index.py覆盖协议完整性、过滤语义、异步、持久化往返、损坏检测与端到端框架接线其余集成适配器agno、haystack、langchain【免费下载链接】turbovecA vector index built on TurboQuant, written in Rust with Python bindings项目地址: https://gitcode.com/GitHub_Trending/tu/turbovec创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考