一小时手搓轻量级向量数据库，能否替代Qdrant？

一个“向量版的 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 集群。 2. 架构设计：拆解一个向量数据库 要在一小时内干完这件事，我们不能去造那些艰深的底层算法轮子，而是要做一位优雅的“架构整合大师”。 一个现代向量数据库，核心其实就三大块： 存储引擎 (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 增强路由，零框架依赖。 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 图索引。 索引策略 构建耗时 平均查询延迟 吞吐量 (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 流程中的检索延迟瓶颈！ 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 (如果这篇文章对你有启发，欢迎在评论区交流你对本地向量存储的看法！)