# 文件输入功能介绍

> 在 FastGPT 对话 Agent 与工作流中启用文件上传功能，支持文档解析、图片识别与多模态问答处理。

Source: https://doc.fastgpt.cn/guide/build/general/fileInput
Last Updated: 2026-11-12

从 4.8.9 版本起，FastGPT 支持在 **对话 Agent（简易版）** 和 **工作流** 中配置用户上传文件功能。下面先介绍如何使用文件输入功能，再说明文档解析和多模态文件处理的区别。

## 对话 Agent（简易版）中使用

对话 Agent（简易版）开启文件上传后，当前文档解析路径会读取普通文档并将文本用于对话。4.8.9–4.8.12 的早期路径由模型通过工具调用决定读取；4.8.13 起采用下面说明的强制解析行为。

可以找到左侧文件上传的配置项，点击其右侧的 `开启` / `关闭` 按键，即可打开配置弹窗。

![打开文件上传](/imgs/optimized/current/file-upload-settings.png.webp)

随后，你的调试对话框中，就会出现一个文件选择的 icon，可以点击文件选择 icon，选择你需要上传的文件。

![打开文件上传](/imgs/optimized/current/file-input-attachment.png.webp)

**工作模式**

从 4.8.13 版本起，对话 Agent（简易版）的文件读取会强制解析文件并合并进对应的用户消息中，确保多轮连续对话稳定引用上传文档内容。

## 工作流中使用

工作流中，可以在系统配置中，找到 `文件上传` 配置项，点击其右侧的 `开启` / `关闭` 按键，即可打开配置弹窗。

![打开文件上传](/imgs/optimized/current/file-upload-settings.png.webp)

将 **流程开始 → 文件链接** 连接到 **文档解析 → 文档链接**，再将解析结果传给 AI 对话、内容提取或 HTTP 请求等节点。上传 TXT 文件运行后，检查解析输出是否包含文件正文。

![文档解析节点与运行结果](/imgs/optimized/current/document-parse-result.png.webp)

![文档解析输入与输出](/imgs/optimized/current/document-parse-node.png.webp)

## 文档解析工作原理

FastGPT 的普通文档解析路径将文件转换为文本后交给模型，多模态文件则按模型能力和文件输入配置处理。以下从存储结构、媒体分流、节点拼接和提示词注入四个环节说明文档解析机制：

### 上传的文件如何存储在数据库中

FastGPT 的对话记录存储结构中，role=user 的消息，value 值会按以下结构存储：

```ts
type UserChatItemValueItemType = {
  text?: {
    content: string;
  };
  file?: {
    type: 'image' | 'audio' | 'video' | 'document' | 'unknown'; // 'file' 仅兼容历史数据
    name?: string;
    key?: string;
    url: string;
  };
};
```

也就是说，上传的文件都会以 URL 的形式存储在库中，并不会存储 `解析后的文档内容`。

### 图片、音频、视频如何处理

文档解析节点不会解析图片、音频、视频等多模态文件。这类文件需要交给支持对应多模态能力的 LLM 处理，并在 [AI 配置说明](https://doc.fastgpt.cn/guide/build/general/ai_settings) 中开启多模态识别。

因此，文件输入中要区分两类处理方式：

1. 文档解析：处理 PDF、Word、Excel、Markdown、HTML 等文档文件，将内容转成文本后提供给 AI。
2. 多模态识别：处理图片、音频、视频等媒体文件，FastGPT 会将其转换为模型可接收的输入，再由支持对应能力的模型读取。

### 文档解析节点如何工作

文档解析依赖文档解析节点，这个节点会接收一个 `array<string>` 类型的输入，对应的是文件输入的 URL；输出的是一个 `string`，对应的是文档解析后的内容。

* 在文档解析节点中，只会解析 `文档` 类型的 URL，它是通过文件 URL 解析出来的 `文件后缀` 去判断的。如果你同时选择了文档和多模态文件，多模态文件会被忽略。
* **文档解析节点，只会解析本轮工作流接收的文件，不会解析历史记录的文件。**
* 多个文档内容如何拼接的

按下列的模板，对多个文件进行拼接，即文件名+文件内容的形式组成一个字符串，不同文档之间用 `\n\n` 连接。

```
## ${filename}
${content}
```

### AI 对话节点中如何传入文件链接

在工作流的 **AI 对话** 节点中，提供了 **文件链接**（早期版本称“文档引用”）输入端口，可直接选择 **流程开始** 节点输出的 **文件链接**（或上游节点输出的文档 URL 数组），实现文档内容的自动解析与引用。

它接收一个 `Array<string>` 类型的输入，最终这些 URL 会被解析，并进行提示词拼接，合并进对应的用户消息中。每个文件按 `<file>` 结构列出（其中还可能包含可选的 `<sandboxPath>` 字段，且 `<content>` 仅在文档已完成文本解析时出现），提示词模板如下：

```
## 对话文件
用户本次对话上传的文件，用途：
1. 可通过 read_files 读取文档内容。
2. 可把 url 作为模型参数。

<file>
<name>${文件名}</name>
<url>${文件 URL}</url>
<content>${文件正文}</content>
</file>
```

## 4.8.13 版本起，关于文件上传的更新

由于与 4.8.9 版本有些差异，尽管我们做了向下兼容，避免工作流立即不可用。但是请尽快的按新版本规则进行调整工作流，后续将会去除兼容性代码。

1. 对话 Agent（简易版）中，强制执行文件解析并注入上下文，保证每次都能参考文档。
2. 文档解析：不再解析历史记录中的文件。
3. AI 对话节点：支持在 **文件链接**（原“文档引用”）输入端口直接选择开始节点输出的 **文件链接**，并自动解析历史记录中的文件。
4. 插件单独运行：插件输入支持配置文件类型，用于接收上传文件。
5. **工作流调用插件：需要手动为插件输入绑定对应的文件链接变量。**
6. **工作流调用工作流：支持手动选择需要传递给子工作流的文件链接。**
