turbovec 概览与 TurboQuant 算法

1. 项目定位与核心价值

turbovec 是一个基于 Rust 实现的向量索引库，并提供 Python 绑定，底层算法来自 Google Research 提出的 TurboQuant —— 一种"数据无关"（data-oblivious）的量化器，能够在不进行独立训练的前提下，将高维向量压缩到每个坐标 2~4 bit，且具有接近最优的失真度。资料来源：README.md、turbovec/src/lib.rs:1-9。

项目的核心价值主张是极高的内存压缩比与速度优势：以 float32 存储的 1000 万条 1536 维文档语料需要约 31 GB 内存，而 turbovec 可以将其压缩到约 4 GB，并且在搜索速度上比 FAISS 更快（ARM 平台下对 FAISS IndexPQFastScan 领先 10%~19%，x86 平台的 4-bit 配置同样胜出）。资料来源：README.md。

主要特性包括：

• 在线摄入（Online ingest）：向量加入后立即被索引，无需训练步骤、参数调优或重建过程。资料来源：README.md、turbovec/src/lib.rs:11-31。
• SIMD 加速搜索：手写 NEON（ARM）与 AVX-512BW（x86）内核。资料来源：README.md。
• 搜索时过滤：search() 可接受 id 白名单或槽位位图，查询内核会直接按其过滤。资料来源：README.md。
• 完全本地化：无托管服务，数据不离开本机或 VPC。资料来源：README.md。

2. TurboQuant 算法与文件格式

2.1 算法基础

TurboQuant 是 Google Research 在论文 *"TurboQuant"*（arXiv:2504.19874）中提出的量化方法。turbovec 将其工程化为可立即使用的向量索引：高维向量通过旋转矩阵降维到偶数维，再借助 Lloyd-Max 质心进行 2/3/4 bit 量化。资料来源：turbovec/src/lib.rs:1-9。

代码库中关键的可调用缓存（旋转矩阵、Lloyd-Max 质心、SIMD 对齐的码字布局）通过 [std::sync::OnceLock] 实现惰性初始化：第一次调用 search 时支付一次性初始化成本，之后所有调用者无锁读取；用户也可以显式调用 prepare() 在 add/load 之后提前完成初始化。资料来源：turbovec/src/lib.rs:33-50。

2.2 文件格式

turbovec 定义两种磁盘格式，版本均为 3（turbovec 0.6.x 引入 TQ+ per-coord 校准）：

版本兼容策略：v2 文件透明加载，标定字段视为空；v1 文件因缺少魔数头会被拒绝并提示重建。资料来源：turbovec/src/io.rs:1-20。

flowchart LR
    A[float32 向量] --> B[TurboQuant 编码]
    B --> C[.tv 索引文件]
    C --> D[TurboQuantIndex / IdMapIndex]
    D --> E[SIMD 距离计算]
    E --> F[Top-k 结果 + 过滤]

3. 主要组件与 API

Rust 端对外暴露的核心类型是 TurboQuantIndex 与 IdMapIndex。前者适合内部槽位编号即可满足需求的场景；后者为每个向量维护一个外部 u64 id，支持 remove(id) 的 O(1) 删除与稳定的 id 映射。资料来源：turbovec/src/lib.rs:1-31、turbovec-python/README.md。

Python 入口从 _turbovec 直接导出这两个类：

from turbovec import TurboQuantIndex, IdMapIndex

资料来源：turbovec-python/python/turbovec/__init__.py。

典型用法分为三步：构造（指定 dim 与 bit_width，可选 2/4）→ 累计 add 向量 → 调用 search(query, k) 取得 (scores, indices)。带 id 的版本使用 add_with_ids(vectors, ids)，并可使用 search(..., allowed=...) 进行"混合检索"——即先用外部系统（SQL/BM25/ACL/时间窗口）缩小候选集合，再由 turbovec 在该集合内重排。资料来源：turbovec-python/README.md。

4. 框架集成与生态

turbovec 提供对主流 LLM 检索框架的适配，所有适配器均通过 IdMapIndex 作为后端以保留稳定 id：

