尧图网站建设 
turbovec API参考上TurboQuantIndex向量索引完整方法手册【免费下载链接】turbovecA vector index built on TurboQuant, written in Rust with Python bindings项目地址: https://gitcode.com/GitHub_Trending/tu/turbovecturbovec是一个基于 GoogleTurboQuant算法的向量索引Vector IndexRust 内核 Python 绑定把高维向量压缩到每维 2–4 bit1000 万条文档约 31 GB 的 float32 存储可以直接装进 4 GB 内存。它是数据无关data-oblivious的量化器——无需训练、无需调参add即可用。本文是 API 参考手册的上篇完整梳理核心类TurboQuantIndex的每一个方法。两个索引类先选对再上手 turbovec 提供两个索引类官方完整文档见 docs/api.md索引类特点适用场景TurboQuantIndex位置索引向量以插入槽位0..n标识只增不删、或接受位置 IDIdMapIndex在TurboQuantIndex之上加一层稳定外部u64ID 映射remove(id)为 O(1)需要可删除、ID 稳定的生产库LangChain/LlamaIndex/Haystack 集成内部均使用它本篇聚焦TurboQuantIndexIdMapIndex的方法与它高度对称将在下篇详解。两类索引的 Rust 实现位于 turbovec/src/lib.rsPython 绑定位于 turbovec-python/src/lib.rsPython 端封装与持久化辅助在 turbovec-python/python/turbovec/_persist.py。构造参数30秒创建向量索引from turbovec import TurboQuantIndex idx TurboQuantIndex(dim1536, bit_width4) # 也可省略 dim首次 add 时自动推断构造参数一览参数取值说明dim8 的正整数倍且≤ 16384MAX_DIM可选向量维度省略则为惰性索引第一次add时锁定bit_width{2, 3, 4}默认 4每维压缩位数2-bit 最省内存4-bit 精度更高惰性索引lazy index的行为在首次add之前idx.dim为None、len(idx)为0、search()返回空结果空批次0 行的add是 no-op索引保持惰性。 典型 embedding 模型OpenAI d1536 / d3072、GloVe d200 都能直接建库。核心工作流add 入库、search 检索import numpy as np idx.add(vectors) # float32 二维数组形状 (n, dim) scores, indices idx.search(query, k10) # 返回内积分数与槽位下标add(vectors)要点输入必须是C 连续的 float32 数组其他 dtype 会被直接拒绝而不是静默转换必要时先np.asarray(x, dtypenp.float32)出现 NaN / Inf 或|值| ≥ 1e16会抛ValueError且报错信息精确到第几条向量第几维L2 范数≤ 1e-10的向量没有可表示方向会以 scale 0 存储对任何查询得分恒为 0记录在len(idx)中但排在所有正常向量之后search(queries, k, *, maskNone)要点返回(scores, indices)形状均为(nq, effective_k)indices是int64槽位下标分数是内积因此与查询向量同向缩放ID 排序对查询乘以任意正数不变effective_k min(k, len(idx))库里向量不足 k 条时返回实际条数不做 NaN 填充mask布尔数组长度len(idx)只允许mask[i] True的槽位参与详见下文过滤检索过滤检索在 SIMD 内核里直接屏蔽槽位turbovec 的过滤不是先搜后扔post-filter而是在内核内直接跳过不允许的向量——总能从允许集合中返回最多 k 条不会被宽松过滤掏空结果mask np.ones(len(idx), dtypebool) mask[disabled_slots] False scores, slots idx.search(query, k10, maskmask)⚠️一个重要陷阱mask引用的是槽位而任何变更哪怕len不变都可能让槽位重排——所以每次变更后必须重建 mask长度校验救不了你。这一点在 docs/api.md 中有专节说明。删除与持久化swap_remove、write、sync 三件套swap_remove(i)O(1) 位置删除把最后一个向量换到槽位i并截断一条。它不是移位——不保序未删除向量的槽位下标可能已指向别的向量。命名对齐 Rust 的Vec::swap_remove语义可预测。write(path)/load(path)整文件快照write以 fsync 原子重命名产出.tv文件load读取。write(path, durableFalse)可跳过重命名前的 fsync更快但断电可能丢文件Rust 侧对应write_with_durability(path, io::Durability::Fast | Durable)。sync(path)增量保存sync只写入自上次 sync 以来的变更追加写入新的 32 行块 提交头删除完全不写数据块只在提交头里记一条 redo 操作。每次sync返回即持久sync_all级 fsync任意字节处崩溃都保留上一次完整提交。load()自动识别快照与增量两种容器格式且加载后的索引仍绑定原路径继续增量同步。内存序列化与拷贝to_bytes、from_bytes、pickleidx.to_bytes()返回与write(path)字节完全一致的内存载荷.tv格式TurboQuantIndex.from_bytes(data)接受bytes/bytearray校验规则与load一致损坏载荷抛ValueErrorpickle.dumps/copy.copy/copy.deepcopy全部支持底层都归约为from_bytes(to_bytes())拷贝与原对象完全独立可跨越multiprocessing的 spawn 边界这条路径是缓存与数据库列存储的推荐方式框架集成库的持久化也构建在它之上。两个小坑值得记住空索引在布尔上下文中为 falsy用idx is None判断索引、len(idx)判断内容索引不允许挂用户属性idx.tag x会抛AttributeError。TQ 校准calibrate 与 calibration_state默认情况下索引是纯 TurboQuant调用一次calibrate(sample)后开启TQ——对每个坐标拟合(shift, scale)校准平均可提升约 2.5 个 R10 召回点最各向异性的数据上提升近 8.7。要点时机能在校准后再add就尽量先校准大批量入库后补校准相当于二次量化会损失几个召回点样本随机且有代表性即可约 1024 行就接近全库拟合效果2048 行在所有测量语料上达标排序/聚类前缀会破坏召回可重调calibrate可随时多次调用会用存储的码重编码全部存量行无需原始向量但被严重偏差校准剪坏的数据无法修复只能从源向量重建idx.calibration_state报告当前状态uncalibrated或calibrated校准状态可完整往返于write/load、to_bytes/from_bytes、pickle 与拷贝Rust 侧对应calibrate(mut self, sample)2D 批次为calibrate_2d测试参考 turbovec/tests/tqplus_calibration.rs。附prepare 预热与内省属性prepare()可选。提前构建旋转矩阵、Lloyd-Max 质心与 SIMD 分块布局让第一次search不必支付一次性初始化成本惰性索引上调用为空操作内省len(idx)向量数、idx.dim已提交维度或None、idx.bit_width、idx.calibration_state线程安全search只读锁多线程并发搜索互不阻塞变更走写锁add/swap_remove期间读者等待TurboQuantIndex 方法速查表方法 / 属性说明TurboQuantIndex(dimNone, bit_width4)构造bit_width ∈ {2,3,4}dim可选add(vectors)批量入库float32 二维数组(n, dim)search(queries, k, *, maskNone)返回(scores, indices)支持布尔 mask 过滤swap_remove(i)O(1) 位置删除末位向量换入i返回被移动向量的原位置prepare()预热缓存消除首次搜索的一次性开销calibrate(sample)/calibration_stateTQ 校准提交与状态查询write(path, *, durableTrue)/load(path).tv整文件快照读写sync(path)增量持久化崩溃安全to_bytes()/from_bytes(data)内存字节序列化len(idx)/idx.dim/idx.bit_width内省延伸阅读完整 API 文档 docs/api.mdRust 入口与并发约定见 turbovec/src/lib.rsPython 绑定实现见 turbovec-python/src/lib.rs召回与速度基准见 benchmarks/results/ 下的 JSON 结果。下篇预告IdMapIndex完整方法手册——add_with_ids、remove(id)、allowlist过滤与.tvim文件格式。【免费下载链接】turbovecA vector index built on TurboQuant, written in Rust with Python bindings项目地址: https://gitcode.com/GitHub_Trending/tu/turbovec创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 turbovec API参考（上）：TurboQuantIndex向量索引完整方法手册
turbovec API参考上TurboQuantIndex向量索引完整方法手册【免费下载链接】turbovecA vector index built on TurboQuant, written in Rust with Python bindings项目地址: https://gitcode.com/GitHub_Trending/tu/turbovecturbovec是一个基于 GoogleTurboQuant算法的向量索引Vector IndexRust 内核 Python 绑定把高维向量压缩到每维 2–4 bit1000 万条文档约 31 GB 的 float32 存储可以直接装进 4 GB 内存。它是数据无关data-oblivious的量化器——无需训练、无需调参add即可用。本文是 API 参考手册的上篇完整梳理核心类TurboQuantIndex的每一个方法。两个索引类先选对再上手 turbovec 提供两个索引类官方完整文档见 docs/api.md索引类特点适用场景TurboQuantIndex位置索引向量以插入槽位0..n标识只增不删、或接受位置 IDIdMapIndex在TurboQuantIndex之上加一层稳定外部u64ID 映射remove(id)为 O(1)需要可删除、ID 稳定的生产库LangChain/LlamaIndex/Haystack 集成内部均使用它本篇聚焦TurboQuantIndexIdMapIndex的方法与它高度对称将在下篇详解。两类索引的 Rust 实现位于 turbovec/src/lib.rsPython 绑定位于 turbovec-python/src/lib.rsPython 端封装与持久化辅助在 turbovec-python/python/turbovec/_persist.py。构造参数30秒创建向量索引from turbovec import TurboQuantIndex idx TurboQuantIndex(dim1536, bit_width4) # 也可省略 dim首次 add 时自动推断构造参数一览参数取值说明dim8 的正整数倍且≤ 16384MAX_DIM可选向量维度省略则为惰性索引第一次add时锁定bit_width{2, 3, 4}默认 4每维压缩位数2-bit 最省内存4-bit 精度更高惰性索引lazy index的行为在首次add之前idx.dim为None、len(idx)为0、search()返回空结果空批次0 行的add是 no-op索引保持惰性。 典型 embedding 模型OpenAI d1536 / d3072、GloVe d200 都能直接建库。核心工作流add 入库、search 检索import numpy as np idx.add(vectors) # float32 二维数组形状 (n, dim) scores, indices idx.search(query, k10) # 返回内积分数与槽位下标add(vectors)要点输入必须是C 连续的 float32 数组其他 dtype 会被直接拒绝而不是静默转换必要时先np.asarray(x, dtypenp.float32)出现 NaN / Inf 或|值| ≥ 1e16会抛ValueError且报错信息精确到第几条向量第几维L2 范数≤ 1e-10的向量没有可表示方向会以 scale 0 存储对任何查询得分恒为 0记录在len(idx)中但排在所有正常向量之后search(queries, k, *, maskNone)要点返回(scores, indices)形状均为(nq, effective_k)indices是int64槽位下标分数是内积因此与查询向量同向缩放ID 排序对查询乘以任意正数不变effective_k min(k, len(idx))库里向量不足 k 条时返回实际条数不做 NaN 填充mask布尔数组长度len(idx)只允许mask[i] True的槽位参与详见下文过滤检索过滤检索在 SIMD 内核里直接屏蔽槽位turbovec 的过滤不是先搜后扔post-filter而是在内核内直接跳过不允许的向量——总能从允许集合中返回最多 k 条不会被宽松过滤掏空结果mask np.ones(len(idx), dtypebool) mask[disabled_slots] False scores, slots idx.search(query, k10, maskmask)⚠️一个重要陷阱mask引用的是槽位而任何变更哪怕len不变都可能让槽位重排——所以每次变更后必须重建 mask长度校验救不了你。这一点在 docs/api.md 中有专节说明。删除与持久化swap_remove、write、sync 三件套swap_remove(i)O(1) 位置删除把最后一个向量换到槽位i并截断一条。它不是移位——不保序未删除向量的槽位下标可能已指向别的向量。命名对齐 Rust 的Vec::swap_remove语义可预测。write(path)/load(path)整文件快照write以 fsync 原子重命名产出.tv文件load读取。write(path, durableFalse)可跳过重命名前的 fsync更快但断电可能丢文件Rust 侧对应write_with_durability(path, io::Durability::Fast | Durable)。sync(path)增量保存sync只写入自上次 sync 以来的变更追加写入新的 32 行块 提交头删除完全不写数据块只在提交头里记一条 redo 操作。每次sync返回即持久sync_all级 fsync任意字节处崩溃都保留上一次完整提交。load()自动识别快照与增量两种容器格式且加载后的索引仍绑定原路径继续增量同步。内存序列化与拷贝to_bytes、from_bytes、pickleidx.to_bytes()返回与write(path)字节完全一致的内存载荷.tv格式TurboQuantIndex.from_bytes(data)接受bytes/bytearray校验规则与load一致损坏载荷抛ValueErrorpickle.dumps/copy.copy/copy.deepcopy全部支持底层都归约为from_bytes(to_bytes())拷贝与原对象完全独立可跨越multiprocessing的 spawn 边界这条路径是缓存与数据库列存储的推荐方式框架集成库的持久化也构建在它之上。两个小坑值得记住空索引在布尔上下文中为 falsy用idx is None判断索引、len(idx)判断内容索引不允许挂用户属性idx.tag x会抛AttributeError。TQ 校准calibrate 与 calibration_state默认情况下索引是纯 TurboQuant调用一次calibrate(sample)后开启TQ——对每个坐标拟合(shift, scale)校准平均可提升约 2.5 个 R10 召回点最各向异性的数据上提升近 8.7。要点时机能在校准后再add就尽量先校准大批量入库后补校准相当于二次量化会损失几个召回点样本随机且有代表性即可约 1024 行就接近全库拟合效果2048 行在所有测量语料上达标排序/聚类前缀会破坏召回可重调calibrate可随时多次调用会用存储的码重编码全部存量行无需原始向量但被严重偏差校准剪坏的数据无法修复只能从源向量重建idx.calibration_state报告当前状态uncalibrated或calibrated校准状态可完整往返于write/load、to_bytes/from_bytes、pickle 与拷贝Rust 侧对应calibrate(mut self, sample)2D 批次为calibrate_2d测试参考 turbovec/tests/tqplus_calibration.rs。附prepare 预热与内省属性prepare()可选。提前构建旋转矩阵、Lloyd-Max 质心与 SIMD 分块布局让第一次search不必支付一次性初始化成本惰性索引上调用为空操作内省len(idx)向量数、idx.dim已提交维度或None、idx.bit_width、idx.calibration_state线程安全search只读锁多线程并发搜索互不阻塞变更走写锁add/swap_remove期间读者等待TurboQuantIndex 方法速查表方法 / 属性说明TurboQuantIndex(dimNone, bit_width4)构造bit_width ∈ {2,3,4}dim可选add(vectors)批量入库float32 二维数组(n, dim)search(queries, k, *, maskNone)返回(scores, indices)支持布尔 mask 过滤swap_remove(i)O(1) 位置删除末位向量换入i返回被移动向量的原位置prepare()预热缓存消除首次搜索的一次性开销calibrate(sample)/calibration_stateTQ 校准提交与状态查询write(path, *, durableTrue)/load(path).tv整文件快照读写sync(path)增量持久化崩溃安全to_bytes()/from_bytes(data)内存字节序列化len(idx)/idx.dim/idx.bit_width内省延伸阅读完整 API 文档 docs/api.mdRust 入口与并发约定见 turbovec/src/lib.rsPython 绑定实现见 turbovec-python/src/lib.rs召回与速度基准见 benchmarks/results/ 下的 JSON 结果。下篇预告IdMapIndex完整方法手册——add_with_ids、remove(id)、allowlist过滤与.tvim文件格式。【免费下载链接】turbovecA vector index built on TurboQuant, written in Rust with Python bindings项目地址: https://gitcode.com/GitHub_Trending/tu/turbovec创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考