Zvec 中文教程：先用小向量验证本地 collection
Zvec 是进程内向量数据库，应用直接打开本地目录，不需要先部署数据库服务器。它支持向量、全文和结构化过滤，也提供内存与磁盘索引。第一次使用先验证最小 collection，随后再接真实 embedding 和较大数据集。
1. 建立隔离环境并固定版本
python3 -m venv .venv source .venv/bin/activate python -m pip install "zvec==0.7.0"
先确认 Python、操作系统和 CPU 架构落在官方 wheel 范围内。数据目录放在临时位置，不要直接指向已有 collection 或共享生产目录。
2. 定义四维测试 schema
import zvec
schema = zvec.CollectionSchema(
name="example",
vectors=zvec.VectorSchema("embedding", zvec.DataType.VECTOR_FP32, 4),
)
collection = zvec.create_and_open("./zvec_example", schema=schema)
向量维度属于 schema。将来切换 embedding 模型时，先确认维度和归一化方式；不要把不同模型产生的向量混入同一字段。
3. 插入两条固定数据并查询
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=2,
)
print(results)
记录 id、分数和排序，然后关闭并重新打开 collection，确认数据仍在。接入真实数据前，还要测试重复 id、错误维度、进程异常退出、备份恢复和磁盘空间不足时的行为。
4. 设计单写者和目录权限
官方 README 说明多个进程可同时读取同一 collection，写入由单进程独占。多 worker 服务应指定一个写入者或使用队列串行化更新。Zvec 本身不提供 HTTP 认证或多租户隔离，数据目录权限和外层 API 鉴权由宿主应用负责。
与 LanceDB 对比
LanceDB 官方项目建立在 Lance 列式格式上，强调多模态数据、向量/全文/SQL、自动版本管理，以及 Python、Node.js、Rust 和 REST 接口。Zvec 更强调直接嵌入进程、稠密/稀疏/全文混合检索、多种 ANN 索引和本地 WAL。需要多模态列式数据与版本管理时可评估 LanceDB；需要轻量本地 collection 和灵活索引组合时可评估 Zvec。
pyproject.toml、Quickstart、Benchmarks 与 v0.7.0 Release；没有安装 wheel、创建 collection、执行插入/查询或复测崩溃恢复、并发、召回率和性能数据。这里仅补原教程没有展开的事实和边界。安装命令与操作步骤仍以前文为准。
先判断这个项目是否适合你
适合谁用
适合桌面工具、CLI、Notebook、单机 RAG、Agent 记忆和边缘应用，把向量检索直接嵌进进程。需要多租户权限、网络 API、独立扩缩容或多写者协调时，应在应用层补服务边界，或选择原生服务型数据库。
采用建议
Zvec 适合希望把混合检索放进单机进程、又不想维护独立数据库服务的项目。先在临时目录用固定小向量验证 schema、写入、查询和重开，再测试自己的数据规模、召回率、索引时间、磁盘占用和单写者安排。
原教程未展开的系统信息
核心功能
多语言 SDK
官方提供 Python、Node.js、Go、Rust 和 Dart/Flutter 入口，v0.7.0 扩展了预编译 SDK 平台。
核验与使用边界
优势与限制
优势
- 无需部署独立服务，接入路径短
- 同时支持向量、全文和结构化过滤
- WAL 与磁盘索引覆盖持久化和较大数据集
限制
- 写入是单进程独占，不适合多个写者直接共享同一 collection
- 库本身不提供网络认证、多租户或 API 网关
- embedding 的生成、版本与维度一致性由应用管理
排错时先核对版本、运行环境和未覆盖范围。这里没有执行过的步骤不会写成实测结论。
常见问题
Zvec v0.7.0 是什么时候发布的？
官方 README 与 Release 记录的日期是 2026-08-24；该版加入 zvec-grep、更多 DiskANN 平台支持、新索引与量化器、DocIterator 和 N-gram tokenizer。
使用 Zvec 需要先启动数据库服务器吗？
不需要。Zvec 是进程内数据库，应用直接打开本地 collection 路径；网络 API、认证和多租户需要应用自行提供。
多个进程可以同时写一个 Zvec collection 吗？
不可以。官方 README 说明多个进程可以并发读取，但写入为单进程独占，需要在应用层安排单写者。
Zvec 会自动把文本转换成 embedding 吗？
README 的基础接口接收用户提供的向量。应用需要自行选择 embedding 模型，并保持写入与查询的模型、维度和归一化方式一致。