• Haystack 2.x：TurboQuantDocumentStore 实现 DocumentStore 协议，覆盖 write/filter/delete、embedding_retrieval、save_to_disk/load_from_disk、管线 to_dict/from_dict，但未实现 BM25 稀疏检索。资料来源：turbovec-python/python/turbovec/haystack.py:1-19。
• LangChain：TurboQuantVectorStore 参考 InMemoryVectorStore 接口，提供 add_texts / aadd_texts / from_texts / afrom_texts，并把内积相似度映射到 [0, 1] 相关性区间。资料来源：turbovec-python/python/turbovec/langchain.py。
• LlamaIndex：将 BaseNode 的 text、metadata、ref_doc_id 与 node_dict（用于 metadata_dict_to_node 重建为完整 BaseNode 子类）一并存储，使检索结果可还原成 TextNode/IndexNode/ImageNode。资料来源：turbovec-python/python/turbovec/llama_index.py。
• Agno：TurboQuantVectorDb 强制 search_type=SearchType.vector 与 distance=Distance.cosine，bit_width 仅接受 2 或 4，并要求 Embedder.dimensions 必须事先设置。资料来源：turbovec-python/python/turbovec/agno.py。

在 examples/downstream-smoke/src/main.rs 中提供了一个端到端的最小用例：构造索引 → 写入 → 重新加载 → 搜索，作为"下游 cargo add turbovec"的烟雾测试，确保 build.rs 的链接指令传播正确。资料来源：examples/downstream-smoke/src/main.rs:1-9。

See Also

• 文件格式与版本迁移（见 turbovec/src/io.rs）
• 框架集成（Haystack / LangChain / LlamaIndex / Agno）适配细节
• 贡献流程（见 CONTRIBUTING.md）与安全策略（见 SECURITY.md）

概述

turbovec 是一个面向向量检索的标量量化（TurboQuant）索引库，其核心 Rust crate 同时维护两类索引对象（TurboQuantIndex 与 IdMapIndex）与两套对应的二进制文件格式（.tv 与 .tvim）。量化位宽支持 2/3/4 bits，配合 AVX-2、AVX-512BW、NEON 等 SIMD 路径实现近似最近邻（ANN）打分。Python 端的 LangChain / LlamaIndex / Haystack 等集成只持有 IdMapIndex 的二进制文件加 JSON 侧车，因此底层二进制布局存在明确的契约约束 资料来源：turbovec/src/io.rs、turbovec-python/python/turbovec/langchain.py。

索引类型

TurboQuantIndex

TurboQuantIndex 是核心量化索引对象。from_parts 显式钉死了几条结构性不变量，例如 TQ+ 校准向量的 shift 与 scale 长度必须相等（要么为空、要么等于 dim），从而把"重建索引时这些字段必须自洽"提升到类型层面 资料来源：turbovec/src/lib.rs。其主要字段包括：

• bit_width: usize：每维编码位宽（2/3/4）；
• dim: Option<usize>：在尚未触发编码的"懒构造"状态下可能为 None，落盘时记为 0；
• n_vectors: usize；
• packed_codes: Vec<u8>、scales: Vec<f32>；
• tqplus_shift: Vec<f32>、tqplus_scale: Vec<f32>：v3+ 引入的 per-coord 校准参数。

IdMapIndex

IdMapIndex 在 TurboQuantIndex 之上追加一个 slot_to_id: Vec<u64> 表，把每个内部槽位映射回外部字符串/整数 ID，从而支撑 LangChain / LlamaIndex 集成所需的 O(1) 删除、按 ref_doc_id 过滤等能力 资料来源：turbovec-python/python/turbovec/langchain.py、turbovec-python/python/turbovec/llama_index.py。

编码流水线

源向量到打包字节的完整数据通路为：

1. 旋转：使用 rotation::make_rotation_matrix 生成的随机正交矩阵降低各维相关性 资料来源：turbovec/examples/dump_state.rs；
2. 码本：每个维度独立的 Lloyd-Max 码本（codebook::codebook），共 2^bits 个质心 资料来源：turbovec/examples/dump_state.rs；
3. 量化：每维坐标就近映射到对应码字，得到 bits-wide 整数码；
4. 归一化：每个向量维护一个 scale，与 packed_codes 一起决定最终的相似度近似；
5. TQ+ 校准（v3+）：按维度额外保存 shift/scale，向后兼容 v2 时该区段为空、视为恒等 资料来源：turbovec/src/io.rs；
6. 打包：pack_blocked 将每 BLOCK 个向量按字节拆成高/低半字节并以 perm0 交织为 FAISS 风格布局，匹配 SIMD 内核读法 资料来源：turbovec/src/pack.rs；
7. 标量回退：deinterleave_x86_code_byte 反向解交织，使非 x86 路径或缺少 AVX2 的虚拟机不会读到错误字节（修复 issue #106） 资料来源：turbovec/src/pack.rs。

