企业官网建设流程全解析

• 向量数据库
• 数据库
• 嵌入式数据库

导读：Zvec 是一款开源的嵌入式（进程内）向量数据库，以极简配置提供生产级、低延迟、可扩展的向量检索能力。本文以官方 README 为骨架，结合仓库内 Python SDK 源码，系统讲解 Zvec 的安装方式、Schema 建模、数据写入、向量/全文/混合检索、索引体系与性能特性，帮助你快速在 Notebook、服务端进程乃至边缘设备中嵌入毫秒级向量检索能力。

Zvec 是什么

Zvec是一款开源的嵌入式（进程内）向量数据库，定位是"轻量、极速、可直接嵌入应用程序"。它不需要单独部署服务进程，而是作为库直接嵌入到你的应用中运行，以极简的配置提供生产级、低延迟、可扩展的向量检索能力。用一句话概括其设计哲学：开箱即用，安装之后即刻开始搜索，纯本地运行，无需服务器、无需配置、零门槛（见 README_CN.md）。

从仓库结构看，Zvec 采用 C++ 核心引擎（src/core/、src/ailego/、src/turbo/）加多语言绑定的架构：src/binding/python/提供 Python 绑定，src/binding/c/提供 C API，并在此基础上衍生出 Node.js、Go、Rust、Dart/Flutter 等官方 SDK，覆盖了从高性能服务器到移动端的主流开发语言。

核心特性一览

根据官方 README 与仓库源码，Zvec 的核心能力可以归纳为以下几点：

• 极致性能：毫秒级响应，可轻松检索数十亿级向量（官方性能报告见仓库 README 引用的 benchmarks 文档）。
• 开箱即用：pip install zvec后即刻开始搜索，纯本地运行，无需服务器与额外配置。
• 稠密 + 稀疏向量：支持稠密向量、稀疏向量与多向量查询，并提供从内存到磁盘的多种向量索引类型。
• 全文检索（FTS）：原生基于关键词的全文检索，可用自然语言或结构化表达式检索字符串字段。
• 混合检索：单次查询中融合向量语义、全文检索与标量过滤，获得精确结果。
• 持久化存储：WAL 预写日志保障数据持久性——即使进程崩溃或意外断电，数据也不会丢失。
• 并发访问：支持多进程同时读取同一个 Collection；写入为单进程独占模式。
• 进程内运行：无需单独部署服务，Notebook、高性能服务器、CLI 工具、边缘设备随处可用。

上述并发与持久化能力在源码中有直接印证：Python 侧Collection的flush()方法会强制将所有待写入数据落盘以确保持久性（见 collection.py），close()会释放集合的文件锁以便路径可被重新打开或删除（见 collection.py）；C++ 侧则由src/db/common/下的 RocksDB 上下文与rocksdb_context.cc等模块支撑 WAL 与存储。

安装与平台支持

多语言 SDK

Zvec 提供多语言官方 SDK：

• Python：pip install zvec（需 64 位 Python 3.10–3.14）
• Node.js：npm install @zvec/zvec
• Go：高性能的 Go 绑定
• Rust：cargo add zvec-rust
• Dart/Flutter：flutter pub add zvec

Python 侧仓库自带的pyproject.toml定义了包的构建与依赖元数据，安装后import zvec即自动加载底层_zvec原生扩展（在 zvec.py 中可以看到它从zvec._zvec导入 C++ 绑定对象）。

支持的平台

• Linux（x86_64、ARM64；glibc 与 musl）
• macOS（ARM64、x86_64）
• Windows（x86_64）

若需从源码构建，可参考仓库根目录的CMakeLists.txt构建体系：cmake/目录下的option.cmake、utils.cmake、bazel.cmake等提供了跨平台构建选项，src/binding/python/CMakeLists.txt与src/binding/c/CMakeLists.txt分别负责 Python 与 C SDK 的编译产出。

一分钟上手：完整 Python 示例

以下是官方 README 中的最小可用示例，完整继承如下：

