# https://github.com/zstar1003/ragflow-plus 项目说明书 生成时间：2026-07-02 10:35:15 UTC ## 目录 - [项目概览与系统架构](#page-1) - [知识库与文档解析（MinerU 集成）](#page-2) - [后台管理系统与用户/团队/租户体系](#page-3) - [RAG 核心、对话与智能检索（GraphRAG / Agentic）](#page-4) ## 项目概览与系统架构 ### 相关页面 相关主题：[知识库与文档解析（MinerU 集成）](#page-2), [后台管理系统与用户/团队/租户体系](#page-3), [RAG 核心、对话与智能检索（GraphRAG / Agentic）](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/zstar1003/ragflow-plus/blob/main/README.md) - [web/package.json](https://github.com/zstar1003/ragflow-plus/blob/main/web/package.json) - [management/web/package.json](https://github.com/zstar1003/ragflow-plus/blob/main/management/web/package.json) - [management/server/app.py](https://github.com/zstar1003/ragflow-plus/blob/main/management/server/app.py) - [management/web/src/layouts/config.ts](https://github.com/zstar1003/ragflow-plus/blob/main/management/web/src/layouts/config.ts) - [management/web/src/common/constants/cache-key.ts](https://github.com/zstar1003/ragflow-plus/blob/main/management/web/src/common/constants/cache-key.ts) - [management/web/src/common/apis/files/type.ts](https://github.com/zstar1003/ragflow-plus/blob/main/management/web/src/common/apis/files/type.ts) - [management/web/src/common/apis/kbs/type.ts](https://github.com/zstar1003/ragflow-plus/blob/main/management/web/src/common/apis/kbs/type.ts) - [management/web/src/common/composables/useWatermark.ts](https://github.com/zstar1003/ragflow-plus/blob/main/management/web/src/common/composables/useWatermark.ts) - [web/src/pages/api/index.tsx](https://github.com/zstar1003/ragflow-plus/blob/main/web/src/pages/api/index.tsx) - [api/apps/sdk/session.py](https://github.com/zstar1003/ragflow-plus/blob/main/api/apps/sdk/session.py) - [api/apps/sdk/doc.py](https://github.com/zstar1003/ragflow-plus/blob/main/api/apps/sdk/doc.py)
# 项目概览与系统架构 ## 1. 项目定位与诞生背景 `ragflow-plus` 是一个在 [RAGFlow](https://github.com/infiniflow/ragflow) 基础上进行功能增强与界面重构的开源 RAG（检索增强生成）平台。其核心目标是补强开源 RAGFlow 在文档解析、知识库管理、检索排序等方面相对薄弱的体验，并自带一套独立的后台管理系统。资料来源：[README.md:1-30]() 与上游 RAGFlow 相比，`ragflow-plus` 在以下方向上进行了扩展： - 引入 [MinerU](https://github.com/opendatalab/MinerU) 作为高质量 PDF / 扫描件解析器，提供更稳定的版面分析与公式识别（社区问题 #180 即围绕 MinerU + OCR 的文本连贯性展开讨论）。资料来源：[README.md:25-50]() - 新增独立的"管理后台"，用于多租户、用户、文档的统一管控。 - 在 v0.5.0 中新增知识库图像集预览、文档撰写模式图片上传、关键词显性显示与跨语言检索。资料来源：[README.md](release notes v0.5.0)() - 解除了原 RAGFlow 强制要求解析模型输出 1024 维向量的限制，使嵌入模型选择更灵活。资料来源：[README.md](release notes v0.5.0)() 项目的协议沿用上游的 **AGPLv3**，因此在分发、二次开发与商用时必须遵守其全部条款。资料来源：[README.md:90-110]() ## 2. 系统整体架构 `ragflow-plus` 在仓库层面被拆分为多个相对独立的工作区，每个工作区承担一组明确的角色： ```mermaid graph TB subgraph 前端层 A[web 用户端
UmiJS + React] B[management/web 管理后台
Vue 3 + Vite + Element Plus] end subgraph 后端层 C[api
RAGFlow 核心服务
Python Flask] D[management/server
管理后台 API
Python] end subgraph 基础设施 E[(Elasticsearch
向量/全文索引)] F[(MySQL
业务数据)] G[(Redis
缓存/连接池)] H[(对象存储
MinIO/本地)] end A --> C B --> D C --> E C --> F C --> G C --> H D --> F D --> G ``` 下面按层次说明各组件的职责。 ### 2.1 核心 RAG 服务（`api/`） `api/` 目录继承自 RAGFlow，承担 RAG 流水线的主要职责： - **文档解析与分块**：支持 MinerU 等多种解析器，将 PDF/Word/图片等拆分为知识 chunk。资料来源：[api/apps/sdk/doc.py:1-80]() - **检索接口**：提供基于 Elasticsearch 的混合检索（关键词 + 向量 + 重要度），并支持按 `dataset_ids` 检索，返回的 chunk 中包含 `content`、`important_keywords`、`image_id` 等字段。资料来源：[api/apps/sdk/doc.py:120-260]() - **SDK 路由**：包括 `/chunks`（增删改查）、`/retrieval`（检索）等 REST 端点，授权通过 `Authorization: Bearer ` 完成。资料来源：[api/apps/sdk/doc.py:40-110]() - **会话层扩展**：例如 `/chatbots//completions` 之外的扩展能力，会通过调用 LLM 生成"相关搜索词"，辅助用户获得更多检索结果。资料来源：[api/apps/sdk/session.py:1-60]() 社区问题 #255 中"文件解析卡 40%"的故障，主要就发生在该层；通常与解析器任务队列、MinerU 进程或 ES 写入阻塞相关。 ### 2.2 用户端 Web（`web/`） `web/` 是面向最终用户的前端工作区，其技术栈以 UmiJS + React + Ant Design 为主： - 包管理使用 `pnpm@9.15.9`，要求 Node `>=18.20.4`。资料来源：[web/package.json:30-50]() - 路由约定式，页面通过 `src/pages/**` 自动注册，例如 `web/src/pages/api/index.tsx` 用于对外提供 API 服务说明。资料来源：[web/src/pages/api/index.tsx:1-10]() - 集成多种编辑器与图表库（Lexical、Monaco、AntV G/G2/G6 等），满足知识库撰写与图谱展示需求。 ### 2.3 管理后台（`management/`） `management/` 是 `ragflow-plus` 在 RAGFlow 之外新增的后台： - **后端**：`management/server/app.py` 提供用户、租户、文档统计等管理 API。 - **前端**：基于 Vue 3 + Vite + Element Plus，模板继承自 [v3-admin-vite](https://github.com/un-pany/v3-admin-vite)。资料来源：[management/web/package.json:1-25]() - **布局与主题**：`config.ts` 中声明了 `LayoutsConfig`，提供主题切换、标签栏、灰色/色弱模式、水印等开关。资料来源：[management/web/src/layouts/config.ts:1-50]() - **水印**：`useWatermark` 组合式函数可在任意容器上叠加防御型水印，并监听 DOM 变化防止被删除。资料来源：[management/web/src/common/composables/useWatermark.ts:1-70]() - **缓存键**：统一在 `cache-key.ts` 中以 `v3-admin-vite` 命名空间管理 token、布局配置、侧边栏状态等。资料来源：[management/web/src/common/constants/cache-key.ts:1-10]() ### 2.4 共享数据契约（TypeScript 类型） `management/web/src/common/apis/**` 定义了与后端交互的接口契约。例如： | 类型文件 | 关键字段 | 用途 | | --- | --- | --- | | [files/type.ts](https://github.com/zstar1003/ragflow-plus/blob/main/management/web/src/common/apis/files/type.ts) | `id`, `name`, `size`, `type`, `kb_id`, `location` | 文档列表与上传结果 | | [kbs/type.ts](https://github.com/zstar1003/ragflow-plus/blob/main/management/web/src/common/apis/kbs/type.ts) | `FileData`, `PageQuery`, `ApiResponse` | 知识库下的文件分页与通用响应 | 统一类型有利于前后端并行开发，并在 v0.5.0 引入"跨语言检索"等新能力时保持一致的数据流。资料来源：[management/web/src/common/apis/files/type.ts:1-50](), [management/web/src/common/apis/kbs/type.ts:1-40]() ## 3. 典型请求链路 以"用户在管理后台查看某个知识库的文档列表"为例，一次端到端调用大致如下： 1. 用户在 `management/web` 前端打开"知识库 → 文档"页； 2. 前端根据 [management/web/src/common/apis/files/type.ts]() 中的 `PageQuery` 构造请求； 3. 请求经 Vue Axios 转发至 `management/server` 后端； 4. 管理后端代理或查询核心 `api/apps/sdk/doc.py` 中的 `/datasets//documents` 等接口；资料来源：[api/apps/sdk/doc.py:80-130]() 5. `api` 服务在 Elasticsearch 中按 `doc_id` / `run` 状态检索，并使用 `run_mapping`（`0=UNSTART, 1=RUNNING, 2=CANCEL, 3=DONE, 4=FAIL`）转换处理状态；资料来源：[api/apps/sdk/doc.py:140-180]() 6. 结果以 `ApiResponse>` 结构返回前端，前端按 `code` 决定弹窗或渲染列表。 ## 4. 常见故障与社区已知问题 社区近期反馈集中在以下几类： - **连接耗尽 #257**：连续切换账号后出现 `MaxConnectionsExceeded`。通常源于 Redis / MySQL 连接池未按租户复用，建议提升连接池上限或复用会话。资料来源：[community #257]() - **解析卡死 #255**：v0.4.3 在 WSL2 / Docker 下偶发"卡 40%"且无日志落盘，建议检查 MinerU 进程与 ES 队列。资料来源：[community #255]() - **GPU 报错 #254**：GTX 50 系显卡需较新的 CUDA/镜像，文档 [README.md]() 的 GPU 启动章节应作为排查起点。资料来源：[community #254]() - **分块不连贯 #180**：标题与正文被切到不同 chunk，建议调整 chunker 或启用跨 chunk 关联上下文。资料来源：[community #180]() ## See Also - 知识库与文档管理：[管理后台用户指南]() - 文档解析与 MinerU 集成：[解析流水线详解]() - SDK 与检索 API：[API 参考]() - 部署与启动：[Docker Compose 部署指南]() - v0.5.0 版本说明：[Release Notes v0.5.0]() --- ## 知识库与文档解析（MinerU 集成） ### 相关页面 相关主题：[项目概览与系统架构](#page-1), [RAG 核心、对话与智能检索（GraphRAG / Agentic）](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [api/apps/sdk/doc.py](https://github.com/zstar1003/ragflow-plus/blob/main/api/apps/sdk/doc.py) - [api/apps/sdk/session.py](https://github.com/zstar1003/ragflow-plus/blob/main/api/apps/sdk/session.py) - [management/web/src/common/apis/kbs/document.ts](https://github.com/zstar1003/ragflow-plus/blob/main/management/web/src/common/apis/kbs/document.ts) - [management/web/src/common/apis/kbs/type.ts](https://github.com/zstar1003/ragflow-plus/blob/main/management/web/src/common/apis/kbs/type.ts) - [management/web/src/common/apis/files/type.ts](https://github.com/zstar1003/ragflow-plus/blob/main/management/web/src/common/apis/files/type.ts) - [management/web/src/common/apis/files/index.ts](https://github.com/zstar1003/ragflow-plus/blob/main/management/web/src/common/apis/files/index.ts) - [README.md](https://github.com/zstar1003/ragflow-plus/blob/main/README.md)
# 知识库与文档解析（MinerU 集成） ## 概述 `ragflow-plus` 是基于开源项目 [ragflow](https://github.com/infiniflow/ragflow) 构建的增强版 RAG 引擎，在文档解析层面通过集成 [MinerU](https://github.com/opendatalab/MinerU) 提供版面分析与 OCR 能力，从而支持对扫描件、复杂版式 PDF 的高质量抽取 资料来源：[README.md](https://github.com/zstar1003/ragflow-plus/blob/main/README.md)。 系统由三层组成： - **后端服务（Python）**：基于 Flask Blueprint 的 SDK 接口，包含文档、Chunk、检索等路由； - **管理后台（Vue 3 / Vite）**：基于 `v3-admin-vite` 模板，用于知识库、用户、文档的可视化管理； - **用户前台（UmiJS）**：用于聊天问答与文档撰写。 MinerU 在该体系中作为解析阶段的"主力"，结合 BGE 等文本向量模型嵌入，再写入 Elasticsearch 索引进行混合检索 资料来源：[README.md](https://github.com/zstar1003/ragflow-plus/blob/main/README.md)。 ## 文档分块模型与元数据 文档经解析后被切成若干 Chunk，每条 Chunk 在 SDK 接口中体现如下字段： ```yaml Chunk: id: string # Chunk 唯一 ID content: string # 渲染后的正文 content_with_weight: string# 用于向量化的带权正文 important_keywords: list # 重要关键词数组 image_id: string # 关联图像（v0.5.0 起图像集预览） document_id: string # 上属文档 dataset_id: string # 上属知识库 similarity: float # 检索返回时的相似度分数 ``` `content_with_weight` 在更新接口中会同步调用 `rag_tokenizer.tokenize` 与 `fine_grained_tokenize` 重新生成 `content_ltks` 与 `content_sm_ltks`，保证索引字段的一致性 资料来源：[api/apps/sdk/doc.py](https://github.com/zstar1003/ragflow-plus/blob/main/api/apps/sdk/doc.py)。 ## 检索与 Chunk 生命周期 检索入口在 `POST /api/v1/retrieval`，流程如下： ```mermaid flowchart TD A[客户端提交 question] --> B[校验 dataset_ids 与 Authorization] B --> C[KnowledgebaseService.accessible 鉴权] C --> D[聚合各 kb 的 embd_id] D --> E{模型一致?} E -- 否 --> F[返回 DATA_ERROR] E -- 是 --> G[调用 docStoreConn.search] G --> H[返回 chunks 含 similarity] ``` 请求体强制要求 `dataset_ids`（数组）与 `question`，否则分别抛出 `\`dataset_ids\` is required.` 与 `\`question\` not in req.` 错误 资料来源：[api/apps/sdk/doc.py](https://github.com/zstar1003/ragflow-plus/blob/main/api/apps/sdk/doc.py)。 各数据集在检索前会被检查嵌入模型是否一致（去除厂商后缀后比较）；若不一致直接拒绝，避免相似度不可比。该机制正是社区中常被讨论的"不同 chunk 都被判定 100 相似度"问题的源头之一：往往是因为跨库混合检索触发了该一致性校验，又或者因为 Chunk 已经被切得过细，文本向量与问题向量夹角趋同 资料来源：[api/apps/sdk/doc.py](https://github.com/zstar1003/ragflow-plus/blob/main/api/apps/sdk/doc.py)。 ## SDK 关键接口与前端封装 后端 SDK 通过 `@manager.route` 注册的典型接口如下表所示： | 方法 | 路径 | 用途 | 关键参数 | | --- | --- | --- | --- | | POST | `/datasets//documents` | 上传文档 | `file`（multipart） | | GET | `/datasets//documents` | 列出文档 | `page`、`page_size`、`orderby`、`desc` | | POST | `/datasets//documents//chunks` | 新增 Chunk | `content`、`important_keywords` | | PATCH | `.../chunks/` | 更新 Chunk | `content`、`available` | | DELETE | `.../chunks` | 删除 Chunk | `chunk_ids` 数组 | | POST | `/retrieval` | 知识检索 | `dataset_ids`、`question` | 所有接口要求请求头 `Authorization: Bearer `，每个 dataset 都会通过 `KnowledgebaseService.accessible(kb_id=, user_id=)` 进行所有权校验 资料来源：[api/apps/sdk/doc.py](https://github.com/zstar1003/ragflow-plus/blob/main/api/apps/sdk/doc.py)。 前端封装位于 `management/web/src/common/apis/kbs/document.ts`，调用与超时设置如下： - `runDocumentParseApi(id)` —— `POST /documents/{id}/parse`，`timeout: 60000000`（约 1000 分钟，规避大型 PDF/MinerU 长任务被中断）； - `getDocumentChunksApi({ doc_id, currentPage, size })` —— `GET /api/v1/chunks`，可按 `content` 关键字过滤； - 文档状态切换：`PUT /documents/{id}/status`。 接口类型在 `kbs/type.ts` 与 `files/type.ts` 中集中定义，文件名、字节大小、所属 `kb_id`、`location`、创建时间等统一建模，便于上层组件复用 资料来源：[management/web/src/common/apis/kbs/type.ts](https://github.com/zstar1003/ragflow-plus/blob/main/management/web/src/common/apis/kbs/type.ts) [management/web/src/common/apis/files/type.ts](https://github.com/zstar1003/ragflow-plus/blob/main/management/web/src/common/apis/files/type.ts)。 下载文件采用流式 Blob，并通过 `validateStatus: () => true` 让所有 HTTP 状态都进入前端统一处理，避免被 axios 全局拦截吃掉 资料来源：[management/web/src/common/apis/files/index.ts](https://github.com/zstar1003/ragflow-plus/blob/main/management/web/src/common/apis/files/index.ts)。 ## 社区反馈与典型问题 围绕"知识库与文档解析"主题，社区高频讨论包含以下几类： - **Chunk 切分不连贯（#180）**：使用 MinerU + `bge-m3` 时，一个标题与其对应段落被切到不同 Chunk，跨 Chunk 的语义在检索时无法联动；混合排序、关键词相似度、向量相似度均出现 100% 的"伪高分" 资料来源：[社区 Issue #180](https://github.com/zstar1003/ragflow-plus/issues/180)。 - **文件解析卡在 40%（#255）**：常见于 Docker/WSL2 + v0.4.3 环境，无日志落盘，可能与 MinerU 子进程超时、ES 写入阻塞或 `embd_id` 维度不匹配相关 资料来源：[社区 Issue #255](https://github.com/zstar1003/ragflow-plus/issues/255)。 - **GPU 启动失败（#254）**：GTX 5070T 等 50 系较新显卡在拉取镜像时缺少匹配的 CUDA/驱动，需要切换到对应基础镜像 资料来源：[社区 Issue #254](https://github.com/zstar1003/ragflow-plus/issues/254)。 v0.5.0 版本针对该模块做了多项修复与新增能力： - 解除解析模型必须为 1024 维的限制（来自贡献者 @xinsenyan）； - 知识库预览页增加关键词显性显示； - 新增图像集预览，支持为文本块自定义添加/修改关联图像； - 文档撰写模式新增上传图片与公式/表格格式自动化转换； - 修复 PDF 渲染时的 `TypeError`，支持解析进度回传 资料来源：[README.md](https://github.com/zstar1003/ragflow-plus/blob/main/README.md)。 ## 排查指引 1. **解析停滞 / 无日志**：先确认 MinerU 容器健康（`docker logs`），再检查 Elasticsearch 集群状态与磁盘；v0.5.0 后可放宽 embedding 维度限制，可尝试更换模型复测 资料来源：[README.md](https://github.com/zstar1003/ragflow-plus/blob/main/README.md)。 2. **相似度异常**：把混合检索拆为单库检索，确认各知识库 `embd_id` 一致；若仍异常，减小 chunk 切分粒度并启用 `important_keywords` 显式标注 资料来源：[api/apps/sdk/doc.py](https://github.com/zstar1003/ragflow-plus/blob/main/api/apps/sdk/doc.py)。 3. **登录连接耗尽（#257）**：频繁切换账号会在后端复用 MySQL/ES 连接，建议重启服务或调高连接池上限 资料来源：[社区 Issue #257](https://github.com/zstar1003/ragflow-plus/issues/257)。 ## See Also - [README.md](https://github.com/zstar1003/ragflow-plus/blob/main/README.md) - 管理后台 API 类型与封装：`management/web/src/common/apis/` - SDK 检索与文档路由：`api/apps/sdk/doc.py`、`api/apps/sdk/session.py` --- ## 后台管理系统与用户/团队/租户体系 ### 相关页面 相关主题：[项目概览与系统架构](#page-1), [RAG 核心、对话与智能检索（GraphRAG / Agentic）](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [management/server/app.py](https://github.com/zstar1003/ragflow-plus/blob/main/management/server/app.py) - [management/server/routes/users/routes.py](https://github.com/zstar1003/ragflow-plus/blob/main/management/server/routes/users/routes.py) - [management/server/routes/teams/routes.py](https://github.com/zstar1003/ragflow-plus/blob/main/management/server/routes/teams/routes.py) - [management/server/routes/tenants/routes.py](https://github.com/zstar1003/ragflow-plus/blob/main/management/server/routes/tenants/routes.py) - [management/server/routes/conversation/routes.py](https://github.com/zstar1003/ragflow-plus/blob/main/management/server/routes/conversation/routes.py) - [management/server/routes/knowledgebases/routes.py](https://github.com/zstar1003/ragflow-plus/blob/main/management/server/routes/knowledgebases/routes.py) - [management/web/src/layouts/config.ts](https://github.com/zstar1003/ragflow-plus/blob/main/management/web/src/layouts/config.ts) - [management/web/src/common/composables/useWatermark.ts](https://github.com/zstar1003/ragflow-plus/blob/main/management/web/src/common/composables/useWatermark.ts)
# 后台管理系统与用户/团队/租户体系 ## 概述 `ragflow-plus` 的后台管理系统是项目在 RAGFlow 之上扩展的管理平面，由 `management/server/` 目录下的 Python Flask 服务与 `management/web/` 目录下的 Vue3 前端组成。该系统通过路由模块化的方式提供用户、团队、租户、会话、知识库等子域的管理能力，并在前端层提供统一的认证、布局与水印能力。后台管理系统的核心目标是：在保留 RAGFlow 多租户检索能力的同时，为运维人员提供可视化的用户/团队/租户/资源管控面板。 资料来源：[management/server/app.py](https://github.com/zstar1003/ragflow-plus/blob/main/management/server/app.py) ## 系统架构与路由组织 后台服务采用 Flask + 模块化蓝图（Blueprint）模式，按业务域拆分路由。`app.py` 作为入口文件汇总所有子域路由并注册到 Flask 应用对象上，形成“应用 → 蓝图 → 路由”的三层调用链。 ```mermaid flowchart TD A[management/server/app.py
Flask 应用入口] --> B[users Blueprint
用户管理] A --> C[teams Blueprint
团队管理] A --> D[tenants Blueprint
租户管理] A --> E[conversation Blueprint
会话管理] A --> F[knowledgebases Blueprint
知识库管理] B --> G[(用户表)] C --> H[(团队表)] D --> I[(租户/租户-用户关联表)] F --> J[(ES 文档存储)] I --> F G --> I ``` 资料来源：[management/server/app.py](https://github.com/zstar1003/ragflow-plus/blob/main/management/server/app.py)、[management/server/routes/users/routes.py](https://github.com/zstar1003/ragflow-plus/blob/main/management/server/routes/users/routes.py)、[management/server/routes/teams/routes.py](https://github.com/zstar1003/ragflow-plus/blob/main/management/server/routes/teams/routes.py)、[management/server/routes/tenants/routes.py](https://github.com/zstar1003/ragflow-plus/blob/main/management/server/routes/tenants/routes.py) ## 核心业务模块 ### 用户管理 `users/routes.py` 提供用户增删改查、状态切换、密码重置等接口，并通过前端 `management/web/src/common/constants/cache-key.ts` 中定义的 Token Key 与其他模块保持会话一致。社区中关于 *#257 用户前台登录时提示 MaxConnectionsExceeded('Exceeded maximum connections.')* 的问题，本质上反映了在多账号快速切换时连接数被占满，需要在数据库/连接池层配置合理上限并复用连接对象。 资料来源：[management/server/routes/users/routes.py](https://github.com/zstar1003/ragflow-plus/blob/main/management/server/routes/users/routes.py)、[management/web/src/common/constants/cache-key.ts](https://github.com/zstar1003/ragflow-plus/blob/main/management/web/src/common/constants/cache-key.ts) ### 团队管理 `teams/routes.py` 负责团队的创建、成员邀请、角色分配。团队是“用户—租户”之间的中间组织，一支团队可以绑定一个或多个租户，从而以团队为单位共享知识库与会话资源。 资料来源：[management/server/routes/teams/routes.py](https://github.com/zstar1003/ragflow-plus/blob/main/management/server/routes/teams/routes.py) ### 租户管理 `tenants/routes.py` 是整个体系的最上层抽象，决定了数据隔离边界。RAGFlow 检索侧通过 `tenant_id` 进行索引隔离（如 `search.index_name(tenant_id)`），因此租户管理必须保证 `tenant_id` 的全局唯一性与可追溯性。该模块向下对接知识库与会话模块，实现权限与数据隔离。 资料来源：[management/server/routes/tenants/routes.py](https://github.com/zstar1003/ragflow-plus/blob/main/management/server/routes/tenants/routes.py) ### 会话与知识库联动 `conversation/routes.py` 与 `knowledgebases/routes.py` 在租户上下文中运行，会话历史与知识库 Chunk 都以 `tenant_id` 作为隔离键。检索返回时会调用 `settings.docStoreConn.get/get_chunk_list` 等方法，根据租户过滤数据，避免跨租户数据泄露。 资料来源：[management/server/routes/conversation/routes.py](https://github.com/zstar1003/ragflow-plus/blob/main/management/server/routes/conversation/routes.py)、[management/server/routes/knowledgebases/routes.py](https://github.com/zstar1003/ragflow-plus/blob/main/management/server/routes/knowledgebases/routes.py) ## 前端支撑能力 前端基于 `v3-admin-vite` 模板，依赖 `layouts/config.ts` 提供的开关项统一控制 Logo、页脚、水印、主题切换等展示行为；`common/composables/useWatermark.ts` 通过 MutationObserver 防御性监听水印 DOM，确保管理员视角下的页面带有可追溯标识，从而与多租户隔离策略呼应。 | 配置项 | 作用 | 默认值 | | --- | --- | --- | | `showWatermark` | 是否在管理后台启用全屏水印 | `true` | | `showLogo` | 是否显示品牌 Logo | `true` | | `fixedHeader` | 顶部 Header 是否固定 | `true` | | `showThemeSwitch` | 是否显示明暗主题切换 | `true` | 资料来源：[management/web/src/layouts/config.ts](https://github.com/zstar1003/ragflow-plus/blob/main/management/web/src/layouts/config.ts)、[management/web/src/common/composables/useWatermark.ts](https://github.com/zstar1003/ragflow-plus/blob/main/management/web/src/common/composables/useWatermark.ts) ## 常见问题与注意事项 - **多账号切换连接耗尽**（#257）：建议在数据库驱动层配置连接池上限，并在登出时显式释放持久连接。 - **多语言缺失**（#256）：当前用户管理页主要为中文，社区可参照现有 i18n Key 自行扩展英文文案。 - **解析阻塞无日志**（#255）：文件解析任务在 v0.4.3 之后已支持“解析具体进度回传”，升级到 v0.5.0 可在日志中观察到 40% 之后的细分阶段。 ## See Also - 知识库与文档解析流程 - SDK 接口（document / chunk / retrieval） - 前端布局与水印机制 --- ## RAG 核心、对话与智能检索（GraphRAG / Agentic） ### 相关页面 相关主题：[项目概览与系统架构](#page-1), [知识库与文档解析（MinerU 集成）](#page-2)
相关源码文件 以下源码文件用于生成本页说明： - [api/apps/sdk/session.py](https://github.com/zstar1003/ragflow-plus/blob/main/api/apps/sdk/session.py) - [api/apps/sdk/doc.py](https://github.com/zstar1003/ragflow-plus/blob/main/api/apps/sdk/doc.py) - [api/apps/sdk/dataset.py](https://github.com/zstar1003/ragflow-plus/blob/main/api/apps/sdk/dataset.py) - [api/apps/sdk/chat.py](https://github.com/zstar1003/ragflow-plus/blob/main/api/apps/sdk/chat.py) - [sdk/python/ragflow_sdk/__init__.py](https://github.com/zstar1003/ragflow-plus/blob/main/sdk/python/ragflow_sdk/__init__.py) - [sdk/python/ragflow_sdk/modules/dataset.py](https://github.com/zstar1003/ragflow-plus/blob/main/sdk/python/ragflow_sdk/modules/dataset.py) - [README.md](https://github.com/zstar1003/ragflow-plus/blob/main/README.md)
# RAG 核心、对话与智能检索（GraphRAG / Agentic） ## 系统概述与定位 ragflow-plus 是在 [infiniflow/ragflow](https://github.com/infiniflow/ragflow) 之上衍生的增强版 RAG（Retrieval-Augmented Generation）平台，其核心目标是提供可生产化的"知识库 → 分块检索 → 大模型对话"完整流水线。该系统同时配套有后台管理系统 [v3-admin-vite](https://github.com/un-pany/v3-admin-vite) 与文档解析引擎 [MinerU](https://github.com/opendatalab/MinerU)，形成了"前端展示 + 后端 RAG + 解析增强"三层结构。 资料来源：[README.md:1-100]() 从架构上看，RAG 核心由四大组件共同构成：知识库/数据集（Dataset）、文档与分块（Document/Chunk）、聊天助理（Chat/Session）以及检索排序服务（Retrievaler）。其中 `sdk/python/ragflow_sdk/__init__.py` 通过 `beartype` 类型校验统一暴露 `RAGFlow / DataSet / Chat / Session / Document / Chunk` 六个核心对象，构成 Python 客户端的能力面。 资料来源：[sdk/python/ragflow_sdk/__init__.py:1-30]() ## 核心数据模型与会话流程 ### 数据模型 后端 SDK 以 `dataset → document → chunk` 三级嵌套组织检索单元。`sdk/python/ragflow_sdk/modules/dataset.py` 中的 `DataSet` 类持有 `name`、`parser_config`、`pagerank` 等字段，并在初始化时通过 `__init__` 丢弃后端未识别的字段，保证前后端契约的向前兼容。 资料来源：[sdk/python/ragflow_sdk/modules/dataset.py:1-50]() 文档与分块模型则由 `api/apps/sdk/doc.py` 暴露：`Chunk` 对象携带 `content`、`important_keywords`、`questions`、`image_id`、`available`、`positions` 等字段，对应 Elasticsearch 中的 `content_with_weight`、`important_kwd`、`question_kwd`、`img_id`、`available_int` 等索引键，体现出 ragflow-plus 持续重索引并维护显式元数据的设计思路。 资料来源：[api/apps/sdk/doc.py:120-180]()、`[api/apps/sdk/doc.py:240-310]()` ### 对话与会话流 `api/apps/sdk/session.py` 同时承担"搜索词扩展"与"对话补全（completions）"两条主线：前者通过内置提示词让 `chat_mdl` 生成 5–10 个相关检索词，使用 `temperature=0.9` 增加发散性，并通过正则 `^[0-9]\. ` 抽取编号项；后者实现 OpenAI 兼容的 `POST /api/v1/chats_openai//chat/completions`，支持 `stream=True` 的流式响应。 资料来源：[api/apps/sdk/session.py:1-90]()、`[api/apps/sdk/session.py:90-200]()` 请求处理时强制要求 `messages` 至少包含 1 条且最后一条 `role` 必须为 `user`，否则返回 `get_error_data_result`，并在内部将除最后一条外的 `content` 长度计入 `context_token_used`，作为推理消耗统计。资料来源：[api/apps/sdk/session.py:200-260]() ```mermaid flowchart LR A[用户提问 question] --> B[会话 Session] B --> C{检索混合模式} C -->|向量相似度| D[ES docStoreConn 向量索引] C -->|关键词相似度| D D --> E[retrievaler.search] E --> F[Chunk 排序 TopK] F --> G[Chat 模型润色] G --> H[OpenAI 兼容响应 stream] ``` ## 智能检索与跨语言支持 ### 混合检索与排序 `api/apps/sdk/doc.py` 中的检索接口 `/retrieval` 强制要求同一请求内所有数据集必须使用**相同的 embedding 模型**，否则在 `embd_nms` 集合去重失败时直接返回 `DATA_ERROR`，避免向量空间不一致造成的"误命中 100% 相似度"。 资料来源：[api/apps/sdk/doc.py:330-420]()、`[api/apps/sdk/doc.py:420-510]()` ### 跨语言检索（v0.5.0 新增） 社区版本 v0.5.0 显式新增"增加跨语言检索功能"作为官方能力，结合 `embedding_model` 与 `term_weight` 的多语种 token 切分，可在 chunk 与 query 不属于同语种时仍然命中。 资料来源：[README.md:120-180]() ### Prompt 配置与"无答案"行为 `api/apps/sdk/chat.py` 中的 `prompt_config` 通过 `key_list_2` 强制补齐 `system / prologue / parameters / empty_response / quote / tts / refine_multiturn` 的默认值，并对每个 `optional=False` 的参数做"模板占位符 (`{%s}`)"校验，避免运行时 `KeyError`。当检索未命中时，系统会返回默认 `empty_response`，由前端作为"未找到相关知识"的提示。 资料来源：[api/apps/sdk/chat.py:120-200]() ## 已知限制与社区反馈 ### 分块不连贯导致的上下文断裂 社区 Issue #180 反映使用 MinerU + bge-m3 时，标题与正文会被切到不同 chunk，造成检索时三路相似度均"100%"但语义无关。这与 `api/apps/sdk/doc.py` 中 chunk 仅以 `position_int` 维护位置、不强制相邻 chunk 关联的设计相关——目前需要依赖前端"图像集预览"和"关键词显性显示"两个 v0.5.0 新增能力，由用户手工合并相邻 chunk。 资料来源：[api/apps/sdk/doc.py:180-240]()、`[README.md:120-180]() ### 大规模连接耗尽 Issue #257 指出当在同一设备连续创建约十余个账号后登录，会触发 `MaxConnectionsExceeded`。这是 MySQL/ES 连接池上限问题，社区建议在管理端修改连接池配置或重启 `api` 服务。 资料来源：[Issue #257]() ### 文件解析卡 40% 与 GPU 支持 Issue #255（解析卡 40% 且无日志）与 Issue #254（GTX 50 系显卡 GPU 报错）属于 v0.4.x 网盘版本的高发故障，前者多与 MinerU 容器无输出相关，后者多因 PyTorch 与 CUDA 12.x 不兼容；升级到 v0.5.0 后"支持解析的具体进度显示回传"有助于排查前者。 资料来源：[Issue #255]()、[Issue #254]()、`[README.md:120-180]() --- ## See Also - [README.md](https://github.com/zstar1003/ragflow-plus/blob/main/README.md) — 项目总览与最新发布说明 - [api/apps/sdk/doc.py](https://github.com/zstar1003/ragflow-plus/blob/main/api/apps/sdk/doc.py) — 文档/分块/检索 API 完整定义 - [sdk/python/ragflow_sdk](https://github.com/zstar1003/ragflow-plus/tree/main/sdk/python/ragflow_sdk) — 官方 Python 客户端 --- --- ## Doramagic 踩坑日志 项目：zstar1003/ragflow-plus 摘要：发现 23 个潜在踩坑项，其中 14 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Bug]: docker部署报错。 ## 1. 安装坑 · 来源证据：[Bug]: docker部署报错 - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: docker部署报错 - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/zstar1003/ragflow-plus/issues/182 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。 ## 2. 安装坑 · 来源证据：[Question]: 大哥请教一下图片显示这边接口的修改，原来的接口自动添加http和9000只适合IP地址，不适合域名 - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Question]: 大哥请教一下图片显示这边接口的修改，原来的接口自动添加http和9000只适合IP地址，不适合域名 - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/zstar1003/ragflow-plus/issues/185 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 3. 配置坑 · 来源证据：[Question]: is there an English language option for the user management page - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Question]: is there an English language option for the user management page - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/zstar1003/ragflow-plus/issues/256 | 来源类型 github_issue 暴露的待验证使用条件。 ## 4. 配置坑 · 来源证据：[Question]: 怎么修改聊天界面，左上角的图标和Ragflow-plus的标题？ - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Question]: 怎么修改聊天界面，左上角的图标和Ragflow-plus的标题？ - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/zstar1003/ragflow-plus/issues/233 | 来源类型 github_issue 暴露的待验证使用条件。 ## 5. 配置坑 · 来源证据：[Question]: 文件上传问题 - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Question]: 文件上传问题 - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/zstar1003/ragflow-plus/issues/239 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 6. 配置坑 · 来源证据：[Question]: 用户前台登录时提示：MaxConnectionsExceeded('Exceeded maximum connections.') - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Question]: 用户前台登录时提示：MaxConnectionsExceeded('Exceeded maximum connections.') - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/zstar1003/ragflow-plus/issues/257 | 来源类型 github_issue 暴露的待验证使用条件。 ## 7. 配置坑 · 来源证据：[Question]: 管理端显示的嵌入模型和第一个用户配置的嵌入模型不一致 - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Question]: 管理端显示的嵌入模型和第一个用户配置的嵌入模型不一致 - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/zstar1003/ragflow-plus/issues/183 | 来源类型 github_issue 暴露的待验证使用条件。 ## 8. 能力坑 · 来源证据：[Question]: 请问如何通过 db_models.py 新增加 user_tenant_kb 列表。 - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：[Question]: 请问如何通过 db_models.py 新增加 user_tenant_kb 列表。 - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/zstar1003/ragflow-plus/issues/250 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 9. 运行坑 · 来源证据：[Bug]: 文档解析失败：Unknown column 'process_duation' in 'field list' - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：[Bug]: 文档解析失败：Unknown column 'process_duation' in 'field list' - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/zstar1003/ragflow-plus/issues/240 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 10. 安全/权限坑 · 来源证据：[Bug]: 登录ragflow时 一直要求进行身份验证 - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: 登录ragflow时 一直要求进行身份验证 - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/zstar1003/ragflow-plus/issues/238 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。 ## 11. 安全/权限坑 · 来源证据：[Question]: 使用docker启动时候报： authentication required - email must be verified before using account - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Question]: 使用docker启动时候报： authentication required - email must be verified before using account - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/zstar1003/ragflow-plus/issues/245 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。 ## 12. 安全/权限坑 · 来源证据：[Question]: 如何添加 open ai 其他支持的模型呢 - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Question]: 如何添加 open ai 其他支持的模型呢 - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/zstar1003/ragflow-plus/issues/249 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。 ## 13. 安全/权限坑 · 来源证据：[Question]: 添加文档报错 - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Question]: 添加文档报错 - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/zstar1003/ragflow-plus/issues/246 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 14. 安全/权限坑 · 来源证据：团队其他成员无法获取到发起者的知识库和聊天机器人 - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：团队其他成员无法获取到发起者的知识库和聊天机器人 - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/zstar1003/ragflow-plus/issues/243 | 来源类型 github_issue 暴露的待验证使用条件。 ## 15. 身份坑 · 仓库名和安装名不一致 - 严重度：medium - 证据强度：runtime_trace - 发现：仓库名 `ragflow-plus` 与安装入口 `ragflow` 不完全一致。 - 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。 - 复现命令：`pip install ragflow` - 证据：identity.distribution | https://github.com/zstar1003/ragflow-plus | repo=ragflow-plus; install=ragflow ## 16. 能力坑 · 来源证据：[Question]: 向量数据库是否只支持es?如何配置使之支持向量数据库infinity、Milvus？ - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：[Question]: 向量数据库是否只支持es?如何配置使之支持向量数据库infinity、Milvus？ - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/zstar1003/ragflow-plus/issues/237 | 来源类型 github_issue 暴露的待验证使用条件。 ## 17. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://github.com/zstar1003/ragflow-plus | README/documentation is current enough for a first validation pass. ## 18. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://github.com/zstar1003/ragflow-plus | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://github.com/zstar1003/ragflow-plus | no_demo; severity=medium ## 20. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://github.com/zstar1003/ragflow-plus | no_demo; severity=medium ## 21. 安全/权限坑 · 来源证据：[Bug]: 创建和编辑解析模块的时候报错【LookupError('Model(bge-m3) not authorized')】 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: 创建和编辑解析模块的时候报错【LookupError('Model(bge-m3) not authorized')】 - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/zstar1003/ragflow-plus/issues/184 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 22. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://github.com/zstar1003/ragflow-plus | issue_or_pr_quality=unknown ## 23. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://github.com/zstar1003/ragflow-plus | release_recency=unknown