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

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

复杂文档理解与引用检索 · 聚焦本章的模块关系、源码依据与实现要点。

项目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

文档与文件管理 API

相关源文件

本章引用的主要源码文件：

  • 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 到代码实体的映射

RAGFlow · 文档管理路由 · 图 1
RAGFlow · 文档管理路由 · 图 1

来源：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。

文件层级映射

RAGFlow · 文件层级与存储映射 · 图 2
RAGFlow · 文件层级与存储映射 · 图 2

来源：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