import zvec # 定义 collection schema schema = zvec.CollectionSchema( name="example", vectors=zvec.VectorSchema("embedding", zvec.DataType.VECTOR_FP32, 4), ) # 创建 collection collection = zvec.create_and_open(path="./zvec_example", schema=schema) # 插入 documents collection.insert([ zvec.Doc(id="doc_1", vectors={"embedding": [0.1, 0.2, 0.3, 0.4]}), zvec.Doc(id="doc_2", vectors={"embedding": [0.2, 0.3, 0.4, 0.1]}), ]) # 向量相似度检索 results = collection.query( zvec.Query(field_name="embedding", vector=[0.4, 0.3, 0.3, 0.1]), topk=10 ) # 查询结果：按相关性排序的 {'id': str, 'score': float, ...} 列表 print(results)

这段代码完整覆盖了 Zvec 的使用闭环：定义 Schema → 创建并打开 Collection → 插入文档 → 向量检索。下面对每一步做源码级拆解。

1. Schema 建模：CollectionSchema / FieldSchema / VectorSchema

Schema 是 Zvec 数据建模的核心。CollectionSchema由名称（name）、标量字段（fields）与向量字段（vectors）构成，字段名在标量与向量之间必须全局唯一（见 collection_schema.py）。

VectorSchema用于定义向量字段，关键参数包括：

• name：向量字段名，须在集合内唯一；
• data_type：向量数据类型，支持VECTOR_FP16、VECTOR_FP32、VECTOR_FP64、VECTOR_INT8，以及稀疏向量SPARSE_VECTOR_FP16、SPARSE_VECTOR_FP32（见 field_schema.py）；
• dimension：稠密向量维度，必须 ≥ 0；稀疏向量维度可为 0；
• index_param：该向量字段的索引配置，默认是FlatIndexParam()（见 field_schema.py）。

FieldSchema用于定义标量字段（如 ID、时间戳、分类标签），支持的类型包括INT32/INT64/UINT32/UINT64、FLOAT/DOUBLE、STRING/BOOL以及各类ARRAY_*数组类型（见 field_schema.py）。标量字段可配置nullable以及倒排索引（InvertIndexParam）或全文检索索引（FtsIndexParam）。

一个更完整的 Schema 建模示例：

from zvec import FieldSchema, VectorSchema, DataType from zvec.model.param import HnswIndexParam, InvertIndexParam, FtsIndexParam schema = zvec.CollectionSchema( name="products", fields=[ FieldSchema("id", DataType.INT64, nullable=False), FieldSchema("category", DataType.STRING, index_param=InvertIndexParam()), FieldSchema("description", DataType.STRING, index_param=FtsIndexParam(tokenizer_name="standard")), ], vectors=VectorSchema( "embedding", DataType.VECTOR_FP32, dimension=128, index_param=HnswIndexParam(m=16, ef_construction=200), ), )

2. 创建与打开：create_and_open / open

• zvec.create_and_open(path, schema, option=None)：创建新集合并打开。若指定路径已存在集合，底层实现可能报错（见 zvec.py）。
• zvec.open(path, option=None)：打开磁盘上已存在的集合，前提是此前通过create_and_open创建过（见 zvec.py）。

两者都返回Collection对象，它封装了完整的 DDL/DML/DQL 操作入口（见 collection.py）。CollectionOption支持read_only（只读打开，默认 False）与enable_mmap（内存映射 I/O，默认 True）两个开关（见 param/init.pyi），适合多进程共享读的场景。

3. 数据写入：insert / upsert / update / delete

Doc是数据写入与查询返回的统一载体，包含id、score（查询时的相关度分数）、vectors（命名字典）与fields（标量字段字典）四个属性（见 doc.py）。构造 Doc 时，numpy.ndarray向量会被自动转换为普通 Python list，便于序列化。

Collection 提供完整的数据操纵 API（见 collection.py）：