文件格式与持久化

二进制格式

库内两套格式统一由 io.rs 维护：

资料来源：turbovec/src/io.rs。

版本演进

• v1（turbovec ≤ 0.4.3）：无 magic，首字节即 bit_width，已被视为不兼容，遇到时给出"重建"提示；
• v2（0.4.4 – 0.6.0）：引入 magic + version；TQ+ 区段为空，按"恒等校准"透明加载，召回不变；
• v3（0.6.x 起）：追加 TQ+ per-coord 校准。

dump_state 示例工具按 (dim, bits) 把旋转矩阵与 Lloyd-Max 码本以裸 little-endian f32 写出（rotation / boundaries / centroids 三段），可被 np.fromfile 直接读入，用作跨实现的逐字节对照 资料来源：turbovec/examples/dump_state.rs。

Python 集成侧的侧车契约

Python 集成把"二进制 IdMapIndex + JSON 侧车"作为约定：LangChain 放在同一目录下（index.tvim + docstore.json，侧车带 _DOCSTORE_SCHEMA_VERSION），LlamaIndex 按用户传入的 persist_path 拆为 <base>.tvim + <base>.nodes.json，同样记录 _NODES_SCHEMA_VERSION。侧车使用纯 JSON（不依赖 pickle），因此不存在反序列化执行任意代码的风险 资料来源：turbovec-python/python/turbovec/langchain.py、turbovec-python/python/turbovec/llama_index.py。

常见失败模式

• 加载 v1 .tv 文件：不会崩溃，但首字节会被识别为"看起来像 v1 turbovec 文件"，并提示重建 资料来源：turbovec/src/io.rs；
• tqplus_shift.len() != tqplus_scale.len() 或长度非 0 且非 dim：from_parts 触发断言 资料来源：turbovec/src/lib.rs；
• 缺少 AVX2 的 x86 主机上若未走标量回退，会读到错误字节（issue #106），务必通过 deinterleave_x86_code_byte 路径解码 资料来源：turbovec/src/pack.rs。

See Also

• 仓库根 README.md：总体介绍与构建/基准测试说明
• CONTRIBUTING.md：贡献流程与集成贡献规范
• turbovec/src/search.rs：SIMD 搜索内核与允许位掩码（block_has_allowed、block_pair_has_allowed）

概述与定位

turbovec 是一套基于 Rust 的在线向量量化实现（TurboQuant 论文的核心思想），通过 PyO3 暴露给 Python 作为扩展模块，并在此基础上为多个主流 LLM 编排框架提供"即插即用"的向量存储后端。其总体设计目标可以概括为三点：第一，把量化后的紧凑索引与原始文本/元数据解耦，避免反序列化代码执行风险；第二，让上层框架无需修改业务代码即可替换为量化存储；第三，对每个集成显式标注"参考实现"，确保行为一致 README.md:1-30。

Python 包按可选依赖（extras）拆分为 langchain、llama-index、haystack、agno 等子模块，每个子模块对应一个独立的 VectorStore / DocumentStore 实现 CONTRIBUTING.md:60-72。

核心绑定层：PyO3 与 Rust 端

绑定层由 turbovec-python/src/lib.rs 中的 PyO3 实现承担，对外暴露的核心类型是 IdMapIndex。其 search 方法签名采用 #[pyo3(signature = (queries, k, *, allowlist=None))] 形式，返回 (scores, ids) 二元组，分别以 (nq, effective_k) 形状的 f32 与 uint64 数组返回；空 allowlist 会直接抛 ValueError，未在索引中的 id 会抛 KeyError turbovec-python/src/lib.rs:1-40。

