feat: add VectorStore CRUD API endpoints and documentation

Wire VectorStoreService to HTTP with 8 endpoints: types metadata, CRUD
(create/list/get/update/delete), and connection testing (raw + by ID).
Register routes, DI container bindings, and add API documentation.
This commit is contained in:
ochan.kwon
2026-04-10 09:32:48 +09:00
committed by lyingbug
parent a2900d5540
commit 82b46b4b38
5 changed files with 842 additions and 1 deletions
+361
View File
@@ -0,0 +1,361 @@
# Vector Store API
[返回目录](./README.md)
向量存储(VectorStore)API 用于管理向量数据库连接配置。支持 Elasticsearch、PostgreSQL、Qdrant、Milvus、Weaviate、SQLite 六种引擎类型。
| 方法 | 路径 | 描述 |
| ------ | ---------------------------- | ------------------------------ |
| GET | `/vector-stores/types` | 获取支持的引擎类型及配置字段 |
| POST | `/vector-stores/test` | 使用原始凭据测试连接(不保存) |
| POST | `/vector-stores` | 创建向量存储 |
| GET | `/vector-stores` | 获取向量存储列表 |
| GET | `/vector-stores/:id` | 获取向量存储详情 |
| PUT | `/vector-stores/:id` | 更新向量存储(仅名称可修改) |
| DELETE | `/vector-stores/:id` | 删除向量存储(软删除) |
| POST | `/vector-stores/:id/test` | 测试已保存的向量存储连接 |
---
## GET `/vector-stores/types` - 获取支持的引擎类型
返回所有支持的引擎类型,包含连接配置和索引配置的字段定义,可用于前端表单生成。
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/vector-stores/types' \
--header 'X-API-Key: sk-xxxxx'
```
**响应**:
```json
{
"success": true,
"data": [
{
"type": "elasticsearch",
"display_name": "Elasticsearch (Keywords + Vector)",
"connection_fields": [
{"name": "addr", "type": "string", "required": true, "description": "Elasticsearch URL (e.g., http://localhost:9200)"},
{"name": "username", "type": "string", "required": false},
{"name": "password", "type": "string", "required": false, "sensitive": true}
],
"index_fields": [
{"name": "index_name", "type": "string", "required": false, "default": "xwrag_default"},
{"name": "number_of_shards", "type": "number", "required": false},
{"name": "number_of_replicas", "type": "number", "required": false}
]
},
{
"type": "postgres",
"display_name": "PostgreSQL (Keywords + Vector)",
"connection_fields": [
{"name": "use_default_connection", "type": "boolean", "required": false, "default": true, "description": "Use the application's default database connection"},
{"name": "addr", "type": "string", "required": false, "description": "PostgreSQL connection string (required if use_default_connection is false)"},
{"name": "username", "type": "string", "required": false},
{"name": "password", "type": "string", "required": false, "sensitive": true}
]
}
]
}
```
---
## POST `/vector-stores/test` - 测试原始凭据连接
使用提供的凭据执行连接测试,不保存任何数据。成功时返回自动检测到的服务器版本。
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/vector-stores/test' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"engine_type": "elasticsearch",
"connection_config": {
"addr": "http://es:9200",
"username": "elastic",
"password": "changeme"
}
}'
```
**响应(成功)**:
```json
{
"success": true,
"version": "7.10.1"
}
```
> `version` 字段包含自动检测到的服务器版本。如果无法检测(如 Milvus、SQLite),则为空字符串。
**响应(失败)**:
```json
{
"success": false,
"error": "failed to connect to elasticsearch: connection refused or authentication failed"
}
```
---
## POST `/vector-stores` - 创建向量存储
创建一个新的向量存储配置。同一 endpoint + index 组合不允许重复注册(包括环境变量配置的存储)。
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/vector-stores' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"name": "elasticsearch-hot",
"engine_type": "elasticsearch",
"connection_config": {
"addr": "http://es-hot:9200",
"username": "elastic",
"password": "changeme"
},
"index_config": {
"index_name": "my_index"
}
}'
```
**响应** (201):
```json
{
"success": true,
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "elasticsearch-hot",
"engine_type": "elasticsearch",
"connection_config": {
"addr": "http://es-hot:9200",
"username": "elastic",
"password": "***"
},
"index_config": {
"index_name": "my_index"
},
"source": "user",
"readonly": false,
"created_at": "2026-04-07T10:00:00Z",
"updated_at": "2026-04-07T10:00:00Z"
}
}
```
> **注意**: 响应中的敏感字段(`password`、`api_key`)会被掩码为 `"***"`。
> `connection_config.version` 字段在连接测试成功后自动填充(如 `"7.10.1"`),创建时为空。
---
## GET `/vector-stores` - 获取向量存储列表
返回当前租户的所有向量存储,包含环境变量配置的存储(`source: "env"`)和用户创建的存储(`source: "user"`)。环境变量存储排列在前。
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/vector-stores' \
--header 'X-API-Key: sk-xxxxx'
```
**响应**:
```json
{
"success": true,
"data": [
{
"id": "__env_postgres__",
"name": "postgres (env)",
"engine_type": "postgres",
"connection_config": {
"use_default_connection": true
},
"source": "env",
"readonly": true
},
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "elasticsearch-hot",
"engine_type": "elasticsearch",
"connection_config": {
"addr": "http://es-hot:9200",
"username": "elastic",
"password": "***"
},
"source": "user",
"readonly": false
}
]
}
```
---
## GET `/vector-stores/:id` - 获取向量存储详情
根据 ID 获取单个向量存储详情。支持 `__env_*` 格式的环境变量存储 ID。
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/vector-stores/550e8400-e29b-41d4-a716-446655440000' \
--header 'X-API-Key: sk-xxxxx'
```
**响应**:
```json
{
"success": true,
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "elasticsearch-hot",
"engine_type": "elasticsearch",
"connection_config": {
"addr": "http://es-hot:9200",
"username": "elastic",
"password": "***",
"version": "7.10.1"
},
"index_config": {
"index_name": "my_index"
},
"source": "user",
"readonly": false,
"created_at": "2026-04-07T10:00:00Z",
"updated_at": "2026-04-07T10:00:00Z"
}
}
```
---
## PUT `/vector-stores/:id` - 更新向量存储
更新向量存储的名称。`engine_type`、`connection_config`、`index_config` 创建后不可变更。环境变量存储不可修改(返回 400)。
**请求**:
```curl
curl --location --request PUT 'http://localhost:8080/api/v1/vector-stores/550e8400-e29b-41d4-a716-446655440000' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"name": "elasticsearch-hot-renamed"
}'
```
**响应**:
```json
{
"success": true,
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "elasticsearch-hot-renamed",
"engine_type": "elasticsearch",
"connection_config": {
"addr": "http://es-hot:9200",
"username": "elastic",
"password": "***"
},
"index_config": {
"index_name": "my_index"
},
"source": "user",
"readonly": false,
"created_at": "2026-04-07T10:00:00Z",
"updated_at": "2026-04-07T10:05:00Z"
}
}
```
---
## DELETE `/vector-stores/:id` - 删除向量存储
软删除向量存储。环境变量存储不可删除(返回 400)。
**请求**:
```curl
curl --location --request DELETE 'http://localhost:8080/api/v1/vector-stores/550e8400-e29b-41d4-a716-446655440000' \
--header 'X-API-Key: sk-xxxxx'
```
**响应**:
```json
{
"success": true
}
```
---
## POST `/vector-stores/:id/test` - 测试已保存的向量存储连接
对已保存的向量存储或环境变量存储执行连接测试。成功时返回检测到的服务器版本,并自动更新存储记录中的 `connection_config.version` 字段。
**请求**:
```curl
curl --location --request POST 'http://localhost:8080/api/v1/vector-stores/550e8400-e29b-41d4-a716-446655440000/test' \
--header 'X-API-Key: sk-xxxxx'
```
**响应(成功)**:
```json
{
"success": true,
"version": "7.10.1"
}
```
> 对于已保存的存储(非环境变量存储),检测到的版本会自动保存到 `connection_config.version` 中。
**响应(失败)**:
```json
{
"success": false,
"error": "failed to connect to elasticsearch: connection refused or authentication failed"
}
```
---
## 环境变量存储
通过 `RETRIEVE_DRIVER` 环境变量配置的向量存储以虚拟条目形式出现在列表中。这些条目的特征:
- **ID 格式**: `__env_{driver}__`(如 `__env_postgres__`、`__env_elasticsearch_v8__`)
- **source**: `"env"`
- **readonly**: `true`
- **不可修改/删除**: PUT 和 DELETE 返回 400
- **可测试连接**: POST `/:id/test` 正常工作
## 错误码
| HTTP 状态码 | 含义 |
|-------------|------|
| 400 | 请求参数错误、验证失败、尝试修改环境变量存储 |
| 401 | 未认证 |
| 404 | 向量存储不存在 |
| 409 | 同一 endpoint + index 组合已存在 |
| 500 | 内部服务器错误 |