CLI使用指南

1. 工具概述与核心功能说明

1.1 工具简介

GoVector CLI 是 GoVector 向量数据库的命令行交互工具，提供轻量级、交互式的向量数据管理能力。作为 GoVector 的双重使用模式之一，CLI 工具让您无需编写任何 Go 代码，即可通过终端完成向量的插入、查询、删除等核心操作。

1.2 核心功能特性

功能类别	具体说明
向量操作	支持向量的批量插入（Upsert）、相似性搜索（Search）、计数统计（Count）、删除操作（Delete）
集合管理	提供集合列表查看（ls）功能，支持多集合管理
服务模式	内置 HTTP API 服务器，提供 Qdrant 兼容的 REST 接口
交互模式	支持交互式 TUI 界面，适合快速测试和探索
参数简写	所有参数均支持简短缩写，提升操作效率

1.3 与嵌入式模式的区别

GoVector 提供两种使用模式：

模式	适用场景	特点
CLI 工具模式	快速测试、数据管理、守护进程部署	无需编写代码，通过命令行操作
嵌入式库模式	深度集成到 Go 应用	通过 Go API 直接操作，零网络开销

---

2. 安装与环境配置步骤

2.1 安装方式

方式一：Homebrew 安装（推荐）

brew tap DotNetAge/govector
brew install govector

安装完成后，二进制文件命名为 govectord。

方式二：下载预编译包

从 GitHub Releases 页面下载对应平台的压缩包：

# macOS ARM64 (M1/M2/M3)
curl -O https://github.com/DotNetAge/govector/releases/download/v0.1.3/govector_v0.1.3_darwin_arm64.tar.gz
tar -xzf govector_v0.1.3_darwin_arm64.tar.gz
sudo mv govector /usr/local/bin/govector
chmod +x /usr/local/bin/govector

# Linux AMD64
curl -O https://github.com/DotNetAge/govector/releases/download/v0.1.3/govector_v0.1.3_linux_amd64.tar.gz
tar -xzf govector_v0.1.3_linux_amd64.tar.gz
sudo mv govector /usr/local/bin/govector
chmod +x /usr/local/bin/govector

方式三：从源码编译

git clone https://github.com/DotNetAge/govector.git
cd govector
make build
# 编译产物位于 bin/govector

2.2 环境要求

环境要求	最低版本	推荐版本
Go	1.20	1.21+
内存	512 MB	2 GB+
磁盘	100 MB	10 GB+

2.3 验证安装

govector --help

成功安装后会显示帮助信息。

---

3. 基础命令语法结构

3.1 命令行语法概述

govector <command> [dbfile] [options]

3.2 可用命令列表

命令	功能描述	语法示例
upsert	插入或更新向量数据	govector upsert [dbfile] -j='[...]' -c='<collection>'
search	执行相似性搜索	govector search [dbfile] -v='[...]' -l=<limit> -c='<collection>'
count	统计集合中的向量数量	govector count [dbfile] -c='<collection>'
delete	删除指定 ID 的向量	govector delete [dbfile] -i='[...]' -c='<collection>'
ls	列出数据库中的所有集合	govector ls [dbfile]
rm	删除指定集合	govector rm [dbfile] -c='<collection>'
serve	启动 HTTP API 服务器	govector serve -d=[dbfile] -p=<port>

3.3 交互式 TUI 模式

直接运行 govector [dbfile]，将启动交互式界面：

govector [dbfile]

交互模式支持命令：

Command (upsert/search/count/delete/?/exit) >
// 支持使用 /? 查看帮助

---

4. 常用命令参数详解

4.1 upsert 命令

功能：插入或更新向量数据点。如果未指定 dbfile 则默认使用 govector.db。如果指定的数据库文件或 collection 不存在，系统会自动创建它们（默认启用 HNSW 索引）。

必选参数：

参数	缩写	说明	示例
--json	-j	JSON 格式的向量数据	-j='[{"id":"1","vector":[0.1,0.2],"payload":{}}]'

可选参数：

