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:
+80
-84
@@ -2,22 +2,35 @@
|
||||
|
||||
[返回目录](./README.md)
|
||||
|
||||
| 方法 | 路径 | 描述 |
|
||||
| ------ | --------------------------- | ------------------------ |
|
||||
| GET | `/chunks/:knowledge_id` | 获取知识的分块列表 |
|
||||
| PUT | `/chunks/:knowledge_id/:id` | 更新分块 |
|
||||
| DELETE | `/chunks/:knowledge_id/:id` | 删除分块 |
|
||||
| DELETE | `/chunks/:knowledge_id` | 删除知识下的所有分块 |
|
||||
| GET | `/chunks/get-by-id/:id` | 根据ID直接获取分块 |
|
||||
| DELETE | `/chunks/:id/delete-question` | 删除分块的生成问题 |
|
||||
| 方法 | 路径 | 描述 |
|
||||
| ------ | --------------------------------- | -------------------------- |
|
||||
| GET | `/chunks/:knowledge_id` | 获取知识的分块列表 |
|
||||
| PUT | `/chunks/:knowledge_id/:id` | 更新分块 |
|
||||
| DELETE | `/chunks/:knowledge_id/:id` | 删除单个分块 |
|
||||
| DELETE | `/chunks/:knowledge_id` | 删除知识下的所有分块 |
|
||||
| GET | `/chunks/by-id/:id` | 根据分块 ID 直接获取分块 |
|
||||
| DELETE | `/chunks/by-id/:id/questions` | 删除分块下的某个生成问题 |
|
||||
|
||||
## GET `/chunks/:knowledge_id?page=&page_size=` - 获取知识的分块列表
|
||||
## GET `/chunks/:knowledge_id` - 获取知识的分块列表
|
||||
|
||||
**路径参数**:
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
| ------------- | ------ | ----------- |
|
||||
| knowledge_id | string | 知识 ID |
|
||||
|
||||
**查询参数**:
|
||||
|
||||
| 字段 | 类型 | 默认 | 说明 |
|
||||
| ---------- | ---- | ---- | ---------- |
|
||||
| page | int | 1 | 页码 |
|
||||
| page_size | int | 20 | 每页条数 |
|
||||
|
||||
**请求**:
|
||||
|
||||
```curl
|
||||
curl --location 'http://localhost:8080/api/v1/chunks/4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5?page=1&page_size=1' \
|
||||
--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \
|
||||
--header 'X-API-Key: sk-xxxxx' \
|
||||
--header 'Content-Type: application/json'
|
||||
```
|
||||
|
||||
@@ -61,21 +74,31 @@ curl --location 'http://localhost:8080/api/v1/chunks/4c4e7c1a-09cf-485b-a7b5-24b
|
||||
|
||||
## PUT `/chunks/:knowledge_id/:id` - 更新分块
|
||||
|
||||
更新指定分块的内容和属性。
|
||||
更新指定分块的内容和属性。所有字段均可选,未传则保留原值。
|
||||
|
||||
**请求参数**:
|
||||
- `content`: 分块内容(可选)
|
||||
- `chunk_index`: 分块索引(可选)
|
||||
- `is_enabled`: 是否启用(可选)
|
||||
- `start_at`: 起始位置(可选)
|
||||
- `end_at`: 结束位置(可选)
|
||||
- `image_info`: 图片信息(可选)
|
||||
**路径参数**:
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
| ------------- | ------ | ----------- |
|
||||
| knowledge_id | string | 知识 ID |
|
||||
| id | string | 分块 ID |
|
||||
|
||||
**参数说明(请求体)**:
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
| ------------ | ------- | ---- | --------------------- |
|
||||
| content | string | 否 | 分块内容 |
|
||||
| chunk_index | int | 否 | 分块在知识中的序号 |
|
||||
| is_enabled | boolean | 否 | 是否启用 |
|
||||
| start_at | int | 否 | 起始位置(字符偏移) |
|
||||
| end_at | int | 否 | 结束位置(字符偏移) |
|
||||
| image_info | string | 否 | 图像分块的元信息(JSON 字符串) |
|
||||
|
||||
**请求**:
|
||||
|
||||
```curl
|
||||
curl --location --request PUT 'http://localhost:8080/api/v1/chunks/4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5/df10b37d-cd05-4b14-ba8a-e1bd0eb3bbd7' \
|
||||
--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \
|
||||
--header 'X-API-Key: sk-xxxxx' \
|
||||
--header 'Content-Type: application/json' \
|
||||
--data '{
|
||||
"content": "更新后的分块内容",
|
||||
@@ -89,41 +112,23 @@ curl --location --request PUT 'http://localhost:8080/api/v1/chunks/4c4e7c1a-09cf
|
||||
{
|
||||
"data": {
|
||||
"id": "df10b37d-cd05-4b14-ba8a-e1bd0eb3bbd7",
|
||||
"tenant_id": 1,
|
||||
"knowledge_id": "4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5",
|
||||
"knowledge_base_id": "kb-00000001",
|
||||
"tag_id": "",
|
||||
"content": "更新后的分块内容",
|
||||
"chunk_index": 0,
|
||||
"is_enabled": true,
|
||||
"status": 2,
|
||||
"start_at": 0,
|
||||
"end_at": 964,
|
||||
"pre_chunk_id": "",
|
||||
"next_chunk_id": "",
|
||||
"chunk_type": "text",
|
||||
"parent_chunk_id": "",
|
||||
"relation_chunks": null,
|
||||
"indirect_relation_chunks": null,
|
||||
"metadata": null,
|
||||
"content_hash": "",
|
||||
"image_info": "",
|
||||
"created_at": "2025-08-12T11:52:36.168632+08:00",
|
||||
"updated_at": "2025-08-12T12:00:00.000000+08:00",
|
||||
"deleted_at": null
|
||||
"...": "其他字段同 GET 响应"
|
||||
},
|
||||
"success": true
|
||||
}
|
||||
```
|
||||
|
||||
## DELETE `/chunks/:knowledge_id/:id` - 删除分块
|
||||
## DELETE `/chunks/:knowledge_id/:id` - 删除单个分块
|
||||
|
||||
**路径参数**: 同 PUT。
|
||||
|
||||
**请求**:
|
||||
|
||||
```curl
|
||||
curl --location --request DELETE 'http://localhost:8080/api/v1/chunks/4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5/df10b37d-cd05-4b14-ba8a-e1bd0eb3bbd7' \
|
||||
--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \
|
||||
--header 'Content-Type: application/json'
|
||||
--header 'X-API-Key: sk-xxxxx'
|
||||
```
|
||||
|
||||
**响应**:
|
||||
@@ -137,12 +142,17 @@ curl --location --request DELETE 'http://localhost:8080/api/v1/chunks/4c4e7c1a-0
|
||||
|
||||
## DELETE `/chunks/:knowledge_id` - 删除知识下的所有分块
|
||||
|
||||
**路径参数**:
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
| ------------- | ------ | ----------- |
|
||||
| knowledge_id | string | 知识 ID |
|
||||
|
||||
**请求**:
|
||||
|
||||
```curl
|
||||
curl --location --request DELETE 'http://localhost:8080/api/v1/chunks/4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5' \
|
||||
--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \
|
||||
--header 'Content-Type: application/json'
|
||||
--header 'X-API-Key: sk-xxxxx'
|
||||
```
|
||||
|
||||
**响应**:
|
||||
@@ -154,60 +164,46 @@ curl --location --request DELETE 'http://localhost:8080/api/v1/chunks/4c4e7c1a-0
|
||||
}
|
||||
```
|
||||
|
||||
## GET `/chunks/get-by-id/:id` - 根据ID直接获取分块
|
||||
## GET `/chunks/by-id/:id` - 根据 ID 直接获取分块
|
||||
|
||||
根据分块ID直接获取分块信息,无需提供知识ID。
|
||||
无需提供 `knowledge_id` 即可获取分块。常用于跨知识库的引用展示。
|
||||
|
||||
**路径参数**:
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
| ---- | ------ | ------- |
|
||||
| id | string | 分块 ID |
|
||||
|
||||
**请求**:
|
||||
|
||||
```curl
|
||||
curl --location 'http://localhost:8080/api/v1/chunks/get-by-id/df10b37d-cd05-4b14-ba8a-e1bd0eb3bbd7' \
|
||||
--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \
|
||||
--header 'Content-Type: application/json'
|
||||
curl --location 'http://localhost:8080/api/v1/chunks/by-id/df10b37d-cd05-4b14-ba8a-e1bd0eb3bbd7' \
|
||||
--header 'X-API-Key: sk-xxxxx'
|
||||
```
|
||||
|
||||
**响应**:
|
||||
**响应**: 同 `GET /chunks/:knowledge_id` 列表中的单条 data。
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"id": "df10b37d-cd05-4b14-ba8a-e1bd0eb3bbd7",
|
||||
"tenant_id": 1,
|
||||
"knowledge_id": "4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5",
|
||||
"knowledge_base_id": "kb-00000001",
|
||||
"tag_id": "",
|
||||
"content": "彗星xxxx",
|
||||
"chunk_index": 0,
|
||||
"is_enabled": true,
|
||||
"status": 2,
|
||||
"start_at": 0,
|
||||
"end_at": 964,
|
||||
"pre_chunk_id": "",
|
||||
"next_chunk_id": "",
|
||||
"chunk_type": "text",
|
||||
"parent_chunk_id": "",
|
||||
"relation_chunks": null,
|
||||
"indirect_relation_chunks": null,
|
||||
"metadata": null,
|
||||
"content_hash": "",
|
||||
"image_info": "",
|
||||
"created_at": "2025-08-12T11:52:36.168632+08:00",
|
||||
"updated_at": "2025-08-12T11:52:53.376871+08:00",
|
||||
"deleted_at": null
|
||||
},
|
||||
"success": true
|
||||
}
|
||||
```
|
||||
## DELETE `/chunks/by-id/:id/questions` - 删除分块下的某个生成问题
|
||||
|
||||
## DELETE `/chunks/:id/delete-question` - 删除分块的生成问题
|
||||
删除指定分块关联的某条生成问题。
|
||||
|
||||
删除指定分块关联的生成问题。
|
||||
**路径参数**:
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
| ---- | ------ | ------- |
|
||||
| id | string | 分块 ID |
|
||||
|
||||
**参数说明(请求体)**:
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
| ----------- | ------ | ---- | ----------- |
|
||||
| question_id | string | 是 | 问题 ID |
|
||||
|
||||
**请求**:
|
||||
|
||||
```curl
|
||||
curl --location --request DELETE 'http://localhost:8080/api/v1/chunks/df10b37d-cd05-4b14-ba8a-e1bd0eb3bbd7/delete-question' \
|
||||
--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \
|
||||
curl --location --request DELETE 'http://localhost:8080/api/v1/chunks/by-id/df10b37d-cd05-4b14-ba8a-e1bd0eb3bbd7/questions' \
|
||||
--header 'X-API-Key: sk-xxxxx' \
|
||||
--header 'Content-Type: application/json' \
|
||||
--data '{
|
||||
"question_id": "q-00000001"
|
||||
|
||||
Reference in New Issue
Block a user