build.rs 仅做一件关键事：调用 pyo3_build_config::add_extension_module_link_args()，在 macOS 上注入 -undefined dynamic_lookup，使得在没有 maturin 的情况下 cargo build 也能正确解析 Py_True 等解释器符号（修复 issue #92）turbovec-python/build.rs:1-15。

框架集成层

LangChain

turbovec.langchain.TurboQuantVectorStore 实现了 langchain_core.vectorstores.VectorStore，对外与内置的 InMemoryVectorStore 完全对齐：构造时可传入已有的 IdMapIndex，或延迟到首次 add_texts 时创建 turbovec-python/python/turbovec/langchain.py:1-60。

搜索路径将查询嵌入到 np.float32 数组后走量化索引重建文档；过滤支持 dict 与 callable 两种形式，二者通过内部 lambda 统一求值 turbovec-python/python/turbovec/langchain.py:120-180。需要特别注意的是 MMR（最大边际相关性）搜索不被支持，因量化后全精度向量已被丢弃，无法计算两两多样性；接口在调用时会抛出携带解释信息的 NotImplementedError，而不是静默退回到基类实现 turbovec-python/python/turbovec/langchain.py:90-110。

LlamaIndex

llama_index 模块在节点元数据上做了更细的设计：除了保留 metadata 与 ref_doc_id 用于快速过滤外，还额外存储 node_dict（通过 node_to_metadata_dict 生成的规范元数据），以便在检索时通过 metadata_dict_to_node 重建完整的 BaseNode，从而保留 PREVIOUS / NEXT / PARENT / CHILD 关系、模板字段、起止字符索引与 mimetype turbovec-python/python/turbovec/llama_index.py:1-30。

Haystack 与 Agno

Haystack 集成对照 InMemoryDocumentStore 校验输入形状，并把 Document 列表按 DuplicatePolicy 解析后再批量写入；持久化时把 u64 -> doc 字典序列化为 [handle, data] 对以避免 JSON 键类型损失 turbovec-python/python/turbovec/haystack.py:1-50。

Agno 集成在语义上对齐 LanceDb：upsert 按 content_hash 替换整批文档；为防止"替换失败导致旧数据被销毁"（issue #89），它先捕获旧 handle、写新数据，再删除旧向量 turbovec-python/python/turbovec/agno.py:1-50。

持久化与 Schema 版本

所有集成都遵循统一的"索引 + side-car JSON"持久化策略：index.tvim 由 Rust 端写入，二进制且与语言无关；docstore.json / docstore.json 之类的人类可读文件存储文档、id↔handle 映射、下一可用 u64、以及 bit_width 等元数据 turbovec-python/python/turbovec/langchain.py:1-40、turbovec-python/python/turbovec/llama_index.py:30-60、turbovec-python/python/turbovec/haystack.py:30-60。

每个集成各自定义 _SCHEMA_VERSION 字段（如 LangChain 为 1），load / from_persist_path 在反序列化前先比对 schema_version，遇到未知版本立即抛 ValueError，从而避免向后兼容的隐式假设 turbovec-python/python/turbovec/langchain.py:30-50、turbovec-python/python/turbovec/llama_index.py:30-50。

数据流与组件关系

flowchart LR
    A[Python 业务代码] --> B[框架集成层<br/>langchain / llama_index / haystack / agno]
    B --> C[_dedup / _persist 工具]
    B --> D[IdMapIndex<br/>PyO3 绑定]
    D --> E[Rust 量化核心<br/>TurboQuant]
    C --> F[index.tvim]
    C --> G[docstore.json]
    F --> H[load / from_persist_path]
    G --> H

常见失败模式

See Also

• Building & Testing（构建与测试）
• Benchmarks & Methodology（基准与方法）
• Architecture Overview（架构总览）

性能、构建、部署与运维

概述

turbovec 是一个基于 Google Research 的 TurboQuant 算法的 Rust 向量索引实现，提供 Python 绑定并对接 LangChain、LlamaIndex、Haystack 等主流 LLM 框架。本页围绕项目的性能特征、构建流程、部署形态以及运维验证进行系统梳理，便于使用者快速完成本地构建、跨架构部署与基准回归。

一、性能特征

压缩比与召回

