docs: update docs and fix portal tool calls (#7194)

4d90b720 · YeYuheng · GitHub · 7e333e85 · 4d90b720 · 4d90b720
Commit 4d90b720 authored Jun 27, 2026 by YeYuheng Committed by GitHub Jun 27, 2026
19 changed files
--- a/document/content/guide/build/general/ai_settings.en.mdx
+++ b/document/content/guide/build/general/ai_settings.en.mdx
--- a/document/content/guide/build/general/ai_settings.mdx
+++ b/document/content/guide/build/general/ai_settings.mdx
--- a/document/content/guide/build/general/fileInput.en.mdx
+++ b/document/content/guide/build/general/fileInput.en.mdx
@@ -3,8 +3,7 @@ title: File Input
 description: FastGPT file input feature overview
 ---
-Starting from version 4.8.9, FastGPT supports configuring file and image uploads in both `Basic Mode` and `Workflows`. This guide covers how to use the file input feature and explains how document parsing works under the hood.
+Starting from version 4.8.9, FastGPT supports configuring file uploads in both `Basic Mode` and `Workflows`. This guide covers how to use file input and explains the difference between document parsing and multimodal file handling.
 ## Using in Basic Mode
@@ -30,8 +29,8 @@ In Workflows, find the `File Input` option in the system configuration panel and
 There are many ways to use files in Workflows. The simplest approach, shown below, connects document parsing via tool calling — achieving the same result as Basic Mode.
-| | |
+|                        |                        |
-| --------------------- | --------------------- |
+| ---------------------- | ---------------------- |
 | ![](/imgs/image-5.png) | ![](/imgs/image-6.png) |
 You can also use Workflows to extract or analyze document content, then pass the results to HTTP requests or other modules to build a document processing pipeline.
@@ -40,7 +39,7 @@ You can also use Workflows to extract or analyze document content, then pass the
 ## How Document Parsing Works
-Unlike image recognition, LLMs currently cannot parse documents directly. All document "understanding" is achieved by converting documents to text and injecting it into the prompt. The following FAQs explain how this works — understanding the mechanics helps you use document parsing more effectively in Workflows.
+Unlike multimodal recognition, LLMs currently cannot parse regular documents directly. All document "understanding" is achieved by converting documents to text and injecting it into the prompt. The following FAQs explain how this works — understanding the mechanics helps you use document parsing more effectively in Workflows.
 ### How are uploaded files stored in the database?
@@ -48,31 +47,37 @@ In FastGPT's chat history, messages with role=user store their value in this str
 ```ts
 type UserChatItemValueItemType = {
-  type: 'text' | 'file'
+  type: 'text' | 'file';
  text?: {
    content: string;
  };
  file?: {
-    type: 'img' | 'doc'
+    type: 'image' | 'audio' | 'video' | 'file';
    name?: string;
+    key?: string;
    url: string;
  };
 };
 ```
-Uploaded images and documents are stored as URLs — the parsed document content is not stored.
+Uploaded files are stored as URLs — parsed document content is not stored.
+### How are images, audio, and video handled?
+The document parsing node does not parse multimodal files such as images, audio, or video. These files should be handled by an LLM that supports the corresponding multimodal capability, with multimodal recognition enabled in [AI Settings](./ai_settings).
-### How are images handled?
+In practice, file input has two different handling paths:
-The document parsing node does not process images. Image URLs are filtered out. For image recognition, use an LLM that supports vision.
+1. Document parsing: handles document files such as PDF, Word, Excel, Markdown, and HTML, converts their content to text, and provides that text to the AI.
+2. Multimodal recognition: handles media files such as images, audio, and video. FastGPT converts them into model-readable input, and a model with the corresponding capability reads them.
 ### How does the document parsing node work?
 The document parsing node accepts an `array<string>` input (file URLs) and outputs a `string` (the parsed content).
-* The node only parses URLs with document-type file extensions. If you upload both documents and images, images are ignored.
+- The node only parses URLs with document-type file extensions. If you upload both documents and multimodal files, multimodal files are ignored.
-* **The document parsing node only processes files from the current workflow run, not files from chat history.**
+- **The document parsing node only processes files from the current workflow run, not files from chat history.**
-* How multiple documents are concatenated:
+- How multiple documents are concatenated:
 Multiple files are concatenated using the following template — filename + content, separated by `\n******\n`:

--- a/document/content/guide/build/general/fileInput.mdx
+++ b/document/content/guide/build/general/fileInput.mdx
@@ -3,14 +3,13 @@ title: 鏂囦欢杈撳叆鍔熻兘浠嬬粛
 description: FastGPT 文件输入功能介绍
 ---
-从 4.8.9 版本起，FastGPT 支持在`简易模式`和`工作流`中，配置用户上传文件、图片功能。下面先简单介绍下如何使用文件输入功能，最后是介绍下文件解析的工作原理。
+从 4.8.9 版本起，FastGPT 支持在 `简易模式` 和 `工作流` 中，配置用户上传文件功能。下面先简单介绍下如何使用文件输入功能，最后介绍文档解析和多模态文件处理的区别。
 ## 简易模式中使用
 简易模式打开文件上传后，会使用工具调用模式，也就是由模型自行决策，是否需要读取文件内容。
-可以找到左侧文件上传的配置项，点击其右侧的`开启`/`关闭`按键，即可打开配置弹窗。
+可以找到左侧文件上传的配置项，点击其右侧的 `开启` / `关闭` 按键，即可打开配置弹窗。
 ![打开文件上传](/imgs/fileinpu-1.png)
@@ -24,14 +23,14 @@ description: FastGPT 鏂囦欢杈撳叆鍔熻兘浠嬬粛
 ## 工作流中使用
-工作流中，可以在系统配置中，找到`文件输入`配置项，点击其右侧的`开启`/`关闭`按键，即可打开配置弹窗。
+工作流中，可以在系统配置中，找到 `文件输入` 配置项，点击其右侧的 `开启` / `关闭` 按键，即可打开配置弹窗。
 ![打开文件上传](/imgs/fileinpu-4.jpg)
 在工作流中，使用文件的方式很多，最简单的就是类似下图中，直接通过工具调用接入文档解析，实现和简易模式一样的效果。
-| | |
+|                        |                        |
-| --------------------- | --------------------- |
+| ---------------------- | ---------------------- |
 | ![](/imgs/image-5.png) | ![](/imgs/image-6.png) |
 当然，你也可以在工作流中，对文档进行内容提取、内容分析等，然后将分析的结果传递给 HTTP 或者其他模块，从而实现文件处理的 SOP。
@@ -40,7 +39,7 @@ description: FastGPT 鏂囦欢杈撳叆鍔熻兘浠嬬粛
 ## 文档解析工作原理
-不同于图片识别，LLM 模型目前没有支持直接解析文档的能力，所有的文档“理解”都是通过文档转文字后拼接 prompt 实现。这里通过几个 FAQ 来解释文档解析的工作原理，理解文档解析的原理，可以更好的在工作流中使用文档解析功能。
+不同于多模态识别，LLM 模型目前没有支持直接解析普通文档的能力，所有的文档“理解”都是通过文档转文字后拼接 prompt 实现。这里通过几个 FAQ 来解释文档解析的工作原理，理解文档解析的原理，可以更好的在工作流中使用文档解析功能。
 ### 上传的文件如何存储在数据库中
@@ -48,31 +47,37 @@ FastGPT 鐨勫璇濊褰曞瓨鍌ㄧ粨鏋勪腑锛宺ole=user 鐨勬秷鎭紝value 鍊间細鎸変
 ```ts
 type UserChatItemValueItemType = {
-  type: 'text' | 'file'
+  type: 'text' | 'file';
  text?: {
    content: string;
  };
  file?: {
-    type: 'img' | 'doc'
+    type: 'image' | 'audio' | 'video' | 'file';
    name?: string;
+    key?: string;
    url: string;
  };
 };
 ```
-也就是说，上传的图片和文档，都会以 URL 的形式存储在库中，并不会存储`解析后的文档内容`。
+也就是说，上传的文件都会以 URL 的形式存储在库中，并不会存储 `解析后的文档内容`。
+### 图片、音频、视频如何处理
+文档解析节点不会解析图片、音频、视频等多模态文件。这类文件需要交给支持对应多模态能力的 LLM 处理，并在 [AI 配置说明](./ai_settings) 中开启多模态识别。
-### 图片如何处理
+因此，文件输入中要区分两类处理方式：
-文档解析节点不会处理图片，图片链接会被过滤，图片识别请直接使用支持图片识别的 LLM 模型。
+1. 文档解析：处理 PDF、Word、Excel、Markdown、HTML 等文档文件，将内容转成文本后提供给 AI。
+2. 多模态识别：处理图片、音频、视频等媒体文件，FastGPT 会将其转换为模型可接收的输入，再由支持对应能力的模型读取。
 ### 文档解析节点如何工作
-文档解析依赖文档解析节点，这个节点会接收一个`array<string>`类型的输入，对应的是文件输入的 URL；输出的是一个`string`，对应的是文档解析后的内容。
+文档解析依赖文档解析节点，这个节点会接收一个 `array<string>` 类型的输入，对应的是文件输入的 URL；输出的是一个 `string`，对应的是文档解析后的内容。
-* 在文档解析节点中，只会解析`文档`类型的 URL，它是通过文件 URL 解析出来的`文名件后缀`去判断的。如果你同时选择了文档和图片，图片会被忽略。
+- 在文档解析节点中，只会解析 `文档` 类型的 URL，它是通过文件 URL 解析出来的 `文件后缀` 去判断的。如果你同时选择了文档和多模态文件，多模态文件会被忽略。
-* **文档解析节点，只会解析本轮工作流接收的文件，不会解析历史记录的文件。**
+- **文档解析节点，只会解析本轮工作流接收的文件，不会解析历史记录的文件。**
-* 多个文档内容如何拼接的
+- 多个文档内容如何拼接的
 按下列的模板，对多个文件进行拼接，即文件名+文件内容的形式组成一个字符串，不同文档之间通过分隔符：`\n******\n` 进行分割。
@@ -83,11 +88,11 @@ ${content}
 </Content>
 ```
-### AI节点中如何使用文档解析
+### AI 节点中如何使用文档解析
-在 AI 节点（AI对话/工具调用）中，新增了一个文档链接的输入，可以直接引用文档的地址，从而实现文档内容的引用。
+在 AI 节点（AI 对话/工具调用）中，新增了一个文档链接的输入，可以直接引用文档的地址，从而实现文档内容的引用。
-它接收一个`Array<string>`类型的输入，最终这些 url 会被解析，并进行提示词拼接，放置在 role=system 的消息中。提示词模板如下：
+它接收一个 `Array<string>` 类型的输入，最终这些 URL 会被解析，并进行提示词拼接，放置在 role=system 的消息中。提示词模板如下：
 ```
 将 <FilesContent></FilesContent> 中的内容作为本次对话的参考:
@@ -96,7 +101,7 @@ ${content}
 </FilesContent>
 ```
-# 4.8.13版本起，关于文件上传的更新
+# 4.8.13 版本起，关于文件上传的更新
 由于与 4.8.9 版本有些差异，尽管我们做了向下兼容，避免工作流立即不可用。但是请尽快的按新版本规则进行调整工作流，后续将会去除兼容性代码。

--- a/document/content/guide/dataset/dataset_engine.en.mdx
+++ b/document/content/guide/dataset/dataset_engine.en.mdx
--- a/document/content/guide/dataset/dataset_engine.mdx
+++ b/document/content/guide/dataset/dataset_engine.mdx
--- a/document/data/doc-last-modified.json
+++ b/document/data/doc-last-modified.json
@@ -291,8 +291,8 @@
  "content/self-host/upgrading/4-14/41481.mdx": "2026-04-26T21:08:47+08:00",
  "content/self-host/upgrading/4-14/4149.en.mdx": "2026-04-26T21:08:47+08:00",
  "content/self-host/upgrading/4-14/4149.mdx": "2026-04-26T21:08:47+08:00",
-  "content/self-host/upgrading/4-15/41500.en.mdx": "2026-06-25T14:51:00+08:00",
+  "content/self-host/upgrading/4-15/41500.en.mdx": "2026-06-27T11:15:35+08:00",
-  "content/self-host/upgrading/4-15/41500.mdx": "2026-06-25T14:51:00+08:00",
+  "content/self-host/upgrading/4-15/41500.mdx": "2026-06-27T11:15:35+08:00",
  "content/self-host/upgrading/4-15/41501.mdx": "2026-06-23T21:09:39+08:00",
  "content/self-host/upgrading/4-15/41502.en.mdx": "2026-05-25T11:21:30+08:00",
  "content/self-host/upgrading/4-15/41502.mdx": "2026-06-23T13:54:06+08:00",
@@ -302,8 +302,8 @@
  "content/self-host/upgrading/4-15/41504.mdx": "2026-06-15T23:34:43+08:00",
  "content/self-host/upgrading/4-15/41505.en.mdx": "2026-06-23T13:54:06+08:00",
  "content/self-host/upgrading/4-15/41505.mdx": "2026-06-24T13:53:05+08:00",
-  "content/self-host/upgrading/4-15/41506.en.mdx": "2026-06-26T17:03:31+08:00",
+  "content/self-host/upgrading/4-15/41506.en.mdx": "2026-06-27T11:15:35+08:00",
-  "content/self-host/upgrading/4-15/41506.mdx": "2026-06-26T17:03:31+08:00",
+  "content/self-host/upgrading/4-15/41506.mdx": "2026-06-27T11:15:35+08:00",
  "content/self-host/upgrading/outdated/40.en.mdx": "2026-04-26T21:08:47+08:00",
  "content/self-host/upgrading/outdated/40.mdx": "2026-04-26T21:08:47+08:00",
  "content/self-host/upgrading/outdated/41.en.mdx": "2026-04-26T21:08:47+08:00",

--- a/document/public/imgs/datasetSetting1.png
+++ b/document/public/imgs/datasetSetting1.png
--- a/document/public/imgs/dataset_search_params1.png
+++ b/document/public/imgs/dataset_search_params1.png
--- a/document/public/imgs/dataset_search_params2.png
+++ b/document/public/imgs/dataset_search_params2.png
--- a/document/public/imgs/dataset_search_params3.png
+++ b/document/public/imgs/dataset_search_params3.png
--- a/document/public/imgs/dataset_search_process.png
+++ b/document/public/imgs/dataset_search_process.png
--- a/document/public/imgs/dataset_tree.png
+++ b/document/public/imgs/dataset_tree.png
--- a/document/public/imgs/image-45.png
+++ b/document/public/imgs/image-45.png
--- a/document/public/imgs/image-53.png
+++ b/document/public/imgs/image-53.png
--- a/pro @ 7eac10c3
+++ b/pro @ 7eac10c3
-Subproject commit 23a105e56fcb7a4e7e0c161e23488290ef297a21
+Subproject commit 7eac10c397a78a1aae5bfc860dd5c3d86c33626d
--- a/projects/app/src/pages/api/v1/chat/completions.ts
+++ b/projects/app/src/pages/api/v1/chat/completions.ts
@@ -243,7 +243,7 @@ async function handler(req: NextApiRequest, res: NextApiResponse) {
        chatId,
        offset: 0,
        limit,
-        field: `obj value nodeOutputs`
+        field: `obj value memories nodeOutputs`
      }),
      getAppLatestVersion(app._id, app),
      MongoChat.findOne(

--- a/projects/app/src/pages/api/v2/chat/completions.ts
+++ b/projects/app/src/pages/api/v2/chat/completions.ts
@@ -245,7 +245,7 @@ async function handler(req: NextApiRequest, res: NextApiResponse) {
        chatId,
        offset: 0,
        limit,
-        field: `obj value nodeOutputs`
+        field: `obj value memories nodeOutputs`
      }),
      getAppLatestVersion(app._id, app),
      MongoChat.findOne(

--- a/projects/app/test/api/chat/completionsHistoryFields.test.ts
+++ b/projects/app/test/api/chat/completionsHistoryFields.test.ts
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+const readSource = (path: string) => readFileSync(resolve(process.cwd(), path), 'utf8');
+describe('chat completions history fields', () => {
+  it.each(['src/pages/api/v1/chat/completions.ts', 'src/pages/api/v2/chat/completions.ts'])(
+    '%s keeps agent loop memories when loading histories',
+    (path) => {
+      const source = readSource(path);
+      expect(source).toContain('field: `obj value memories nodeOutputs`');
+    }
+  );
+});