尧图网站建设 
1 项目背景业务场景「云帆科技」HR 部门的小王接手了一个任务把公司所有 HR 制度文档导入 RAGFlow构建一个HR 制度知识库供全公司 500 名员工自助查询。她手上有 200 多份文档涵盖薪酬制度、考勤制度、招聘流程、培训手册、员工福利、离职管理、劳动合同模板等十几类。文档格式也五花八门最新版是 PDF老版本是 Word还有一些 Markdown 格式的临时通知。小王在 RAGFlow 控制台折腾了半天困惑越来越多「知识库」和「数据集」到底什么关系一个 PDF 上传后「等待解析」了半小时还没动静是什么情况文档删了以后数据真的清干净了吗最要命的是——她不小心删了一个数据集里面的文档还能恢复吗痛点缺乏对 RAGFlow 数据模型和理解的情况下概念混淆以为知识库就是数据集把不同类别的制度全塞进一个数据集导致搜索结果混乱——问加班费怎么算返回了离职流程。状态盲区文档状态从「上传中→等待解析→解析中→成功/失败」是一个异步过程但用户看不到中间态以为系统卡死了。元数据缺失只知道文件名不知道谁上传的、什么时候传的、解析配置是什么出了问题无从追溯。删除不彻底在控制台删了文档以为万事大吉但 MinIO 里的原文件和 ES 里的向量数据可能还残留着占用空间且存在合规风险。小王的心路历程 上传 200 份文档 → 全部堆在一个数据集 → 搜索效果差 ↓ 试图分类 → 创建多个数据集 → 不知道怎么把文档搬家 ↓ 手滑删了一个数据集 → 200MB 文档全没了 → 要重新上传 ↓ 文件被多个同事编辑过 → 命名混乱 → 版本混乱 → 谁传的不知道2 项目设计小胖举着手机冲进会议室“大师救急小王刚才在群里哭诉她把 HR 制度全导进 RAGFlow 了但搜索结果一塌糊涂——问’年假几天’返回的是’离职要提前多久通知’这是咋回事”大师“问题出在数据组织上。我问你她是不是把所有文件都放进了一个数据集”小胖“对啊她说就一个知识库全放一起方便。”大师“这就是典型的’数据粥’——把所有食材一锅炖想喝粥的时候捞到的是骨头。RAGFlow 的数据结构是分层的你看这张图”Knowledge Base知识库HR 制度库 ├── Dataset 1数据集薪酬制度 │ ├── Document 1文档2024薪酬管理办法.pdf │ │ ├── Chunk 1: 第3条 基本工资结构... │ │ ├── Chunk 2: 第4条 绩效奖金... │ │ └── Chunk 3: 第5条 年终奖... │ ├── Document 2文档2024社保缴纳标准.docx │ └── Document 3文档加班费计算规则.md ├── Dataset 2数据集考勤制度 │ ├── Document 4文档考勤管理办法2024.pdf │ └── Document 5文档远程办公规定.md └── Dataset 3数据集招聘流程 ├── Document 6文档招聘管理办法.pdf └── Document 7文档面试评估标准.xlsx技术映射Knowledge Base 图书馆Dataset 书架分类文学/科技/历史Document 一本书Chunk 书里的每一段。小胖“哦所以一个知识库下面可以有多个数据集数据集下面有文档文档查出来的是一个一个的 Chunk 片段。小王把所有东西扔一个数据集就像把小说、菜谱、字典全堆一个书架当然搜不准”大师“对。合理的数据集划分能提高检索精度。因为 RAGFlow 检索时可以指定数据集范围你问’加班费’它就只在’薪酬制度’数据集里搜不会被’招聘流程’干扰。”小白推了推眼镜“那数据集下面还能再分吗比如’薪酬制度’下面还有’基本工资’、‘奖金’、‘社保’我希望更细粒度地管理。”大师“当前版本数据集不支持多级子集。但你可以在数据集命名上用约定来分组比如’薪酬-基本工资’、‘薪酬-奖金’、‘薪酬-社保’。或者利用 RAGFlow 的 Tag标签功能给文档打标签检索时按标签过滤。”小白“那文档在 RAGFlow 中的完整生命周期是怎样的从上传到最终删除中间经历了什么”大师“问到了核心。一个文档的生命周期有七个状态”┌─────────────┐ │ 上传中 │ ← 文件正在传输到 MinIO └──────┬──────┘ ▼ ┌─────────────┐ │ 等待解析 │ ← 保存在 MinIO任务已入 Redis 队列 └──────┬──────┘ ▼ ┌─────────────┐ │ 解析中 │ ← Task Executor 正在处理 └──────┬──────┘ ▼ ┌────────────┴────────────┐ ▼ ▼ ┌─────────────┐ ┌─────────────┐ │ 解析成功 │ │ 解析失败 │ └──────┬──────┘ └──────┬──────┘ ▼ ▼ ┌─────────────┐ ┌─────────────┐ │ 可检索问答 │ │ 查看失败原因 │ │ 可删除重传 │ │ 重新上传 │ └─────────────┘ └─────────────┘ │ ▼ ┌─────────────┐ │ 停止解析 │ ← 用户手动停止处理中可中断 └─────────────┘小胖“天哪居然这么多状态。我以为传上去就完事了。那小王说的’等待解析了半小时’是怎么回事”大师“这是队列机制在起作用。RAGFlow 用 Redis Stream 做任务队列如果同时上传了 200 个文件它们会排队等 Task Executor 一个个处理。Worker 数量由环境变量WS控制默认可能是 1 或 2。Worker 少、文档多自然要排队。你可以通过增加 Worker 数量提升并发解析能力。”技术映射Redis 任务队列 银行叫号系统Task Executor Worker 柜台上传文档 取号等待解析 排队等叫号。小白“那文档的元数据呢文件存在哪里数据库里存了什么”大师“好我们追踪一份文档在 RAGFlow 各存储中的足迹”存储存放内容关键表/路径MySQL文档元数据ID、文件名、类型、大小、租户、状态、解析配置document表、file表MinIO原始文件、解析中间产物{tenant_id}/路径下Redis任务队列消息、临时状态Stream:ragflow_tasksES/InfinityChunk 文本、向量、全文索引{dataset_id}索引-- 数据库中 Document 记录的关键字段SELECTid,name,type,size,status,tenant_id,parser_id,chunk_count,token_count,create_time,update_timeFROMdocumentWHEREidabc-123-def;小白“那删除文档时这些存储里的数据都会清理干净吗”大师“理想情况是都会清理——删 Document 记录、删 MinIO 原文件、删 ES 索引。但实际中可能有残留尤其是非正常删除比如直接在数据库里删记录。所以生产环境建议定期巡检对比数据库和 MinIO 的数据量对比数据库和 ES 的索引数量。”小胖“最后一个问题。小王如果不小心删了一个数据集能恢复吗”大师“RAGFlow 目前不提供回收站功能。删除操作在数据库中就是把记录标记删除或物理删除。如果刚删而且数据库有备份可以从备份恢复。否则——只能重新上传。所以给团队定一个铁律删除数据集前先用 API 导出文档列表和元数据做备份。”技术映射删除数据集 撕掉图书馆的图书分类标签 把书扔进碎纸机没法 undo。3 项目实战环境准备目标在已部署的 RAGFlow 环境中规划并创建一套规范的 HR 制度知识库。前提第2章的 Docker 环境已成功运行。数据准备收集 10 份 HR 制度文档模拟分类如下薪酬类3 份基本工资、绩效奖金、社保缴纳考勤类3 份日常考勤、请假管理、远程办公福利类2 份年度体检、团建活动招聘类2 份招聘流程、面试标准分步实现步骤1设计数据模型目标在代码层面规划知识库和数据集结构。# hr_kb_design.py - 知识库规划方案hr_kb{knowledge_base:云帆科技-HR制度库,datasets:[{name:HR-薪酬制度,description:包含基本工资、绩效奖金、社保公积金等薪酬制度文件,tags:[薪酬,工资,社保,奖金],documents:[2024薪酬管理办法.pdf,绩效奖金发放细则.docx,社保公积金缴纳标准.xlsx]},{name:HR-考勤制度,description:包含日常考勤、请假、加班、远程办公等制度文件,tags:[考勤,请假,加班,远程],documents:[考勤管理办法2024.pdf,请假与调休规定.docx,远程办公管理办法.md]},{name:HR-员工福利,description:包含体检、团建、商业保险等福利政策,tags:[福利,体检,团建,保险],documents:[年度员工体检方案.pdf,团建活动管理办法.docx]},{name:HR-招聘管理,description:包含招聘流程、面试规范、背调等制度,tags:[招聘,面试,背调],documents:[招聘管理办法.pdf,面试评估标准.docx]}]}步骤2通过 API 批量创建数据集目标用 Python SDK 自动化创建数据集避免手动一个个点。# create_datasets.py - 批量创建数据集fromragflowimportRAGFlowimportjson# 初始化客户端ragRAGFlow(api_keyragflow-xxxxxxxxxxxx,# 从控制台获取base_urlhttp://localhost:8080/api/v1)# 数据集定义datasets_config[{name:HR-薪酬制度,description:基本工资、绩效奖金、社保公积金},{name:HR-考勤制度,description:日常考勤、请假、加班、远程办公},{name:HR-员工福利,description:体检、团建、商业保险},{name:HR-招聘管理,description:招聘流程、面试规范、背调},]created_datasets{}forcfgindatasets_config:try:dsrag.create_dataset(namecfg[name],descriptioncfg[description],embedding_modelBAAI/bge-large-zh-v1.5,# 选用中文 embedding 模型chunk_methodnaive# 通用切片方法)created_datasets[cfg[name]]ds.idprint(f[OK] 数据集 {cfg[name]} 创建成功ID:{ds.id})exceptExceptionase:print(f[FAIL] 数据集 {cfg[name]} 创建失败:{e})# 保存映射文件方便后续使用withopen(dataset_mapping.json,w)asf:json.dump(created_datasets,f,indent2,ensure_asciiFalse)print(f\n共创建{len(created_datasets)}个数据集)步骤3上传文档并跟踪状态目标批量上传文档观察状态流转记录完整生命周期。# upload_and_track.py - 上传文档并跟踪状态importosimporttimefromragflowimportRAGFlow ragRAGFlow(api_keyragflow-xxxx,base_urlhttp://localhost:8080/api/v1)# 文档-数据集映射upload_map{HR-薪酬制度:[docs/hr/2024薪酬管理办法.pdf,docs/hr/绩效奖金发放细则.docx,docs/hr/社保公积金缴纳标准.xlsx,],HR-考勤制度:[docs/hr/考勤管理办法2024.pdf,docs/hr/请假与调休规定.docx,docs/hr/远程办公管理办法.md,],HR-员工福利:[docs/hr/年度员工体检方案.pdf,docs/hr/团建活动管理办法.docx,],HR-招聘管理:[docs/hr/招聘管理办法.pdf,docs/hr/面试评估标准.docx,],}# 获取已创建的数据集datasetsrag.list_datasets()ds_name_to_obj{ds.name:dsfordsindatasets}uploaded_docs[]fords_name,filesinupload_map.items():ifds_namenotinds_name_to_obj:print(f[SKIP] 数据集{ds_name}未找到)continuedatasetds_name_to_obj[ds_name]forfile_pathinfiles:ifnotos.path.exists(file_path):print(f[SKIP] 文件{file_path}不存在)continueprint(f[UPLOAD] 正在上传{file_path}到{ds_name}...)docdataset.upload_document(file_path)print(f 文档 ID:{doc.id}, 初始状态:{doc.status})uploaded_docs.append({dataset:ds_name,file:file_path,doc_id:doc.id,status:doc.status})# 等待解析完成轮询max_wait300# 最多等 5 分钟waited0whilewaitedmax_wait:time.sleep(5)waited5updated_docdataset.get_document(doc.id)print(f 状态:{updated_doc.status}(已等待{waited}s))ifupdated_doc.statusin[success,failed,stopped]:breakifupdated_doc.statussuccess:print(f [OK] 解析成功切片数:{updated_doc.chunk_count})elifupdated_doc.statusfailed:print(f [FAIL] 解析失败原因:{updated_doc.error_msg})else:print(f [WARN] 超时未完成当前状态:{updated_doc.status})print(f\n总计上传{len(uploaded_docs)}个文档)命令行输出示例[UPLOAD] 正在上传 docs/hr/2024薪酬管理办法.pdf 到 HR-薪酬制度... 文档 ID: doc_abc123, 初始状态: uploading 状态: waiting_parse (已等待 5s) 状态: parsing (已等待 10s) 状态: parsing (已等待 15s) 状态: success (已等待 20s) [OK] 解析成功切片数: 47步骤4验证数据隔离与检索精度目标确认不同数据集之间的检索互相隔离、互不干扰。# 跨数据集检索测试# 问题1薪酬相关应在薪酬制度数据集中搜到curl-XPOST http://localhost:8080/api/v1/chats\-HAuthorization: Bearer token\-HContent-Type: application/json\-d{ question: 绩效奖金怎么计算, dataset_ids: [薪酬制度数据集ID], stream: false }# 问题2同样的问题在考勤制度数据集中应该搜不到curl-XPOST http://localhost:8080/api/v1/chats\-HAuthorization: Bearer token\-HContent-Type: application/json\-d{ question: 绩效奖金怎么计算, dataset_ids: [考勤制度数据集ID], stream: false }预期结果问题1返回相关答案和引用问题2返回未找到相关信息或拒绝回答。步骤5探索文档管理操作目标掌握文档的启停、重试、删除等管理操作。# 1. 停止正在解析的文档curl-XPUT http://localhost:8080/api/v1/documents/doc_id/status\-HAuthorization: Bearer token\-HContent-Type: application/json\-d{status: stop}# 2. 重试解析失败的文档curl-XPUT http://localhost:8080/api/v1/documents/doc_id/status\-HAuthorization: Bearer token\-HContent-Type: application/json\-d{status: retry}# 3. 删除文档注意不可恢复curl-XDELETE http://localhost:8080/api/v1/documents/doc_id\-HAuthorization: Bearer token# 4. 删除数据集注意会级联删除所有文档curl-XDELETE http://localhost:8080/api/v1/datasets/dataset_id\-HAuthorization: Bearer token坑点删除数据集是级联操作其下所有文档、切片、向量数据都会被清理。务必先导出元数据备份。删除操作在 API 层通常不可回滚。测试验证# test_lifecycle.py - 文档生命周期单元测试importpytestfromragflowimportRAGFlow ragRAGFlow(api_keytest-key,base_urlhttp://localhost:8080/api/v1)deftest_create_and_delete_dataset():测试创建和删除数据集# 创建dsrag.create_dataset(nameTEST-生命周期测试,description自动化测试)assertds.idisnotNoneassertds.nameTEST-生命周期测试# 删除resultrag.delete_dataset(ds.id)assertresultisTruedeftest_upload_and_parse_document():测试文档上传和解析状态流转dsrag.create_dataset(nameTEST-文档状态测试)# 上传文档docds.upload_document(test_data/sample_policy.pdf)assertdoc.statusin[uploading,waiting_parse]# 等待解析完成importtimefor_inrange(60):# 最多等 5 分钟time.sleep(5)docds.get_document(doc.id)ifdoc.statusin[success,failed]:breakassertdoc.statussuccessassertdoc.chunk_count0# 清理rag.delete_dataset(ds.id)deftest_cross_dataset_isolation():测试跨数据集检索隔离ds_salaryrag.get_dataset(HR-薪酬制度)ds_attendancerag.get_dataset(HR-考勤制度)# 在薪酬数据集中检索薪酬问题resultrag.chat(question绩效奖金怎么计算,dataset_ids[ds_salary.id])assertresult.answerisnotNoneassertlen(result.references)0# 在考勤数据集中检索薪酬问题应该搜不到result2rag.chat(question绩效奖金怎么计算,dataset_ids[ds_attendance.id])assertresult2.answerisNoneor未找到inresult2.answer完整代码清单Git 仓库https://github.com/infiniflow/ragflow文件说明api/db/services/file_service.py文件存储服务api/db/services/document_service.py文档管理服务api/db/services/file2document_service.py文件到文档的关系服务api/db/db_models.py数据库模型定义Document、File 表4 项目总结优点 缺点维度RAGFlow 数据模型自建文档管理MySQL S3SharePoint 文档库检索能力★★★ 语义检索 引用★☆☆ 需自建搜索引擎★★☆ 全文检索数据分层★★★ KB → Dataset → Doc → Chunk★☆☆ 需自己设计★★☆ 文件夹 元数据文档解析★★★ DeepDoc 多格式★☆☆ 需自集成解析器★★☆ Office 格式权限粒度★★☆ 数据集级★★★ 可自定义字段级★★★ 细粒度 ACL生命周期管理★★☆ 基本状态追踪★★★ 可自定义工作流★★★ 审批、版本控制适用场景企业制度管理按部门HR/财务/法务划分数据集每个数据集下管理相关制度文档。产品文档分类按产品线或版本号划分数据集支持多版本并存。项目资料归档按项目阶段需求/设计/测试/部署划分数据集。培训课程管理按课程分类划分数据集课程材料作为文档上传。合规审计管理按法规类型划分数据集确保检索范围精确。不适用场景需要细粒度文档权限控制如按段落、按章节授权RAGFlow 权限粒度是数据集级别。需要强版本管理如文档修订历史对比、回滚RAGFlow 不内置版本管理。注意事项命名规范建议团队制定数据集和文档命名规范例如{部门}-{类别}-{年份}格式避免后续数据混乱。数据集不宜过多一个知识库下建议数据集不超过 50 个过多会影响检索性能和管理效率。删除确认机制建议在 API 层增加二次确认防止误删。控制台前端已有弹窗确认但 API 调用无二次确认。文档大小限制单位文档建议不超过 100MB过大文件解析耗时长且容易超时。状态同步延迟文档状态从前端看到的变化可能有 1-3 秒延迟这是正常现象轮询间隔。常见踩坑经验故障现象根因解决方法文档一直等待解析超过 1 小时Task Executor 已挂掉或 Worker 全部阻塞docker logs ragflow-task-executor检查必要时重启创建数据集时提示名称已存在数据集名称全系统唯一含已删除的软删除记录加时间戳或序号后缀删除数据集后 MinIO 文件仍存在异步删除未完成或垃圾回收未触发手动检查 MinIO定期清理孤儿文件大批量上传时部分文档失败Redis 队列积压导致超时或 Worker 内存不足分批上传每批 20 个增大 Worker 内存限制跨数据集检索结果混乱同时传多个 dataset_id 时结果合并排序来源不可区分前端区分来源展示或分开调用 API思考题如果需要在 RAGFlow 中实现文档的版本管理比如同一份文件有 v1、v2、v3 三个版本你会如何设计数据模型请考虑 Document 表需要增加哪些字段以及检索时如何确保用户读到的是最新版本。公司有 100 个部门每个部门需要独立的知识库且部门间数据完全隔离。你会选择「每个部门一个知识库」还是「一个知识库 100 个数据集」请从权限、成本、运维三个维度分析利弊。答案提示见第4章末尾或附录 D。延伸阅读与资源10倍开发者的 Dify 魔法书从零构建全栈 AI 应用后端工程师转型AI第一课-Ollama 与私有化大模型实战大型语言模型(LLM) vLLM 高性能推理落地实战Agent开发之LlamaIndex 实战修炼与源码进阶大语言模型Transformers 实战修炼与源码剖析 第3章：RAGFlow 知识库、数据集与文档生命周期
1 项目背景业务场景「云帆科技」HR 部门的小王接手了一个任务把公司所有 HR 制度文档导入 RAGFlow构建一个HR 制度知识库供全公司 500 名员工自助查询。她手上有 200 多份文档涵盖薪酬制度、考勤制度、招聘流程、培训手册、员工福利、离职管理、劳动合同模板等十几类。文档格式也五花八门最新版是 PDF老版本是 Word还有一些 Markdown 格式的临时通知。小王在 RAGFlow 控制台折腾了半天困惑越来越多「知识库」和「数据集」到底什么关系一个 PDF 上传后「等待解析」了半小时还没动静是什么情况文档删了以后数据真的清干净了吗最要命的是——她不小心删了一个数据集里面的文档还能恢复吗痛点缺乏对 RAGFlow 数据模型和理解的情况下概念混淆以为知识库就是数据集把不同类别的制度全塞进一个数据集导致搜索结果混乱——问加班费怎么算返回了离职流程。状态盲区文档状态从「上传中→等待解析→解析中→成功/失败」是一个异步过程但用户看不到中间态以为系统卡死了。元数据缺失只知道文件名不知道谁上传的、什么时候传的、解析配置是什么出了问题无从追溯。删除不彻底在控制台删了文档以为万事大吉但 MinIO 里的原文件和 ES 里的向量数据可能还残留着占用空间且存在合规风险。小王的心路历程 上传 200 份文档 → 全部堆在一个数据集 → 搜索效果差 ↓ 试图分类 → 创建多个数据集 → 不知道怎么把文档搬家 ↓ 手滑删了一个数据集 → 200MB 文档全没了 → 要重新上传 ↓ 文件被多个同事编辑过 → 命名混乱 → 版本混乱 → 谁传的不知道2 项目设计小胖举着手机冲进会议室“大师救急小王刚才在群里哭诉她把 HR 制度全导进 RAGFlow 了但搜索结果一塌糊涂——问’年假几天’返回的是’离职要提前多久通知’这是咋回事”大师“问题出在数据组织上。我问你她是不是把所有文件都放进了一个数据集”小胖“对啊她说就一个知识库全放一起方便。”大师“这就是典型的’数据粥’——把所有食材一锅炖想喝粥的时候捞到的是骨头。RAGFlow 的数据结构是分层的你看这张图”Knowledge Base知识库HR 制度库 ├── Dataset 1数据集薪酬制度 │ ├── Document 1文档2024薪酬管理办法.pdf │ │ ├── Chunk 1: 第3条 基本工资结构... │ │ ├── Chunk 2: 第4条 绩效奖金... │ │ └── Chunk 3: 第5条 年终奖... │ ├── Document 2文档2024社保缴纳标准.docx │ └── Document 3文档加班费计算规则.md ├── Dataset 2数据集考勤制度 │ ├── Document 4文档考勤管理办法2024.pdf │ └── Document 5文档远程办公规定.md └── Dataset 3数据集招聘流程 ├── Document 6文档招聘管理办法.pdf └── Document 7文档面试评估标准.xlsx技术映射Knowledge Base 图书馆Dataset 书架分类文学/科技/历史Document 一本书Chunk 书里的每一段。小胖“哦所以一个知识库下面可以有多个数据集数据集下面有文档文档查出来的是一个一个的 Chunk 片段。小王把所有东西扔一个数据集就像把小说、菜谱、字典全堆一个书架当然搜不准”大师“对。合理的数据集划分能提高检索精度。因为 RAGFlow 检索时可以指定数据集范围你问’加班费’它就只在’薪酬制度’数据集里搜不会被’招聘流程’干扰。”小白推了推眼镜“那数据集下面还能再分吗比如’薪酬制度’下面还有’基本工资’、‘奖金’、‘社保’我希望更细粒度地管理。”大师“当前版本数据集不支持多级子集。但你可以在数据集命名上用约定来分组比如’薪酬-基本工资’、‘薪酬-奖金’、‘薪酬-社保’。或者利用 RAGFlow 的 Tag标签功能给文档打标签检索时按标签过滤。”小白“那文档在 RAGFlow 中的完整生命周期是怎样的从上传到最终删除中间经历了什么”大师“问到了核心。一个文档的生命周期有七个状态”┌─────────────┐ │ 上传中 │ ← 文件正在传输到 MinIO └──────┬──────┘ ▼ ┌─────────────┐ │ 等待解析 │ ← 保存在 MinIO任务已入 Redis 队列 └──────┬──────┘ ▼ ┌─────────────┐ │ 解析中 │ ← Task Executor 正在处理 └──────┬──────┘ ▼ ┌────────────┴────────────┐ ▼ ▼ ┌─────────────┐ ┌─────────────┐ │ 解析成功 │ │ 解析失败 │ └──────┬──────┘ └──────┬──────┘ ▼ ▼ ┌─────────────┐ ┌─────────────┐ │ 可检索问答 │ │ 查看失败原因 │ │ 可删除重传 │ │ 重新上传 │ └─────────────┘ └─────────────┘ │ ▼ ┌─────────────┐ │ 停止解析 │ ← 用户手动停止处理中可中断 └─────────────┘小胖“天哪居然这么多状态。我以为传上去就完事了。那小王说的’等待解析了半小时’是怎么回事”大师“这是队列机制在起作用。RAGFlow 用 Redis Stream 做任务队列如果同时上传了 200 个文件它们会排队等 Task Executor 一个个处理。Worker 数量由环境变量WS控制默认可能是 1 或 2。Worker 少、文档多自然要排队。你可以通过增加 Worker 数量提升并发解析能力。”技术映射Redis 任务队列 银行叫号系统Task Executor Worker 柜台上传文档 取号等待解析 排队等叫号。小白“那文档的元数据呢文件存在哪里数据库里存了什么”大师“好我们追踪一份文档在 RAGFlow 各存储中的足迹”存储存放内容关键表/路径MySQL文档元数据ID、文件名、类型、大小、租户、状态、解析配置document表、file表MinIO原始文件、解析中间产物{tenant_id}/路径下Redis任务队列消息、临时状态Stream:ragflow_tasksES/InfinityChunk 文本、向量、全文索引{dataset_id}索引-- 数据库中 Document 记录的关键字段SELECTid,name,type,size,status,tenant_id,parser_id,chunk_count,token_count,create_time,update_timeFROMdocumentWHEREidabc-123-def;小白“那删除文档时这些存储里的数据都会清理干净吗”大师“理想情况是都会清理——删 Document 记录、删 MinIO 原文件、删 ES 索引。但实际中可能有残留尤其是非正常删除比如直接在数据库里删记录。所以生产环境建议定期巡检对比数据库和 MinIO 的数据量对比数据库和 ES 的索引数量。”小胖“最后一个问题。小王如果不小心删了一个数据集能恢复吗”大师“RAGFlow 目前不提供回收站功能。删除操作在数据库中就是把记录标记删除或物理删除。如果刚删而且数据库有备份可以从备份恢复。否则——只能重新上传。所以给团队定一个铁律删除数据集前先用 API 导出文档列表和元数据做备份。”技术映射删除数据集 撕掉图书馆的图书分类标签 把书扔进碎纸机没法 undo。3 项目实战环境准备目标在已部署的 RAGFlow 环境中规划并创建一套规范的 HR 制度知识库。前提第2章的 Docker 环境已成功运行。数据准备收集 10 份 HR 制度文档模拟分类如下薪酬类3 份基本工资、绩效奖金、社保缴纳考勤类3 份日常考勤、请假管理、远程办公福利类2 份年度体检、团建活动招聘类2 份招聘流程、面试标准分步实现步骤1设计数据模型目标在代码层面规划知识库和数据集结构。# hr_kb_design.py - 知识库规划方案hr_kb{knowledge_base:云帆科技-HR制度库,datasets:[{name:HR-薪酬制度,description:包含基本工资、绩效奖金、社保公积金等薪酬制度文件,tags:[薪酬,工资,社保,奖金],documents:[2024薪酬管理办法.pdf,绩效奖金发放细则.docx,社保公积金缴纳标准.xlsx]},{name:HR-考勤制度,description:包含日常考勤、请假、加班、远程办公等制度文件,tags:[考勤,请假,加班,远程],documents:[考勤管理办法2024.pdf,请假与调休规定.docx,远程办公管理办法.md]},{name:HR-员工福利,description:包含体检、团建、商业保险等福利政策,tags:[福利,体检,团建,保险],documents:[年度员工体检方案.pdf,团建活动管理办法.docx]},{name:HR-招聘管理,description:包含招聘流程、面试规范、背调等制度,tags:[招聘,面试,背调],documents:[招聘管理办法.pdf,面试评估标准.docx]}]}步骤2通过 API 批量创建数据集目标用 Python SDK 自动化创建数据集避免手动一个个点。# create_datasets.py - 批量创建数据集fromragflowimportRAGFlowimportjson# 初始化客户端ragRAGFlow(api_keyragflow-xxxxxxxxxxxx,# 从控制台获取base_urlhttp://localhost:8080/api/v1)# 数据集定义datasets_config[{name:HR-薪酬制度,description:基本工资、绩效奖金、社保公积金},{name:HR-考勤制度,description:日常考勤、请假、加班、远程办公},{name:HR-员工福利,description:体检、团建、商业保险},{name:HR-招聘管理,description:招聘流程、面试规范、背调},]created_datasets{}forcfgindatasets_config:try:dsrag.create_dataset(namecfg[name],descriptioncfg[description],embedding_modelBAAI/bge-large-zh-v1.5,# 选用中文 embedding 模型chunk_methodnaive# 通用切片方法)created_datasets[cfg[name]]ds.idprint(f[OK] 数据集 {cfg[name]} 创建成功ID:{ds.id})exceptExceptionase:print(f[FAIL] 数据集 {cfg[name]} 创建失败:{e})# 保存映射文件方便后续使用withopen(dataset_mapping.json,w)asf:json.dump(created_datasets,f,indent2,ensure_asciiFalse)print(f\n共创建{len(created_datasets)}个数据集)步骤3上传文档并跟踪状态目标批量上传文档观察状态流转记录完整生命周期。# upload_and_track.py - 上传文档并跟踪状态importosimporttimefromragflowimportRAGFlow ragRAGFlow(api_keyragflow-xxxx,base_urlhttp://localhost:8080/api/v1)# 文档-数据集映射upload_map{HR-薪酬制度:[docs/hr/2024薪酬管理办法.pdf,docs/hr/绩效奖金发放细则.docx,docs/hr/社保公积金缴纳标准.xlsx,],HR-考勤制度:[docs/hr/考勤管理办法2024.pdf,docs/hr/请假与调休规定.docx,docs/hr/远程办公管理办法.md,],HR-员工福利:[docs/hr/年度员工体检方案.pdf,docs/hr/团建活动管理办法.docx,],HR-招聘管理:[docs/hr/招聘管理办法.pdf,docs/hr/面试评估标准.docx,],}# 获取已创建的数据集datasetsrag.list_datasets()ds_name_to_obj{ds.name:dsfordsindatasets}uploaded_docs[]fords_name,filesinupload_map.items():ifds_namenotinds_name_to_obj:print(f[SKIP] 数据集{ds_name}未找到)continuedatasetds_name_to_obj[ds_name]forfile_pathinfiles:ifnotos.path.exists(file_path):print(f[SKIP] 文件{file_path}不存在)continueprint(f[UPLOAD] 正在上传{file_path}到{ds_name}...)docdataset.upload_document(file_path)print(f 文档 ID:{doc.id}, 初始状态:{doc.status})uploaded_docs.append({dataset:ds_name,file:file_path,doc_id:doc.id,status:doc.status})# 等待解析完成轮询max_wait300# 最多等 5 分钟waited0whilewaitedmax_wait:time.sleep(5)waited5updated_docdataset.get_document(doc.id)print(f 状态:{updated_doc.status}(已等待{waited}s))ifupdated_doc.statusin[success,failed,stopped]:breakifupdated_doc.statussuccess:print(f [OK] 解析成功切片数:{updated_doc.chunk_count})elifupdated_doc.statusfailed:print(f [FAIL] 解析失败原因:{updated_doc.error_msg})else:print(f [WARN] 超时未完成当前状态:{updated_doc.status})print(f\n总计上传{len(uploaded_docs)}个文档)命令行输出示例[UPLOAD] 正在上传 docs/hr/2024薪酬管理办法.pdf 到 HR-薪酬制度... 文档 ID: doc_abc123, 初始状态: uploading 状态: waiting_parse (已等待 5s) 状态: parsing (已等待 10s) 状态: parsing (已等待 15s) 状态: success (已等待 20s) [OK] 解析成功切片数: 47步骤4验证数据隔离与检索精度目标确认不同数据集之间的检索互相隔离、互不干扰。# 跨数据集检索测试# 问题1薪酬相关应在薪酬制度数据集中搜到curl-XPOST http://localhost:8080/api/v1/chats\-HAuthorization: Bearer token\-HContent-Type: application/json\-d{ question: 绩效奖金怎么计算, dataset_ids: [薪酬制度数据集ID], stream: false }# 问题2同样的问题在考勤制度数据集中应该搜不到curl-XPOST http://localhost:8080/api/v1/chats\-HAuthorization: Bearer token\-HContent-Type: application/json\-d{ question: 绩效奖金怎么计算, dataset_ids: [考勤制度数据集ID], stream: false }预期结果问题1返回相关答案和引用问题2返回未找到相关信息或拒绝回答。步骤5探索文档管理操作目标掌握文档的启停、重试、删除等管理操作。# 1. 停止正在解析的文档curl-XPUT http://localhost:8080/api/v1/documents/doc_id/status\-HAuthorization: Bearer token\-HContent-Type: application/json\-d{status: stop}# 2. 重试解析失败的文档curl-XPUT http://localhost:8080/api/v1/documents/doc_id/status\-HAuthorization: Bearer token\-HContent-Type: application/json\-d{status: retry}# 3. 删除文档注意不可恢复curl-XDELETE http://localhost:8080/api/v1/documents/doc_id\-HAuthorization: Bearer token# 4. 删除数据集注意会级联删除所有文档curl-XDELETE http://localhost:8080/api/v1/datasets/dataset_id\-HAuthorization: Bearer token坑点删除数据集是级联操作其下所有文档、切片、向量数据都会被清理。务必先导出元数据备份。删除操作在 API 层通常不可回滚。测试验证# test_lifecycle.py - 文档生命周期单元测试importpytestfromragflowimportRAGFlow ragRAGFlow(api_keytest-key,base_urlhttp://localhost:8080/api/v1)deftest_create_and_delete_dataset():测试创建和删除数据集# 创建dsrag.create_dataset(nameTEST-生命周期测试,description自动化测试)assertds.idisnotNoneassertds.nameTEST-生命周期测试# 删除resultrag.delete_dataset(ds.id)assertresultisTruedeftest_upload_and_parse_document():测试文档上传和解析状态流转dsrag.create_dataset(nameTEST-文档状态测试)# 上传文档docds.upload_document(test_data/sample_policy.pdf)assertdoc.statusin[uploading,waiting_parse]# 等待解析完成importtimefor_inrange(60):# 最多等 5 分钟time.sleep(5)docds.get_document(doc.id)ifdoc.statusin[success,failed]:breakassertdoc.statussuccessassertdoc.chunk_count0# 清理rag.delete_dataset(ds.id)deftest_cross_dataset_isolation():测试跨数据集检索隔离ds_salaryrag.get_dataset(HR-薪酬制度)ds_attendancerag.get_dataset(HR-考勤制度)# 在薪酬数据集中检索薪酬问题resultrag.chat(question绩效奖金怎么计算,dataset_ids[ds_salary.id])assertresult.answerisnotNoneassertlen(result.references)0# 在考勤数据集中检索薪酬问题应该搜不到result2rag.chat(question绩效奖金怎么计算,dataset_ids[ds_attendance.id])assertresult2.answerisNoneor未找到inresult2.answer完整代码清单Git 仓库https://github.com/infiniflow/ragflow文件说明api/db/services/file_service.py文件存储服务api/db/services/document_service.py文档管理服务api/db/services/file2document_service.py文件到文档的关系服务api/db/db_models.py数据库模型定义Document、File 表4 项目总结优点 缺点维度RAGFlow 数据模型自建文档管理MySQL S3SharePoint 文档库检索能力★★★ 语义检索 引用★☆☆ 需自建搜索引擎★★☆ 全文检索数据分层★★★ KB → Dataset → Doc → Chunk★☆☆ 需自己设计★★☆ 文件夹 元数据文档解析★★★ DeepDoc 多格式★☆☆ 需自集成解析器★★☆ Office 格式权限粒度★★☆ 数据集级★★★ 可自定义字段级★★★ 细粒度 ACL生命周期管理★★☆ 基本状态追踪★★★ 可自定义工作流★★★ 审批、版本控制适用场景企业制度管理按部门HR/财务/法务划分数据集每个数据集下管理相关制度文档。产品文档分类按产品线或版本号划分数据集支持多版本并存。项目资料归档按项目阶段需求/设计/测试/部署划分数据集。培训课程管理按课程分类划分数据集课程材料作为文档上传。合规审计管理按法规类型划分数据集确保检索范围精确。不适用场景需要细粒度文档权限控制如按段落、按章节授权RAGFlow 权限粒度是数据集级别。需要强版本管理如文档修订历史对比、回滚RAGFlow 不内置版本管理。注意事项命名规范建议团队制定数据集和文档命名规范例如{部门}-{类别}-{年份}格式避免后续数据混乱。数据集不宜过多一个知识库下建议数据集不超过 50 个过多会影响检索性能和管理效率。删除确认机制建议在 API 层增加二次确认防止误删。控制台前端已有弹窗确认但 API 调用无二次确认。文档大小限制单位文档建议不超过 100MB过大文件解析耗时长且容易超时。状态同步延迟文档状态从前端看到的变化可能有 1-3 秒延迟这是正常现象轮询间隔。常见踩坑经验故障现象根因解决方法文档一直等待解析超过 1 小时Task Executor 已挂掉或 Worker 全部阻塞docker logs ragflow-task-executor检查必要时重启创建数据集时提示名称已存在数据集名称全系统唯一含已删除的软删除记录加时间戳或序号后缀删除数据集后 MinIO 文件仍存在异步删除未完成或垃圾回收未触发手动检查 MinIO定期清理孤儿文件大批量上传时部分文档失败Redis 队列积压导致超时或 Worker 内存不足分批上传每批 20 个增大 Worker 内存限制跨数据集检索结果混乱同时传多个 dataset_id 时结果合并排序来源不可区分前端区分来源展示或分开调用 API思考题如果需要在 RAGFlow 中实现文档的版本管理比如同一份文件有 v1、v2、v3 三个版本你会如何设计数据模型请考虑 Document 表需要增加哪些字段以及检索时如何确保用户读到的是最新版本。公司有 100 个部门每个部门需要独立的知识库且部门间数据完全隔离。你会选择「每个部门一个知识库」还是「一个知识库 100 个数据集」请从权限、成本、运维三个维度分析利弊。答案提示见第4章末尾或附录 D。延伸阅读与资源10倍开发者的 Dify 魔法书从零构建全栈 AI 应用后端工程师转型AI第一课-Ollama 与私有化大模型实战大型语言模型(LLM) vLLM 高性能推理落地实战Agent开发之LlamaIndex 实战修炼与源码进阶大语言模型Transformers 实战修炼与源码剖析