docs(api): rewrite markdown to match current routes

Refs #890 #1049 #1168.

按集成方视角全量审计 17 个 API markdown 文档与 internal/router/router.go
对齐。每个端点新增参数说明小节(path/query/body 字段含义)和响应字段
含义说明(#1168 的核心诉求)。

【与代码对齐】
- 删除已下线端点:system.md 中的 /system/minio/buckets(代码中已无对
  应路由)。
- 修正路径错误:chunk.md 中 /chunks/get-by-id/:id → /chunks/by-id/:id;
  /chunks/:id/delete-question → /chunks/by-id/:id/questions;
  organization.md 中 /organizations/preview/:invite_code → :code。
- 修正字段类型:faq tag_id / entry_id 由 string 改为 int64;
  knowledge.search 响应结构纠正。
- 补齐缺失端点(move-targets、batch-delete、move/progress、pin/unpin/
  stop/continue-stream、tool-approvals、organization agent-shares 等
  30+ 条)。

【精简】
- knowledge-base.md / model.md 把重复 5 次 / 3 次的完整对象样例
  收敛为指向首次出现("字段结构同 POST /xxx 响应"),节省约 400 行
  而不损失信息(仅去重,原作者写的每个字段定义都保留可达)。
- 示例 X-API-Key 统一为 sk-xxxxx(避免读者复制看似真实的 key)。

【清理】
- 删除内部实现细节引用:mcp-service.md 中 6 处 "issue #1173"、
  organization.md 中 "RegisterOrganizationRoutes" 等。

不动 initialization.md:其中端点(KB 配置、模型连通性测试、Ollama 管理)
对集成方有实用价值,保留原作者写好的内容不删。

格式统一遵循 web-search.md 重写后的范式(路由表 + 每端点方法/路径 +
参数表 + curl + 响应 JSON + 字段说明)。
This commit is contained in:
nullkey
2026-05-11 17:37:14 +08:00
committed by lyingbug
parent 54b6f2dc35
commit 1c7171b2c6
17 changed files with 3312 additions and 2393 deletions
+93 -66
View File
@@ -2,24 +2,22 @@
[返回目录](./README.md)
向量存储(VectorStore)API 用于管理向量数据库连接配置。支持 Elasticsearch、PostgreSQL、Qdrant、Milvus、Weaviate、Tencent VectorDB、SQLite 七种引擎类型。
向量存储(VectorStore)API 用于管理租户的向量数据库连接配置,支持 Elasticsearch、PostgreSQL、Qdrant、Milvus、Weaviate、Tencent VectorDB、SQLite 等引擎。接口同时管理用户在 DB 中创建的配置(`source: "user"`)以及通过 `RETRIEVE_DRIVER` 环境变量配置的虚拟存储(`source: "env"`,只读)。
| 方法 | 路径 | 描述 |
| ------ | ---------------------------- | ------------------------------ |
| 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` | 获取支持的引擎类型及字段元数据 |
| 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` - 获取支持的引擎类型
返回所有支持的引擎类型,包含连接配置和索引配置的字段定义,可用于前端表单生成。
返回所有支持的引擎类型及其连接配置字段、索引配置字段的定义,可用于前端动态表单生成。系统级元数据,无需鉴权感知,但仍需 `X-API-Key`。
**请求**:
@@ -38,40 +36,45 @@ curl --location 'http://localhost:8080/api/v1/vector-stores/types' \
"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}
{ "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}
{ "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}
{ "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` - 使用原始凭据测试连接
## POST `/vector-stores/test` - 测试原始凭据连接
用前端表单中尚未保存的凭据执行一次连通性测试,不会写入数据库。成功时返回自动检测到的服务器版本(如 ES 版本号);某些引擎(如 Milvus、SQLite)无法检测版本,`version` 会返回空字符串。
使用提供的凭据执行连接测试,不保存任何数据。成功时返回自动检测到的服务器版本。
**参数说明(请求体)**:
| 字段 | 类型 | 必填 | 说明 |
| ----------------- | ------ | ---- | ------------------------------------------------------------- |
| engine_type | string | 是 | 引擎类型,取自 `/vector-stores/types` 的 `type` |
| connection_config | object | 是 | 该引擎对应的连接配置字段(与 `connection_fields` 对应) |
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/vector-stores/test' \
curl --location --request POST 'http://localhost:8080/api/v1/vector-stores/test' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
@@ -93,8 +96,6 @@ curl --location 'http://localhost:8080/api/v1/vector-stores/test' \
}
```
> `version` 字段包含自动检测到的服务器版本。如果无法检测(如 Milvus、SQLite),则为空字符串。
**响应(失败)**:
```json
@@ -104,13 +105,22 @@ curl --location 'http://localhost:8080/api/v1/vector-stores/test' \
}
```
---
> 注意:测试失败时 HTTP 状态码仍为 `200`,错误信息通过 `success: false` + `error` 字段返回。
## POST `/vector-stores` - 创建向量存储
创建一个新的向量存储配置。同一 endpoint + index 组合不允许重复注册(包括环境变量配置的存储)。
为当前租户创建一个新的向量存储配置。同一 endpoint + index 组合在租户内不允许重复(与环境变量配置的存储也会冲突)。
Tencent VectorDB 使用 `engine_type: "tencent_vectordb"`。`connection_config` 中 `addr`、`username`、`api_key` 为必填,`database` 可选;`index_config.collection_name` 表示集合名前缀,实际集合会按向量维度追加后缀,例如 `weknora_embeddings_768`。Tencent VectorDB 适配器同时支持向量检索和基于 BM25 sparse vector 的关键词检索;旧版本已创建且没有 `sparse_vector` 索引的集合,需要重建并重新导入数据后才能启用关键词检索。
**参数说明(请求体)**:
| 字段 | 类型 | 必填 | 说明 |
| ----------------- | ------ | ---- | --------------------------------------------------------------- |
| name | string | 是 | 存储显示名(租户内友好名) |
| engine_type | string | 是 | 引擎类型,取自 `/vector-stores/types` |
| connection_config | object | 是 | 连接配置(与所选引擎的 `connection_fields` 对应) |
| index_config | object | 否 | 索引配置(与所选引擎的 `index_fields` 对应) |
> Tencent VectorDB 使用 `engine_type: "tencent_vectordb"`。`connection_config` 中 `addr`、`username`、`api_key` 必填,`database` 可选;`index_config.collection_name` 表示集合名前缀,实际集合会按向量维度追加后缀(例如 `weknora_embeddings_768`)。该适配器同时支持向量检索和基于 BM25 sparse vector 的关键词检索;旧版本已创建且没有 `sparse_vector` 索引的集合需要重建并重新导入数据后才能启用关键词检索。
**请求**:
@@ -178,14 +188,11 @@ curl --location 'http://localhost:8080/api/v1/vector-stores' \
}
```
> **注意**: 响应中的敏感字段(`password`、`api_key`)会被掩码为 `"***"`。
> `connection_config.version` 字段在连接测试成功后自动填充(如 `"7.10.1"`),创建时为空。
---
> 响应中的敏感字段(`password`、`api_key` 等)会被掩码为 `"***"`。`connection_config.version` 字段在连接测试成功后才会自动填充,创建时为空。
## GET `/vector-stores` - 获取向量存储列表
返回当前租户的所有向量存储,包含环境变量配置的存储(`source: "env"`)和用户创建的存储(`source: "user"`)。环境变量存储排列在前。
返回当前租户的所有向量存储,包含 `RETRIEVE_DRIVER` 环境变量配置的虚拟存储(`source: "env"`、`readonly: true`)和用户在 DB 中创建的存储(`source: "user"`、`readonly: false`)。环境变量存储排列在前。
**请求**:
@@ -226,11 +233,15 @@ curl --location 'http://localhost:8080/api/v1/vector-stores' \
}
```
---
## GET `/vector-stores/:id` - 获取向量存储详情
根据 ID 获取单个向量存储详情。支持 `__env_*` 格式的环境变量存储 ID。
根据 ID 获取单个向量存储。支持 DB 存储 UUID 和 `__env_*` 形式的环境变量存储 ID(例如 `__env_postgres__`)。
**路径参数**:
| 字段 | 类型 | 必填 | 说明 |
| ---- | ------ | ---- | --------------------------------------------------- |
| id | string | 是 | 向量存储 ID(DB UUID 或 `__env_{driver}__`) |
**请求**:
@@ -265,11 +276,21 @@ curl --location 'http://localhost:8080/api/v1/vector-stores/550e8400-e29b-41d4-a
}
```
---
## PUT `/vector-stores/:id` - 更新向量存储
更新向量存储的名称。`engine_type`、`connection_config`、`index_config` 创建后不可变更。环境变量存储不可修改(返回 400)。
仅支持更新 `name`。`engine_type`、`connection_config`、`index_config` 创建后不可变更;环境变量存储不可修改(返回 `400`)。
**路径参数**:
| 字段 | 类型 | 必填 | 说明 |
| ---- | ------ | ---- | -------------- |
| id | string | 是 | 向量存储 ID |
**参数说明(请求体)**:
| 字段 | 类型 | 必填 | 说明 |
| ---- | ------ | ---- | ----------------- |
| name | string | 是 | 新的存储显示名 |
**请求**:
@@ -307,11 +328,15 @@ curl --location --request PUT 'http://localhost:8080/api/v1/vector-stores/550e84
}
```
---
## DELETE `/vector-stores/:id` - 删除向量存储
软删除向量存储。环境变量存储不可删除(返回 400)。
对 DB 中的存储执行软删除。环境变量存储不可删除(返回 `400`)。
**路径参数**:
| 字段 | 类型 | 必填 | 说明 |
| ---- | ------ | ---- | -------------- |
| id | string | 是 | 向量存储 ID |
**请求**:
@@ -328,11 +353,15 @@ curl --location --request DELETE 'http://localhost:8080/api/v1/vector-stores/550
}
```
---
## POST `/vector-stores/:id/test` - 测试已保存或环境变量存储的连接
## POST `/vector-stores/:id/test` - 测试已保存的向量存储连接
对已保存的 DB 存储或环境变量虚拟存储执行一次连接测试。成功时返回检测到的服务器版本;对 DB 存储,检测到的版本会被自动写回 `connection_config.version`,环境变量存储不会更新。
对已保存的向量存储或环境变量存储执行连接测试。成功时返回检测到的服务器版本,并自动更新存储记录中的 `connection_config.version` 字段。
**路径参数**:
| 字段 | 类型 | 必填 | 说明 |
| ---- | ------ | ---- | --------------------------------------------------- |
| id | string | 是 | 向量存储 ID(DB UUID 或 `__env_{driver}__`) |
**请求**:
@@ -350,8 +379,6 @@ curl --location --request POST 'http://localhost:8080/api/v1/vector-stores/550e8
}
```
> 对于已保存的存储(非环境变量存储),检测到的版本会自动保存到 `connection_config.version` 中。
**响应(失败)**:
```json
@@ -361,24 +388,24 @@ curl --location --request POST 'http://localhost:8080/api/v1/vector-stores/550e8
}
```
---
> 与 `/vector-stores/test` 一致,测试失败时 HTTP 状态码仍为 `200`,错误通过 `success: false` + `error` 返回。
## 环境变量存储
通过 `RETRIEVE_DRIVER` 环境变量配置的向量存储以虚拟条目形式出现在列表中。这些条目的特征:
通过 `RETRIEVE_DRIVER` 环境变量配置的向量存储以虚拟条目形式出现在列表和详情中。这些条目的特征:
- **ID 格式**: `__env_{driver}__`(如 `__env_postgres__`、`__env_elasticsearch_v8__`)
- **source**: `"env"`
- **readonly**: `true`
- **不可修改/删除**: PUT 和 DELETE 返回 400
- **可测试连接**: POST `/:id/test` 正常工作
- **ID 格式**:`__env_{driver}__`(如 `__env_postgres__`、`__env_elasticsearch_v8__`)
- **source**:`"env"`
- **readonly**:`true`
- **不可修改/删除**:`PUT` 和 `DELETE` 返回 `400`
- **可测试连通性**:`POST /vector-stores/:id/test` 正常工作
## 错误码
| HTTP 状态码 | 含义 |
|-------------|------|
| 400 | 请求参数错误、验证失败、尝试修改环境变量存储 |
| 401 | 未认证 |
| 404 | 向量存储不存在 |
| 409 | 同一 endpoint + index 组合已存在 |
| 500 | 内部服务器错误 |
| HTTP 状态码 | 含义 |
| ----------- | --------------------------------------------------- |
| 400 | 请求参数错误、校验失败、尝试修改环境变量存储 |
| 401 | 未认证(缺少租户上下文或 API Key) |
| 404 | 向量存储不存在 |
| 409 | 同一 endpoint + index 组合已存在 |
| 500 | 内部服务器错误 |