跳转至

快速开始

本指南面向首次接触 GoVector 的用户，目标是在约 15 分钟内完成环境搭建，并运行第一个向量搜索示例。内容覆盖：

  • 作为 Go 库导入与 Homebrew 安装两种方式
  • 嵌入式模式（零网络开销）的完整流程：初始化存储、创建集合、插入向量、查询与过滤
  • 微服务模式（HTTP API）的启动与基础调用
  • 常见初始化步骤、错误处理与最佳实践
  • 故障排除与常见问题

项目结构

仓库采用按“功能域+层次”混合组织方式：

  • 核心库位于 core/，提供存储、集合、索引、模型等能力
  • API 层位于 api/，提供 Qdrant 兼容的 HTTP 接口
  • 可执行程序位于 cmd/govector/main.go，作为独立服务
  • 示例位于 example/embedded/main.go，展示嵌入式用法
  • Homebrew 脚本位于 scripts/release/govector.rb
  • 性能基准与脚本位于 cmd/bench/ 与 demo.sh
graph TB
subgraph "应用层"
APP["你的 Go 应用
或命令行脚本"]
end
subgraph "GoVector 核心"
CORE_STORAGE["core/Storage
持久化(BoltDB)"]
CORE_COLLECTION["core/Collection
集合管理"]
CORE_MODELS["core/* 模型与过滤器"]
CORE_INDEX["core/VectorIndex 接口"]
end
subgraph "API 层"
API_SERVER["api/Server
HTTP API"]
end
subgraph "可执行程序"
BIN_MAIN["cmd/govector/main.go
微服务入口"]
end
APP --> CORE_COLLECTION
CORE_COLLECTION --> CORE_STORAGE
CORE_COLLECTION --> CORE_INDEX
API_SERVER --> CORE_COLLECTION
BIN_MAIN --> API_SERVER
BIN_MAIN --> CORE_STORAGE

核心组件

  • 存储引擎 Storage：基于 bbolt 的本地持久化，支持点的增删改查、集合元数据管理、可选向量量化
  • 集合 Collection：逻辑集合，封装索引与存储，提供 Upsert/Search/Delete 等线程安全操作
  • 模型与过滤：PointStruct、ScoredPoint、Filter、Condition 等，支持多种匹配类型
  • 索引接口 VectorIndex：统一 Flat/HNSW 等不同索引策略
  • API Server：提供 Qdrant 兼容的 REST 接口，支持集合管理与点操作

架构总览

下图展示了嵌入式与微服务两种模式的交互关系与数据流。

graph TB
subgraph "嵌入式模式"
E_APP["你的应用代码"]
E_STORE["core/Storage"]
E_COL["core/Collection"]
E_IDX["VectorIndex(HNSW/Flat)"]
E_APP --> E_STORE
E_APP --> E_COL
E_COL --> E_IDX
E_COL --> E_STORE
end
subgraph "微服务模式"
S_CLI["客户端/脚本(curl)"]
S_API["api/Server(HTTP)"]
S_BIN["cmd/govector/main.go"]
S_STORE["core/Storage"]
S_COL["core/Collection"]
S_IDX["VectorIndex(HNSW/Flat)"]
S_CLI --> S_API
S_BIN --> S_API
S_BIN --> S_STORE
S_API --> S_COL
S_COL --> S_STORE
S_COL --> S_IDX
end

详细组件分析

嵌入式模式：从零到一的完整示例

嵌入式模式适合直接在你的 Go 应用中使用，无需网络开销。典型流程如下： 1) 初始化本地存储（创建数据库文件） 2) 创建集合（指定维度、距离度量、是否启用 HNSW） 3) 批量写入向量（Upsert） 4) 执行相似度检索（Search），可带 Payload 过滤 5) 关闭存储释放资源

sequenceDiagram
participant App as "你的应用"
participant Store as "core/Storage"
participant Col as "core/Collection"
participant Idx as "VectorIndex"
App->>Store : 初始化存储(路径)
App->>Col : 创建集合(名称, 维度, 度量, 存储, 是否HNSW)
App->>Col : Upsert(向量+元数据)
Col->>Store : 写入持久化
Col->>Idx : 更新内存索引
App->>Col : Search(查询向量, 过滤, K)
Col->>Idx : 查询返回TopK
Col-->>App : 结果(含ID/分数/元数据)
App->>Store : 关闭存储

命令行工具 (CLI) 模式

GoVector 提供了强大的交互式与非交互式命令行工具，支持缩写参数。

  • 启动参数与子命令
  • serve：启动 HTTP 服务，例如 govector serve -p=18080 -d=govector.db
  • ls：列出数据库中的所有集合，例如 govector ls demo.db
  • upsert：写入数据，例如 govector upsert demo.db -c=demo_col -j=[id:1]
  • search：相似度检索，例如 govector search demo.db -c=demo_col -v=[0.1] -l=10
  • count：统计点数，例如 govector count demo.db -c=demo_col
  • delete：删除数据，例如 govector delete demo.db -c=demo_col -i=[1]

命令行工具 (CLI) 模式

