项目定位与核心能力

Zvec 是一款开源、进程内（in-process）向量数据库，主打轻量、极速，可作为库直接嵌入到各类应用中。README 中明确指出，它"已在阿里巴巴集团内部经过大规模生产验证，能够提供生产级、低延迟、可扩展的相似性搜索能力，几乎无需任何额外配置即可投入使用"。资料来源：README.md:1-15

围绕这一目标，Zvec 提供了以下核心能力：

• 多种向量索引：内建 HNSW、DiskANN 等可从内存扩展到磁盘的向量索引类型，可根据数据规模与硬件条件灵活选型。资料来源：README.md:20-30
• 全文本搜索（FTS）：自 v0.5.0 起，原生支持在任意字符串字段上挂载 FTS 索引，并提供自然语言或结构化表达式查询。资料来源：README.md:32-40
• 混合检索（Hybrid Search）：在同一次 MultiQuery 中融合稠密向量、稀疏向量、标量过滤与文本条件。资料来源：README.md:40-50
• 持久化与并发：基于预写日志（WAL）的持久化保证断电不丢数据；多进程可同时读、写入互斥。资料来源：README.md:55-65
• 跨平台运行：作为进程内库，Zvec 可运行在笔记本、服务器、CLI 工具乃至边缘设备上，目前在 Linux、macOS、Windows、Android、iOS 均有官方分发包。资料来源：README.md:70-80

系统分层与模块结构

Zvec 的代码组织以 src/db/common 为公共基础层，向下封装 RocksDB、Roaring Bitmap、Cgroup 探测、Profiler 等基础设施，向上为集合（Collection）、SQL 引擎、索引框架等核心模块提供一致的状态、错误与线程模型。资料来源：src/db/common/CMakeLists.txt:1-15

graph TD
    A[多语言 SDK<br/>Python / Node / Go / Rust / Dart] --> B[核心 C++ API<br/>Collection / Query]
    B --> C[SQL 引擎与查询计划]
    C --> D[索引框架<br/>HNSW / DiskANN / FTS]
    B --> E[公共基础层 db/common]
    E --> F[RocksDB 列族存储]
    E --> G[Roaring Bitmap<br/>并发位图]
    E --> H[Cgroup 资源探测]
    E --> I[Profiler / Logger]
    D --> J[向量相似度计算<br/>含 AVX 分发]

公共基础层在构建时被编译为 zvec_common 静态库，并通过 ALWAYS_LINK 强制被链接，显式依赖 glog、ailego、roaring、rocksdb 等第三方库。资料来源：src/db/common/CMakeLists.txt:5-12

公共基础组件详解

线程与资源管理

GlobalResource 维护两个由 ailego::ThreadPool 实现的进程级单例线程池，分别用于查询（query_thread_pool_）和后台优化任务（optimize_thread_pool_）。initialize() 在首次访问时被调用，实现懒加载，避免启动阶段产生不必要的开销。资料来源：src/db/common/global_resource.h:13-30

类型、日志与 Profiler

typedef.h 定义了 idx_t（即 uint64_t）等基础类型，并提供 CLOG_DEBUG/INFO/WARN/ERROR/FATAL 等与 collection 名称绑定的日志宏，使日志输出天然携带 collection 上下文。资料来源：src/db/common/typedef.h:21-50

Profiler 类在启用时使用 ailego::JsonObject 树收集查询各阶段延迟，配合 Stage 对象的 RAII 计时（ailego::ElapsedTime），可在作用域结束时自动累加耗时。资料来源：src/db/common/profiler.h:33-55

存储与数据结构

RocksdbContext 是一个轻量封装，通过 Args 结构描述库路径、列族名称、自定义 Merge Operator，并支持按列族粒度配置 per_cf_merge_ops，便于针对不同列族（向量、标量、FTS）使用不同的合并策略。资料来源：src/db/common/rocksdb_context.h:25-45

