agentic_huge_data_base / wiki
页面 Open WebUI · 4.4 文件上传与处理·DeepWiki 中文全文译文
DeepWiki 中文译文 / Open WebUI / 4.4

4.4 · 文件上传与处理（File Upload and Processing）

多模型对话工作台与知识应用入口 · 本章是 Open WebUI DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目Open WebUI 章节4.4 状态全文译文 模块接口与服务契约、界面与交互、检索、召回与知识系统、系统架构
项目要点页2.5 参考项目 项目章节目录Open WebUI DeepWiki 原始章节File Upload and Processing 上一章4.3 下一章4.5
源码线索
  • backend/open_webui/routers/files.py
  • backend/open_webui/routers/knowledge.py
  • src/lib/apis/files/index.ts
  • src/lib/components/chat/Chat.svelte
  • src/lib/components/chat/MessageInput.svelte
  • src/lib/components/chat/Messages.svelte
  • src/lib/components/chat/Messages/Message.svelte
  • src/lib/components/chat/Messages/MultiResponseMessages.svelte
  • src/lib/components/chat/Messages/ResponseMessage.svelte
  • src/lib/components/chat/Messages/UserMessage.svelte
模块标签
  • 接口与服务契约
  • 界面与交互
  • 检索、召回与知识系统
  • 系统架构
  • 工具、记忆与模型调用

中文译文

文件上传与处理（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/open-webui/open-webui/4.4-file-upload-and-processing
翻译时间：2026-06-09T16:08:07.413Z
翻译模型：deepseek-chat
原文字符数：10830
项目：Open WebUI (open-webui)

---

文件上传与处理

相关源文件

以下文件被用作生成此 wiki 页面的上下文：

  • backend/open_webui/routers/files.py
  • backend/open_webui/routers/knowledge.py
  • src/lib/apis/files/index.ts
  • src/lib/components/chat/Chat.svelte
  • src/lib/components/chat/MessageInput.svelte
  • src/lib/components/chat/Messages.svelte
  • src/lib/components/chat/Messages/Message.svelte
  • src/lib/components/chat/Messages/MultiResponseMessages.svelte
  • src/lib/components/chat/Messages/ResponseMessage.svelte
  • src/lib/components/chat/Messages/UserMessage.svelte
  • src/lib/utils/google-drive-picker.ts
  • src/lib/utils/index.ts

目的与范围

本文档描述了 Open WebUI 中完整的文件上传与处理系统。该系统支持广泛的功能，包括拖放界面、图像压缩、HEIC 转 JPEG 以及多引擎内容提取。文档详细介绍了 SvelteKit 中的前端编排、FastAPI 后端路由以及底层的存储提供程序抽象层。

该系统设计用于处理多种输入，从标准文档和图像到 Google Drive 和 OneDrive 等专用集成。

---

系统架构与数据流

文件系统将前端用户界面与后端存储及处理引擎连接起来。它遵循响应式流程：文件在客户端本地处理后，再传输到服务器进行持久化和内容提取。

前端到后端的实体映射

下图将功能概念映射到仓库中的具体代码实体，追踪从用户选择文件到存储的完整路径。

graph TD
    subgraph "前端（SvelteKit 空间）"
        UI["拖放 / 文件选择器"] --> MI["MessageInput.svelte"]
        MI --> UTILS["src/lib/utils/index.ts"]
        UTILS --> COMP["compressImage()"]
        UTILS --> HEIC["convertHeicToJpeg()"]
        MI --> API_CLIENT["src/lib/apis/files/index.ts"]
        API_CLIENT --> UPLOAD_FN["uploadFile()"]
        MI --> GOOGLE["src/lib/utils/google-drive-picker.ts"]
        MI --> ONEDRIVE["src/lib/utils/onedrive-file-picker.ts"]
    end

    subgraph "后端（FastAPI 空间）"
        UPLOAD_FN -- "POST /api/v1/files/" --> ROUTER["backend/open_webui/routers/files.py"]
        ROUTER --> HANDLER["upload_file_handler()"]
        HANDLER --> DB["Files.insert_new_file()"]
        HANDLER --> STORAGE["backend/open_webui/storage/provider.py"]
        HANDLER --> PROC["process_uploaded_file()"]
    end

    subgraph "存储与检索"
        PROC --> RETRIEVAL["backend/open_webui/routers/retrieval.py: process_file()"]
        STORAGE --> LOCAL["LocalStorageProvider"]
        STORAGE --> S3["S3StorageProvider"]
    end

来源： src/lib/components/chat/MessageInput.svelte:40-55，backend/open_webui/routers/files.py:178-197，backend/open_webui/routers/files.py:200-209，src/lib/apis/files/index.ts:4-10，src/lib/utils/google-drive-picker.ts:107-110

---

前端处理管道

前端负责文件的初始生命周期，包括 UI 反馈、验证以及预处理，以优化带宽和兼容性。

客户端预处理

当用户通过 MessageInput.svelte 附加文件时，会执行以下序列：

  1. HEIC 转换：如果检测到 .heic 或 .heif 图像，则使用 convertHeicToJpeg 将其转换为 JPEG src/lib/utils:41。
  2. 图像压缩：根据应用设置，使用 compressImage 压缩图像以确保快速上传 src/lib/utils:42。
  3. 内容提取（可选）：对于某些基于文本的文件，前端可能会调用 extractContentFromFile 来预览或直接将文本注入提示词 src/lib/utils:44。
  4. 变量替换：系统支持直接从剪贴板粘贴图像，或通过 {{CLIPBOARD}} 变量处理器引用图像 src/lib/components/chat/MessageInput.svelte:206-223。在渲染过程中，它还会处理 {{VIDEO_FILE_ID_...}} 和 {{HTML_FILE_ID_...}} 等特殊令牌 src/lib/utils/index.ts:55-69。
