V4.8.15 feature (#3331)

* feat: add customize toolkit (#3205) * chaoyang * fix-auth * add toolkit * add order * plugin usage * fix * delete console: * Fix: Fix fullscreen preview top positioning and improve Markdown rendering logic (#3247) * 完成任务：修复全屏预览顶部固定问题，优化 Markdown 渲染逻辑 * 有问题修改 * 问题再修改 * 修正问题 * fix: plugin standalone display issue (#3254) * 4.8.15 test (#3246) * o1 config * perf: system plugin code * 调整系统插件代码。增加html 渲染安全配置。 (#3258) * perf: base64 picker * perf: list app or dataset * perf: plugin config code * 小窗适配等问题 (#3257) * 小窗适配等问题 * git问题 * 小窗剩余问题 * feat: system plugin auth and lock version (#3265) * feat: system plugin auth and lock version * update comment * 4.8.15 test (#3267) * tmp log * perf: login direct * perf: iframe html code * remove log * fix: plugin standalone display (#3277) * refactor: 页面拆分&i18n拆分 (#3281) * refactor: account组件拆成独立页面 * script: 新增i18n json文件创建脚本 * refactor: 页面i18n拆分 * i18n: add en&hant * 4.8.15 test (#3285) * tmp log * remove log * fix: watch avatar refresh * perf: i18n code * fix(plugin): use intro instead of userguide (#3290) * Universal SSO (#3292) * tmp log * remove log * feat: common oauth * readme * perf: sso provider * remove sso code * perf: refresh plugins * feat: add api dataset (#3272) * add api-dataset * fix api-dataset * fix api dataset * fix ts * perf: create collection code (#3301) * tmp log * remove log * perf: i18n change * update version doc * feat: question guide from chatId * perf: create collection code * fix: request api * fix: request api * fix: tts auth and response type (#3303) * perf: md splitter * fix: tts auth and response type * fix: api file dataset (#3307) * perf: api dataset init (#3310) * perf: collection schema * perf: api dataset init * refactor: 团队管理独立页面 (#3302) * ui: 团队管理独立页面 * 代码优化 * fix * perf: sync collection and ui check (#3314) * perf: sync collection * remove script * perf: update api server * perf: api dataset parent * perf: team ui * perf: team 18n * update team ui * perf: ui check * perf: i18n * fix: debug variables & cronjob & system plugin callback load (#3315) * fix: debug variables & cronjob & system plugin callback load * fix type * fix * fix * fix: plugin dataset quote;perf: system variables init (#3316) * fix: plugin dataset quote * perf: system variables init * perf: node templates ui;fix: dataset import ui (#3318) * fix: dataset import ui * perf: node templates ui * perf: ui refresh * feat:套餐改名和套餐跳转配置 (#3309) * fixing:except Sidebar * 去除了多余的代码 * 修正了套餐说明的代码 * 修正了误删除的show_git代码 * 修正了名字部分等代码 * 修正了问题,遗留了其他和ui讨论不一致的部分 * 4.8.15 test (#3319) * remove log * pref: bill ui * pref: bill ui * perf: log * html渲染文档 (#3270) * html渲染文档 * 文档有点小问题 * feat: doc (#3322) * 集合重训练 (#3282) * rebaser * 一点补充 * 小问题 * 其他问题修正，删除集合保留文件的参数还没找到... * reTraining * delete uesless * 删除了一行错误代码 * 集合重训练部分 * fixing * 删除console代码 * feat: navbar item config (#3326) * perf: custom navbar code;perf: retraining code;feat: api dataset and dataset api doc (#3329) * feat: api dataset and dataset api doc * perf: retraining code * perf: custom navbar code * fix: ts (#3330) * fix: ts * fix: ts * retraining ui * perf: api collection filter * perf: retrining button --------- Co-authored-by: heheer <heheer@sealos.io> Co-authored-by: Jiangween <145003935+Jiangween@users.noreply.github.com> Co-authored-by: papapatrick <109422393+Patrickill@users.noreply.github.com>
2025-07-21 03:35:36 +00:00 · 2024-12-06 10:56:53 +08:00
parent b188544386
commit 1aebe5f185
307 changed files with 7383 additions and 3981 deletions
--- a/docSite/content/zh-cn/docs/development/configuration.md
+++ b/docSite/content/zh-cn/docs/development/configuration.md
@@ -43,7 +43,7 @@ weight: 708
      "usedInExtractFields": true, // 是否用于内容提取（务必保证至少有一个为true）
      "usedInToolCall": true, // 是否用于工具调用（务必保证至少有一个为true）
      "usedInQueryExtension": true, // 是否用于问题优化（务必保证至少有一个为true）
-      "toolChoice": true, // 是否支持工具选择（分类，内容提取，工具调用会用到。目前只有gpt支持）
+      "toolChoice": true, // 是否支持工具选择（分类，内容提取，工具调用会用到。）
      "functionCall": false, // 是否支持函数调用（分类，内容提取，工具调用会用到。会优先使用 toolChoice，如果为false，则使用 functionCall，如果仍为 false，则使用提示词模式）
      "customCQPrompt": "", // 自定义文本分类提示词（不支持工具和函数调用的模型
      "customExtractPrompt": "", // 自定义内容提取提示词
@@ -95,9 +95,7 @@ weight: 708
      "customExtractPrompt": "",
      "defaultSystemChatPrompt": "",
      "defaultConfig": {
-        "temperature": 1,
-        "max_tokens": null,
-        "stream": false
+        "temperature": 1
      }
    },
    {
@@ -122,9 +120,7 @@ weight: 708
      "customExtractPrompt": "",
      "defaultSystemChatPrompt": "",
      "defaultConfig": {
-        "temperature": 1,
-        "max_tokens": null,
-        "stream": false
+        "temperature": 1
      }
    }
  ],
