Qdrant REST API 文档

基础地址: https://saaschroma.ylrzcloud.com Qdrant 版本: 1.17.1 向量维度: 1024 距离算法: Cosine 已有 Collection: saasai_3

所有请求 Content-Type: application/json

1. 基础信息

1.1 获取服务状态

GET https://saaschroma.ylrzcloud.com/

响应示例：

{
  "title": "qdrant - vector search engine",
  "version": "1.17.1",
  "commit": "eabee371fda447974a94d29fbaa675a6a596cc7b"
}

2. Collection 管理

2.1 获取所有 Collection 列表

GET https://saaschroma.ylrzcloud.com/collections

响应示例：

{
  "result": {
    "collections": [
      {
        "name": "saasai_3"
      }
    ]
  },
  "status": "ok",
  "time": 5.9e-6
}

2.2 获取 Collection 详情

GET https://saaschroma.ylrzcloud.com/collections/saasai_3

响应示例：

{
  "result": {
    "status": "green",
    "optimizer_status": "ok",
    "indexed_vectors_count": 0,
    "points_count": 1,
    "segments_count": 4,
    "config": {
      "params": {
        "vectors": {
          "size": 1024,
          "distance": "Cosine"
        },
        "shard_number": 1,
        "replication_factor": 1,
        "write_consistency_factor": 1,
        "on_disk_payload": true
      },
      "hnsw_config": {
        "m": 16,
        "ef_construct": 100,
        "full_scan_threshold": 10000,
        "max_indexing_threads": 0,
        "on_disk": false
      },
      "optimizer_config": {
        "deleted_threshold": 0.2,
        "vacuum_min_vector_number": 1000,
        "default_segment_number": 0,
        "max_segment_size": null,
        "indexing_threshold": 10000,
        "flush_interval_sec": 5
      },
      "wal_config": {
        "wal_capacity_mb": 32,
        "wal_segments_ahead": 0
      },
      "quantization_config": null
    },
    "payload_schema": {},
    "update_queue": {
      "length": 0
    }
  },
  "status": "ok",
  "time": 0.0002909
}

2.3 创建 Collection

PUT https://saaschroma.ylrzcloud.com/collections/{collectionName}

请求参数（Path 参数）：

参数	类型	说明
collectionName	String	集合名称，例如 `my_knowledge_base`

请求体：

{
  "vectors": {
    "size": 1024,
    "distance": "Cosine"
  }
}

参数说明：

参数	类型	必填	说明
vectors.size	int	是	向量维度（当前固定 1024）
vectors.distance	String	是	距离算法：`Cosine` / `Euclid` / `Dot`

响应示例：

{
  "result": true,
  "status": "ok",
  "time": 0.058248
}

2.4 删除 Collection

DELETE https://saaschroma.ylrzcloud.com/collections/{collectionName}

请求参数（Path 参数）：

参数	类型	说明
collectionName	String	要删除的集合名称

响应示例：

{
  "result": true,
  "status": "ok",
  "time": 0.016075
}

2.5 更新 Collection 配置

PATCH https://saaschroma.ylrzcloud.com/collections/{collectionName}

请求体：

{
  "optimizers_config": {
    "indexing_threshold": 10000
  },
  "params": {
    "replication_factor": 2,
    "write_consistency_factor": 1
  }
}

参数说明：

参数	类型	说明
optimizers_config.indexing_threshold	int	索引阈值，超过此数量自动建索引
params.replication_factor	int	副本因子
params.write_consistency_factor	int	写入一致性因子

响应示例：

{
  "result": true,
  "status": "ok",
  "time": 0.053372
}

3. Point 管理

3.1 批量写入（Upsert）Points

PUT https://saaschroma.ylrzcloud.com/collections/{collectionName}/points

请求参数（Path 参数）：

参数	类型	说明
collectionName	String	集合名称

请求体：

{
  "points": [
    {
      "id": 1,
      "vector": [0.01, 0.02, 0.03, ...],  ← 1024 个 float
      "payload": {
        "document": "这份文件的主要内容是关于XX疾病的基本知识。",
        "chunk_index": 0,
        "doc_id": 1001,
        "dataset_id": 1,
        "file_name": "XX疾病知识手册.pdf"
      }
    },
    {
      "id": 2,
      "vector": [0.04, 0.05, 0.06, ...],  ← 1024 个 float
      "payload": {
        "document": "疾病的病因包括遗传因素和环境因素两个方面。",
        "chunk_index": 1,
        "doc_id": 1001,
        "dataset_id": 1,
        "file_name": "XX疾病知识手册.pdf"
      }
    }
  ],
  "wait": true
}