外部集成

Open WebUI 支持直接从云服务提供商选取文件：

  • Google Drive：使用 createPicker 和 getAuthToken 与 Google Picker API 交互，将文件下载为 Blob 后再上传到 WebUI 后端 src/lib/utils/google-drive-picker.ts:74-107。
  • OneDrive：使用 pickAndDownloadFile 实现微软集成 src/lib/components/chat/MessageInput.svelte:17。
上传编排

前端的 uploadFile API 函数充当后端的网关 src/lib/apis/files/index.ts:4-9。它发送 multipart/form-data 请求，然后监听处理状态流，为用户提供实时更新 src/lib/apis/files/index.ts:45-55。

函数文件路径作用
onUploadsrc/lib/components/chat/MessageInput.svelte编排本地处理并调用上传。 src/lib/components/chat/MessageInput.svelte:106
uploadFilesrc/lib/apis/files/index.ts执行 POST 请求并处理状态流。 src/lib/apis/files/index.ts:4-95
getFileProcessStatussrc/lib/apis/files/index.ts获取文件处理的服务器推送事件（SSE）。 src/lib/apis/files/index.ts:97-119
FileItemsrc/lib/components/common/FileItem.svelte在聊天气泡中渲染文件附件 UI。 src/lib/components/chat/Messages/UserMessage.svelte:218-226

来源： src/lib/components/chat/MessageInput.svelte:41-55，src/lib/utils/index.ts:41-44，src/lib/apis/files/index.ts:4-95

---

后端存储与处理

后端负责持久化文件并触发异步处理任务，例如 OCR 或转录。

存储提供程序架构

Open WebUI 使用可插拔的存储系统。这使得应用程序可以通过 STORAGE_PROVIDER 环境变量在本地磁盘存储和云提供商（S3、GCS、Azure）之间切换 backend/open_webui/routers/files.py:48-51。

sequenceDiagram
    participant R as "backend/open_webui/routers/files.py"
    participant H as "upload_file_handler"
    participant S as "backend/open_webui/storage/provider.py"
    participant P as "process_uploaded_file"
    participant RET as "backend/open_webui/routers/retrieval.py"

    R->>H: 接收 UploadFile
    H->>S: Storage.upload_file(file, filename)
    S-->>H: 返回 file_path
    H->>P: 触发后台处理
    P->>RET: process_file(file_id)
    Note over P: 转录 / 提取
    H-->>R: 返回 FileModelResponse

来源： backend/open_webui/routers/files.py:200-209，backend/open_webui/routers/files.py:105-113，backend/open_webui/routers/files.py:130-144

文件类型检测与处理

后端对上传的文件进行深度检查，以确定正确的处理路径：

  • 错误标记的文本文件：_is_text_file 辅助函数通过检查空字节和 UTF-8 有效性，来识别被标记为二进制（如 .ts 视频文件）的文件是否实际上是纯文本 backend/open_webui/routers/files.py:70-88。
  • 音频转录：如果文件匹配 STT_SUPPORTED_CONTENT_TYPES，系统会调用 transcribe 函数 backend/open_webui/routers/files.py:124-128。
  • 内容提取：非媒体文件会被传递给检索路由中的 process_file，以导入向量数据库 backend/open_webui/routers/files.py:130-135。
  • 知识库：文件可以与特定的知识集合关联，然后被嵌入用于 RAG backend/open_webui/routers/knowledge.py:59-82。

来源： backend/open_webui/routers/files.py:70-154，backend/open_webui/routers/knowledge.py:16-28

---

消息渲染与文件显示

文件根据其角色（用户附件 vs. 助手响应）和内容类型以不同方式渲染。

聊天界面组件
  • UserMessage.svelte：遍历 message.files，使用 Image 组件显示图像，或使用 FileItem 显示其他文件 src/lib/components/chat/Messages/UserMessage.svelte:204-228。
  • ResponseMessage.svelte：显示来自已处理文件的来源和引用 src/lib/components/chat/Messages/ResponseMessage.svelte:55-59。
  • MultiResponseMessages.svelte：处理模型响应的并排比较，这些响应可能包含对同一上传文件的不同解读 src/lib/components/chat/Messages/MultiResponseMessages.svelte:12-20。
文件 URL

前端根据文件的存储位置构建 URL：

  • 本地/数据 URL 用于即时预览 src/lib/components/chat/Messages/UserMessage.svelte:211-212。
  • 后端提供的文件使用 /api/v1/files/{id}/content 端点 src/lib/components/chat/Messages/UserMessage.svelte:213。

来源： src/lib/components/chat/Messages/UserMessage.svelte:204-228，src/lib/components/chat/Messages/ResponseMessage.svelte:67-116

---

配置与状态管理

关键后端配置
  • UPLOAD_DIR：使用本地提供程序时存储文件的本地目录 backend/open_webui/routers/files.py:51。
  • CONTENT_EXTRACTION_ENGINE：确定提取是在本地进行还是通过外部服务进行 backend/open_webui/routers/files.py:137。
  • STT_SUPPORTED_CONTENT_TYPES：定义哪些 MIME 类型会触发转录管道 backend/open_webui/routers/files.py:124。
关键前端存储
  • files：一个 Svelte 存储，保存当前活跃聊天的附件列表 src/lib/stores:176。
  • chatRequestQueues：管理特定聊天的文件相关请求队列，防止上传期间的竞态条件 src/lib/stores:50。
  • temporaryChatEnabled：如果为 true，则阻止上传的文件被持久化到长期聊天历史中 src/lib/components/chat/Chat.svelte:186-188。

来源： backend/open_webui/routers/files.py:51-137，src/lib/stores:18-52，src/lib/components/chat/Chat.svelte:35