agentic_huge_data_base / wiki
页面 RAGFlow · 7.5 文档与文件管理 API·DeepWiki 中文全文译文
DeepWiki 中文译文 / RAGFlow / 7.5

7.5 · 文档与文件管理 API（Document and File Management APIs）

复杂文档理解与引用检索 · 本章是 RAGFlow DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目RAGFlow 章节7.5 状态全文译文 模块文档对象与元数据、系统架构、接口与服务契约、界面与交互
项目要点页2.5 参考项目 项目章节目录RAGFlow DeepWiki 原始章节Document and File Management APIs 上一章7.4 下一章7.6
源码线索
  • api/apps/restful_apis/document_api.py
  • api/apps/restful_apis/file_api.py
  • api/apps/services/file_api_service.py
  • internal/common/error_code.go
  • internal/dao/connector.go
  • internal/dao/document.go
  • internal/dao/file.go
  • internal/dao/file2document.go
  • internal/handler/file.go
  • internal/service/file.go
模块标签
  • 文档对象与元数据
  • 系统架构
  • 接口与服务契约
  • 界面与交互
  • 入库与解析

中文译文

文档与文件管理 API（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/infiniflow/ragflow/7.5-document-and-file-management-apis
翻译时间：2026-05-27T08:44:24.221Z
翻译模型：deepseek-chat
原文字符数：11640
项目：RAGFlow (ragflow)

---

文档与文件管理 API

相关源文件

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

  • api/apps/restful_apis/document_api.py
  • api/apps/restful_apis/file_api.py
  • api/apps/services/file_api_service.py
  • internal/common/error_code.go
  • internal/dao/connector.go
  • internal/dao/document.go
  • internal/dao/file.go
  • internal/dao/file2document.go
  • internal/handler/file.go
  • internal/service/file.go
  • internal/utility/file.go
  • sdk/python/test/test_http_api/test_file_management_within_dataset/test_stop_parse_documents.py
  • test/testcases/test_http_api/test_file_app/test_file_routes.py
  • test/testcases/test_http_api/test_file_management_within_dataset/test_delete_documents.py
  • test/testcases/test_http_api/test_file_management_within_dataset/test_parse_documents.py
  • test/testcases/test_http_api/test_file_management_within_dataset/test_stop_parse_documents.py
  • test/testcases/test_sdk_api/test_file_management_within_dataset/test_delete_documents.py
  • test/testcases/test_sdk_api/test_file_management_within_dataset/test_download_document.py
  • test/testcases/test_sdk_api/test_file_management_within_dataset/test_parse_documents.py
  • test/testcases/test_web_api/test_common.py
  • test/testcases/test_web_api/test_document_app/conftest.py
  • test/testcases/test_web_api/test_document_app/test_document_metadata.py
  • test/testcases/test_web_api/test_document_app/test_rm_documents.py
  • test/testcases/test_web_api/test_file_app/test_file_routes_unit.py
  • web/public/iconfont.js
  • web/src/components/icon-font.tsx
  • web/src/components/ui/table.tsx
  • web/src/hooks/logic-hooks/use-row-selection.ts
  • web/src/hooks/use-document-request.ts
  • web/src/hooks/use-file-request.ts
  • web/src/pages/files/action-cell.tsx
  • web/src/pages/files/files-table.tsx
  • web/src/pages/files/hooks.ts
  • web/src/pages/files/index.tsx
  • web/src/pages/files/knowledge-cell.tsx
  • web/src/pages/files/use-bulk-operate-file.tsx
  • web/src/pages/files/use-move-file.ts
  • web/src/pages/files/util.ts
  • web/src/services/knowledge-service.ts
  • web/src/utils/api.ts

本文档记录了 RAGFlow 中用于管理文档和文件的 API 端点与服务。这些 API 负责处理文件上传、文档生命周期管理、元数据操作，以及文件存储层与文档处理管线之间的协调。

概述

RAGFlow 采用双层架构进行内容管理：

  1. 文件层：物理文件存储与层级化文件夹组织。由 FileService api/apps/services/file_api_service.py:25 和 file_api.py 管理。该层在 File 模型中跟踪文件元数据。
  2. 文档层：与知识库（数据集）关联的逻辑文档记录。由 DocumentService api/db/services/document_service.py:35 和 document_api.py api/apps/restful_apis/document_api.py:120 管理。该层在 Document 模型中跟踪解析状态和统计信息。

两者之间的关系通过 File2DocumentService 维护，该服务将物理文件映射到 RAG 系统中的逻辑文档对应项 api/apps/services/file_api_service.py:24。

API 架构

文档管理路由

文档管理 API 主要由 document_api.py（RESTful API）和 knowledge-service.ts（前端）处理。这些路由管理数据集内文档的入库、重命名和解析触发。

文档 API 到代码实体的映射