--- a/docSite/content/zh-cn/docs/development/custom-models/marker.md
+++ b/docSite/content/zh-cn/docs/development/custom-models/marker.md
@@ -0,0 +1,64 @@
+---
+title: '接入 Marker  PDF 文档解析'
+description: '使用 Marker 解析 PDF 文档，可实现图片提取和布局识别'
+icon: 'api'
+draft: false
+toc: true
+weight: 909
+---
+
+## 背景
+
+PDF 是一个相对复杂的文件格式，在 FastGPT 内置的 pdf 解析器中，依赖的是 pdfjs 库解析，该库基于逻辑解析，无法有效的理解复杂的 pdf 文件。所以我们在解析 pdf 时候，如果遇到图片、表格、公式等非简单文本内容，会发现解析效果不佳。
+
+市面上目前有多种解析 PDF 的方法，比如使用 [Marker](https://github.com/VikParuchuri/marker)，该项目使用了 Surya 模型，基于视觉解析，可以有效提取图片、表格、公式等复杂内容。为了可以让 Marker 快速接入 FastGPT，我们做了一个自定义解析的拓展 Demo。
+
+在 FastGPT 4.8.15 版本中，你可以通过增加一个环境变量，来替换掉 FastGPT 系统内置解析器，实现自定义的文档解析服务。该功能只是 Demo 阶段，后期配置模式和交互规则会发生改动。
+
+## 使用教程
+
+### 1. 按照 Marker
+
+参考文档 [Marker 安装教程](https://github.com/labring/FastGPT/tree/main/python/pdf-marker)，安装 Marker 模型。封装的 API 已经适配了 FastGPT 自定义解析服务。
+
+这里介绍快速 Docker 按照的方法：
+
+```
+```
+
+### 2. 添加 FastGPT 环境变量
+
+```
+CUSTOM_READ_FILE_URL=http://xxxx.com/v1/parse/file
+CUSTOM_READ_FILE_EXTENSION=pdf
+```
+
+* CUSTOM_READ_FILE_URL - 自定义解析服务的地址, host改成解析服务的访问地址，path 不能变动。
+* CUSTOM_READ_FILE_EXTENSION - 支持的文件后缀，多个文件类型，可用逗号隔开。
+
+### 3. 测试效果
+
+通过知识库上传一个 pdf 文件，并确认上传，可以在日志中看到 LOG （LOG_LEVEL需要设置 info 或者 debug）：
+
+```
+[Info] 2024-12-05 15:04:42 Parsing files from an external service 
+[Info] 2024-12-05 15:07:08 Custom file parsing is complete, time: 1316ms 
+```
+
+然后你就可以发现，通过 Marker 解析出来的 pdf 会携带图片链接：
+
+![alt text](/imgs/image-10.png)
+
+
+## 效果展示
+
+以清华的 [ChatDev Communicative Agents for Software Develop.pdf](https://arxiv.org/abs/2307.07924) 为例，展示 Marker 解析的效果：
+
+|  |  |  |
+| --- | --- | --- |
+| ![alt text](/imgs/image-11.png) | ![alt text](/imgs/image-12.png) | ![alt text](/imgs/image-13.png)  |
+| ![alt text](/imgs/image-14.png) | ![alt text](/imgs/image-15.png) | ![alt text](/imgs/image-16.png) |
+
+上图是分块后的结果，下图是 pdf 原文。整体图片、公式、表格都可以提取出来，效果还是杠杠的。
+
+不过要注意的是，[Marker](https://github.com/VikParuchuri/marker) 的协议是`GPL-3.0 license`，请在遵守协议的前提下使用。
--- a/docSite/content/zh-cn/docs/development/custom-models/xinference.md
+++ b/docSite/content/zh-cn/docs/development/custom-models/xinference.md
@@ -145,7 +145,7 @@ curl --location --request POST 'https://<oneapi_url>/v1/chat/completions' \
      "usedInExtractFields": true, // 是否用于内容提取（务必保证至少有一个为true）
      "usedInToolCall": true, // 是否用于工具调用（务必保证至少有一个为true）
      "usedInQueryExtension": true, // 是否用于问题优化（务必保证至少有一个为true）
-      "toolChoice": true, // 是否支持工具选择（分类，内容提取，工具调用会用到。目前只有gpt支持）
+      "toolChoice": true, // 是否支持工具选择（分类，内容提取，工具调用会用到。）
      "functionCall": false, // 是否支持函数调用（分类，内容提取，工具调用会用到。会优先使用 toolChoice，如果为false，则使用 functionCall，如果仍为 false，则使用提示词模式）
      "customCQPrompt": "", // 自定义文本分类提示词（不支持工具和函数调用的模型
      "customExtractPrompt": "", // 自定义内容提取提示词
--- a/docSite/content/zh-cn/docs/development/openapi/dataset.md
+++ b/docSite/content/zh-cn/docs/development/openapi/dataset.md
@@ -407,9 +407,7 @@ curl --location --request POST 'http://localhost:3000/api/core/dataset/collectio
 - parentId： 父级ID，不填则默认为根目录
 - name: 集合名称（必填）
 - metadata： 元数据（暂时没啥用）
- trainingType:（必填）
-  - chunk: 按文本长度进行分割
-  - qa: QA拆分
+- trainingType: 训练模式（必填）
 - chunkSize: 每个 chunk 的长度（可选）. chunk模式:100~3000; qa模式: 4000~模型最大token（16k模型通常建议不超过10000）
 - chunkSplitter: 自定义最高优先分割符号（可选）
 - qaPrompt: qa拆分自定义提示词（可选）
@@ -483,9 +481,7 @@ curl --location --request POST 'http://localhost:3000/api/core/dataset/collectio
 - datasetId: 知识库的ID(必填)
 - parentId： 父级ID，不填则默认为根目录
 - metadata.webPageSelector: 网页选择器，用于指定网页中的哪个元素作为文本(可选)
- trainingType:（必填）
-  - chunk: 按文本长度进行分割
-  - qa: QA拆分
+- trainingType:训练模式（必填）
 - chunkSize: 每个 chunk 的长度（可选）. chunk模式:100~3000; qa模式: 4000~模型最大token（16k模型通常建议不超过10000）
 - chunkSplitter: 自定义最高优先分割符号（可选）
 - qaPrompt: qa拆分自定义提示词（可选）
@@ -505,7 +501,13 @@ data 为集合的 ID。
    "statusText": "",
    "message": "",
    "data": {
-        "collectionId": "65abd0ad9d1448617cba6031"
+        "collectionId": "65abd0ad9d1448617cba6031",
+        "results": {
+            "insertLen": 1,
+            "overToken": [],
+            "repeat": [],
+            "error": []
+        }
    }
 }
 ```
@@ -544,9 +546,7 @@ curl --location --request POST 'http://localhost:3000/api/core/dataset/collectio
 - data: 知识库相关信息（json序列化后传入）
  - datasetId: 知识库的ID(必填)
  - parentId： 父级ID，不填则默认为根目录
-  - trainingType:（必填）
-    - chunk: 按文本长度进行分割
-    - qa: QA拆分
+  - trainingType:训练模式（必填）
  - chunkSize: 每个 chunk 的长度（可选）. chunk模式:100~3000; qa模式: 4000~模型最大token（16k模型通常建议不超过10000）
  - chunkSplitter: 自定义最高优先分割符号（可选）
  - qaPrompt: qa拆分自定义提示词（可选）
@@ -581,6 +581,82 @@ data 为集合的 ID。
 {{< /tab >}}
 {{< /tabs >}}

+### 创建一个API集合
+
+传入一个文件的 id，创建一个集合，会读取文件内容进行分割。目前支持：pdf, docx, md, txt, html, csv。
+
+{{< tabs tabTotal="3" >}}
+{{< tab tabName="请求示例" >}}
+{{< markdownify >}}
+
+使用代码上传时，请注意中文 filename 需要进行 encode 处理，否则容易乱码。
+
+```bash
+curl --location --request POST 'http://localhost:3000/api/core/dataset/collection/create/apiCollection' \
+--header 'Authorization: Bearer fastgpt-xxx' \
+--header 'Content-Type: application/json' \
+--data-raw '{
+    "name": "A Quick Guide to Building a Discord Bot.pdf",
+    "apiFileId":"A Quick Guide to Building a Discord Bot.pdf",
+
+    "datasetId": "674e9e479c3503c385495027",
+    "parentId": null,
+
+    "trainingType": "chunk",
+    "chunkSize":512,
+    "chunkSplitter":"",
+    "qaPrompt":""
+}'
+```
+
+{{< /markdownify >}}
+{{< /tab >}}
+
+{{< tab tabName="参数说明" >}}
+{{< markdownify >}}
+
+需要使用 POST form-data 的格式上传。包含 file 和 data 两个字段。
+
+{{% alert icon=" " context="success" %}}
+- name: 集合名，建议就用文件名，必填。
+- apiFileId: 文件的ID，必填。
+- datasetId: 知识库的ID(必填)
+- parentId： 父级ID，不填则默认为根目录
+- trainingType:训练模式（必填）
+- chunkSize: 每个 chunk 的长度（可选）. chunk模式:100~3000; qa模式: 4000~模型最大token（16k模型通常建议不超过10000）
+- chunkSplitter: 自定义最高优先分割符号（可选）
+- qaPrompt: qa拆分自定义提示词（可选）
+{{% /alert %}}
+
+{{< /markdownify >}}
+{{< /tab >}}
+
+{{< tab tabName="响应示例" >}}
+{{< markdownify >}}
+
+data 为集合的 ID。
+
+```json
+{
+    "code": 200,
+    "statusText": "",
+    "message": "",
+    "data": {
+        "collectionId": "65abc044e4704bac793fbd81",
+        "results": {
+            "insertLen": 1,
+            "overToken": [],
+            "repeat": [],
+            "error": []
+        }
+    }
+}
+```
+
+{{< /markdownify >}}
+{{< /tab >}}
+{{< /tabs >}}
+
 ### 创建一个外部文件库集合（商业版）

 {{< tabs tabTotal="3" >}}
@@ -637,7 +713,12 @@ data 为集合的 ID。
  "message": "",
  "data": {
    "collectionId": "6646fcedfabd823cdc6de746",
-    "insertLen": 3
+    "results": {
+        "insertLen": 1,
+        "overToken": [],
+        "repeat": [],
+        "error": []
+    }
  }
 }
 ```
@@ -1017,9 +1098,7 @@ curl --location --request POST 'https://api.fastgpt.in/api/core/dataset/data/pus

 {{% alert icon=" " context="success" %}}
 - collectionId: 集合ID（必填）
- trainingType:（必填）
-  - chunk: 按文本长度进行分割
-  - qa: QA拆分
+- trainingType:训练模式（必填）
 - prompt: 自定义 QA 拆分提示词，需严格按照模板，建议不要传入。（选填）
 - data：（具体数据）
  - q: 主要数据（必填）
--- a/docSite/content/zh-cn/docs/development/upgrading/4811.md
+++ b/docSite/content/zh-cn/docs/development/upgrading/4811.md
@@ -38,11 +38,7 @@ weight: 813
    "customExtractPrompt": "",
    "defaultSystemChatPrompt": "",
    "defaultConfig": {
-        "temperature": 1,
-        "stream": false
-    },
-    "fieldMap": {
-        "max_tokens": "max_completion_tokens"
+        "temperature": 1
    }
 },
 {
@@ -67,11 +63,7 @@ weight: 813
    "customExtractPrompt": "",
    "defaultSystemChatPrompt": "",
    "defaultConfig": {
-        "temperature": 1,
-        "stream": false
-    },
-    "fieldMap": {
-        "max_tokens": "max_completion_tokens"
+        "temperature": 1
    }
 }
 ```
--- a/docSite/content/zh-cn/docs/development/upgrading/4815.md
+++ b/docSite/content/zh-cn/docs/development/upgrading/4815.md
@@ -0,0 +1,27 @@
+---
+title: 'V4.8.15(进行中)'
+description: 'FastGPT V4.8.15 更新说明'
+icon: 'upgrade'
+draft: false
+toc: true
+weight: 809
+---
+
+
+## 完整更新内容
+
+1. 新增 - API 知识库, 见 [API 知识库介绍](/docs/guide/knowledge_base/api_dataset/)，外部文件库会被弃用。
+2. 新增 - 工具箱页面，展示所有可用的系统资源。商业版后台可更便捷的配置系统插件和自定义分类。
+3. 新增 - Markdown 中，HTML代码会被额外渲染，可以选择预览模式，会限制所有 script 脚本，仅做展示。
+4. 新增 - 自定义系统级文件解析服务, 见 [接入 Marker PDF 文档解析](/docs/development/custom-models/marker/)
+5. 新增 - 集合直接重新调整参数，无需删除再导入。
+6. 新增 - 商业版后台支持配置侧边栏跳转链接。
+7. 优化 - base64 图片截取判断。
+8. 优化 - i18n cookie 判断。
+9. 优化 - 支持 Markdown 文本分割时，只有标题，无内容。
+10. 优化 - 字符串变量替换，未赋值的变量会转成 undefined，而不是保留原来 id 串。
+11. 优化 - 全局变量默认值在 API 生效，并且自定义变量支持默认值。
+12. 修复 - 分享链接点赞鉴权问题。
+13. 修复 - 对话页面切换自动执行应用时，会误触发非自动执行应用。
+14. 修复 - 语言播放鉴权问题。
+15. 修复 - 插件应用知识库引用上限始终为 3000
--- a/docSite/content/zh-cn/docs/guide/DialogBoxes/_index.md
+++ b/docSite/content/zh-cn/docs/guide/DialogBoxes/_index.md
@@ -0,0 +1,9 @@
+---
+weight: 470
+title: '对话框'
+description: '对话框组件，支持多种交互方式，提升用户在应用中的交互体验。'
+icon: 'chat_bubble'
+draft: false
+images: []
+---
+<!-- 470 ~ 500 -->
--- a/docSite/content/zh-cn/docs/guide/DialogBoxes/htmlRendering.md
+++ b/docSite/content/zh-cn/docs/guide/DialogBoxes/htmlRendering.md
@@ -0,0 +1,57 @@
+---
+title: "对话框与HTML渲染"
+description: "如何在FastGPT中通过Markdown嵌入HTML代码块，并提供全屏、源代码切换等交互功能"
+icon: "group"
+draft: false
+toc: true
+weight: 470
+---
+
+| 源码模式 | 预览模式 | 全屏模式 |
+| --- | --- | --- |
+| ![](/imgs/htmlRendering1.png) | ![](/imgs/htmlRendering2.png) | ![](/imgs/htmlRendering3.png) |
+
+
+### 1. **设计背景**
+
+  尽管Markdown本身支持嵌入HTML标签，但由于安全问题，许多平台和环境对HTML的渲染进行了限制，特别是在渲染动态内容、交互式元素以及外部资源时。这些限制大大降低了用户在撰写和展示复杂文档时的灵活性，尤其是当需要嵌入外部HTML内容时。为了应对这一问题，我们通过使用 `iframe` 来嵌入和渲染HTML内容，并结合 `sandbox` 属性，保障了外部HTML的安全渲染。
+
+### 2. 功能简介
+
+  该功能模块的主要目的是扩展FastGPT在Markdown渲染中的能力，支持嵌入和渲染HTML内容。由于是利用 Iframe 渲染，所以无法确认内容的高度，FastGPT 中会给 Iframe 设置一个固定高度来进行渲染。并且不支持 HTML 中执行 js 脚本。
+
+### 3. 技术实现
+
+  本模块通过以下方式实现了HTML渲染和互动功能：
+
+  - **组件设计**：该模块通过渲染 `iframe` 类型的代码块展示HTML内容。使用自定义的 `IframeBlock` 组件，结合 `sandbox` 属性来保障嵌入内容的安全性。`sandbox` 限制了外部HTML中的行为，如禁用脚本执行、限制表单提交等，确保HTML内容的安全性。通过辅助函数与渲染Markdown内容的部分结合，处理 `iframe` 嵌入的HTML内容。
+  - **安全机制**：通过 `iframe` 的 `sandbox` 属性和 `referrerPolicy` 来防止潜在的安全风险。`sandbox` 属性提供了细粒度的控制，允许特定的功能（如脚本、表单、弹出窗口等）在受限的环境中执行，以确保渲染的HTML内容不会对系统造成威胁。
+  - **展示与互动功能**：用户可以通过不同的展示模式（如全屏、预览、源代码模式）自由切换，以便更灵活地查看和控制嵌入的HTML内容。嵌入的 `iframe` 自适应父容器的宽度，同时保证 `iframe`嵌入的内容能够适当显示。
+
+### 4. 如何使用
+
+你只需要通过 Markdown 代码块格式，并标记语言为 `html` 即可。例如：
+
+```md
+```html
+<!DOCTYPE html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta http-equiv="X-UA-Compatible" content="ie=edge">
+    <title>欢迎使用FastGPT</title>
+  </head>
+  <body>
+    <nav>
+      <ul>
+        <li><a href="#home">首页</a></li>
+        <li><a href="#about">关于我们</a></li>
+        <li><a href="#contact">联系我们</a></li>
+        <li><a href="#gallery">图库</a></li>
+      </ul>
+    </nav>
+  </body>
+</html>
+
+```
--- a/docSite/content/zh-cn/docs/guide/knowledge_base/api_dataset.md
+++ b/docSite/content/zh-cn/docs/guide/knowledge_base/api_dataset.md
@@ -0,0 +1,183 @@
+---
+title: 'API 文件库'
+description: 'FastGPT API 文件库功能介绍和使用方式'
+icon: 'language'
+draft: false
+toc: true
+weight: 405
+---
+
+| | |
+| --- | --- |
+| ![](/imgs/image-18.png) | ![](/imgs/image-19.png) |
+
+## 背景
+
+目前 FastGPT 支持本地文件导入，但是很多时候，用户自身已经有了一套文档库，如果把文件重复导入一遍，会造成二次存储，并且不方便管理。因为 FastGPT 提供了一个 API 文件库的概念，可以通过简单的 API 接口，去拉取已有的文档库，并且可以灵活配置是否导入。
+
+API 文件库能够让用户轻松对接已有的文档库，只需要按照 FastGPT 的 API 文件库规范，提供相应文件接口，然后将服务接口的 baseURL 和 token 填入知识库创建参数中，就能直接在页面上拿到文件库的内容，并选择性导入
+
+## 如何使用 API 文件库
+
+创建知识库时，选择 API 文件库类型，然后需要配置两个关键参数:文件服务接口的 baseURL 和用于身份验证的请求头信息。只要提供的接口规范符合 FastGPT 的要求，系统就能自动获取并展示完整的文件列表，可以根据需要选择性地将文件导入到知识库中。
+
+你需要提供两个参数：
+- baseURL: 文件服务接口的 baseURL
+- authorization: 用于身份验证的请求头信息，实际请求格式为 `Authorization: Bearer <token>`
+
+## 接口规范
+
+接口响应格式：
+
+```ts
+type ResponseType = {
+  success: boolean;
+  message: string;
+  data: any;
+}
+```
+
+数据类型：
+
+```ts
+// 文件列表中，单项的文件类型
+type FileListItem = {
+  id: string;
+  parentId: string | null;
+  name: string;
+  type: 'file' | 'folder';
+  updateTime: Date;
+  createTime: Date;
+}
+```
+
+
+### 1. 获取文件树
+
+{{< tabs tabTotal="2" >}}
+{{< tab tabName="请求示例" >}}
+{{< markdownify >}}
+
+{{% alert icon=" " context="success" %}}
+- parentId - 父级 id，可选，或者 null。
+- searchKey - 检索词，可选
+{{% /alert %}}
+
+```bash
+curl --location --request POST '{{baseURL}}/v1/file/list' \
+--header 'Authorization: Bearer {{authorization}}' \
+--header 'Content-Type: application/json' \
+--data-raw '{
+    "parentId": null,
+    "searchKey": ""
+}'
+```
+
+{{< /markdownify >}}
+{{< /tab >}}
+
+{{< tab tabName="响应示例" >}}
+{{< markdownify >}}
+
+```json
+{
+    "code": 200,
+    "success": true,
+    "message": "",
+    "data": [
+        {
+            "id": "xxxx",
+            "parentId": "xxxx",
+            "type": "file",  // file | folder
+            "name":"test.json",
+            "updateTime":"2024-11-26T03:05:24.759Z",
+            "createTime":"2024-11-26T03:05:24.759Z"
+        }
+   ]
+}
+```
+
+{{< /markdownify >}}
+{{< /tab >}}
+{{< /tabs >}}
+
+### 2. 获取单个文件内容（文本内容或访问链接）
+
+{{< tabs tabTotal="3" >}}
+{{< tab tabName="请求示例" >}}
+{{< markdownify >}}
+
+```bash
+curl --location --request GET '{{baseURL}}/v1/file/content?id=xx' \
+--header 'Authorization: Bearer {{authorization}}'
+```
+
+{{< /markdownify >}}
+{{< /tab >}}
+
+{{< tab tabName="响应示例" >}}
+{{< markdownify >}}
+
+```json
+{
+    "code": 200,
+    "success": true,
+    "message": "",
+    "data": {
+        "content": "FastGPT 是一个基于 LLM 大语言模型的知识库问答系统，提供开箱即用的数据处理、模型调用等能力。同时可以通过 Flow 可视化进行工作流编排，从而实现复杂的问答场景！\n",
+        "previewUrl": "xxxx"
+    }
+}
+```
+
+{{% alert icon=" " context="success" %}}
+二选一返回，如果同时返回则 content 优先级更高。
+
+- content - 文件内容，直接拿来用。
+- previewUrl - 文件链接，系统会请求该地址获取文件内容。
+{{% /alert %}}
+
+{{< /markdownify >}}
+{{< /tab >}}
+{{< /tabs >}}
+
+
+### 3. 获取文件阅读链接（用于查看原文）
+
+{{< tabs tabTotal="2" >}}
+{{< tab tabName="请求示例" >}}
+{{< markdownify >}}
+
+id 为文件的 id。
+
+```bash
+curl --location --request GET '{{baseURL}}/v1/file/read?id=xx' \
+--header 'Authorization: Bearer {{authorization}}'
+```
+
+{{< /markdownify >}}
+{{< /tab >}}
+
+{{< tab tabName="响应示例" >}}
+{{< markdownify >}}
+
+```json
+{
+    "code": 200,
+    "success": true,
+    "message": "",
+    "data": {
+        "url": "xxxx"
+    }
+}
+```
+
+{{% alert icon=" " context="success" %}}
+- url - 文件访问链接，拿到后会自动打开。
+{{% /alert %}}
+
+{{< /markdownify >}}
+{{< /tab >}}
+{{< /tabs >}}
+
+
--- a/docSite/content/zh-cn/docs/guide/knowledge_base/externalFile.md
+++ b/docSite/content/zh-cn/docs/guide/knowledge_base/externalFile.md
@@ -23,4 +23,17 @@ weight: 408
 - 文件阅读ID：通常情况下，文件访问URL是临时的。如果希望永久可以访问，你需要使用该文件阅读ID，并配合上“外部预览地址”，跳转至新的阅读地址进行原文件访问。
 - 文件名：默认会自动解析文件访问URL上的文件名。如果你手动填写，将会以手动填写的值为准。

-[点击查看API导入文档](/docs/development/openapi/dataset/#创建一个外部文件库集合商业版)
+[点击查看API导入文档](/docs/development/openapi/dataset/#创建一个外部文件库集合商业版)
+
+## API 文件库替代方案
+
+4.8.15 提供了新的知识库类型 - API 文件库，对外部文件知识库做了进一步的拓展
+
+通过对接口进行简单的调整，就能使用 API 文件库代替外部文件知识库的功能
+
+你可以直接将外部文件知识库中的外部预览地址，作为 API 文件库接口规范中获取文件阅读链接的接口返回
+
+然后再以相同的 baseURL 实现获取文件列表和获取单个文件内容这两个接口
+
+这样就能轻松地使用 API 文件库替代原有的外部文件知识库，更多详细的内容见 API 文件库的文档
+