企业官网建设流程全解析

如何创建第一个zvec Collection？Schema设计分步图解

【免费下载链接】zvecA lightweight, lightning-fast, in-process vector database项目地址: https://gitcode.com/GitHub_Trending/zve/zvec

zvec是一款轻量级、极速的进程内向量数据库（in-process vector database），它直接嵌入你的应用运行，无需独立服务、无需额外配置。本文将带你分步图解如何创建第一个zvec Collection，并给出Schema 设计的完整思路：从字段定义、向量索引选择，到插入与查询，新手也能一次跑通。

为什么选择 zvec 向量数据库？

• 🚀进程内运行：像 SQLite 一样嵌入应用，支持 Python、C++、C 等多种语言 SDK
• ⚡极速检索：毫秒级相似度搜索，内置 HNSW、IVF、Flat 等多种向量索引
• 📦功能完整：稠密/稀疏向量、全文检索（FTS）、混合检索开箱即用
• 💾数据持久：WAL 预写日志保证掉电不丢数据

先搞懂：Collection 和 Schema 是什么？

在 zvec 中，数据的组织方式和关系数据库非常相似：

一个 Schema 由两部分组成：标量字段（用于过滤和展示）与向量字段（用于相似度检索），字段名必须全局唯一。

核心 API 定义在 python/zvec/model/schema/collection_schema.py 与 python/zvec/model/schema/field_schema.py，创建与打开逻辑在 python/zvec/zvec.py。

第 0 步：安装 zvec 向量数据库

打开终端，一行命令完成安装（需 64 位 Python 3.10–3.14）：

pip install zvec

分步图解：创建第一个 Collection

步骤 1️⃣：初始化 zvec

在程序入口处调用一次初始化（只能调用一次），它会配置日志、线程数等资源：

import zvec zvec.init() # 使用默认配置即可

步骤 2️⃣：设计 Schema（关键一步）

Schema 设计决定了后续查询性能。以"笔记检索"场景为例，我们规划 3 个字段：

schema = zvec.CollectionSchema( name="notes", fields=[ zvec.FieldSchema("title", zvec.DataType.STRING), zvec.FieldSchema("score", zvec.DataType.FLOAT), ], vectors=[ zvec.VectorSchema( "embedding", zvec.DataType.VECTOR_FP32, 4, zvec.HnswIndexParam(m=16, ef_construction=200), ) ], )

向量索引怎么选？这是新手最常纠结的问题：

标量字段也可选挂InvertIndexParam（倒排索引加速过滤）或FtsIndexParam（全文检索），详见 python/zvec/model/param/init.pyi。

步骤 3️⃣：创建并打开 Collection

create_and_open会在磁盘上创建 Collection 并立即返回可用实例；之后重启程序用zvec.open(path)重新打开即可：

collection = zvec.create_and_open(path="./my_notes", schema=schema)

步骤 4️⃣：插入文档并查询

每条文档（Doc）由主键id+ 标量字段fields+ 向量vectors组成：

# 插入 collection.insert([ zvec.Doc(id="doc_1", fields={"title": "向量入门", "score": 0.8}, vectors={"embedding": [0.1, 0.2, 0.3, 0.4]}), zvec.Doc(id="doc_2", fields={"title": "索引实战", "score": 0.6}, 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, ) print(results) # 按相似度得分降序返回

至此，你已完成 zvec Collection 的完整生命周期：设计 Schema → 创建 → 写入 → 检索。Collection 的插入、更新、删除（DML）与过滤查询（DQL）能力都封装在 python/zvec/model/collection.py 的Collection类中。

常用数据类型速查

标量字段：STRING、BOOL、INT32、INT64、UINT32、UINT64、FLOAT、DOUBLE，以及对应的ARRAY_*数组类型。

向量字段：VECTOR_FP32（通用首选）、VECTOR_FP16（省一半内存）、VECTOR_FP64（高精度）、VECTOR_INT8（量化压缩）、SPARSE_VECTOR_FP32/SPARSE_VECTOR_FP16（稀疏向量）。

完整枚举定义见 python/zvec/typing/init.pyi。

常见错误与避坑指南 🛠️

小结

创建第一个 zvec Collection 只需 4 步：zvec.init()初始化 → 用CollectionSchema定义标量字段与向量字段 →create_and_open创建 →insert/query读写数据。掌握标量/向量字段的划分和 Flat/HNSW 索引的取舍，你的 Schema 设计就已经超过大多数人了。想继续深入，可以阅读 C 语言完整示例 examples/c/collection_schema_example.c 和 C++ 示例 examples/c++/db/main.cc。

【免费下载链接】zvecA lightweight, lightning-fast, in-process vector database项目地址: https://gitcode.com/GitHub_Trending/zve/zvec