API 参考¶

GoVector 提供与 Qdrant 兼容的 REST API，用于管理向量集合和执行相似度搜索。本文档提供了所有 API 端点、请求/响应格式和使用示例的全面参考。

📡 API 端点¶

集合管理¶

方法	端点	描述
POST	`/collections`	创建新集合
DELETE	`/collections/{name}`	删除集合
GET	`/collections`	列出所有集合
GET	`/collections/{name}`	获取集合信息

点操作¶

方法	端点	描述
PUT	`/collections/{name}/points`	写入点
POST	`/collections/{name}/points/search`	搜索相似向量
POST	`/collections/{name}/points/delete`	删除点

📝 端点详情¶

POST /collections¶

创建具有指定配置的新集合。

请求体：

{
  "name": "documents",
  "vector_size": 384,
  "distance": "cosine",
  "hnsw": true,
  "parameters": {
    "m": 16,
    "ef_construction": 100,
    "ef_search": 10,
    "k": 10
  }
}

参数： - name：(必填) 集合名称 - vector_size：(必填) 向量维度 - distance：(必填) 距离度量，支持 "cosine"、"euclidean"、"dot" - hnsw：(可选) 是否启用 HNSW 索引（默认：true） - parameters：(可选) HNSW 索引参数

响应：

{
  "status": "ok",
  "result": {
    "name": "documents",
    "vector_size": 384,
    "distance": "cosine",
    "hnsw": true,
    "parameters": {
      "m": 16,
      "ef_construction": 100,
      "ef_search": 10,
      "k": 10
    },
    "operation": "completed"
  }
}

错误： - 400 Bad Request：无效参数 - 409 Conflict：集合已存在 - 500 Internal Server Error：内部错误

DELETE /collections/{name}¶

删除集合及其所有数据。

响应：

{
  "status": "ok",
  "result": {
    "operation": "completed",
    "collection": "documents"
  }
}

错误： - 404 Not Found：集合不存在

GET /collections¶

列出所有集合的基本信息。

响应：

{
  "status": "ok",
  "result": [
    {
      "name": "documents",
      "vector_size": 384,
      "distance": "cosine",
      "points_count": 100
    }
  ]
}

GET /collections/{name}¶

获取集合的详细信息。

响应：

{
  "status": "ok",
  "result": {
    "name": "documents",
    "vector_size": 384,
    "distance": "cosine",
    "points_count": 100
  }
}

错误： - 404 Not Found：集合不存在

PUT /collections/{name}/points¶

向集合中写入点。

请求体：

{
  "points": [
    {
      "id": "doc_1",
      "vector": [0.1, 0.2, 0.3, /* ... */],
      "payload": {"category": "tech", "author": "John"}
    }
  ]
}

响应：

{
  "status": "ok",
  "result": {
    "operation": "completed"
  }
}

错误： - 400 Bad Request：无效参数 - 404 Not Found：集合不存在

POST /collections/{name}/points/search¶

搜索相似向量。

请求体：

{
  "vector": [0.1, 0.2, 0.3, /* ... */],
  "filter": {
    "must": [
      {
        "key": "category",
        "type": "exact",
        "match": {"value": "tech"}
      }
    ]
  },
  "limit": 10
}

响应：

{
  "status": "ok",
  "result": [
    {
      "id": "doc_1",
      "score": 0.999,
      "payload": {"category": "tech", "author": "John"}
    }
  ]
}

错误： - 400 Bad Request：无效参数 - 404 Not Found：集合不存在

POST /collections/{name}/points/delete¶

按 ID 或过滤器删除点。

请求体（按 ID）：

{
  "points": ["doc_1", "doc_2"]
}

请求体（按过滤器）：

{
  "filter": {
    "must": [
      {
        "key": "category",
        "type": "exact",
        "match": {"value": "tech"}
      }
    ]
  }
}

响应：

{
  "status": "ok",
  "result": {
    "operation": "completed",
    "deleted": 2
  }
}

错误： - 400 Bad Request：无效参数 - 404 Not Found：集合不存在

📊 数据模型¶