• insert(docs)：插入新文档，文档 ID 必须唯一且符合 Schema；
• upsert(docs)：按 ID 插入新文档或更新已有文档；
• update(docs)：按 ID 更新已有文档，只更新指定的字段；
• delete(ids)/delete_by_filter(filter)：按 ID 或按过滤表达式（如"age > 30"）删除文档。

所有写入方法都返回Status对象（批量操作返回list[Status]），用于逐条判断成功与否。

4. 向量检索：Query 与 collection.query

Query是 Zvec 的查询单元，一个Query只针对一个字段，且只能承载一种检索语义（见 param/query.py）：

• 向量查询：通过vector（显式查询向量）或id（指定文档 ID，取该文档的向量作为查询向量）发起；
• 全文检索（FTS）：通过fts=Fts(...)发起，其中Fts支持query_string（结构化表达式，如'+vector -slow "exact phrase"'）与match_string（自然语言匹配串）两种形式，二者互斥；
• 校验规则明确：id与vector不能同时提供；FTS 与向量字段不能组合在同一个Query中（见 param/query.py）。

collection.query()的核心参数（见 collection.py）：

• queries：一个或多个Query（vectors为已废弃的旧参数名，仍兼容但会发出 DeprecationWarning）；
• topk：返回最近邻数量，默认 10，必须为正整数；
• filter：标量过滤的布尔表达式（如"category == 'tech'"），在检索前对候选集做预过滤；
• include_vector：是否在结果中携带向量数据，默认 False；
• output_fields：指定返回的标量字段，默认返回全部；
• reranker：对 Top-k 结果做重排的精排器。

同时Collection还提供fetch(ids, ...)按 ID 取文档、iter_docs()全集合流式遍历（内存占用恒定，且提供快照语义，见 collection.py），以及group_by_query()分组向量检索（按标量字段值分组返回各组 Top-k，见 collection.py）。

索引体系与量化：按需选型

Zvec 覆盖了从内存到磁盘、从精确到近似的完整索引谱系，全部参数类定义在 param/init.pyi 中：

与索引配套的查询参数同样按索引类型区分，例如HnswQueryParam(ef=300)通过ef控制检索精度与延迟的权衡，IVFQueryParam(nprobe=10)控制探测的倒排列表数，VamanaQueryParam(ef_search=200)控制图检索候选列表大小。HNSW 查询参数还支持radius（范围查询半径）、is_linear（强制线性扫描）以及extra_params中的prefetch_offset/prefetch_lines缓存预取调优（见 param/init.pyi）。

从源码结构看，各索引的实现在src/core/algorithm/下分目录组织：hnsw/、hnsw_rabitq/、ivf/、ivf_rabitq/、diskann/、vamana/、flat/、flat_sparse/、hnsw_sparse/等；量化器位于src/core/quantizer/（如uniform_uint4/7/8_converter.cc、integer_quantizer_converter.cc、half_float_converter.cc等），标量/向量距离计算由src/ailego/math/与src/turbo/提供多指令集实现（AVX2/AVX512/NEON/SSE 及 fp16 等变体）。v0.7.0 还新增了PQ-INT8 量化器，并让 RaBitQ 支持运行时AVX2/AVX512 指令集动态分发，同一套二进制可在不同 CPU 上自动选择最优路径。

全文检索（FTS）与混合检索

Zvec 的 FTS 索引由FtsIndexParam配置（见 param/init.pyi）：

• tokenizer_name：分词器，支持"standard"、"ngram"（v0.7.0 新增，更适合短语、代码、短文本）、"jieba"（中文，需jieba.dict.utf8词典，可配置jieba_dict_dir与user_dict_path）、"whitespace"；
• filters：分词后处理过滤器，支持"lowercase"（默认）、"ascii_folding"、"stemmer"；
• extra_params：分词器/过滤器的额外参数（JSON 字符串），如 ngram 的ngram_min/ngram_max、standard 的max_token_length等。