参数说明：

参数	类型	必填	说明
points[].id	int/long	是	Point 唯一 ID
points[].vector	float[]	是	向量数据，长度 1024
points[].payload	object	否	附加元数据
wait	boolean	否	true=等待写入完成再返回；false=异步返回

响应示例：

{
  "result": {
    "operation_id": 123,
    "status": "completed"
  },
  "status": "ok",
  "time": 0.015
}

3.2 查询单个 Point

GET https://saaschroma.ylrzcloud.com/collections/{collectionName}/points/{id}?with_payload=true&with_vector=true

请求参数：

参数	位置	类型	必填	说明
collectionName	Path	String	是	集合名称
id	Path	long	是	Point ID
with_payload	Query	boolean	否	是否返回 payload，默认 false
with_vector	Query	boolean	否	是否返回 vector，默认 false

响应示例：

{
  "result": {
    "id": 1,
    "version": 2,
    "payload": {
      "document": "这份文件的主要内容是关于XX疾病的基本知识。",
      "chunk_index": 0,
      "doc_id": 1001,
      "file_name": "XX疾病知识手册.pdf"
    },
    "vector": [0.01, 0.02, 0.03, ...]
  },
  "status": "ok",
  "time": 0.000227
}

3.3 滚动查询 Points（分页）

POST https://saaschroma.ylrzcloud.com/collections/{collectionName}/points/scroll

请求体：

{
  "limit": 10,
  "offset": 0,
  "with_payload": true,
  "with_vector": false,
  "filter": {
    "must": [
      {
        "key": "doc_id",
        "match": {
          "value": 1001
        }
      }
    ]
  }
}

参数说明：

参数	类型	必填	说明
limit	int	否	返回数量，默认 10
offset	long/int	否	偏移量（从 0 开始）
with_payload	boolean	否	是否返回 payload
with_vector	boolean	否	是否返回 vector
filter	object	否	筛选条件

响应示例：

{
  "result": {
    "points": [
      {
        "id": 1,
        "payload": {
          "document": "这份文件的主要内容是关于XX疾病的基本知识。",
          "chunk_index": 0,
          "doc_id": 1001
        },
        "vector": null
      },
      {
        "id": 2,
        "payload": {
          "document": "疾病的病因包括遗传因素和环境因素两个方面。",
          "chunk_index": 1,
          "doc_id": 1001
        },
        "vector": null
      }
    ],
    "next_page_offset": 2
  },
  "status": "ok",
  "time": 0.0001
}

注：next_page_offset 为 null 时表示无更多数据。将 next_page_offset 作为下一次请求的 offset 参数即可翻页。

3.4 删除 Points

POST https://saaschroma.ylrzcloud.com/collections/{collectionName}/points/delete

请求体（按 ID 删除）：

{
  "points": [1, 2, 3],
  "wait": true
}

请求体（按 Filter 删除）：

{
  "filter": {
    "must": [
      {
        "key": "doc_id",
        "match": {
          "value": 1001
        }
      }
    ]
  },
  "wait": true
}

参数说明：

参数	类型	必填	说明
points	long[]	二选一	按 ID 列表删除
filter	object	二选一	按筛选条件删除
wait	boolean	否	是否等待完成

响应示例：

{
  "result": {
    "operation_id": 456,
    "status": "completed"
  },
  "status": "ok",
  "time": 0.005
}

3.5 计数 Points

POST https://saaschroma.ylrzcloud.com/collections/{collectionName}/points/count

注意：不是 GET，是 POST

请求体：

{
  "filter": {
    "must": [
      {
        "key": "doc_id",
        "match": {
          "value": 1001
        }
      }
    ]
  }
}

参数说明：

参数	类型	必填	说明
filter	object	否	筛选条件；不传则统计整个 Collection 总数

响应示例：

{
  "result": {
    "count": 5
  },
  "status": "ok",
  "time": 0.00005
}

3.6 更新向量（不修改 Payload）

PUT https://saaschroma.ylrzcloud.com/collections/{collectionName}/points/vectors

请求体：

