turbovec 文件格式逐字节解剖.tv 与 .tvim 的完整结构图解【免费下载链接】turbovecA vector index built on TurboQuant, written in Rust with Python bindings项目地址: https://gitcode.com/GitHub_Trending/tu/turbovec如果你用过turbovec基于 TurboQuant 量化、用 Rust 编写并带 Python 绑定的向量索引库一定见过它落盘生成的.tv和.tvim文件。这篇文章带你逐字节打开这两个文件从文件头的魔术字到 4 个主要区域再到 CRC 校验的落点把 turbovec文件格式的完整结构讲清楚。先说结论两个文件名同一种格式扩展名索引类型kind字节多存了什么index.tvTurboQuantIndex纯向量0无index.tvimIdMapIndex向量 外部 ID 映射1每行多一个 8 字节u64外部 ID两者内部都是同一个v7 容器唯一的区别就是每个数据块末尾是否附带 ID 表。所有偏移量都由 5 个几何参数kind、dim、bit_width、校准长度推导出来文件格式定义在 turbovec/src/io_v7.rs 中。文件全景四大区域一个.tv/.tvim文件的布局从前往后是[超级块 Superblock] → [头槽 A Header A] → [头槽 B Header B] → [块单元区 Block Units…]区域作用是否带 CRC超级块索引几何维度、位宽、码本、校准参数✅ 尾部 CRC-32C头槽 A/B两代提交记录行数、尾部不满 32 行的残行、删除重放操作、增量摘要✅ 尾部 CRC-32C块单元区每 32 个向量一个单元量化码字 32 个缩放因子 (32 个 ID)❌由提交头部的增量摘要统一覆盖超级块逐字节解剖超级块是文件的身份证长度公式23 4×(2^n_levels - 1) 4×n_calib×2 4字节。以最常见的 2bit/4bit 为例偏移长度字段说明04magic固定为TV7\00x54 56 37 0041revision当前为251bit_width量化位宽只允许 2、3、461kind0.tv1.tvim跨类型加载会被直接拒绝74dimu32小端必须为 8 的倍数0 表示惰性空索引118nonceu64文件身份标识0表示未认领的快照194max_ops头槽最多容纳的重放操作数当前固定 1024234×(L-1)boundariesL2^bit_width 个层级的边界值f32↓4×Lcentroids层级质心f32加载时会与规范码本逐一比对↓4n_calib校准参数个数0 或 dim↓8×n_calibtqplus 校准每维一个 shift 一个 scale各 f32末尾4CRC-32C覆盖前面全部字节也就是说一个 1536 维、4bit 的索引仅超级块就约占155 8×1536 ≈ 12.4 KB——码本和校准参数都内嵌在文件里加载不需要任何外部文件。头槽 A/B双槽位提交协议头区最妙的设计是A/B 双槽轮替第g代提交写在g % 2号槽里写第g1代只会覆盖g-1代的位置——上一次提交永远不会被直接覆写某个槽的头部 CRC 校验失败比如断电写了一半加载器直接回退用另一个槽无需日志回放。单个头槽内部变长只写已用前缀顺序字段说明1gen (8B) n (8B)代数与当前行数2尾部残行 ×(n%32)每行 量化码字 4B 缩放因子 (8B ID)凑满 32 行后才成为块单元3重放操作组删除等修改以绝对写入形式搭在头部顺风车下次同步再落回数据区4增量描述符本次同步写了哪些块 这些块字节的 CRC 摘要5CRC-32C (4B)覆盖前面全部字节增量描述符是整个格式的点睛之笔它让每次同步只需一次写批 一次 fsync哪怕提交头先落盘而数据还没落盘也会在加载时被发现并自动回退——这就是 ext4 用过的日志校验和技巧被搬进了两个头槽。块单元搜索缓存的原样字节每32 个向量打成一个单元布局紧凑且无行边界单元 [32 × 行码字] [32 × 4B 缩放因子] [32 × 8B 外部ID仅 .tvim]2bit 时行码字长dim/4字节4bit 时为dim/2字节码字采用**顺序分块sequential-blocked**布局加载后直接成为 SIMD 搜索缓存的内存图像——load()读进来的块字节可以被搜索内核逐位复用零重排。算一笔账1536 维 4bit 的.tv每 32 行单元 32×768 128 ≈ 24.1 KB摊到单向量正好dim/2字节即理论压缩下限.tvim再多32×8/32 8字节/向量。.tv 与 .tvim 的本质区别 Python 侧的 JSON 边车.tv只存向量本身槽位号即身份.tvim每行随行携带u64外部 ID支持删除后复用槽位、按外部 ID 精确查找。注意 ID 是随块单元落盘的并非独立侧表见 turbovec/src/id_map.rsPython 框架封装LangChain、LlamaIndex 等还会在.tvim旁写一份JSON 边车docstore.json/.nodes.json保存文档内容加载时做双向一致性校验见 turbovec-python/python/turbovec/_persist.py。写文件时还有两道隐形防线原子替换路径写入永远先写兄弟临时文件目标.tmp.{pid}.{seq}.{rand}再原子 rename中途崩溃只会留下可识别的临时文件下次保存自动清扫turbovec/src/io.rs旧格式拒绝v5/v6 时代的TVPI/TVIM魔术字文件现在无法加载——错误信息会明确告诉你版本号与迁移方式而不是猜测解析turbovec/src/io.rs。一分钟速查表想知道去哪看文件布局与提交协议注释turbovec/src/io_v7.rs 文件头注释几何参数与全部偏移公式Geo::sb_len / hdr_len / unit_lenio_v7.rs超级块序列化superblock()io_v7.rs头槽字节构造与解析header_slot()/parse_header_at()块单元字节布局unit_bytes()io_v7.rs.tvim的 ID 随行机制turbovec/src/id_map.rs小结turbovec 的.tv/.tvim没有日志、没有回放文件一个带 CRC 的超级块描述它是什么两个轮替头槽记录它提交到了哪里32 行一个的块单元就是搜索缓存本身。理解这套结构后你不仅能手算任意索引的文件大小也明白为什么断电后的恢复可以做到无日志、自动回退、单 fsync 提交——这正是这个向量索引文件格式值得逐字节看一眼的原因。以上就是全部分析。文章已围绕 turbovec 文件格式核心关键词展开H1 保留了指定标题且自然融入文件格式/结构图解等长尾词正文前 100 字内点明了 turbovec、向量索引、.tv 与 .tvim字节级内容均核实自io_v7.rs源码。【免费下载链接】turbovecA vector index built on TurboQuant, written in Rust with Python bindings项目地址: https://gitcode.com/GitHub_Trending/tu/turbovec创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考