【教程】阿里zvec向量数据库实战：5分钟搭建本地AI语义搜索引擎
前言最近GitHub Trending上阿里开源的zvec火得不行——10K+星标，号称"轻量级、闪电般速度的进程内向量数据库"。它支持Python/Node.js/Go/Rust/Dart多语言SDK，最近v0.5.0还新增了全文检索和混合检索功能。
今天这篇教程，手把手教你用zvec搭建一个本地AI语义搜索引擎，实现"以文搜文"的核心能力。无需Docker，无需配置服务器，pip安装即用。
一、前置条件
[*]Python 3.10 - 3.14
[*]至少4GB内存（建议8GB以上）
[*]一个文本嵌入模型（本教程使用 sentence-transformers）
安装依赖：
pip install zvec sentence-transformers
二、步骤详解
步骤1：创建向量数据库集合
首先定义数据集合的结构。zvec使用 CollectionSchema 来声明字段：
import zvec
# 定义集合结构
schema = zvec.CollectionSchema(
name="docs",
vectors=zvec.VectorSchema(
"embedding", # 向量字段名
zvec.DataType.VECTOR_FP32,# 数据类型
384 # 向量维度（取决于嵌入模型）
),
fields=[
zvec.FieldSchema("title", zvec.DataType.STRING),
zvec.FieldSchema("content", zvec.DataType.STRING),
]
)
# 创建并打开集合
collection = zvec.create_and_open(
path="./my_search_db",
schema=schema
)
步骤2：生成文本嵌入并插入数据
使用 sentence-transformers 将文本转为向量，然后存入zvec：
from sentence_transformers import SentenceTransformer
# 加载轻量级嵌入模型（384维）
model = SentenceTransformer("sentence-transformers/all-MiniLM-L6-v2")
# 示例文档
documents = [
{"id": "doc1", "title": "Rust入门指南", "content": "Rust是一门系统编程语言，注重安全和性能..."},
{"id": "doc2", "title": "Python异步编程", "content": "asyncio是Python标准库中的异步I/O框架..."},
{"id": "doc3", "title": "向量数据库对比", "content": "zvec、Milvus、Pinecone都是流行的向量数据库..."},
]
# 批量插入
for doc in documents:
embedding = model.encode(doc["content"]).tolist()
collection.insert([
zvec.Doc(
id=doc["id"],
vectors={"embedding": embedding},
fields={
"title": doc["title"],
"content": doc["content"]
}
)
])
print(f"已插入 {len(documents)} 条文档")
步骤3：执行语义搜索
输入查询文本，zvec会自动找到语义最相近的文档：
def semantic_search(query, top_k=3):
# 将查询转为向量
query_vec = model.encode(query).tolist()
# 执行向量搜索
results = collection.query(
zvec.VectorQuery("embedding", vector=query_vec),
topk=top_k
)
print(f"\n查询：'{query}'\n{'='*50}")
for i, r in enumerate(results, 1):
print(f"{i}. [{r['fields']['title']}] 相似度: {r['score']:.4f}")
print(f" {r['fields']['content'][:80]}...\n")
# 测试搜索
semantic_search("如何学习系统编程")
semantic_search("Python并发处理")
步骤4：混合检索（向量+全文）
zvec v0.5.0 支持混合检索，同时匹配语义相似度和关键词：
# 先创建全文索引（只需执行一次）
collection.create_index(
"content_fts",
zvec.IndexType.FULL_TEXT,
field="content"
)
# 混合查询
results = collection.query(
zvec.MultiQuery([
zvec.VectorQuery("embedding", vector=query_vec, weight=0.7),
zvec.TextQuery("content", text="Python 异步", weight=0.3)
]),
topk=5
)
三、完整可运行代码
#!/usr/bin/env python3
"""
zvec 语义搜索引擎 - 完整示例
依赖: pip install zvec sentence-transformers
"""
import zvec
from sentence_transformers import SentenceTransformer
# 1. 初始化
schema = zvec.CollectionSchema(
name="docs",
vectors=zvec.VectorSchema("embedding", zvec.DataType.VECTOR_FP32, 384),
fields=[
zvec.FieldSchema("title", zvec.DataType.STRING),
zvec.FieldSchema("content", zvec.DataType.STRING),
]
)
collection = zvec.create_and_open(path="./search_db", schema=schema)
model = SentenceTransformer("sentence-transformers/all-MiniLM-L6-v2")
# 2. 插入数据
docs = [
{"id": "1", "title": "Rust所有权机制", "content": "Rust通过所有权系统管理内存，无需垃圾回收器..."},
{"id": "2", "title": "Python装饰器详解", "content": "装饰器是Python的高阶函数，用于扩展函数功能..."},
{"id": "3", "title": "Docker容器化部署", "content": "Docker通过容器技术实现应用隔离和快速部署..."},
]
for d in docs:
vec = model.encode(d["content"]).tolist()
collection.insert([zvec.Doc(
id=d["id"],
vectors={"embedding": vec},
fields={"title": d["title"], "content": d["content"]}
)])
# 3. 搜索
query = "内存管理技术"
qvec = model.encode(query).tolist()
results = collection.query(zvec.VectorQuery("embedding", vector=qvec), topk=3)
print(f"查询: {query}")
for r in results:
print(f"{r['fields']['title']} (score: {r['score']:.3f})")
四、常见问题
[*]Q: zvec和Milvus/Pinecone有什么区别？
A: zvec是进程内数据库，无需单独部署服务，适合嵌入应用。Milvus/Pinecone是独立服务，适合大规模分布式场景。
[*]Q: 向量维度必须固定吗？
A: 是的，创建集合时需要指定维度。如果更换嵌入模型，需要重新创建集合。
[*]Q: 数据持久化吗？
A: 是的，zvec使用WAL（预写日志）保证数据持久化，即使进程崩溃也不会丢失数据。
[*]Q: 支持多进程并发吗？
A: 支持多进程同时读取，但写入是单进程独占的。
[*]Q: 有可视化工具吗？
A: 有！官方提供了 Zvec Studio，可以图形化浏览数据和调试查询。
五、总结
通过本教程，你学会了：
[*]用zvec创建向量数据库集合
[*]将文本转为向量并存储
[*]执行语义相似度搜索
[*]使用混合检索提升搜索质量
zvec的最大优势是极简——pip安装、几行代码就能跑起来，非常适合快速原型和中小型项目。如果你的应用需要海量数据（十亿级以上），可以考虑Milvus或Pinecone；但对于大多数场景，zvec完全够用。
下一步建议：尝试用zvec搭建一个个人知识库搜索，或者给现有项目加上语义搜索能力。有问题欢迎在楼下讨论！
---
参考资料：
[*]zvec GitHub 仓库
[*]官方快速入门文档
[*]Zvec Studio 可视化工具
页:
[1]