Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

docs: explain knowledge upload folder paths (#4177)

Jarvisc2edec192b5b
diff --git a/website-docs/04-api/02-api-knowledge.md b/website-docs/04-api/02-api-knowledge.md
index bee5a7bc6..16bed4a7c 100644
--- a/website-docs/04-api/02-api-knowledge.md
+++ b/website-docs/04-api/02-api-knowledge.md
@@ -247,7 +247,7 @@ multipart/form-data 字段:
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `file` | file | 是 | 上传文件 |
-| `fileName` | string | 否 | 覆盖显示名 |
+| `fileName` | string | 否 | 自定义文件名或包含目录的相对路径,如 `docs/spec/design.md`;目录部分用于归类,最后一段作为文件名 |
| `metadata` | JSON 字符串 | 否 | 自定义元数据 |
| `enable_multimodel` | bool | 否 | 多模态处理开关 |
| `tag_ids` | string | 否 | 逗号分隔标签 ID |
@@ -273,6 +273,21 @@ curl -X POST $BASE/api/v1/knowledge-bases/kb-1/knowledge/file \
-H "X-API-Key: $API_KEY" -F 'file=@./manual.pdf' -F 'enable_multimodel=true'
```
+**上传到指定文件夹:** 在 `fileName` 中传入相对于知识库根目录的路径,使用 `/` 分隔目录,并保留文件名及扩展名。上传接口不单独接收 `folder_path` 字段。
+
+```bash
+curl -X POST "$BASE/api/v1/knowledge-bases/kb-1/knowledge/file" \
+ -H "X-API-Key: $API_KEY" \
+ -F 'file=@./design.md' \
+ -F 'fileName=docs/spec/design.md'
+```
+
+上述请求将文档归类到 `docs/spec`,返回的 Knowledge 中 `folder_path` 为 `docs/spec`、`file_name` 为 `design.md`。`file=@./design.md` 指定本地文件,`fileName` 指定知识库中的归类路径。省略 `fileName` 或仅传文件名时,文档位于知识库根目录。
+
+文档知识库的目录由文档的 `folder_path` 推导,无需预先创建:上传到新路径后,目录及其中间层级会出现在目录树中。当前不支持独立创建、保留没有任何文档或子目录文档的空文件夹。Wiki 的创建目录接口管理的是 Wiki 目录,不用于文档知识库。
+
+上传后可用本页的 `GET /api/v1/knowledge-bases/:id/knowledge/folders` 查看目录树。已有文档可通过 `POST /api/v1/knowledge/folder` 移到新路径,无需重新上传;该移动接口才使用 `folder_path` 请求字段。
+
### POST /api/v1/knowledge-bases/:id/knowledge/url
用途:从 URL 抓取创建知识。权限/API key 同上。
@@ -367,7 +382,33 @@ curl -X POST $BASE/api/v1/knowledge-bases/kb-1/knowledge/batch-download \
用途:获取知识库的文件夹目录树。整目录上传时目录结构会被保留(migration `000079` 起存在 `knowledges.folder_path` 列,历史 `file_name` 中的路径已回填到该字段)。权限:Viewer+ + KBAccessRead。
-响应:200 `{"success":true,"data":[{FolderNode}]}`
+目录树由知识条目的 `folder_path` 汇总生成;没有直接文档但包含子目录文档的中间目录也会返回。目录下最后一份文档及所有子目录文档移走后,该目录不再出现在树中。
+
+响应:200。示例(仅有上述上传的 `docs/spec/design.md`):
+
+```json
+{
+ "success": true,
+ "data": {
+ "root_document_count": 0,
+ "total_document_count": 1,
+ "folders": [{
+ "path": "docs",
+ "name": "docs",
+ "document_count": 0,
+ "total_count": 1,
+ "children": [{
+ "path": "docs/spec",
+ "name": "spec",
+ "document_count": 1,
+ "total_count": 1
+ }]
+ }]
+ }
+}
+```
+
+`root_document_count` 为知识库根目录中的文档数,`total_document_count` 为知识库总文档数;目录节点的 `document_count` 仅统计直接文档,`total_count` 包含所有子目录文档。
```bash
curl $BASE/api/v1/knowledge-bases/kb-1/knowledge/folders -H "Authorization: Bearer $TOKEN"
@@ -631,7 +672,7 @@ curl -X POST $BASE/api/v1/knowledge/batch-delete -H "Authorization: Bearer $TOKE
| --- | --- | --- | --- |
| `kb_id` | string | 是 | 知识库 ID |
| `knowledge_ids` | []string | 是 | 待移动的文档 |
-| `folder_path` | string | 否 | 目标文件夹;空字符串表示移回知识库根目录 |
+| `folder_path` | string | 否 | 相对于知识库根目录的目标文件夹路径,如 `docs/spec`;新路径无需预先创建,空字符串表示移回知识库根目录 |
响应:200 `{"success":true}`