快速开始¶

欢迎使用 GoVector！本指南将帮助你在几分钟内快速上手 GoVector。GoVector 是一个完全使用 Go 语言编写的轻量化嵌入式向量数据库，与 Qdrant 的 API 兼容。

📦 安装¶

选项 A：通过 Homebrew 安装（Mac/Linux）¶

最简单的安装方法是使用 Homebrew 并将其作为服务运行：

brew tap DotNetAge/govector
brew install govector

# 启动后台服务（启动 REST API 服务器）
brew services start govector

选项 B：从源码构建¶

git clone https://github.com/DotNetAge/govector.git
cd govector
make build
# 二进制文件将在 ./bin/govector 可用

选项 C：作为 Go 库使用¶

go get github.com/DotNetAge/govector/core

🚀 快速入门示例¶

嵌入式模式（零网络开销）¶

在你的 Go 应用中直接使用 GoVector：

package main

import (
    "fmt"
    "github.com/DotNetAge/govector/core"
)

func main() {
    // 1. 初始化本地存储（创建单个 .db 文件）
    store, _ := core.NewStorage("govector.db")
    defer store.Close()

    // 2. 创建集合（自动持久化）
    col, _ := core.NewCollection("documents", 384, core.Cosine, store, true)

    // 3. 写入数据（带版本控制）
    col.Upsert([]core.PointStruct{
        {
            ID:      "doc_1",
            Vector:  []float32{0.1, 0.2, 0.3, /* ... 384 维度 ... */},
            Payload: core.Payload{"category": "tech", "author": "John"},
        },
        {
            ID:      "doc_2",
            Vector:  []float32{0.4, 0.5, 0.6, /* ... 384 维度 ... */},
            Payload: core.Payload{"category": "business", "author": "Jane"},
        },
    })

    // 4. 带元数据过滤的搜索
    query := []float32{0.15, 0.25, 0.35, /* ... 384 维度 ... */}
    filter := &core.Filter{
        Must: []core.Condition{
            {
                Key:   "category",
                Type:  core.MatchTypeExact,
                Match: core.MatchValue{Value: "tech"},
            },
        },
    }

    results, _ := col.Search(query, filter, 10)
    fmt.Printf("最佳匹配: %s (分数: %f)\n", results[0].ID, results[0].Score)
}

微服务模式（与 Qdrant 兼容）¶

将 GoVector 作为带有 REST API 的独立服务器运行：

# 启动服务器
govector serve ./govector.db -port 18080

# API 服务器在 http://localhost:18080 上就绪

创建集合¶

curl -X POST http://localhost:18080/collections -H "Content-Type: application/json" -d '{
  "name": "documents",
  "vector_size": 384,
  "distance": "cosine",
  "hnsw": true
}'

写入向量¶

curl -X PUT http://localhost:18080/collections/documents/points -H "Content-Type: application/json" -d '{
  "points": [
    {
      "id": "doc_1",
      "vector": [0.1, 0.2, 0.3, /* ... 384 维度 ... */],
      "payload": {"category": "tech", "author": "John"}
    },
    {
      "id": "doc_2",
      "vector": [0.4, 0.5, 0.6, /* ... 384 维度 ... */],
      "payload": {"category": "business", "author": "Jane"}
    }
  ]
}'

搜索向量¶

curl -X POST http://localhost:18080/collections/documents/points/search -H "Content-Type: application/json" -d '{
  "vector": [0.15, 0.25, 0.35, /* ... 384 维度 ... */],
  "filter": {
    "must": [
      {
        "key": "category",
        "type": "exact",
        "match": {"value": "tech"}
      }
    ]
  },
  "limit": 10
}'

CLI 模式¶

GoVector 提供了强大的命令行界面 (CLI) 和交互式终端用户界面 (TUI)。

交互式 TUI¶

运行二进制文件而不带参数即可进入 交互式 TUI：

govector

(提供美观的绿色主题环境，带有 /? 帮助菜单，自动创建数据库/集合，以及优雅的 serve 中断功能。)

直接命令¶

# 通用语法
govector <命令> [数据库文件] [选项]

# 启动与 Qdrant 兼容的 REST API 服务器
govector serve mydata.db -port 18080

# 插入数据（自动创建数据库和启用 HNSW 的集合，如果不存在）
govector upsert mydata.db -c documents -j '{"id":"1", "vector":[0.1, 0.2], "payload":{"tag":"A"}}'

# 搜索数据（带存在性验证）
govector search mydata.db -c documents -v 0.1,0.2 -l 5

# 列出所有集合
govector ls mydata.db

# 获取集合中的点数
govector count mydata.db -c documents

# 删除集合（保护措施会保护 "default" 集合）
govector rm mydata.db -c documents

🏗️ 架构概览¶

GoVector 的架构由以下几个核心组件构成：

存储引擎：使用 go.etcd.io/bbolt 和 Protocol Buffers 实现持久化存储
索引模块：实现 HNSW（层次可导航小世界）和 Flat 索引
集合管理：为集合提供命名空间隔离和 CRUD 操作
API 层：同时提供 Go 库 API 和与 Qdrant 兼容的 HTTP REST API
量化模块：实现 SQ8 量化以优化内存使用

📊 性能基准¶

在配备 16GB RAM 的标准机器上，使用 128 维向量进行测量：

索引	规模 (N)	构建时间	延迟 (平均)	吞吐量 (QPS)	内存 (分配)
Flat	100K	186 ms	54.46 ms	18 QPS	59 MB
HNSW	100K	20.9 s	0.08 ms	11,812 QPS	311 MB
HNSW	1M	4m 17s	0.11 ms	8,709 QPS	3.32 GB

注意：HNSW 即使在 100 万规模下也保持亚毫秒级延迟，在 100K 时比 Flat 索引快 480 倍。

🛠️ 核心特性¶

纯 Go 实现 & 无 CGO 依赖：可跨平台编译，无需复杂的 C/C++ 依赖
Qdrant 兼容 API：与 Qdrant 相同的 REST API 接口，可作为直接替代品
高性能：针对单节点性能优化，支持亚毫秒级搜索延迟
HNSW 索引：工业级图索引，实现 O(log N) 的搜索复杂度
持久化存储：使用 BoltDB 和 Protocol Buffers 实现超快速持久化
高级过滤：支持 payload 过滤（精确匹配、范围、前缀、正则、包含）
SQ8 量化：内置 8 位标量量化，减少大规模数据的磁盘占用
双模式部署：嵌入式库或带有 REST API 的独立微服务
统一 CLI 和 TUI：强大的命令行界面，带有交互式终端用户界面

📖 下一步¶

命令行指南 - 了解更多关于命令行界面的信息
嵌入式模式 - 深入了解如何将 GoVector 作为库使用
微服务模式 - 了解如何将 GoVector 作为服务器运行
API 参考 - 完整的 API 文档
架构概览 - 详细了解 GoVector 的架构