ConcurrentRoaringBitmap32 在 roaring_bitmap 之上叠加读写互斥，提供线程安全的位图操作，常用于标量索引和删除标记。资料来源：src/db/common/concurrent_roaring_bitmap.h:27-45

FileID 枚举与 GetFileName() 映射定义了集合的物理文件命名约定，包括 idmap、del、data.fwd、data.pxa、segment、wal 等核心文件类型。资料来源：src/db/common/file_helper.h:21-60

资源探测与错误体系

CgroupUtil 在 Linux/macOS/Windows 三类平台上分别使用 sysinfo、mach 或 Windows API 获取 CPU 限额、内存限额与运行时长，是 DEFAULT_MEMORY_LIMIT_RATIO = 0.8 等内存策略的输入来源。资料来源：src/db/common/cgroup_util.h:14-50、资料来源：src/db/common/constants.h:25-30

ErrorCode 采用集中注册方式：Code 构造时将自身插入到全局 map_，外部通过 PROXIMA_ZVEC_ERROR_CODE_DECLARE 宏声明、PROXIMA_ZVEC_ERROR_CODE 宏引用，错误码按区间划分（0~999 内置、1000~1999 通用、2000+ 集合相关）。资料来源：src/db/common/error_code.h:21-90

constants.h 还集中了集合名/字段名/主键的正则约束（COLLECTION_NAME_REGEX 长度 3-64，FIELD_NAME_REGEX 长度 1-32），以及 kSparseMaxDimSize = 16384、COMPACT_DELETE_RATIO_THRESHOLD = 0.3 等运行时硬限制。资料来源：src/db/common/constants.h:30-60

LogUtil::Init 支持 file 类型 logger，会自动创建缺失的日志目录，并将初始化结果包装为 Status 返回，便于上层进行错误传播。资料来源：src/db/common/logger.h:25-40

已知问题与社区关注点

围绕 Zvec 概览与系统架构，社区中受到较多关注的几类话题如下：

• CPU 指令集兼容：Node SDK 在构建时启用了 AVX 优化，但部分老旧 CPU 不支持，会导致启动崩溃。资料来源：Issue #512
• 索引生命周期缺陷：在标量字段上调用 drop_index() 后，对应的 RocksDB column family（例如 category$TERMS）未彻底清理，再次 create_index() 时会触发空消息的 ValueError，提示公共基础层在列族管理上仍有改进空间。资料来源：Issue #427
• 多平台分发：Windows 平台支持已在 v0.3.0 合入，Python 3.13/3.14 的 wheel 也在后续版本中提供，体现出 Zvec "Runs Anywhere" 的设计目标。资料来源：Issue #23、资料来源：Issue #131
• 多语言绑定：除官方 Python/Node/Dart 之外，社区与官方正推进 Go、Rust、Elixir 等更多绑定，使 C++ 公共基础层得以被更广泛复用。资料来源：Issue #61、资料来源：Issue #403

See Also

• 项目首页与快速开始
• 公共基础组件 API 参考
• 错误码与状态处理体系
• 线程池与全局资源
• 集合与索引生命周期

一、模块定位与能力边界

Zvec 在 v0.5.0 中将检索能力扩展为三大支柱：稠密/稀疏向量检索、原生全文检索（FTS） 与混合检索（Hybrid Retrieval），三者共用同一份 Schema 与同一个 Collection 实例，使用方可在一次 MultiQuery 中把稠密向量、稀疏向量、结构化标量过滤与全文条件融合 README.md。这种"一库多模"的定位，让 Zvec 既能承担 RAG 召回，也能承担关键字检索与多路召回融合，无需引入额外的 Elasticsearch / OpenSearch 等外部组件。

二、向量索引家族

README 将索引分为"内存到磁盘"的多档选择，社区讨论（#199、#23）与发布说明（v0.4.0、v0.5.0、v0.5.1）也反复强调索引选型与平台兼容性。Zvec 提供的向量索引类型（按用途分组）：

