概述

Vearch 是一款云原生分布式向量数据库，专为您的 AI 应用程序中嵌入向量的高效相似性搜索而设计。

核心特性

• 混合搜索：同时支持向量搜索和标量过滤。
• 性能：快速向量检索——可在毫秒级内从数百万个对象中完成搜索。
• 可扩展性与可靠性：支持副本机制和弹性水平扩展。

文档

Restful API

• 教程 | 参考文档

OpenAPI

• API 文档

SDK

SDK	描述
Python SDK	Vearch 的 Python 客户端
Go SDK	Vearch 的 Go 客户端
Java SDK	Vearch 的 Java 客户端
Rust SDK	Vearch 的 Rust 客户端

使用场景

将 Vearch 用作内存后端

Vearch 可与主流 AI 框架集成：

框架	集成方式
Langchain	在 Langchain 中将 Vearch 用作向量存储
LlamaIndex	与 LlamaIndex 集成以构建知识库
Langchaingo	支持 Vearch 的 Langchain Go 实现
LangChain4j	支持 Vearch 集成的 Java 实现

现实世界演示

• VisualSearch：Vearch 可用于构建完整的视觉搜索系统，索引数十亿张图片。此外，还需要图像检索插件来进行目标检测和特征提取。

快速入门

Kubernetes 部署

# 通过 Helm 仓库
$ helm repo add vearch https://vearch.github.io/vearch-helm
$ helm repo update && helm install my-release vearch/vearch

# 或从本地 Charts
$ git clone https://github.com/vearch/vearch-helm.git && cd vearch-helm
$ helm install my-release ./charts -f ./charts/values.yaml

Docker Compose 部署

# 单机模式
$ cd cloud && cp ../config/config.toml .
$ docker-compose --profile standalone up -d

# 集群模式
$ cd cloud && cp ../config/config_cluster.toml .
$ docker-compose --profile cluster up -d

其他部署方式

• DeployByDocker：通过 Docker 部署 Vearch
• SourceCompileDeployment：从源码编译部署 Vearch

组件

Vearch 架构

Master：负责模式管理、集群级元数据以及资源协调。 Router：提供 RESTful API：upsert、delete、search 和 query；进行请求路由和结果合并。 PartitionServer (PS)：托管基于 Raft 的副本机制的文档分区。Gamma 是核心向量搜索引擎，基于 faiss 实现。它具备存储、索引和检索向量及标量的能力。

技术参考

学术引用

在学术或研究项目中使用 Vearch 时，请引用我们的论文：

@misc{li2019design,
      title={The Design and Implementation of a Real Time Visual Search System on JD E-commerce Platform},
      author={Jie Li and Haifeng Liu and Chuanghua Gui and Jianyu Chen and Zhenyun Ni and Ning Wang},
      year={2019},
      eprint={1908.07389},
      archivePrefix={arXiv},
      primaryClass={cs.IR}
}

社区支持

联系我们

您可以通过多种渠道与 Vearch 社区互动：

• GitHub Issues：在我们的 问题页面 上报告 bug 或请求功能。
• 邮件讨论：如需公开讨论或提问，请发送邮件至 vearch-maintainers@groups.io。
• Slack 频道：加入我们的 Slack 社区，进行实时交流。

贡献

我们欢迎社区贡献！请查看我们的贡献指南以开始参与。

许可证

Vearch 采用 Apache License, Version 2.0 许可。

有关完整许可信息，请参阅我们仓库中的 LICENSE 和 NOTICE。

---

Vearch 快速上手指南

Vearch 是一个云原生的分布式向量数据库，专为 AI 应用中的嵌入向量高效相似性搜索而设计。它支持混合搜索（向量检索 + 标量过滤），具备毫秒级检索百万级数据的能力，并支持弹性扩缩容。

1. 环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux (推荐 Ubuntu/CentOS) 或 macOS。
• 容器环境（推荐方式）：
  • Docker (版本 20.10+)
  • Docker Compose (版本 2.0+)
• Kubernetes 环境（集群部署可选）：
  • Kubernetes 集群 (v1.16+)
  • Helm (版本 3.0+)
• 网络要求：确保能够访问 GitHub 或配置了国内镜像加速。

2. 安装步骤

Vearch 提供多种部署方式，以下是两种最快捷的启动方法。

方法一：Docker Compose 部署（推荐单机/测试体验）

此方法适合快速本地体验或小规模测试。

1. 克隆项目并进入目录

git clone https://github.com/vearch/vearch.git
cd vearch/cloud

2. 单机模式启动 复制配置文件并启动 standalone 模式：

cp ../config/config.toml .
docker-compose --profile standalone up -d

3. 集群模式启动 若需体验集群功能，复制集群配置文件并启动：

cp ../config/config_cluster.toml .
docker-compose --profile cluster up -d

启动完成后，可通过 docker ps 查看容器状态，默认 API 端口通常为 8817。

方法二：Helm 部署（推荐 K8s 生产环境）

如果您已在 Kubernetes 环境中，可使用 Helm 快速部署。

1. 添加 Helm 仓库

helm repo add vearch https://vearch.github.io/vearch-helm
helm repo update

2. 安装 Vearch

helm install my-release vearch/vearch

或者从源码安装：

git clone https://github.com/vearch/vearch-helm.git && cd vearch-helm
helm install my-release ./charts -f ./charts/values.yaml

3. 基本使用

安装完成后，您可以通过 RESTful API 或官方 SDK 进行操作。以下展示最基础的 HTTP API 使用流程。

3.1 创建空间（Space）

首先需要通过 Router 创建一个包含向量索引配置的空间。

curl -XPUT -H "content-type: application/json" -d '
{
    "name": "test_space",
    "partition_num": 1,
    "replica_num": 1,
    "fields": [
        {
            "name": "field_int",
            "type": "integer"
        },
        {
            "name": "field_vector",
            "type": "vector",
            "dimension": 128,
            "index": {
                "name": "gamma",
                "type": "FLAT",
                "params": {
                    "metric_type": "InnerProduct"
                }
            }
        }
    ]
}' http://localhost:8817/space/test_db/_create

3.2 插入数据（Upsert）

向空间中插入带有向量数据和标量字段的数据。

curl -XPOST -H "content-type: application/json" -d '
{
    "documents": [
        {
            "_id": "1",
            "field_int": 100,
            "field_vector": [0.1, 0.2, 0.3, "... (共 128 维)"] 
        }
    ]
}' http://localhost:8817/space/test_db/test_space/_upsert

(注：请将 [0.1, 0.2, ...] 替换为实际的 128 维浮点数数组)

3.3 执行搜索（Search）

执行向量相似性搜索，并可结合标量字段进行过滤。

curl -XPOST -H "content-type: application/json" -d '
{
    "query": {
        "sum": [
            {
                "field": "field_vector",
                "feature": [0.1, 0.2, 0.3, "... (共 128 维)"],
                "min_score": 0.5
            }
        ],
        "filter": [
            {
                "field": "field_int",
                "operator": ">=",
                "value": 50
            }
        ]
    },
    "size": 10
}' http://localhost:8817/space/test_db/test_space/_search

3.4 使用 SDK（以 Python 为例）

除了直接调用 API，推荐使用官方 SDK 简化开发：

pip install vearch

import vearch

# 初始化连接
db = vearch.Vearch("http://localhost:8817")

# 执行搜索逻辑可参考 sdk/python/README.md 中的详细示例

更多语言 SDK（Go, Java, Rust）及 LangChain/LlamaIndex 集成方案，请参考官方文档中的 SDK 列表 和 集成案例。