FTS 查询通过Query(field_name="content", fts=Fts(match_string="machine learning"))发起，并可搭配FtsQueryParam(default_operator="AND")控制多词匹配逻辑。混合检索即在同一collection.query()调用中传入多个Query（向量 + FTS + 标量filter），由查询执行器统一融合打分——Python 侧入口为 query_executor.py，底层由src/db/sqlengine/的 SQL 引擎与src/core/mixed_reducer/的混合归约模块承担。仓库测试python/tests/test_collection_fts_vector_hybrid.py专门验证了向量 + 全文的混合检索路径。

init 全局配置：面向容器环境的自适应调优

在调用任何 Collection 操作之前，可先通过zvec.init()做全局初始化（只能调用一次，重复调用会抛出RuntimeError，见 zvec.py）。其关键参数如下：

设计要点：所有None参数都不会进入配置载荷，由核心库按运行环境（cgroup CPU/内存限制）应用自适应默认值——这在 Kubernetes/Docker 下特别有用：省略memory_limit_mb与线程数即可让 Zvec 自动适配容器配额（见 zvec.py）。仓库测试python/tests/test_db_config.py与tests/db/common/config_test.cc覆盖了相关配置解析逻辑。

版本动态与生态

v0.7.0（2026 年 8 月 24 日发布）带来了多项关键更新：

• zvec-grep（zg）：本地优先的工作区搜索 CLI，统一 ripgrep、BM25 与向量检索，为人类与 AI Agent 设计；
• ReMe 集成：zvec 成为 ReMe（Agent 记忆管理套件）的文件存储后端，提供进程内 HNSW 向量检索；
• DiskANN 生产化：新增 Linux/macOS ARM64 支持与 io_uring 异步 I/O 后端，自动回退到最优 I/O 方案，无需任何配置；
• 索引优化：新增 IVF-RaBitQ 索引、PQ-INT8 量化器；RaBitQ 支持运行时指令集动态分发；
• 部署体验优化：动态库大幅瘦身（macOS arm64 C API 库 37→22 MB，降幅 40%）；新增 musl libc / Alpine Linux 支持；每次发布自动提供 Linux（glibc/musl）、macOS、Windows、Android、iOS 的预编译 SDK；
• DocIterator：全集合文档流式遍历迭代器，覆盖 C++、C、Python；
• 全文检索：新增 N-gram 分词器，更适合短语、代码、短文本检索。

仓库中的scripts/generate_standard_tokenizer_unicode.py与src/db/index/column/下的 tokenizer 相关实现（含*.g4ANTLR 语法文件）印证了分词器体系的演进路径；python/tests/test_collection_diskann.py、test_collection_ivf_rabitq.py、test_collection_hnsw_rabitq.py、test_iter_docs.py等测试文件则分别覆盖了上述新特性。

性能定位

Zvec 官方将自身定位为"毫秒级响应、轻松检索数十亿级向量"的嵌入式向量数据库，README 中提供了 QPS 性能基准图并指向官方性能报告（含具体测试方法、配置与完整结果）。需要说明的是，具体基准数值以官方性能报告为准，本仓库内不包含可独立复现的完整 benchmark 数据集。仓库tools/core/下提供了bench.cc、recall.cc等评测工具与txt2vecs.cc数据转换工具，可在本地构建后自行复现压测。

参与贡献

Zvec 欢迎来自社区的每一份贡献——无论是修复 Bug、新增功能，还是完善文档。开始参与前请查阅 贡献指南，其中规定了代码风格、提交流程与测试要求；仓库内python/tests/与tests/下提供了覆盖 Python 与 C++ 两层的完整测试用例，可作为新增代码的回归基线。

小结

Zvec 的核心价值在于"把向量数据库塞进进程里"：通过pip install zvec一行命令，即可获得涵盖稠密/稀疏向量、全文检索、混合检索、多索引类型与 WAL 持久化的完整检索能力。本文给出的 Schema 建模、数据写入与检索代码均可直接复制运行；进一步的参数细节（索引、量化、分词器、全局配置）可在 Python 参数定义、Collection API 与 查询模型 中查阅，C++ 底层实现则分布在src/core/与src/db/目录中，可供深度使用者继续溯源。

• 向量数据库
• 数据库
• 嵌入式数据库