• HNSW：图算法，擅长高召回、低延迟；v0.1.1 明确 m 为上层最大邻居数，并把 scaling_factor 默认改为 m 而非 50，需重建索引才能升级 v0.1.1 Release Notes。
• HNSW + RaBitQ：在 HNSW 图上叠加 RaBitQ 二值化量化，进一步压缩内存。
• IVF：倒排文件结构，适合大批量、训练集完备的场景。
• DiskANN：v0.5.0 新增的磁盘索引，将索引主体落盘，显著降低内存占用，专为十亿级向量设计 v0.5.0 Release Notes。

底层存储由 RocksDB 承担，每个字段（含标量与向量）通常对应一个 Column Family；索引参数通过 JSON 配置载入，由 src/core/interface/utils/utils.h 中的 extract_enum_from_json 模板统一解析。索引创建/删除通过 Collection::CreateIndex / DropIndex 暴露给 SDK，这与 FTS、向量索引的索引生命周期管理是一致的（见 v0.5.0 Release Notes）。

三、全文检索（FTS）

FTS 在 v0.5.0 中以一等公民形式引入：开发者只需为任意 string 字段挂载 FTS 索引，就能用自然语言或结构化表达式查询 README.md。其内部实现位于 src/db/index/column/fts_column/，主要组件包括：

• fts_indexer.h：分词、倒排表与可持久化索引结构；
• bm25_scorer.h：BM25 评分器，将关键字命中与文档长度归一化结合。

由于 FTS 复用与向量索引相同的 CreateIndex / DropIndex 入口，社区已经发现了一个与之相关的回归：在标量字段上调用 drop_index() 后再次 create_index() 会因 RocksDB Column Family 未清理而抛出空消息 ValueError（issue #427）——这提醒我们，所有索引（向量、标量、全文）都应被视为同级别的索引对象，遵循一致的清理流程。

四、混合检索（Hybrid Retrieval）

混合检索并非新增一种物理索引，而是在 MultiQuery 之上对四类子句做并行打分与融合：

flowchart LR
  A[MultiQuery] --> B[稠密向量打分]
  A --> C[稀疏向量打分]
  A --> D[BM25 全文打分]
  A --> E[标量过滤剪枝]
  B --> F[RRF / 加权融合]
  C --> F
  D --> F
  E --> F
  F --> G[Top-K 结果]

并发执行依托于 GlobalResource 单例维护的查询线程池与优化线程池，跨实例共享以避免重复创建开销；请求级延迟则由 Profiler 按"Stage"分段记录，可输出 JSON 形式的火焰数据，便于定位向量打分或 BM25 阶段的瓶颈。v0.5.1 还新增 SearchPrefetch 配置，让调用方显式控制预取行为 #490 / v0.5.1 Release Notes。

五、配置、常量与常见失败模式

底层常量集中在 src/db/common/constants.h：

• 集合名 ^[a-zA-Z0-9_-]{3,64}$、字段名 ^[a-zA-Z0-9_-]{1,32}$，命名不合规会在建表阶段被拒绝；
• DEFAULT_MEMORY_LIMIT_RATIO = 0.8f 与 MIN_MEMORY_LIMIT_BYTES = 100MB 共同决定向量化时段的内存上限；
• COMPACT_DELETE_RATIO_THRESHOLD = 0.3f 控制段文件触发压缩的删除比例。

工程化层面有两类已知陷阱值得提前规避：

1. CPU 指令集不匹配：issue #512 报告在不支持 AVX 的老旧 CPU 上，Node SDK（Bun + Hono.js 场景）会崩溃；构建机支持 AVX 并不代表目标机支持，建议在分发前给出非 AVX 兜底包，或在启动时通过 cpu flag detect & dispatch 能力优雅降级（v0.1.0 PR #3）。
2. 索引生命周期残留：issue #427 反映 drop_index() 后 Column Family 未清理，导致同名重建失败；建议在 SDK 侧捕获异常并显式调用一次 Compact，或等待官方修复。

