# Qdrant REST API 文档

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

> 所有请求 **Content-Type**: `application/json`

---

## 目录

1. [基础信息](#1-基础信息)
2. [Collection 管理](#2-collection-管理)
3. [Point 管理](#3-point-管理)
4. [向量搜索](#4-向量搜索)
5. [Cluster 管理](#5-cluster-管理)

---

## 1. 基础信息

### 1.1 获取服务状态

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

**响应示例**：

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

---

## 2. Collection 管理

### 2.1 获取所有 Collection 列表

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

**响应示例**：

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

---

### 2.2 获取 Collection 详情

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

**响应示例**：

```json
{
  "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` |

**请求体**：

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

**参数说明**：

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

**响应示例**：

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

---

### 2.4 删除 Collection

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

**请求参数**（Path 参数）：

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

**响应示例**：

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

---

### 2.5 更新 Collection 配置

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

**请求体**：

```json
{
  "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 | 写入一致性因子 |

**响应示例**：

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

---

## 3. Point 管理

### 3.1 批量写入（Upsert）Points

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

**请求参数**（Path 参数）：

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

**请求体**：

```json
{
  "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=异步返回 |

**响应示例**：

```json
{
  "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 |

**响应示例**：

```json
{
  "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
```

**请求体**：

```json
{
  "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 | 否 | 筛选条件 |

**响应示例**：

```json
{
  "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 删除）**：

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

**请求体（按 Filter 删除）**：

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

**参数说明**：

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

**响应示例**：

```json
{
  "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

**请求体**：

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

**参数说明**：

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

**响应示例**：

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

---

### 3.6 更新向量（不修改 Payload）

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

**请求体**：

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

**响应示例**：

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

---

### 3.7 设置 Payload

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

**请求体**：

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

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

**响应示例**：

```json
{
  "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
```

**请求体**：

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

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

**响应示例**：

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

---

### 3.9 清空所有 Payload

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

**请求体**：

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

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

**响应示例**：

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

---

## 4. 向量搜索

### 4.1 向量相似度搜索

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

**请求体**：

```json
{
  "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 条件详细说明**：

```json
{
  "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 结构，排除匹配 */ ]
}
```

**响应示例**：

```json
{
  "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
```

**请求体**：

```json
{
  "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 | 是 | 返回多少组 |

**响应示例**：

```json
{
  "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
```

**响应示例**：

```json
{
  "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 导入说明

### 快速使用步骤

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

### 常见问题

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

---

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