点¶

{
  "id": "doc_1",
  "vector": [0.1, 0.2, 0.3],
  "payload": {"category": "tech", "author": "John"}
}

带分数的点¶

{
  "id": "doc_1",
  "score": 0.999,
  "payload": {"category": "tech", "author": "John"}
}

过滤器¶

{
  "must": [
    {
      "key": "category",
      "type": "exact",
      "match": {"value": "tech"}
    },
    {
      "key": "age",
      "type": "range",
      "range": {"gte": 18, "lte": 30}
    }
  ],
  "must_not": [
    {
      "key": "status",
      "type": "exact",
      "match": {"value": "inactive"}
    }
  ]
}

条件类型¶

exact：精确值匹配
range：范围比较（gt, gte, lt, lte）
prefix：前缀匹配（字符串）
contains：包含匹配（数组或字符串）
regex：正则表达式匹配（字符串）

🚀 使用示例¶

创建集合¶

curl -X POST http://localhost:18080/collections \
  -H "Content-Type: application/json" \
  -d '{
    "name": "documents",
    "vector_size": 384,
    "distance": "cosine",
    "hnsw": true
  }'

写入点¶

curl -X PUT http://localhost:18080/collections/documents/points \
  -H "Content-Type: application/json" \
  -d '{
    "points": [
      {
        "id": "doc_1",
        "vector": [0.1, 0.2, 0.3, /* ... 384 维度 ... */],
        "payload": {"category": "tech", "author": "John"}
      },
      {
        "id": "doc_2",
        "vector": [0.4, 0.5, 0.6, /* ... 384 维度 ... */],
        "payload": {"category": "business", "author": "Jane"}
      }
    ]
  }'

搜索向量¶

curl -X POST http://localhost:18080/collections/documents/points/search \
  -H "Content-Type: application/json" \
  -d '{
    "vector": [0.15, 0.25, 0.35, /* ... 384 维度 ... */],
    "filter": {
      "must": [
        {
          "key": "category",
          "type": "exact",
          "match": {"value": "tech"}
        }
      ]
    },
    "limit": 10
  }'

删除点¶

curl -X POST http://localhost:18080/collections/documents/points/delete \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "must": [
        {
          "key": "category",
          "type": "exact",
          "match": {"value": "tech"}
        }
      ]
    }
  }'

⚠️ 错误码¶

状态码	描述
400	Bad Request - 无效参数
404	Not Found - 集合不存在
409	Conflict - 集合已存在
500	Internal Server Error - 内部错误

🔧 配置¶

服务器启动¶

# 启动服务器
./govector serve [数据库路径] [选项]

# 选项：
# -port: 监听端口（默认：18080）
# -db: 数据库文件路径（默认：govector.db）

示例¶

# 在端口 8080 上启动服务器，使用数据库文件 "myvectors.db"
./govector serve myvectors.db -port 8080

📚 Qdrant 兼容性¶

GoVector 提供与 Qdrant 兼容的 API，这意味着你可以使用与 Qdrant 相同的客户端库和代码。

关键兼容性特性¶

相同的 API 端点和请求/响应格式
相同的过滤器语法和语义
相同的距离度量（cosine, euclidean, dot）

差异¶

GoVector 是轻量级嵌入式的，而 Qdrant 是分布式系统
GoVector 使用 BoltDB 进行存储，而不是 RocksDB
GoVector 内置支持 SQ8 量化
GoVector 不包含内置的认证或速率限制（建议通过反向代理实现）

🤔 故障排查¶

常见问题¶

集合未找到
确保在执行操作前集合已存在
检查集合名称是否拼写正确
向量维度不匹配
确保向量长度与集合的 vector_size 匹配
端口被占用
使用 -port 参数指定不同的端口
权限问题
确保数据库目录可读/可写
搜索结果为空
检查向量维度是否匹配
检查过滤器条件是否过于严格

📖 下一步¶

集合管理 API - 详细的集合管理 API
点操作 API - 详细的点操作 API
数据模型 - 详细的数据模型文档
错误处理 - 错误处理最佳实践