Zvec 向量数据库安装与使用

一、Zvec 的优势有哪些？

1.1 什么是 Zvec？
Zvec 是阿里巴巴开源的嵌入式向量数据库，基于 Proxima 向量检索引擎构建，主要用于向量存储、相似度检索和 AI 知识库检索。与 Qdrant、Milvus 等需要独立部署服务的常见方案不同，Zvec 可以直接集成到 Python 等应用程序中，不需要单独启动数据库服务。

项目地址：
GitHub：https://github.com/alibaba/zvec
官方文档：https://zvec.org/
Python API：https://zvec.org/api-reference/python/

1.2 核心优势
优势一：嵌入式架构，部署简单
Zvec 可以直接在应用程序中调用，不需要额外部署独立的数据库服务。

适合：
本地 AI 应用
Python 知识库项目
单机 RAG 系统 
桌面端 AI 工具

优势二：支持多种检索方式
Zvec 支持向量检索、全文检索和结构化字段过滤，可用于构建混合检索系统。

例如：
根据语义相似度搜索文档
根据关键词搜索文本
按文档分类、来源等元数据过滤
结合语义检索和关键词检索
具体全文索引及混合检索能力，应以实际安装版本的官方文档为准。

优势三：支持本地存储
数据和索引可以保存在本地磁盘，不需要将知识库内容上传到第三方云服务。
结合本地 Embedding 模型，可以构建完全离线运行的知识库系统。

优势四：支持高效向量索引
Zvec 提供多种向量索引方案，可根据数据规模、查询延迟和资源限制选择合适的索引。

优势五：支持 Python 开发
可以在 Python 项目中直接调用 SDK，方便集成到现有的 AI 应用、RAG 系统和数据处理流程。

1.3 使用时需要注意的问题

Zvec 不等于 Embedding 模型。它主要负责向量存储和检索，不会自动把任意文字转换为语义向量。
嵌入式架构虽然部署简单，但需要关注多进程写入、备份恢复和数据更新等问题。
如果多个业务服务需要共享一个中心化数据库，Qdrant 这类独立服务架构可能更合适。
不应仅凭官方基准测试判断性能，需要结合实际数据规模和检索场景测试。

二、Zvec 安装过程

2.1 环境要求
建议使用独立 Python 虚拟环境，避免与其他项目的依赖冲突。
开始安装前，检查 Python 版本：

python3 --version

2.2 创建项目

mkdir zvec-demo
cd zvec-demo
python3 -m venv .venv
# macOS/Linux 激活环境：
source .venv/bin/activate

2.3 安装 Zvec

python -m pip install --upgrade pip
python -m pip install zvec
#验证安装：
python -c "import zvec; print('Zvec installed successfully')"

如果安装失败，应先检查 Python 版本、操作系统架构以及当前版本是否提供对应的预编译安装包。

2.4 安装 Embedding 模型依赖
如果需要语义检索，还需要安装 Embedding 模型运行依赖：

pip install zvec sentence-transformers

本教程使用 BGE-M3 作为示例模型。
注意：首次加载模型时，需要提前下载模型文件。完成下载后，可以配置为本地加载，避免运行时访问网络。

三、Zvec 基础使用案例
3.1 重要说明：Zvec 不负责生成 Embedding
Zvec 存储和检索的是向量，而不是直接理解原始文字的语义。

完整流程如下：
原始文本->Embedding 模型，例如 BGE-M3 ->生成数值向量->Zvec 存储原始文本、向量和元数据->使用查询向量执行相似度检索

如果只保存文本，可以进行普通字段查询或配置全文检索；如果需要根据语义寻找相似内容，就必须先生成向量。

3.2 创建集合并插入数据,使用 BGE-M3 转换文本并存入 Zvec
下面用四维模拟向量演示基础 API。模拟向量只用于验证存储和检索流程，不能用于真实语义搜索。

3.3 BGE-M3 简介
BGE-M3 是一个多语言文本表示模型，支持中英文等多种语言，适合用于跨语言语义搜索和 RAG 知识库。
模型地址：
https://huggingface.co/BAAI/bge-m3
BGE-M3 的典型稠密向量维度为 1024。
它也支持稀疏表示等能力，但本教程先使用稠密向量，简化实现流程。