六、相关模块一览

• 通用框架：src/db/common/（含常量、错误码、RocksDB 上下文、Profiler、文件辅助）
• 索引实现：src/core/algorithm/{hnsw,ivf,diskann,hnsw_rabitq}/
• 全文实现：src/db/index/column/fts_column/
• 公共工具：src/core/interface/utils/utils.h、src/db/common/utils.h

See Also

• README.md — 总体特性与安装
• v0.5.0 Release Notes — FTS、Hybrid、DiskANN 介绍
• v0.5.1 Release Notes — External Vector Source、VectorViewClause
• Issue #427 — drop/create 索引 Column Family 残留
• Issue #512 — 老旧 CPU 上的 AVX 崩溃
• Issue #199 — 多语言 FTS + 混合检索

概述

Zvec 是一个进程内（in-process）向量数据库，核心由 C++ 编写，并以"通用接口 + 跨语言绑定 + AI 扩展"三层结构对外提供服务。src/db/common 目录中的公共组件是连接 C++ 内核与各语言 SDK 的桥梁，它们负责统一错误码、配置常量、日志、线程池、性能分析、RocksDB 上下文与文件命名等横向能力。资料来源：src/db/common/error_code.h:1-60 资料来源：src/db/common/CMakeLists.txt:1-12

围绕这一核心，Zvec 提供了多语言 SDK 与绑定，覆盖 Python、Node.js、Go、Rust、Dart/Flutter 等运行时；并通过 AI 扩展框架支持在客户端侧完成嵌入计算（embedding）、Jina/OpenAI 等第三方模型接入，以及与全文本、向量、标量过滤的混合检索。

flowchart LR
  A[应用层: Python/Node/Go/Rust/Dart] --> B[语言绑定层<br/>SWIG / FFI / C ABI]
  B --> C[核心接口层<br/>src/core/interface]
  C --> D[公共组件层<br/>src/db/common]
  D --> E[存储/索引引擎<br/>HNSW / DiskANN / RocksDB]
  E --> F[MMap + WAL + Bitmap]
  A -.可选.-> G[AI 扩展层<br/>Embedding / FTS / Hybrid]
  G --> A

核心引擎与公共绑定基础

类型与全局资源

所有跨语言绑定最终都落到 typedef.h 中定义的通用类型与日志宏，例如 idx_t（64 位行号别名）和 CLOG_* 系列日志宏。资料来源：src/db/common/typedef.h:24-46 这意味着 Python、Node、Go 等 SDK 在传递查询参数与日志时，会在 FFI 边界上把它转换回 C++ 等价类型。

全局线程池、查询线程池与优化线程池由单例 GlobalResource 管理，并在绑定层首次调用时惰性初始化。资料来源：src/db/common/global_resource.h:14-44 这一设计让绑定层在跨线程调用查询与重建索引时无需关心线程生命周期。

错误码与常量

ErrorCode::Code 体系使用「负值 + 描述」的集中注册模式，覆盖 0~999 内置错误、1000~1999 通用错误（RuntimeError、InvalidArgument、OpenFile、ExceedLimit 等）以及 2000 以上的领域错误。资料来源：src/db/common/error_code.h:1-87 任何语言 SDK 的异常最终都需要把这些错误码翻译为本地异常类型。

constants.h 中定义的关键常量同样通过绑定层暴露，例如内存上限比例 DEFAULT_MEMORY_LIMIT_RATIO = 0.8f、最小内存上限 100MB、稀疏向量最大维度 kSparseMaxDimSize = 16384、最大记录批 kMaxRecordBatchNumRows = 4096，以及集合名/字段名/DocPK 的合法正则。资料来源：src/db/common/constants.h:23-56 这些常量通常用于在绑定层进行前置校验，避免不必要的 JNI/FFI 跨越。