参数	缩写	默认值	说明
--collection	-c	default	目标集合名称

数据点 JSON 结构：

{
  "id": "唯一标识符",
  "vector": [0.1, 0.2, 0.3],
  "payload": {
    "key": "value"
  }
}

4.2 search 命令

功能：执行向量相似性搜索。如果指定的数据库文件或 collection 不存在，程序将提示错误并优雅退出。

必选参数：

参数	缩写	说明	示例
--vector	-v	查询向量（JSON 数组）	-v='[0.1, 0.2, 0.3]'

可选参数：

参数	缩写	默认值	说明
--limit	-l	10	返回结果数量上限
--collection	-c	default	目标集合名称

4.3 count 命令

功能：统计指定集合中的向量数量。

可选参数：

参数	缩写	默认值	说明
--collection	-c	default	目标集合名称

4.4 delete 命令

功能：删除指定 ID 的向量。

必选参数：

参数	缩写	说明	示例
--ids	-i	要删除的 ID 数组（JSON）	-i='["id1","id2"]'

可选参数：

参数	缩写	默认值	说明
--collection	-c	default	目标集合名称

4.5 ls 命令

功能：列出数据库中的所有集合及其元信息。

参数：无额外参数，直接指定数据库文件即可。

输出信息：

列名	说明
NAME	集合名称
DIM	向量维度
METRIC	距离度量方式（Cosine/Euclidean/Dot）
HNSW	是否启用 HNSW 索引

4.6 rm 命令

功能：删除指定的集合。

必选参数：

参数	缩写	说明	示例
--collection	-c	目标集合名称	-c='test'

注：禁止删除默认集合（default），且若数据库不存在会报错。

4.7 serve 命令

功能：启动 Qdrant 兼容的 HTTP API 服务器。

参数：

参数	缩写	默认值	说明
--port	-p	18080	HTTP 服务端口
--db	-d	govector.db	数据库文件路径

---

5. 各功能模块的具体使用示例

5.1 基础向量操作

示例 1：启动服务

# 使用默认端口 18080
govector serve

# 指定端口和数据库
govector serve -p=18080 -d=mydb.db

# 使用简写参数
govector serve -p=8080 -d=/path/to/data.db

示例 2：插入向量数据

# 插入单条数据
govector upsert mydb.db -j='[{"id":"1","vector":[0.1,0.2,0.3],"payload":{"name":"Apple"}}]' -c=fruits

# 批量插入多条数据
govector upsert mydb.db -j='[
  {"id":"2","vector":[0.8,0.1,0.1],"payload":{"name":"Orange"}},
  {"id":"3","vector":[0.1,0.8,0.1],"payload":{"name":"Dog"}},
  {"id":"4","vector":[0.1,0.1,0.8],"payload":{"name":"Cat"}}
]' -c=animals

示例 3：执行相似性搜索

# 基础搜索
govector search mydb.db -v='[0.9,0.1,0.0]' -c=fruits

# 指定返回结果数量
govector search mydb.db -v='[0.9,0.1,0.0]' -l=5 -c=fruits

# 使用简写
govector search mydb.db -v='[0.8,0.2,0.0]' -l=3 -c=animals

示例 4：统计向量数量

# 统计指定集合
govector count mydb.db -c=fruits

# 使用默认集合
govector count mydb.db

示例 5：删除向量

# 删除单条
govector delete mydb.db -i='["1"]' -c=fruits

# 批量删除
govector delete mydb.db -i='["2","3"]' -c=animals

示例 6：查看所有集合

govector ls mydb.db

输出示例：

Collections in [mydb.db]:
NAME                 | DIM   | METRIC    | HNSW
--------------------------------------------------
fruits               | 3     | Cosine    | true
animals              | 3     | Cosine    | true
--------------------------------------------------

5.2 交互式 TUI 模式示例

$ govector

--- GoVector Interactive TUI ---

[mydb.db | default] Command (upsert/search/count/delete/?/exit) >
// 支持使用 /? 查看帮助 ls
NAME                 | DIM   | METRIC    | HNSW
--------------------------------------------------
fruits               | 3     | Cosine    | true
animals              | 3     | Cosine    | true
--------------------------------------------------