根据 README.md 的描述，1000 万文档语料在 float32 编码下占用约 31 GB 内存，turbovec 可将其压缩至约 4 GB 并保持更快搜索速度。该压缩来自 2–4 bit 每维的量化策略，体现 TurboQuant 算法 "near-optimal distortion" 的工程化结果。

搜索内核

在 x86_64 平台上，turbovec/src/search.rs 同时实现了 AVX2 与 AVX-512 两套打分内核。AVX-512 内核一次处理两个 32 字节码块，通过 _mm512_inserti64x4 与 _mm512_shuffle_epi8 在单指令对中完成查找，并通过 FLUSH_EVERY 间隔刷新至 f32 累加器与 top-k 堆；尾部未配对块以单次 AVX2 内层循环收尾，避免任何 masked AVX-512 逻辑。

基准套件

turbovec-python/README.md 提供了完整的基准脚本集合：

python3 benchmarks/download_data.py openai-1536   # AI DBpedia d=1536
python3 benchmarks/download_data.py openai-3072   # OpenAI DBpedia d=3072
python3 benchmarks/suite/speed_d1536_2bit_arm_mt.py
python3 benchmarks/suite/recall_d1536_2bit.py
python3 benchmarks/suite/compression.py

结果以 JSON 写入 benchmarks/results/，并可通过 python3 benchmarks/create_diagrams.py 重新生成图表。

二、构建流程

Rust 核心库

通过 Cargo 直接构建即可：

cargo build --release

核心入口 turbovec/src/lib.rs 通过 pub fn load 与 pub fn write 完成 .tv 文件读写；from_parts 在构造时强制 tqplus_shift.len() == tqplus_scale.len() 的结构不变式。

Python 绑定

turbovec-python/build.rs 调用 pyo3_build_config::add_extension_module_link_args()，在 macOS 上注入 -undefined dynamic_lookup，避免裸 cargo build 出现 "symbol(s) not found for architecture arm64" 的链接错误（issue #92）。Maturin 构建已自动注入相同参数。

框架集成扩展

CONTRIBUTING.md 指出：新增或修改 LangChain、LlamaIndex、Haystack、Agno 集成时，应在结构上与各框架内树的参考实现（InMemoryVectorStore、SimpleVectorStore、InMemoryDocumentStore 等）保持一致。运行对应集成测试需安装 extras：

pip install -e ".[langchain,llama-index,haystack,agno]"

三、部署形态

文件格式

索引持久化采用 .tvim 量化码本加 JSON 侧车的双文件结构。turbovec/src/io.rs 中 write 写入 TV_MAGIC 与版本字节 TV_VERSION；load 透明处理 v2（无 TQ+）与 v3（含 TQ+）格式，对 v1 无魔数文件以针对性错误区分。

集成适配

三个集成模块共享相似的持久化策略：

turbovec-python/python/turbovec/langchain.py 中的 TurboQuantVectorStore 提供 add_texts、delete、from_persist_path 等接口；turbovec-python/python/turbovec/llama_index.py 在存储节点时同时保留 node_dict，由 metadata_dict_to_node 重建完整的 BaseNode，从而保留 PREVIOUS / NEXT / PARENT / CHILD 关系以及 start/end_char_idx 等字段；turbovec-python/python/turbovec/haystack.py 镜像 InMemoryDocumentStore 的 save_to_disk / load_from_disk 接口，实现 Haystack 2.x DocumentStore 协议。

四、运维与验证

跨架构一致性

turbovec/examples/kernel_xtest.rs 是一个跨架构内核对齐冒烟测试。在 ARM 与 x86 上分别构建运行并对比输出文件一致性，可验证两套打分内核在相同输入下的等价性：

cargo run --release --example kernel_xtest -- <dim> <bits> <seed> > /tmp/out.txt

由于使用固定的 ROTATION_SEED，旋转计算完全确定，不引入数据集或 BLAS 后端噪声。

持久化安全性

三个集成模块均强调侧车文件为纯 JSON 而非 pickle，避免任意代码反序列化风险。langchain.py 的 from_persist_path 显式拒绝 fsspec 文件系统并提示需传入本地路径。

协作约定