日志与性能分析

日志使用 ailego 抽象，并通过 LogUtil::Init 支持文件/控制台两种 logger 工厂。资料来源：src/db/common/logger.h:18-37 glogger.h 进一步将 Google glog 接入到同一抽象下，方便需要与 protobuf 生态共用的项目。资料来源：src/db/common/glogger.h:1-30 SDK 在调试模式下可注册回调，把 C++ 日志转发到 Python 的 logging、Node 的 console 等宿主日志系统。

Profiler 以 JSON 树记录每个查询阶段（Query / Filter / Index）的耗时，对 SDK 暴露的 explain 调试接口至关重要。资料来源：src/db/common/profiler.h:1-50

存储与文件命名

RocksdbContext 把每个字段（向量、标量、PK、删除位图）映射为独立的 column family，绑定层在创建/删除索引时也通过这层 API 操作 RocksDB。资料来源：src/db/common/rocksdb_context.h:13-60 文件命名由 FileID 枚举统一规定，例如 idmap、data.fwd、data.pxa、segment_*、lsn_*、wal_*，跨语言路径解析都需要遵循此约定。资料来源：src/db/common/file_helper.h:1-40

并发删除与筛选基于线程安全的 32 位 Roaring Bitmap 实现，绑定层在「按位图过滤」的查询中直接消费。资料来源：src/db/common/concurrent_roaring_bitmap.h:1-30

cgroup_util.h 提供跨平台（Linux/macOS/Windows）CPU 与内存限制探测，绑定层在初始化阶段据此决定内存分配与并发度。资料来源：src/db/common/cgroup_util.h:1-35

多语言 SDK 与绑定

SDK 总览

README 列出了官方维护的客户端生态。资料来源：README.md:1-100

第三方扩展还包括基于 C API 的 Elixir SDK（#403）。Windows 平台在 v0.3.0 起得到官方支持，v0.3.1 修复了跨盘符创建集合与错误信息等问题。资料来源：README.md:1-100

绑定层与接口约定

绑定层主要通过 src/core/interface 调用 C++ 实现，再以 SWIG（C/Python）、FFI（Rust/Go/Dart）或动态链接 C ABI 暴露。utils.h 中提供了枚举值与 JSON 字符串的双向解析模板，方便在绑定层自动生成枚举类型。资料来源：src/core/interface/utils/utils.h:1-30 公共组件通过 CMakeLists.txt 中的 cc_library 统一编译为静态库 zvec_common，被各绑定目标链接。资料来源：src/db/common/CMakeLists.txt:1-12

AI 扩展框架与生态

嵌入函数与外部向量源

v0.2.0 引入 AI 扩展框架，支持端侧嵌入工作流；v0.2.1 进一步加入 Jina Embeddings v5 与自定义嵌入函数能力。绑定层允许把 EmbeddingFunction 实现注册到 SDK，在 insert/upsert 之前自动把字符串字段转换为向量。v0.5.1 新增「外部向量源（External Vector Source）」，让数据在外部计算好向量后只写入 ID，从而支持更灵活的数据采集与检索链路。

全文本搜索与混合检索

v0.5.0 起，Zvec 在任何字符串字段上可附加 FTS 索引，通过 Collection::CreateIndex / DropIndex 管理。MultiQuery 在单次请求中融合 dense vector、sparse vector、标量过滤与全文本条件，实现真正意义上的混合检索。社区（#199）就多语言 FTS 与混合搜索提出了具体用例。FTS 索引与倒排索引在底层共享 RocksDB column family，因此 create_index/drop_index 生命周期管理必须正确，否则会出现列族残留（#427）。

零拷贝查询路径

v0.5.1 引入 VectorViewClause，支持零拷贝向量查询路径，并统一了向量查询的校验逻辑。在 FFI 边界上，这意味着宿主语言可以直接传一个内存视图（如 Python memoryview、Rust slice、Go unsafe.Pointer）而无需先做一次拷贝。配合 prefetch 配置可在大批量检索时显著降低端到端延迟。

