zvec

使用说明

开始之前，请先了解以下内容：

1. 开发语言：Python 还是 Node.js？

   • Python：使用 pip install zvec
   • Node.js：使用 npm install @zvec/zvec

2. 使用场景：

   • RAG 文档检索系统
   • 语义搜索
   • 多模态搜索（图像 + 文本）
   • 混合搜索（关键词 + 语义）

3. 数据规模：

   • < 100k：使用 FLAT 索引（精确搜索）
   • 100k-10M：使用 HNSW 索引（推荐默认选项）

   • 10M：使用 IVF 索引（优化内存）

决策工作流

• 用户需要向量搜索功能
  • 选择开发语言（Python/Node.js）
  • 确定使用场景
    • RAG 系统 → 使用单向量搜索 + 文档分块管理
    • 电商搜索 → 使用混合搜索（向量 + 筛选）
    • 多模态 → 使用多向量搜索 + 加权排序
  • 设计 Schema（向量字段 + 标量字段）
  • 选择索引类型（HNSW/FLAT/IVF）
  • 实现数据同步策略

默认建议

• 使用 create_and_open() / ZVecCreateAndOpen() 创建 Collection
• 使用余弦相似度（COSINE）作为默认距离度量
• 为稠密向量使用 FP32 类型
• 为筛选字段创建 InvertIndexParam 索引

验证清单

• 向量维度与 Schema 定义一致
• 标量字段类型正确
• 筛选条件语法正确
• 大批量写入后调用 optimize()

快速开始

Python：

import zvec

# Create Collection
schema = zvec.CollectionSchema(
    name="my_collection",
    fields=[
        zvec.FieldSchema(name="title", data_type=zvec.DataType.STRING),
    ],
    vectors=[
        zvec.VectorSchema(
            name="embedding",
            data_type=zvec.DataType.VECTOR_FP32,
            dimension=768,
            index_param=zvec.HnswIndexParam(
                metric_type=zvec.MetricType.COSINE
            ),
        ),
    ],
)

collection = zvec.create_and_open("./my_data", schema)

# Insert document
collection.upsert(zvec.Doc(
    id="doc_1",
    vectors={"embedding": [0.1] * 768},
    fields={"title": "Hello World"},
))

# Search
results = collection.query(
    vectors=zvec.VectorQuery(
        field_name="embedding",
        vector=[0.1] * 768,
    ),
    topk=10,
)

Node.js：

import { ZVecCreateAndOpen, ZVecCollectionSchema, ZVecFieldSchema, ZVecVectorSchema, ZVecDataType, ZVecHnswIndexParams, ZVecMetricType } from "@zvec/zvec";

const schema = new ZVecCollectionSchema({
  name: "my_collection",
  fields: [new ZVecFieldSchema({ name: "title", dataType: ZVecDataType.STRING })],
  vectors: [new ZVecVectorSchema({
    name: "embedding",
    dataType: ZVecDataType.VECTOR_FP32,
    dimension: 768,
    indexParams: new ZVecHnswIndexParams({ metricType: ZVecMetricType.COSINE }),
  })],
});

const collection = ZVecCreateAndOpen("./my_data", schema);

核心概念

数据模型

Collection

• 类似于关系数据库中的表，是用于存储、组织和查询数据的容器
• 每个 Collection 都有一个定义其结构的 Schema
• 每个 Collection 都独立持久化在磁盘上的专用目录中

Document

• 数据存储的基本单元，类似于关系表中的一行
• 包含三个核心组件：
  • id：唯一的字符串标识符
  • vectors：具名向量集合（支持稠密向量和稀疏向量）
  • fields：具名标量字段集合

Schema

• 动态 Schema：可随时添加或移除标量字段和向量
• 强类型系统：每个字段都必须声明 DataType

向量类型

稠密向量

• 固定长度的实数嵌入
• 类型：VECTOR_FP16、VECTOR_FP32、VECTOR_INT8
• 适用于：语义理解、上下文捕捉

稀疏向量

• 高维表示，其中只有少数维度非零
• 类型：SPARSE_VECTOR_FP32、SPARSE_VECTOR_FP16
• 适用于：关键词匹配、BM25 评分

索引类型

索引类型	特点	使用场景
FLAT	暴力搜索，结果精确	小规模数据（<100k）
HNSW	近似最近邻，图结构	大规模数据（推荐默认选项）
IVF	倒排文件索引	超大规模数据

可用主题

Python

• 快速开始 - 快速上手 Zvec Python API
• Collection 管理 - 创建、打开和管理 Collection
• 数据操作 - 插入、更新和删除文档
• 向量搜索 - 单向量、多向量和混合搜索
• RAG 系统 - 构建文档检索系统
• 混合搜索 - 向量相似度 + 标量筛选
• 多模态搜索 - 图像 + 文本联合搜索

Node.js

• 快速入门 - 使用 Zvec Node.js API 快速入门
• 集合管理 - 创建、打开和管理集合
• 数据操作 - 插入、更新和删除文档
• 向量搜索 - 单向量、多向量和混合搜索
• RAG 系统 - 构建文档检索系统
• 混合搜索 - 向量相似度 + 标量筛选
• 多模态搜索 - 图像 + 文本联合搜索

通用

• 配置 - 全局配置和初始化
• 数据模型 - Zvec 数据模型概述
• 嵌入 - 文本嵌入函数（仅限 Python）
• 重排器 - 结果重排函数（仅限 Python）
• API 速查表 - Python 和 Node.js API 快速参考
• 故障排除 - 常见问题和解决方案

可用主题

Python

• 集合管理
• 数据操作
• 混合搜索
• 多模态搜索
• 快速入门
• RAG 系统
• 向量搜索

Node.js

• 集合管理
• 数据操作
• 混合搜索
• 多模态搜索
• 快速入门
• RAG 系统
• 向量搜索

通用

• 配置
• 数据模型
• 嵌入
• 重排器
• API 速查表
• 故障排除