[mydb.db | default] Command (upsert/search/count/delete/?/exit) >
// 支持使用 /? 查看帮助 search
-v='[0.9,0.1,0.0]' -c=fruits
Search Results (1):
1. ID: 2, Score: 0.948683, Payload: map[name:Orange]

[mydb.db | default] Command (upsert/search/count/delete/?/exit) >
// 支持使用 /? 查看帮助 exit
Goodbye!

5.3 服务模式与 HTTP API

当使用 serve 命令启动服务后，可以通过 HTTP API 进行操作：

# 启动服务
govector serve -d=mydb.db -p=18080

# 在另一个终端执行操作
# 插入数据
curl -X PUT http://localhost:18080/collections/fruits/points -H "Content-Type: application/json" -d '{
  "points": [
    {"id": "1", "vector": [1.0, 0.0, 0.0], "payload": {"name": "Apple"}}
  ]
}'

# 搜索
curl -X POST http://localhost:18080/collections/fruits/points/search -H "Content-Type: application/json" -d '{
  "vector": [0.9, 0.1, 0.0],
  "limit": 3
}'

---

6. 高级操作技巧与最佳实践

6.1 批量操作优化

当需要插入大量向量时，建议分批处理：

# 将数据分成小批量，每批 100 条
govector upsert mydb.db -j='[...]batch1...' -c=large_collection
govector upsert mydb.db -j='[...]batch2...' -c=large_collection
# ...

6.2 使用 HNSW 索引提升搜索性能

GoVector 默认使用 HNSW 索引。对于百万级向量规模：

索引类型	搜索延迟	QPS	适用场景
Flat	54 ms	18	小规模（<1万）精确搜索
HNSW	0.08 ms	11,812	大规模（>10万）近似搜索

6.3 量化压缩减少存储

启用 SQ8 量化可将内存占用减少 75%：

在嵌入式模式中启用：

col, err := core.NewCollection("compressed", 128, core.Cosine, store, true)
col.UseQuantization = true  // 启用量化

6.4 守护进程部署

使用 systemd 守护进程：

# /etc/systemd/system/govector.service
[Unit]
Description=GoVector Database Service
After=network.target

[Service]
Type=simple
User=root
ExecStart=/usr/local/bin/govectord -port=18080 -db=/var/lib/govector/data.db -hnsw=true
Restart=always

[Install]
WantedBy=multi-user.target

sudo systemctl enable govector
sudo systemctl start govector

6.5 交互模式中使用历史命令

在交互式 TUI 中，可以结合 shell 历史功能：

# 启用命令历史
export HISTSIZE=1000
govector

---

7. 常见问题解决方案及错误代码说明

7.1 常见错误及解决方案

错误信息	原因分析	解决方案
missing database file	未指定数据库文件	确保命令中包含 .db 文件路径
Invalid JSON	JSON 格式错误	检查 -j 参数的 JSON 语法
Failed to initialize storage	数据库文件权限问题或路径不存在	检查文件路径和目录权限
Failed to open collection	集合不存在或向量维度不匹配	确保集合存在或维度正确
unknown command	命令拼写错误	使用 upsert, search, count, delete, ls, serve
Invalid vector JSON	向量格式错误	确保向量是 JSON 数组格式 [0.1,0.2,0.3]

7.2 向量维度不匹配问题

问题：插入的向量维度与集合定义不一致。

解决方案：

1. 首次插入时指定正确维度
2. 查询现有集合的维度：govector ls mydb.db
3. 确保所有向量具有相同维度

7.3 内存不足问题

问题：处理大规模向量时内存不足。

解决方案：

1. 启用量化压缩
2. 减小批量处理大小
3. 使用 Flat 索引替代 HNSW（内存占用更低）

7.4 端口占用问题

问题：serve 命令启动失败，提示端口被占用。

解决方案：

# 查找占用端口的进程
lsof -i :18080