3.4 首次运行前，需要下载 BGE-M3 模型文件。下载完成后，可以将模型保存在本地目录，例如：
models/
└── bge-m3/
如果模型已经下载完成，后续可通过本地路径加载，并关闭远程模型文件访问。
代码如下：

from pathlib import Path

import zvec
from sentence_transformers import SentenceTransformer

DB_PATH = "./rag_zvec_data"
MODEL_PATH = "./models/bge-m3"
VECTOR_DIM = 1024

# 1. 加载本地 Embedding 模型
model = SentenceTransformer(
    MODEL_PATH,
    local_files_only = True,
)

# 2. 创建或打开 Zvec 集合
def create_collection():
    schema = zvec.CollectionSchema(
        name = "rag_knowledge",
        fields = [
            zvec.FieldSchema(
                name = "content",
                data_type = zvec.DataType.STRING,
            ),
            zvec.FieldSchema(
                name = "category",
                data_type = zvec.DataType.STRING,
            ),
        ],
        vectors = [
            zvec.VectorSchema(
                name = "embedding",
                data_type = zvec.DataType.VECTOR_FP32,
                dimension = VECTOR_DIM,
                index_param = zvec.HnswIndexParam(
                    metric_type = zvec.MetricType.COSINE
                ),
            )
        ],
    )

    if Path(DB_PATH).exists():
        return zvec.open(
            path = DB_PATH,
            schema = schema,
        )

    return zvec.create_and_open(
        path = DB_PATH,
        schema = schema,
    )

# 3. 将原始文本转换为向量
def embed_texts(texts):
    vectors = model.encode(
        texts,
        normalize_embeddings = True,
        convert_to_numpy = True,
    )

    return vectors

# 4. 写入文本和向量
def insert_documents(collection):
    texts = [
        "Python 可以使用 venv 创建独立的虚拟环境。",
        "PostgreSQL 可以通过合适的索引提升查询性能。",
        "Zvec 是一个嵌入式向量数据库，可以用于本地 RAG。",
        "BGE-M3 可以把中文和英文文本转换为稠密向量。",
    ]

    categories = [
        "python",
        "database",
        "vector_db",
        "embedding",
    ]

    vectors = embed_texts(texts)

    docs = []

    for i, (text, vector) in enumerate(
        zip(texts, vectors)
    ):
        docs.append(
            zvec.Doc(
                id = f"doc_{i + 1:03d}",
                vectors = {
                    "embedding": vector.tolist(),
                },
                fields = {
                    "content": text,
                    "category": categories[i],
                },
            )
        )

    collection.insert(docs)
    collection.optimize()

    print(f"成功写入 {len(docs)} 条记录")

# 5. 语义检索
def search_documents(collection, query_text):
    # 查询文字必须使用同一个 Embedding 模型
    query_vector = embed_texts([query_text])[0]

    results = collection.query(
        queries = zvec.Query(
            field_name = "embedding",
            vector = query_vector.tolist(),
        ),
        topk = 3,
    )

    print(f"\n查询问题：{query_text}")
    print("\n检索结果：")

    for item in results:
        print(item)

def main():
    is_new = not Path(DB_PATH).exists()
    collection = create_collection()

    if is_new:
        insert_documents(collection)

    search_documents(
        collection,
        "如何提升数据库查询速度？",
    )

    search_documents(
        collection,
        "How can I create a Python virtual environment?",
    )

if __name__ = = "__main__":
    main()

3.5 运行

python rag_demo.py

首次运行时，程序会：
(1)加载本地 BGE-M3 模型。
(2)创建 Zvec 集合。
(3)将四条文本转换成 1024 维向量。
(4)将文本、向量和分类信息一起写入 Zvec。
(5)使用中文和英文问题分别执行语义检索。

第二次运行时，程序会打开现有数据库并执行检索，不会重复插入示例数据。
如果需要重新初始化，请先确认旧数据不再需要，再删除 rag_zvec_data 目录。

注意：示例使用的 Zvec 集合创建、查询及过滤 API 应以安装版本的官方文档为准；首次运行前建议先用最小数据集验证 API 兼容性。