GoVector 提供了强大的交互式与非交互式命令行工具，支持缩写参数。

  • 启动参数与子命令
  • serve：启动 HTTP 服务，例如 govector serve -p=18080 -d=govector.db
  • ls：列出数据库中的所有集合，例如 govector ls demo.db
  • upsert：写入数据，例如 govector upsert demo.db -c=demo_col -j='[{"id":"1","vector":[0.1]}]'
  • search：相似度检索，例如 govector search demo.db -c=demo_col -v='[0.1]' -l=10
  • count：统计点数，例如 govector count demo.db -c=demo_col
  • delete：删除数据，例如 govector delete demo.db -c=demo_col -i='["1"]'

微服务模式：启动与基础 API 调用

微服务模式以 HTTP API 提供 Qdrant 兼容接口，适合独立部署或与其他语言服务集成。

  • 启动命令与参数
  • 端口：-port，默认 18080
  • 数据库路径：-db，默认 govector.db
  • 基础 API 调用（参考 demo.sh）
  • 创建集合：POST /collections
  • 写入向量：PUT /collections/{name}/points
  • 搜索：POST /collections/{name}/points/search
  • 删除：POST /collections/{name}/points/delete
  • 列表/详情：GET /collections, GET /collections/{name}
sequenceDiagram
participant Client as "客户端(curl)"
participant Bin as "cmd/govector/main.go"
participant API as "api/Server"
participant Col as "core/Collection"
participant Store as "core/Storage"
Client->>Bin : 启动(端口/数据库/索引参数)
Bin->>Store : 初始化存储
Bin->>Col : 创建默认集合(维度/度量/索引)
Bin->>API : 注册集合并启动HTTP监听
Client->>API : POST /collections (创建集合)
API->>Col : 新建集合
Client->>API : PUT /collections/{name}/points (批量写入)
API->>Col : Upsert
Client->>API : POST /collections/{name}/points/search (查询)
API->>Col : Search(过滤+TopK)
Col-->>API : 返回结果
API-->>Client : JSON响应

数据模型与过滤机制

  • PointStruct：包含 ID、向量、版本号、Payload
  • ScoredPoint：查询结果，包含 ID、版本、分数、Payload
  • Filter/Condition：支持 must/must_not，条件类型包括 exact、range、prefix、contains、regex
  • 匹配规则：Must 全部满足且 MustNot 全不满足时才命中
flowchart TD
Start(["进入过滤匹配"]) --> NilCheck{"Filter为空?"}
NilCheck --> |是| True["返回true(无过滤)"]
NilCheck --> |否| MustAll["遍历Must条件"]
MustAll --> MustFail{"任一不满足?"}
MustFail --> |是| False["返回false"]
MustFail --> |否| MustNotAll["遍历MustNot条件"]
MustNotAll --> MustNotFail{"任一满足?"}
MustNotFail --> |是| False
MustNotFail --> |否| True

依赖关系分析

  • 外部依赖
  • bbolt：本地键值存储
  • protobuf：序列化点与元数据
  • hnsw：HNSW 图索引实现
  • 内部模块
  • core：存储、集合、索引、模型
  • api：HTTP 服务器与路由
  • cmd/govector：微服务入口
  • example/embedded：嵌入式示例
graph LR
GOV["github.com/DotNetAge/govector"]
BBOLT["go.etcd.io/bbolt"]
PROTO["google.golang.org/protobuf"]
HNSW["github.com/coder/hnsw"]
GOV --> BBOLT
GOV --> PROTO
GOV --> HNSW

性能与最佳实践

  • 选择合适的索引
  • 小规模/开发环境：Flat 索引，简单稳定
  • 生产/大规模：HNSW 索引，亚线性搜索复杂度
  • 维度与度量
  • 确保写入向量维度与集合一致
  • Cosine/Euclidean/Dot 在不同场景下表现不同
  • 写入与一致性
  • Upsert 先落盘再更新内存索引；失败时尝试回滚
  • 过滤与查询
  • 使用 Payload 过滤减少候选集，提升查询效率
  • 量化
  • 可开启 SQ8 量化以降低磁盘占用，注意精度权衡

故障排除指南

  • 启动微服务报错
  • 端口被占用：修改 -port 参数
  • 数据库路径权限不足：确保目录可读写
  • 集合参数非法：检查集合配置参数
  • 写入失败
  • 向量维度不匹配：确认集合维度与向量长度一致
  • 存储关闭：确保未提前 Close
  • 查询异常
  • 集合不存在：先创建集合或确认名称正确
  • 过滤语法错误：核对 JSON 结构与字段名
  • Homebrew 安装
  • 权限问题：使用 sudo 或修正目录权限
  • 服务无法启动：查看日志路径 var/log/govector.log

结论

通过本指南，你可以在 15 分钟内完成 GoVector 的安装与首次运行，掌握嵌入式与微服务两种模式的核心用法。建议优先使用嵌入式模式进行本地开发与测试，生产环境推荐 HNSW 索引与合理的过滤策略，结合量化以平衡性能与存储成本。

附录：命令与示例路径