一个“向量版的 SQLite”？

前两天我直在优化goRAG那个项目，当我想RAG寻找一个存储方案时，我傻眼了：

• 用 Qdrant / Milvus / Weaviate？它们非常强大，但都是为了云原生和海量集群设计的。让一个本地桌面 App 启动时去跑一个几百 MB 内存占用的 Docker 容器？这绝对是反人类的设计。
• 用 SQLite / PostgreSQL (pgvector)？这确实是个好主意，但引入 C/C++ 依赖会让跨平台编译（尤其是 Go 的交叉编译）变成一场灾难。

所以我只能妥协，现在只能让goRAG同时支持各个主流的向量数据库，要用起来还得靠Docker，实在太不优雅了！

我真正想要的，是一个“纯粹的、无 CGO 依赖的、可以直接嵌在 Go 代码里，而且能够把数据持久化到本地单文件”的向量数据库。

我不死心在网上又收刮了一通，最后只能放弃，竟然没有人考虑要做个轻量的可嵌入式的 Qrant ?

既然找不到完全满意的轮子，那就自己造一个！我的目标很明确：

1. 纯 Go 实现 (CGO-Free)：一个 go build 走天下。
2. 持久化存储：程序重启，向量不丢。
3. 支持元数据过滤 (Payload)：搜索向量时，能加上 category == "tech" 这样的硬性条件。
4. 兼容 Qdrant API：以后如果业务做大了，代码不用改，无缝把后端 URL 切到真正的 Qdrant 集群。

2. 架构设计：拆解一个向量数据库

要在一小时内干完这件事，我们不能去造那些艰深的底层算法轮子，而是要做一位优雅的“架构整合大师”。

一个现代向量数据库，核心其实就三大块：

1. 存储引擎 (Storage Engine)：负责把向量和附带的 JSON 元数据（Payload）落盘。
2. 索引引擎 (Index Engine)：负责在海量向量中快速找到“最近邻”。
3. API 层 (Serving Layer)：负责对外提供通信接口。

技术选型：

原则：必须小！

• 存储引擎：我选择了 go.etcd.io/bbolt (BoltDB)。它是一个纯 Go 写的 KV 数据库，极其轻量，性能极佳，数据全保存在本地一个 .db 文件里，简直是嵌入式存储的完美之选。
• 索引引擎：暴力轮询（Flat Index）在几百条数据时还凑合，上万条就拉胯了。我们需要 HNSW（分层可导航小世界） 算法。我在这里引入了 Coder 团队开源的纯 Go HNSW 库 github.com/coder/hnsw。
• API 层：直接使用 Go 1.22 原生的 http.ServeMux 增强路由，零框架依赖。

3. 核心代码实战：如何将它们组装起来？

步骤一：定义数据模型 (对齐 Qdrant)

为了能兼容 Qdrant，我们的数据结构必须和它长得一样：一个点（Point）包含 ID、向量（Vector）以及元数据（Payload）。

// Payload 模拟 Qdrant 的 JSON 元数据
type Payload map[string]interface{}

type PointStruct struct {
	ID      string    `json:"id"`
	Vector  []float32 `json:"vector"` 
	Payload Payload   `json:"payload,omitempty"` // 用于条件过滤
}

步骤二：实现带 Payload 过滤的 HNSW 搜索

这是最核心的部分。单纯的 HNSW 只能做空间上的最近邻搜索，但如果用户要求“帮我找最相似的 10 篇文章，但作者必须是 Alice”怎么办？

我们的解法是 后置过滤 (Post-Filtering)：
当带有 Filter 时，我们让 HNSW 引擎超额召回 (Over-fetch)（比如取 Top 100），然后在内存中进行精准的 Payload 匹配，剔除不符合条件的结果，最后再截取 Top 10 返回。