graph TB
    subgraph "自然语言空间"
        UPL["上传文档到数据集"]
        UP_INFO["上传信息（URL/文件）"]
        PATCH["更新文档（解析器/名称）"]
        DL["下载文档"]
    end

    subgraph "代码实体空间（Python/JS）"
        subgraph "前端服务（web/src/services/knowledge-service.ts）"
            JS_UPL["documentUpload"]
            JS_ING["documentIngest"]
        end

        subgraph "后端路由（api/apps/restful_apis/document_api.py）"
            R_INFO["@manager.route('/documents/upload')"]
            R_PATCH["@manager.route('/datasets/<dataset_id>/documents/<document_id>')"]
            R_DL["@manager.route('/documents/<docId>/download')"]
        end

        subgraph "服务层"
            FS["FileService"]
            DS["DocumentService"]
            DAS["DocumentApiService"]
            F2D["File2DocumentService"]
        end
    end

    UPL --> JS_UPL
    JS_UPL --> R_PATCH
    UP_INFO --> R_INFO
    PATCH --> R_PATCH
    DL --> R_DL

    R_INFO --> FS
    R_PATCH --> DAS
    R_DL --> F2D
    DAS --> DS

来源：api/apps/restful_apis/document_api.py:57-60，api/apps/restful_apis/document_api.py:120-123，web/src/services/knowledge-service.ts:18-22，web/src/utils/api.ts:130-136

文件层级与存储映射

FileService 为每个租户管理一个虚拟文件系统。这包括递归文件夹遍历、大小计算和跟踪数据集关联。文件按树形结构组织，每个文件或文件夹都有一个 parent_id api/apps/services/file_api_service.py:91。

文件层级映射

graph TB
    subgraph "文件操作（api/apps/services/file_api_service.py）"
        L_FILES["list_files"]
        U_FILE["upload_file"]
        C_FOLDER["create_folder"]
    end

    subgraph "数据访问（internal/dao/）"
        D_FILE["FileDAO"]
        D_DOC["DocumentDAO"]
        D_F2D["File2DocumentDAO"]
    end

    subgraph "数据库实体"
        M_FILE["File（parent_id, type）"]
        M_DOC["Document（kb_id, parser_id）"]
    end

    L_FILES --> D_FILE
    U_FILE --> D_FILE
    C_FOLDER --> D_FILE
    D_FILE --> M_FILE
    D_DOC --> M_DOC

来源：api/apps/services/file_api_service.py:32-40，api/apps/services/file_api_service.py:105-114，api/apps/services/file_api_service.py:142-149，internal/dao/document.go:24-30

文档与文件的关系

在 RAGFlow 中，"文件"是存储实体，而"文档"是处理实体。

  • 文件：上传到文件管理器时创建。它包含 parent_id（文件夹）和 type（例如 folder、virtual 或基于扩展名的类型）api/apps/services/file_api_service.py:124-138。
  • 文档：当文件导入到知识库时创建。它包含解析配置（parser_id）、片段切分状态（run）以及 token_num 和 chunk_num 等统计信息。

系统使用 filename_type 根据扩展名自动对文件进行分类 api/apps/services/file_api_service.py:80。

元数据管理

元数据通过专用服务处理，这些服务与关系型数据库和文档存储进行交互。

  • DocMetadataService：管理文档级别的元数据 api/apps/restful_apis/document_api.py:33。
  • 元数据配置：存在用于在数据集和文档级别更新元数据配置的端点 web/src/utils/api.ts:93-98。
  • 批量操作：系统支持对数据集中的多个文档进行批量元数据更新 web/src/utils/api.ts:93-94。

来源：api/apps/restful_apis/document_api.py:33，web/src/utils/api.ts:93-98，web/src/services/knowledge-service.ts:69-72

核心 API 端点

文档操作（数据集上下文）
端点方法描述
/datasets/<id>/documentsPOST上传文档到指定数据集 web/src/utils/api.ts:135-136
/datasets/<id>/documents/<doc_id>PATCH更新文档名称、解析器或状态 api/apps/restful_apis/document_api.py:120-123
/documents/uploadPOST上传文件/URL 以获取解析信息，不绑定数据集 api/apps/restful_apis/document_api.py:57-60
/documents/<doc_id>/downloadGET下载与文档关联的物理文件 web/src/utils/api.ts:133-134
/datasets/<id>/documents/batch-update-statusPOST批量更新文档的启用/禁用状态 web/src/utils/api.ts:118-119
文件操作（租户上下文）
端点方法描述
/connectorsGET/POST管理数据源连接器并同步文件 web/src/utils/api.ts:39-40
/datasets/<id>/documents?type=webPOST网页抓取并创建文档 web/src/utils/api.ts:137-138
/datasets/<id>/documents?type=emptyPOST创建空文档记录 web/src/utils/api.ts:125-126

来源：api/apps/restful_apis/document_api.py:57-123，web/src/utils/api.ts:39-138，web/src/services/knowledge-service.ts:45-68

解析生命周期

  1. 入库：通过 documentIngest 触发 web/src/services/knowledge-service.ts:49-52。
  2. 任务创建：后端在 Task 表中创建条目，以跟踪异步片段切分过程 api/apps/restful_apis/document_api.py:34。
  3. 状态跟踪：Document 模型中的 run 字段跟踪状态。当文档处于 RunningStatus.RUNNING 状态时，前端会轮询状态更新 web/src/hooks/use-document-request.ts:117-120。
  4. 重新解析：通过 reset_document_for_reparse 触发，该操作会清除现有片段并重置任务状态 api/apps/services/document_api_service.py:30。
  5. 片段管理：可以通过特定的文档子路由列出、创建或更新片段 web/src/services/knowledge-service.ts:166-208。

来源：web/src/services/knowledge-service.ts:49-52，web/src/hooks/use-document-request.ts:117-120，api/apps/services/document_api_service.py:30，web/src/services/knowledge-service.ts:166-208