{
  "points": [
    {
      "id": 1,
      "vector": [0.05, 0.06, 0.07, ...]
    },
    {
      "id": 2,
      "vector": [0.08, 0.09, 0.10, ...]
    }
  ],
  "wait": true
}

响应示例：

{
  "result": {
    "operation_id": 789,
    "status": "completed"
  },
  "status": "ok",
  "time": 0.012
}

3.7 设置 Payload

POST https://saaschroma.ylrzcloud.com/collections/{collectionName}/points/payload

请求体：

{
  "payload": {
    "category": "内科",
    "tags": ["高血压", "糖尿病"],
    "importance": 5
  },
  "points": [1, 2, 3],
  "wait": true
}

可选使用 filter 替代 points 按筛选条件设置

响应示例：

{
  "result": {
    "operation_id": 101,
    "status": "completed"
  },
  "status": "ok",
  "time": 0.008
}

3.8 按 Key 删除 Payload

POST https://saaschroma.ylrzcloud.com/collections/{collectionName}/points/payload/delete

请求体：

{
  "keys": ["category", "tags"],
  "points": [1, 2],
  "wait": true
}

可选使用 filter 替代 points 按筛选条件删除

响应示例：

{
  "result": {
    "operation_id": 102,
    "status": "completed"
  },
  "status": "ok",
  "time": 0.006
}

3.9 清空所有 Payload

PUT https://saaschroma.ylrzcloud.com/collections/{collectionName}/points/payload/clear

请求体：

{
  "points": [1, 2, 3],
  "wait": true
}

可选使用 filter 替代 points 按筛选条件清空

响应示例：

{
  "result": {
    "operation_id": 103,
    "status": "completed"
  },
  "status": "ok",
  "time": 0.007
}

4. 向量搜索

4.1 向量相似度搜索

POST https://saaschroma.ylrzcloud.com/collections/{collectionName}/points/search

请求体：

{
  "vector": [0.01, 0.02, 0.03, ...],
  "limit": 5,
  "with_payload": true,
  "with_vector": false,
  "filter": {
    "must": [
      {
        "key": "dataset_id",
        "match": {
          "value": 1
        }
      },
      {
        "key": "doc_id",
        "match": {
          "value": 1001
        }
      }
    ]
  },
  "params": {
    "hnsw_ef": 128,
    "exact": false
  }
}

参数说明：

参数	类型	必填	说明
vector	float[]	是	查询向量，长度 1024
limit	int	否	返回 TopK 数量，默认 10
with_payload	boolean	否	是否返回 payload
with_vector	boolean	否	是否返回 vector
filter.must[]	object[]	否	筛选条件（AND 关系）
filter.should[]	object[]	否	筛选条件（OR 关系）
params.hnsw_ef	int	否	搜索精度（越大越精确越慢），默认 128
params.exact	boolean	否	true=精确搜索，false=近似搜索

Filter 条件详细说明：

{
  "must": [
    { "key": "string_field",   "match":         { "value": "xxx" } },     // 精确匹配
    { "key": "keyword_field",  "match":         { "keyword": "xxx" } },   // 关键词匹配
    { "key": "text_field",     "match":         { "text": "xxx" } },      // 全文匹配（需配置全文索引）
    { "key": "int_field",      "range":         { "gte": 1, "lte": 100 } },  // 范围匹配
    { "key": "id_field",       "has_id":        [1, 2, 3] },              // ID 匹配
    { "key": "ids_field",      "values_count":  { "gte": 2 } }            // 数组数量匹配
  ],
  "should": [ /* 同 must 结构，OR 逻辑 */ ],
  "must_not": [ /* 同 must 结构，排除匹配 */ ]
}

响应示例：

{
  "result": [
    {
      "id": 2,
      "version": 2,
      "score": 0.923456,
      "payload": {
        "document": "疾病的病因包括遗传因素和环境因素两个方面。",
        "chunk_index": 1,
        "doc_id": 1001,
        "dataset_id": 1,
        "file_name": "XX疾病知识手册.pdf"
      },
      "vector": null
    },
    {
      "id": 1,
      "version": 2,
      "score": 0.891234,
      "payload": {
        "document": "这份文件的主要内容是关于XX疾病的基本知识。",
        "chunk_index": 0,
        "doc_id": 1001,
        "dataset_id": 1,
        "file_name": "XX疾病知识手册.pdf"
      },
      "vector": null
    }
  ],
  "status": "ok",
  "time": 0.002
}