CONTRIBUTING.md 明确：每个 PR 一个逻辑变更；提交信息采用短祈使句标题 + 解释 *why* 的正文；引用 issue 时使用 Closes #N；Co-Authored-By: 工具 trailer 可保留；仅维护者合并至 main。

另请参阅

• TurboQuant 论文（arXiv:2504.19874）
• RaBitQ 论文（arXiv:2405.12497）

Pitfall Log / 踩坑日志

项目：RyanCodrai/turbovec

摘要：发现 20 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：安装坑 - 来源证据：Proposal: official Node.js binding (turbovec-node)。

1. 安装坑 · 来源证据：Proposal: official Node.js binding (turbovec-node)

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Proposal: official Node.js binding (turbovec-node)
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/RyanCodrai/turbovec/issues/85 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

2. 安装坑 · 来源证据：TurboVec on Snowpark Container Services (SPCS)

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：TurboVec on Snowpark Container Services (SPCS)
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/RyanCodrai/turbovec/issues/95 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

3. 安全/权限坑 · 来源证据：Add insertion + removal speed benchmarks to benchmarks/suite/

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add insertion + removal speed benchmarks to benchmarks/suite/
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/RyanCodrai/turbovec/issues/65 | 来源类型 github_issue 暴露的待验证使用条件。

4. 安全/权限坑 · 来源证据：Public Read/Write I/O API + pub TurboQuantIndex::from_parts

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Public Read/Write I/O API + pub TurboQuantIndex::from_parts
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/RyanCodrai/turbovec/issues/70 | 来源类型 github_issue 暴露的待验证使用条件。

5. 安装坑 · 来源证据：Proposal: Swift / macOS binding (turbovec-swift)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Proposal: Swift / macOS binding (turbovec-swift)
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/RyanCodrai/turbovec/issues/86 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

6. 安装坑 · 来源证据：TQ+ calibration: silent identity-freeze on small first add; fit from a cumulative warm-up sample

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：TQ+ calibration: silent identity-freeze on small first add; fit from a cumulative warm-up sample
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/RyanCodrai/turbovec/issues/107 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

7. 安装坑 · 来源证据：x86_64 scalar fallback (no AVX2 at runtime) returns incorrect results: reads perm0-interleaved layout as if sequential

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：x86_64 scalar fallback (no AVX2 at runtime) returns incorrect results: reads perm0-interleaved layout as if sequential
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/RyanCodrai/turbovec/issues/106 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

8. 安装坑 · 来源证据：✨ Node.js / TypeScript bindings (turbovec-node)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：✨ Node.js / TypeScript bindings (turbovec-node)
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/RyanCodrai/turbovec/issues/111 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

9. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/RyanCodrai/turbovec | README/documentation is current enough for a first validation pass.

10. 运行坑 · 来源证据：bug: agno insert() orphans vectors on intra-batch duplicate derived doc_ids

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：bug: agno insert() orphans vectors on intra-batch duplicate derived doc_ids
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/RyanCodrai/turbovec/issues/104 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

11. 维护坑 · 来源证据：Docs: API reference drift around bit widths and file formats

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Docs: API reference drift around bit widths and file formats
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/RyanCodrai/turbovec/issues/101 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

12. 维护坑 · 来源证据：proposal: bindings for ruby

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：proposal: bindings for ruby
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/RyanCodrai/turbovec/issues/94 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

13. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/RyanCodrai/turbovec | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/RyanCodrai/turbovec | no_demo; severity=medium

15. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/RyanCodrai/turbovec | no_demo; severity=medium

16. 安全/权限坑 · 来源证据：Security fixes: integer overflow on .tv load + Python NaN query validation

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Security fixes: integer overflow on .tv load + Python NaN query validation
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/RyanCodrai/turbovec/issues/105 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

17. 安全/权限坑 · 来源证据：ask about project

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：ask about project
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/RyanCodrai/turbovec/issues/110 | 来源类型 github_issue 暴露的待验证使用条件。

18. 安全/权限坑 · 来源证据：can not build on mac arm when simple run cargo build

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：can not build on mac arm when simple run cargo build
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/RyanCodrai/turbovec/issues/92 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

19. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/RyanCodrai/turbovec | issue_or_pr_quality=unknown

20. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/RyanCodrai/turbovec | release_recency=unknown