常见失败模式

• AVX 不支持崩溃：在缺少 AVX 指令集的老旧 CPU 上运行 Node.js SDK 会因 SIMD 加速路径触发非法指令（#512）。解决思路是构建兼容的 baseline 版本或在部署侧屏蔽 AVX 代码路径。
• 索引重建残留：drop_index() 不会清理对应的 RocksDB column family，导致后续 create_index 失败（#427）。绑定层应在 drop 后强制重建 CF 或提示用户重建集合。
• 跨盘符/跨设备路径：Windows 跨盘符创建集合曾在 v0.3.1 之前失败（#337/#340），升级到 v0.3.1+ 即可解决。
• Python 版本不匹配：早期 wheel 仅覆盖 cp313，曾导致 Python 3.10–3.12 用户无法安装（#131），当前已扩展到 3.10–3.14。

See Also

• 核心引擎与存储架构
• 索引类型与算法
• 混合检索与 FTS
• 构建系统与跨平台编译

存储引擎架构

Zvec 的存储由 RocksDB 列族、MMap 前向索引与磁盘 WAL 三层共同支撑。RocksdbContext 是一个轻量封装，用于管理数据库句柄、列族句柄以及每个列族独立的 MergeOperator 资料来源：src/db/common/rocksdb_context.h:18-44。

file_helper.h 用枚举 FileID 定义了集合在磁盘上的全部文件语义，例如 ID_FILE（idmap）、DELETE_FILE（del）、FORWARD_FILE（data.fwd）、PROXIMA_FILE（data.pxa）、WAL_FILE（WAL）、MANIFEST_FILE 等。资料来源：src/db/common/file_helper.h:23-58。下表列出关键文件及用途：

GlobalResource 在进程内以单例形式持有查询线程池与优化线程池，并通过 initialize() 懒加载策略避免提前占用资源。资料来源：src/db/common/global_resource.h:17-35。

平台与 CPU 特性支持

cgroup_util.h 通过条件编译区分 __APPLE__、__linux__ 与 _WIN32 三大平台，分别使用 mach/sysctl、sysinfo/sysconf 与 Windows API 读取 CPU 与内存限额。资料来源：src/db/common/cgroup_util.h:13-21。

CPU 特性调度与社区反馈紧密相关：在 v0.1.0 中已经引入 "cpu flag detect & dispatch"，但 Node.js 预编译包默认发布支持 AVX 的二进制，导致在老旧 CPU 上直接崩溃。资料来源：README.md:51-58、相关 issue #512。

平台支持历史如下（综合 README 与 release notes）：

• v0.3.0 起官方支持 Windows（MSVC 2022+），同时启用 Android 交叉编译。资料来源：README.md:42-58
• v0.3.1 修复了 Windows 跨盘符创建集合与文件路径限制问题。资料来源：v0.3.1 release notes
• v0.4.0 发布 Dart/Flutter SDK，覆盖 Android (arm64-v8a) 与 iOS (arm64)。资料来源：v0.4.0 release notes
• v0.5.0 新增 RISC-V 架构支持并引入 DiskANN 索引。资料来源：v0.5.0 release notes

核心数据结构与并发原语

ConcurrentRoaringBitmap32 在 Roaring 位图基础上以 std::shared_mutex 封装读写并发模型，identifier_ 用于日志定位，bitmap_ 由 roaring_bitmap_create 分配并在析构时释放。资料来源：src/db/common/concurrent_roaring_bitmap.h:27-44。

Profiler 采用嵌套 JSON 树与 Stage RAII 对象，按阶段记录查询延迟，可选启用。资料来源：src/db/common/profiler.h:23-44。LogUtil::Init 与 AppendLogger 共同负责日志目录创建、文件切分以及基于 glog 的文件日志初始化。资料来源：src/db/common/logger.h:23-44、src/db/common/glogger.h:23-44。