# 使用其他端口
govector serve -p=18081

---

8. 命令输出结果解释

8.1 search 命令输出格式

Search Results (n):
1. ID: <id>, Score: <score>, Payload: <payload>
2. ID: <id>, Score: <score>, Payload: <payload>
...

字段说明：

字段	说明	示例值
n	返回结果总数	3
ID	向量的唯一标识符	"user_101"
Score	相似度得分（取决于度量方式）	0.9487
Payload	向量的负载数据	map[name:Apple]

8.2 count 命令输出格式

Collection '<name>' count: <count>

8.3 upsert 命令输出格式

Successfully upserted <n> points.

8.4 delete 命令输出格式

deleted <n> points.

8.5 ls 命令输出格式

Collections in [[dbfile]]:
NAME                 | DIM   | METRIC    | HNSW
--------------------------------------------------
<name>               | <dim> | <metric>  | <bool>

---

9. 配置文件说明及自定义配置方法

9.1 环境变量配置

环境变量	说明	默认值
GOVECTOR_DB_PATH	默认数据库路径	govector.db
GOVECTOR_PORT	默认服务端口	18080

9.2 配置文件

GoVector CLI 支持通过 YAML 配置文件进行预设配置：

# ~/.govector/config.yaml
database:
  path: /path/to/default.db
  default_collection: myapp

server:
  port: 18080
  host: 0.0.0.0

index:
  use_hnsw: true
  hnsw_m: 16
  hnsw_ef_construction: 200

quantization:
  enabled: true
  type: sq8

9.3 服务启动参数

参数	说明	推荐值
-hnsw	启用 HNSW 索引	true（生产环境）
-db	数据库文件路径	自定义
-port	服务端口	18080

---

10. 版本信息与更新日志

10.1 版本信息查看

govector --version

或查看 GoVector GitHub 页面获取最新版本信息。

10.2 更新日志

v0.1.3（最新版本）

新增功能：

• 支持 SQ8 量化压缩，减少 75% 内存占用
• 新增 delete 命令支持批量删除
• 增强 search 命令的过滤功能

性能优化：

• HNSW 索引搜索性能提升 15%
• 批量插入速度提升 30%

问题修复：

• 修复特定场景下向量维度验证问题
• 修复并发写入时的竞态条件

v0.1.2

• 新增交互式 TUI 模式
• 支持 systemd 守护进程配置
• 优化内存管理

v0.1.1

• 修复 ls 命令在空数据库上的显示问题
• 增强错误提示信息

v0.1.0

• 初始版本发布
• 支持基础 CRUD 操作
• 内置 HTTP API 服务
• HNSW 索引支持

---

附录 A：快速参考卡片

╔══════════════════════════════════════════════════════════════╗
║                    GoVector CLI 快速参考                      ║
╠══════════════════════════════════════════════════════════════╣
║ 启动服务    govector serve -d=mydb.db -p=18080               ║
║ 交互模式    govector                                          ║
╠══════════════════════════════════════════════════════════════╣
║ 插入向量    govector upsert [dbfile] -j='[...]' -c=<col>          ║
║ 搜索向量    govector search [dbfile] -v='[...]' -l=10 -c=<col>   ║
║ 统计数量    govector count [dbfile] -c=<col>                     ║
║ 删除向量    govector delete [dbfile] -i='["id"]' -c=<col>        ║
║ 列出集合    govector ls [dbfile]                                  ║
╠══════════════════════════════════════════════════════════════╣
║ 参数缩写    -j=json  -v=vector  -l=limit  -c=collection       ║
║             -i=ids   -d=db     -p=port                        ║
╚══════════════════════════════════════════════════════════════╝

---

附录 B：API 端点参考

当服务启动后，可用的 HTTP API 端点：

方法	端点	说明
PUT	/collections/{name}/points	插入或更新向量
POST	/collections/{name}/points/search	搜索相似向量
DELETE	/collections/{name}/points	删除向量
GET	/collections	列出所有集合
GET	/health	健康检查

---

本文档最后更新于 2026-03-27