注意：score 值范围 0~1（Cosine 距离），值越大表示越相似。

4.2 分组搜索

POST https://saaschroma.ylrzcloud.com/collections/{collectionName}/points/search/groups

请求体：

{
  "vector": [0.01, 0.02, 0.03, ...],
  "limit": 5,
  "group_by": "doc_id",
  "group_size": 3,
  "with_payload": true,
  "with_vector": false
}

参数说明：

参数	类型	必填	说明
group_by	String	是	按哪个 payload key 分组
group_size	int	是	每组返回多少个结果
limit	int	是	返回多少组

响应示例：

{
  "result": {
    "groups": [
      {
        "id": "1001",
        "hits": [
          { "id": 2, "score": 0.923, "payload": { "doc_id": 1001, ... } },
          { "id": 1, "score": 0.891, "payload": { "doc_id": 1001, ... } }
        ]
      },
      {
        "id": "1002",
        "hits": [
          { "id": 5, "score": 0.815, "payload": { "doc_id": 1002, ... } }
        ]
      }
    ]
  },
  "status": "ok",
  "time": 0.003
}

5. Cluster 管理

5.1 获取 Collection 集群信息

GET https://saaschroma.ylrzcloud.com/collections/{collectionName}/cluster

响应示例：

{
  "result": {
    "peer_id": 1752358415013712,
    "shard_count": 1,
    "local_shards": [
      {
        "shard_id": 0,
        "points_count": 1,
        "state": "Active"
      }
    ],
    "remote_shards": [],
    "shard_transfers": []
  },
  "status": "ok",
  "time": 0.0002224
}

附：APIPost 导入说明

快速使用步骤

打开 APIPost
创建项目或文件夹（如 "Qdrant"）
按上面的格式逐个添加请求：
- 方法：根据接口选择 GET/POST/PUT/DELETE/PATCH
- URL：https://saaschroma.ylrzcloud.com/xxx
- Headers：Content-Type: application/json
- Body：选择 JSON 格式并粘贴对应请求体
点击发送

常见问题

问题	原因	解决
返回 404	Collection 不存在	先创建 Collection 或检查名称拼写
返回 400	请求参数格式错误	检查 JSON 格式和必填字段
搜索返回 score = 0	向量维度不匹配	确认 vector 长度 = 1024
响应慢	数据量太大或未建索引	设置 `params.exact: false` 使用近似搜索

本文档对应 Qdrant v1.17.1 REST API，完整官方文档请参考： https://api.qdrant.tech/api-reference

Qdrant API 文档.md 16 KB

История Исходник

Qdrant REST API 文档

目录

1. 基础信息

1.1 获取服务状态

2. Collection 管理

2.1 获取所有 Collection 列表

2.2 获取 Collection 详情

2.3 创建 Collection

2.4 删除 Collection

2.5 更新 Collection 配置

3. Point 管理

3.1 批量写入（Upsert）Points

3.2 查询单个 Point

3.3 滚动查询 Points（分页）

3.4 删除 Points

3.5 计数 Points

3.6 更新向量（不修改 Payload）

3.7 设置 Payload

3.8 按 Key 删除 Payload

3.9 清空所有 Payload

4. 向量搜索

4.1 向量相似度搜索

4.2 分组搜索

5. Cluster 管理

5.1 获取 Collection 集群信息

附：APIPost 导入说明

快速使用步骤

常见问题

Qdrant API 文档.md 16 KB История Исходник

Qdrant REST API 文档

目录

1. 基础信息

1.1 获取服务状态

2. Collection 管理

2.1 获取所有 Collection 列表

2.2 获取 Collection 详情

2.3 创建 Collection

2.4 删除 Collection

2.5 更新 Collection 配置

3. Point 管理

3.1 批量写入（Upsert）Points

3.2 查询单个 Point

3.3 滚动查询 Points（分页）

3.4 删除 Points

3.5 计数 Points

3.6 更新向量（不修改 Payload）

3.7 设置 Payload

3.8 按 Key 删除 Payload

3.9 清空所有 Payload

4. 向量搜索

4.1 向量相似度搜索

4.2 分组搜索

5. Cluster 管理

5.1 获取 Collection 集群信息

附：APIPost 导入说明

快速使用步骤

常见问题

Qdrant API 文档.md 16 KB

История Исходник