alibaba/zvec - 项目详情

项目介绍快速开始学习路径项目截图 3 贡献者 9 增长趋势代码统计生态关系项目时间线项目竞品依赖分析上榜历史

5分钟上手 Zvec 向量数据库

本指南将帮助你在5分钟内安装Zvec并运行第一个向量相似度搜索示例

环境要求

支持的操作系统

Linux (x86_64, ARM64) macOS (ARM64)

运行环境

Python 3.10 - 3.12 必需

所需工具

pip

Python包管理工具

必需

操作步骤

安装Zvec Python包

使用pip安装Zvec的Python绑定

安装最新版本的Zvec

pip install zvec

预期结果：看到类似 'Successfully installed zvec-x.x.x' 的输出

建议使用虚拟环境（如venv或conda）来管理依赖

创建并运行示例代码

创建一个简单的Python脚本，演示Zvec的基本功能

创建示例Python脚本

cat > zvec_demo.py << 'EOF'
import numpy as np
import zvec

# 创建向量数据库
index = zvec.Index(dim=128, metric='ip')

# 生成一些随机向量作为示例数据
vectors = np.random.rand(1000, 128).astype(np.float32)
ids = list(range(1000))

# 添加向量到索引
index.add(vectors, ids)

# 创建查询向量
query_vector = np.random.rand(1, 128).astype(np.float32)

# 执行相似度搜索
results = index.search(query_vector, k=5)

print(f"Top 5 similar vectors: {results}")
print("✅ Zvec is working!")
EOF

运行示例脚本

python zvec_demo.py

预期结果：看到类似 'Top 5 similar vectors: [...]' 和 '✅ Zvec is working!' 的输出

这个示例展示了最基本的向量搜索功能，实际使用时需要替换为真实的数据

验证成功

如果看到以下输出，说明Zvec已成功安装并运行

成功导入zvec模块

成功创建索引并添加向量

成功执行相似度搜索并返回结果

看到'✅ Zvec is working!'提示

快速提示

性能

对于生产环境，建议使用真实数据而不是随机向量，并调整索引参数以获得最佳性能

配置

Zvec支持多种距离度量方式，包括'ip'(内积)、'l2'(欧氏距离)和'cosine'(余弦相似度)

性能

如果遇到内存问题，可以分批添加向量而不是一次性添加所有数据

常见问题

安装失败，提示找不到合适的版本

检查Python版本是否为3.10-3.12，并确保操作系统符合要求（Linux x86_64/ARM64 或 macOS ARM64）

导入zvec时出现ImportError

确认安装成功，尝试重新安装：pip install --force-reinstall zvec

运行速度慢或内存占用高

对于大数据集，考虑使用更高效的索引类型或调整索引参数，参考官方文档的优化建议

下一步

查看官方文档

了解Zvec的高级功能，如稀疏向量支持、混合搜索等

尝试真实数据集

使用你自己的向量数据替换示例中的随机向量

探索混合搜索功能

学习如何结合语义相似度和结构化过滤条件进行精确搜索