一句话定位RAGFlow 是 infiniflow 团队开源的 RAG检索增强生成引擎核心差异点是深度文档理解DeepDoc——能从复杂格式PDF、扫描件、表格、幻灯片等中精准提取结构化知识配合多路召回重排序为 LLM 提供高质量、可溯源的上下文。目前 GitHub 81.6k Stars。它同时融合了 Agent 能力、MCP 支持、代码执行沙箱和记忆系统不只是做一个向量检索库而是想做一套企业级的 RAG 工作流平台。一、部署方式方式一Docker 一键部署推荐硬件要求CPU ≥ 4 核RAM ≥ 16 GB磁盘 ≥ 50 GB前置检查# 检查 vm.max_map_count必须 ≥ 262144sysctlvm.max_map_count# 不够的话临时设置sudosysctl-wvm.max_map_count262144# 永久生效写入 /etc/sysctl.confechovm.max_map_count262144|sudotee-a/etc/sysctl.conf启动服务gitclone https://github.com/infiniflow/ragflow.gitcdragflow/docker# 可选切换到稳定版本# git checkout v0.25.6# CPU 模式启动dockercompose-fdocker-compose.yml up-d# GPU 加速 DeepDoc需 NVIDIA GPU# sed -i 1i DEVICEgpu .env# docker compose -f docker-compose.yml up -d确认启动成功dockerlogs-fdocker-ragflow-cpu-1看到 RAGFlow 的 ASCII Logo 和Running on all addresses即表示启动完成。访问浏览器打开http://你的服务器IP默认端口 80。注意目前官方只提供 x86 平台的 Docker 镜像ARM64 需要自行构建。方式二云服务免部署直接访问 https://cloud.ragflow.io 使用托管版。方式三源码开发需要 Python 3.13、Node.js、Docker 基础服务MinIO、ES/Infinity、Redis、MySQL。详见官方文档「Launch service from source for development」。二、使用前必做配置 LLM 和 Embedding 模型首次登录后需要先配置模型。RAGFlow 不内置商业大模型需要你自己接入支持的模型来源OpenAIGPT 系列Azure OpenAIAnthropicClaudeGeminiDeepSeek本地模型Ollama、Xinference、LocalAI 等各种国内模型厂商通过 OpenAI-compatible API 接入配置路径登录后 → 右上角头像 →Model→ 添加模型供应商一个典型的配置需要设置Chat Model对话用如 GPT-4o、Claude 3.5 Sonnet、DeepSeek-V3Embedding Model文本向量化用如 text-embedding-3-small、BGE 系列Rerank Model重排序用如 BGE-Reranker、Cohere RerankEmbedding 和 Rerank 直接影响检索质量建议不要省。三、核心使用流程RAGFlow 的使用遵循一个标准流水线创建知识库Dataset → 上传文件 → 解析/分块Chunking → 创建对话助手Chat/ Agent → 开始问答下面按步骤拆解。四、第一步创建知识库Dataset路径左侧菜单Datasets→Create dataset创建时需要配置几个关键参数参数说明Name知识库名称Embedding Model选择刚才配置的 Embedding 模型Chunk Method分块策略这是 RAGFlow 的核心能力之一分块策略Chunk MethodRAGFlow 提供了多种针对不同文档类型的分块模板分块策略适用场景Naive通用文本按固定长度切分Manual手动切分用户自己定义边界QA问答对格式适合 FAQ 类文档Table表格数据保留行列结构Paper学术论文按章节结构切分Book书籍按目录层级切分Laws法律条文按条款结构切分PresentationPPT/幻灯片按页切分Picture图片用多模态模型理解内容One整篇文档作为一个 chunk为什么分块策略很重要RAG 的效果很大程度上取决于 chunk 的质量。RAGFlow 的 DeepDoc 引擎会基于文档结构标题、段落、表格、图片等做智能分块而不是无脑按字符数切。比如PDF 论文会按标题 → 摘要 → 章节 → 小节的层级保留结构Excel 表格会保留行列语义扫描件会先 OCR 再按版面结构分块选好分块策略后后续上传的文档会自动按这个策略处理。五、第二步上传文件并解析路径进入 Dataset →Files→Upload支持的文件格式文档Word.doc/.docx、PDF、TXT、Markdown表格Excel.xls/.xlsx、CSV幻灯片PPT.ppt/.pptx图片PNG、JPG 等支持 OCR 和多模态理解网页URL结构化数据JSON 等上传后的处理流程上传→ 文件存入 MinIO解析Parsing→ DeepDoc 引擎提取文本、表格、图片分块Chunking→ 按设定的 Chunk Method 切分向量化Embedding→ 每个 chunk 生成向量存入检索引擎→ 默认 Elasticsearch可切换 Infinity人工干预环节RAGFlow 允许你在解析完成后查看和编辑 chunk进入 Dataset → 点击文件 →Chunks可以看到每个 chunk 的内容、来源位置支持手动拆分、合并、编辑 chunk支持给 chunk 打标签这个功能很实在——自动分块不可能 100% 完美尤其是复杂版面的 PDF 和扫描件人工微调能显著提升问答质量。六、第三步创建对话助手Chat路径左侧菜单Chat→Create chat assistant创建对话助手时需要关联一个或多个 Dataset并配置检索策略检索配置参数说明Datasets关联的知识库可多选Rerank Model重排序模型提升检索精度Similarity Threshold相似度阈值低于此值的 chunk 会被过滤Top K每次检索返回多少个 chunk多路召回 融合重排RAGFlow 的检索不是简单的向量相似度搜索而是多路召回同时用多种方式召回候选关键词匹配 向量相似度 全文检索等融合重排用 Rerank 模型对多路结果重新打分排序引用溯源回答中标注引用来源点击可跳转到原始 chunk对话中使用用户公司的报销流程是什么 AI根据《员工手册》第三章第二节报销流程如下[1] 1. 填写报销单... 2. 部门主管审批... 3. 财务审核... [1] 来源员工手册.pdf第 12 页Chunk #5每个回答底部会显示引用的 chunk点击可以查看原文减少幻觉。七、第四步Agent 工作流进阶除了基础的 Chat 问答RAGFlow 还支持Agentic Workflow。路径左侧菜单Agents→Create agentAgent 的核心能力工具调用可以调用外部工具搜索、计算、API 等MCP 支持通过 Model Context Protocol 连接外部服务代码执行内置 Python/JavaScript 代码执行沙箱需 gVisor记忆系统Agent 能记住对话历史和上下文工作流编排通过可视化画布编排多步骤任务Agent 使用场景举例研究报告生成检索多个知识库 → 综合分析 → 生成结构化报告数据查询助手理解自然语言 → 生成查询逻辑 → 调用代码执行器 → 返回结果多源信息整合同时查内部文档 外部网页 数据库 → 综合回答八、Search 模式纯检索不带生成如果你只需要检索相关片段不需要 LLM 生成回答可以用 Search 模式路径左侧菜单Search输入查询后RAGFlow 会返回匹配的 chunks相似度分数来源文档和位置适合用来做文档检索、内容审核、相似度分析等场景。九、团队与权限管理RAGFlow 支持多用户协作Team创建团队邀请成员权限控制不同成员可访问不同的 Dataset 和 Chat对话共享可以将某个 Chat 配置分享给团队成员路径左侧菜单Team十、数据同步连接外部数据源RAGFlow 支持从外部系统自动同步数据Confluence自动拉取 Wiki 内容S3对象存储中的文件Notion笔记页面Discord消息记录Google Drive云端文档网页爬虫指定 URL 自动抓取配置好后数据源更新会自动同步到 RAGFlow 中重新解析。十一、API 集成把 RAGFlow 接入你的应用RAGFlow 提供了 RESTful API可以把对话能力集成到自己的产品里。基础调用流程创建对话会话发送消息→ 流式返回回答获取引用来源Python SDK 示例fromragflow_sdkimportRAGFlow# 初始化ragRAGFlow(api_keyyour-api-key,base_urlhttp://localhost:80)# 获取 Datasetdatasetrag.list_datasets()[0]# 创建对话助手assistantdataset.create_chat_session(name客服助手)# 对话forchunkinassistant.chat(公司的年假政策是什么):print(chunk.content,end)完整的 API 文档参考官方 References 章节。十二、架构与核心组件理解架构对排查问题和性能调优至关重要。RAGFlow 是一个典型的主从分布式架构——前端 API 一组无状态 Worker 一组有状态存储。这一章讲清三件事组件角色分工、两条关键数据流、可替换点。12.1 全局架构分层视图┌──────────────────────────────────────────────────────────────┐ │ 接入层 │ │ Web UI(:80)API Server(:9380)MCP 接入 │ └──────────────────────────────┬───────────────────────────────┘ │ ┌──────────────────────────────▼───────────────────────────────┐ │ 业务层(RAGFlow Core 进程)│ │ ├─ 文档处理 Worker(TaskExecutor)│ │ ├─ 对话 / Agent / Search 引擎 │ │ └─ 代码沙箱(gVisor 隔离, 可选)│ └──────────────────────────────┬───────────────────────────────┘ │ ┌──────────────────────────────▼───────────────────────────────┐ │ 模型层(可插拔, 外部调用)│ │ Chat Model · Embedding Model · Rerank Model · OCR/多模态 │ └──────────────────────────────┬───────────────────────────────┘ │ ┌──────────────────────────────▼───────────────────────────────┐ │ 存储层(Docker Compose 内置)│ │ Elasticsearch ← 向量 全文 倒排索引 │ │ MySQL ← 元数据 / 用户 / Dataset / Chat 配置 │ │ Redis ← 任务队列 / 缓存 / 会话状态 │ │ MinIO ← 原始文件 / 解析中间产物 / 切片图片 │ └──────────────────────────────────────────────────────────────┘12.2 核心组件一览组件角色默认端口资源占用关键日志Web UI(nginx)反向代理 静态资源80极小docker logs docker-ragflow-cpu-1API Server业务中枢对外暴露 RESTful API9380中4-8 GB同上关注/api/v1/...路由TaskExecutor解析、分块、向量化等长任务-吃 CPU / 内存task_executor.logElasticsearch向量 全文 倒排检索9200最吃内存建议 heap ≥ 8 GBelasticsearch.logMySQL元数据3306轻量mysql.logRedis任务队列、缓存、会话6379极轻量redis.logMinIO对象存储9000 / 9001 (控制台)吃磁盘minio.logSandbox (gVisor)Agent 代码执行隔离-可选sandbox.log提示容器名通常是docker-ragflow-cpu-1、docker-ragflow-mysql-1等可用docker ps \| grep ragflow查看。12.3 组件依赖关系ES 启动 → MySQL 启动 → Redis 启动 → MinIO 启动 ↓ API Server 启动 → TaskExecutor 启动 → Web UI(nginx)排查原则先看依赖链上游。在docker compose ps里看到 “Restarting” 的容器先排它前面的依赖。例如 ES 没起好下游所有组件都会反复重启。12.4 两条关键数据流流程 A文件处理流水线从上传到可检索用户上传文件 │ ▼[API Server]接收 → 校验格式 / 大小 │ ▼[MinIO]存原始文件按 dataset_id 分桶 │ ▼[Redis]入队 task: parse_file_id│ ▼[TaskExecutor]取出任务 │ ├─ 调 DeepDoc 做版面分析OCR / 表格识别 / 图片提取 │ ├─ 按 Chunk Method 切分 │ ├─ 调 Embedding 模型生成向量 │ └─ 写入[Elasticsearch]索引每个 chunk 一条 doc含 text vector metadata │ ▼ 更新[MySQL]中文件状态为parsed│ ▼ 前端轮询UI 显示✅ 解析完成排查要点文件卡在 “Parsing…”先看task_executor.logDeepDoc 步骤最慢、最容易 OOM文件解析后搜不到检查 ES 索引中dataset_id是否匹配权限配置是否正确Embedding 超时检查模型 base_url、网络连通性、是否走了代理流程 B查询处理流水线从用户提问到拿到答案用户提问公司年假政策是什么│ ▼[API Server]接收 → 关联 Chat / Agent 配置 │ ▼[Query 预处理]← RAGFlow v0.20 已内置 Query 改写可选开启 │ ▼[Elasticsearch]多路召回 ├─ 向量召回top_k × similarity_threshold 过滤 ├─ 关键词召回BM25 └─ 全文召回可选 │ ▼ 多路结果融合 → 送 Rerank 模型重排 │ ▼[Chat Model]拼装 Prompt系统提示 召回 chunks 用户问题→ 流式输出 │ ▼[API Server]把回答 引用 chunk 列表返回前端 │ ▼ 前端渲染AI 回答 [1][2]底部显示来源 PDF / Page / Chunk排查要点回答慢80% 卡在 LLM 调用看 API Server 响应时间分布答非所问先关掉 LLM 直接看 Search 结果判断是召回质量还是生成环节出问题没引用检查 Chat 配置里是否启用了 Rerank 和引用回传12.5 可替换组件的选型与切换组件默认备选切换建议检索引擎Elasticsearch 8.xInfinity数据量 ≥ 千万级、纯向量为主 → 选 Infinity性能更好、资源占用更低否则 ES 稳定且生态全文档解析DeepDocMinerU / Docling学术论文公式多→ MinerU复杂版式 PDF → Docling通用场景 → DeepDoc 已够用对象存储MinIOAWS S3 / 阿里 OSS / 腾讯 COS生产环境外接 S3 兼容存储更可靠本地开发用 MinIO向量库内嵌在 ES / Infinity-不必单独切ES 本身已是混合检索如何切换检索引擎以 ES → Infinity 为例# 1. 修改 .env# DOCUMENT_ENGINEinfinity# INFINITY_HOSTinfinity# 2. 拉起新组件dockercompose-fdocker-compose.yml up-dinfinity# 3. 重建索引必须数据格式不兼容# 在 Web UI → Dataset → 重建索引# 4. 重启 API Serverdockercompose restart ragflow⚠️重要切换检索引擎后所有知识库必须重建索引——向量字段类型、分片策略、相似度算法都不同无法平滑迁移。12.6 性能调优实战对照表现象优先查的组件命令优化方向文件解析慢、CPU 满载TaskExecutor DeepDocdocker stats升 CPU 核数 / 开 GPU 加速 / 拆分大文件ES 查询慢、内存满Elasticsearchcurl :9200/_cat/nodes?v加 heap (ES_JAVA_OPTS-Xms8g -Xmx8g) / 加节点 / 切 InfinityLLM 回答慢API Server 上游模型看 nginx 响应时间换更快的模型 / 改流式 / 加缓存MinIO 磁盘满MinIOdu -sh /var/lib/docker/volumes/...清理失败解析的中间产物 / 加磁盘 / 切 S3Web UI 加载慢Nginxdocker logs静态资源 CDN 化 / 开启 gzip12.7 扩展点自定义你的 RAGFlowRAGFlow 在三处留了扩展接口不需要改核心代码升级时也不会被覆盖自定义文档解析器在deepdoc/parser下实现注册到task_executor即可自定义 Embedding / Rerank 模型只要符合 OpenAI 兼容 API 规范就能在 Model 配置里加MCP 工具在 Agent 配置里接入外部 MCP Server扩展 Agent 能力生产部署推荐至少补两层HTTPS前置 Nginx/Caddy 监控Grafana Prometheus把上面那张表里的指标都接上。十三、常见问题与调优建议1. 问答质量差经常答非所问排查方向Chunk 质量进入 Dataset → 检查 chunk 是否把关键信息切碎了相似度阈值调低 Top K 或降低 Similarity ThresholdRerank 模型确保配置了 Rerank纯向量检索精度有限文档格式扫描件/图片是否成功 OCR2. 解析速度慢DeepDoc 的 OCR 和版面分析是 CPU 密集型任务建议用 GPU 加速大文件可以拆分成小文件分批上传3. 部署后无法访问检查vm.max_map_count设置检查 Docker 日志确认服务完全启动防火墙是否放行了对应端口十四、写在最后RAGFlow 不是又一个简单的「上传文件 → 向量检索 → LLM 回答」的玩具项目。它在文档解析深度和分块智能度上下了真功夫配合多路召回、重排序、引用溯源确实能在企业复杂文档场景下给出更可靠的回答。加上 Agent 工作流、MCP、代码沙箱和记忆系统它正在从一个 RAG 引擎向一个企业知识处理平台演进。如果你的场景涉及大量非结构化文档合同、论文、手册、报表且对回答的准确性和可追溯性有要求RAGFlow 值得认真评估。GitHubhttps://github.com/infiniflow/ragflow文档https://ragflow.io/docs/dev/云服务https://cloud.ragflow.io