func (h *HNSWIndex) Search(query []float32, filter *Filter, topK int) ([]ScoredPoint, error) {
	// 如果带有过滤条件，放大召回深度以防止结果被全部过滤掉
	fetchK := topK
	if filter != nil {
		fetchK = topK * 10 
	}

	// 1. O(log N) 极速图搜索
	neighbors := h.graph.Search(query, fetchK)

	var results []ScoredPoint
	for _, neighbor := range neighbors {
		point := h.points[neighbor.Key]
		
		// 2. 精确过滤 Payload 元数据
		if !MatchFilter(point.Payload, filter) {
			continue // 作者不是 Alice，跳过！
		}

		// 3. 计算并格式化最终得分
		score := CalculateDistance(h.metric, query, point.Vector)
		results = append(results, ScoredPoint{ID: point.ID, Score: score, Payload: point.Payload})

		if len(results) == topK {
			break
		}
	}
	return results, nil
}

步骤三：暴露 Qdrant 兼容的 REST API

在 api/server.go 中，我们仅需几行代码就能复刻 Qdrant 的搜索接口：

// 拦截 POST /collections/{name}/points/search
func (s *Server) handleSearch(w http.ResponseWriter, r *http.Request) {
    // 解析 Qdrant 格式的请求体 (包含 vector 和 filter)
    var req struct {
        Vector []float32    `json:"vector"`
        Filter *core.Filter `json:"filter,omitempty"` 
        Limit  int          `json:"limit"`
    }
    json.NewDecoder(r.Body).Decode(&req)

    // 调用底层核心执行搜索
    results, _ := col.Search(req.Vector, req.Filter, req.Limit)

    // 返回标准 Qdrant 响应格式
    json.NewEncoder(w).Encode(map[string]interface{}{
        "status": "ok",
        "result": results,
    })
}

4. 暴力美学：性能基准测试 (Benchmark)

1小时后 .... 代码写完了，它到底有多快？

我写了一个 Benchmark 脚本，在纯内存下生成了 10,000 条 128维 的向量，并生成 1,000 条查询，对比普通的暴力轮询（Flat）和我们引入的 HNSW 图索引。

结果极其惊艳！
HNSW 带来了高达 73倍 的性能跃升。在单机单核下，轻松跑出了 1.7万 QPS，每次检索仅需 58微秒。
想象一下，大模型生成一个词都需要几十毫秒，而你的知识库检索时间连 0.1 毫秒都不到，完全消除了 RAG 流程中的检索延迟瓶颈！

5. 成果展示：三种绝佳的食用方式

你可以通过三种方式使用我写的这个轮子：

方式一：微服务模式 (平替本地 Qdrant)

直接跑起来，它就是一个监听 18080 端口的微服务。

go run cmd/govector-server/main.go -port 18080 -db ./govector.db -hnsw=true

然后你在 Python 代码里原来请求 Qdrant 的地方，直接把端口改成 18080，一切照旧运转！

方式二：内嵌模式 (极致性能)

如果你写的是 Go 服务，连 HTTP 都不需要！直接把它像 SQLite 一样 import 进去。

import "github.com/yourusername/govector/core"

// 本地落盘，零网络开销
store, _ := core.NewStorage("app.db")
col, _ := core.NewCollection("docs", 128, core.Cosine, store, true)

// 直接查！
results, _ := col.Search(queryVector, filter, 10)

方式三: home brew

macOS上只要去 brew 一下就能用

 $ brew tap DotNetAge/govector
 $ brew install govector

就这么简单！

结语

这个名为 GoVector 的项目我已经开源到了 GitHub，没有任何外部服务的依赖绑定，非常纯粹。如果国内的开发者兄弟们也在苦恼本地 AI 缺乏好用的嵌入式向量库，源码编译包都一应准备好了，欢迎来白嫖代码或者点个 Star！

👉 源码地址： https://github.com/DotNetAge/govector

(如果这篇文章对你有启发，欢迎在评论区交流你对本地向量存储的看法！)