字掠哪庸一个"向量版的 SQLite"？
前两天我直在优化goRAG那个项目，当我想RAG寻找一个存储方案时，我傻眼了：
用 Qdrant / Milvus / Weaviate？它们非常强大，但都是为了云原生和海量集群设计的。让一个本地桌面 App 启动时去跑一个几百 MB 内存占用的 Docker 容器？这绝对是反人类的设计。
用 SQLite / PostgreSQL (pgvector)？这确实是个好主意，但引入 C/C++ 依赖会让跨平台编译（尤其是 Go 的交叉编译）变成一场灾难。
所以我只能妥协，现在只能让goRAG同时支持各个主流的向量数据库，要用起来还得靠Docker，实在太不优雅了！
我真正想要的，是一个"纯粹的、无 CGO 依赖的、可以直接嵌在 Go 代码里，而且能够把数据持久化到本地单文件"的向量数据库。
我不死心在网上又收刮了一通，最后只能放弃，竟然没有人考虑要做个轻量的可嵌入式的 Qrant ?
既然找不到完全满意的轮子，那就自己造一个！我的目标很明确：
纯 Go 实现 (CGO-Free)：一个 go build 走天下。
持久化存储：程序重启，向量不丢。
支持元数据过滤 (Payload)：搜索向量时，能加上 category == "tech" 这样的硬性条件。
兼容 Qdrant API：以后如果业务做大了，代码不用改，无缝把后端 URL 切到真正的 Qdrant 集群。
- 架构设计：拆解一个向量数据库
要在一小时内干完这件事，我们不能去造那些艰深的底层算法轮子，而是要做一位优雅的"架构整合大师"。
一个现代向量数据库，核心其实就三大块：
存储引擎 (Storage Engine)：负责把向量和附带的 JSON 元数据（Payload）落盘。
索引引擎 (Index Engine)：负责在海量向量中快速找到"最近邻"。
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 增强路由，零框架依赖。
- 核心代码实战：如何将它们组装起来？
步骤一：定义数据模型 (对齐 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,
})
}
- 暴力美学：性能基准测试 (Benchmark)
1小时后 .... 代码写完了，它到底有多快？
我写了一个 Benchmark 脚本，在纯内存下生成了 10,000 条 128维 的向量，并生成 1,000 条查询，对比普通的暴力轮询（Flat）和我们引入的 HNSW 图索引。
索引策略 构建耗时 平均查询延迟 吞吐量 (QPS)
Flat Index (线性扫描) 0 ms 4.267 毫秒 234 次/秒
HNSW Index (图搜索) 1688 ms 0.058 毫秒 (58微秒) 17,150 次/秒
结果极其惊艳！
HNSW 带来了高达 73倍 的性能跃升。在单机单核下，轻松跑出了 1.7万 QPS，每次检索仅需 58微秒。
想象一下，大模型生成一个词都需要几十毫秒，而你的知识库检索时间连 0.1 毫秒都不到，完全消除了 RAG 流程中的检索延迟瓶颈！
- 成果展示：三种绝佳的食用方式
你可以通过三种方式使用我写的这个轮子：
方式一：微服务模式 (平替本地 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