constants.h 定义了命名合法性校验、稀疏向量维度上限 (kSparseMaxDimSize = 16384)、批量写入上限 (kMaxRecordBatchNumRows = 4096)、数组字段长度上限 (MAX_ARRAY_FIELD_LEN = 32)、删除压缩阈值 (COMPACT_DELETE_RATIO_THRESHOLD = 0.3f) 等关键常量。资料来源：src/db/common/constants.h:18-44。typedef.h 集中定义 idx_t = uint64_t 以及 CLOG_*/WLOG_* 系列的日志与状态检查宏。资料来源：src/db/common/typedef.h:23-44。

构建层面，zvec_common 静态库依赖 glog、zvec_ailego、roaring 与 rocksdb，并在 CMakeLists.txt 中显式声明 ALWAYS_LINK。资料来源：src/db/common/CMakeLists.txt:3-16。

graph TD
    A[Application / SDK] --> B[GlobalResource]
    B -->|query/optimize| C[ThreadPool]
    A --> D[Collection]
    D --> E[RocksdbContext]
    D --> F[MMap Forward Store]
    D --> G[WAL + Segments]
    E --> H[(idmap / manifest / data.pxa)]
    F --> I[(data.fwd)]
    G --> J[(WAL files)]
    D --> K[ConcurrentRoaringBitmap32]
    D --> L[Profiler / Logger]

常见故障与社区反馈

1. AVX 缺失导致崩溃（Issue #512）：Node.js 预构建包默认使用 AVX 指令集，在不支持 AVX 的老旧 CPU 上会出现 SIGILL。临时方案是在目标机器上用 bun + hono.js 重新构建或等待官方发布非 AVX 版本。
2. drop_index 后 RocksDB 列族残留（Issue #427）：对标量字段执行 drop_index() 后，category$TERMS 等列族未被彻底清理，再次 create_index() 会抛出空消息的 ValueError。建议在调用前显式 compact() 或升级到包含 RocksDB 列族回收修复的版本。资料来源：src/db/common/rocksdb_context.h:18-44。
3. Windows 路径与跨盘符问题：v0.3.1 之前集合路径受限，且无法跨盘符创建；升级到 v0.3.1+ 可解决。资料来源：v0.3.1 release notes
4. Python 版本支持（Issue #131）：早期 wheel 仅支持 Python 3.13+；当前 README 已声明 python-3.10 ~ 3.14。资料来源：README.md:42-58

See Also

• README.md — 项目总览与平台矩阵
• v0.5.0 / v0.4.0 / v0.3.1 / v0.3.0 / v0.2.1 Release Notes — 版本演进
• Issue #512、#427 — 旧 CPU 兼容与索引重建故障参考

Pitfall Log / 踩坑日志

项目：alibaba/zvec

摘要：发现 9 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Bug]: 在老旧的机器上使用zvec导致奔溃。

1. 安装坑 · 来源证据：[Bug]: 在老旧的机器上使用zvec导致奔溃

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: 在老旧的机器上使用zvec导致奔溃
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/alibaba/zvec/issues/512 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

2. 安装坑 · 来源证据：[BUG]: create_index() fails after drop_index() on scalar fields - RocksDB column family not cleaned up

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG]: create_index() fails after drop_index() on scalar fields - RocksDB column family not cleaned up
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/alibaba/zvec/issues/427 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

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

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

4. 运行坑 · 运行可能依赖外部服务

• 严重度：medium
• 证据强度：source_linked
• 发现：项目说明出现 external service/cloud/webhook/database 等运行依赖关键词。
• 对用户的影响：本地安装成功不等于能力可用，外部服务不可用会阻断体验。
• 证据：packet_text.keyword_scan | https://github.com/alibaba/zvec | matched external service / cloud / webhook / database keyword

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

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

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

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

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

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

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

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

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