From d602b805bdca899e5524e6b5f0c63bd0bb25c351 Mon Sep 17 00:00:00 2001 From: wangle Date: Tue, 7 Apr 2026 21:04:31 +0800 Subject: [PATCH] =?UTF-8?q?docs=EF=BC=9A=E6=9B=B4=E6=96=B0=E6=8A=80?= =?UTF-8?q?=E6=9C=AF=E6=A0=88=E7=89=88=E6=9C=AC=E5=8F=B7=E5=B9=B6=E6=B8=85?= =?UTF-8?q?=E7=90=86=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 更新后端架构版本为 Spring Boot 3.5.8 + Langchain4j - 删除 rag-failures.md 和文件上传接口文档 - 重命名 mcp-api-spec.md 为 MCP工具模块接口文档.md Co-Authored-By: Claude Opus 4.6 --- README.md | 8 +- README_EN.md | 8 +- docs/troubleshooting/rag-failures.md | 352 ------------------ docs/文件上传接口文档.md | 42 --- ...mcp-api-spec.md => MCP工具模块接口文档.md} | 0 5 files changed, 2 insertions(+), 408 deletions(-) delete mode 100644 docs/troubleshooting/rag-failures.md delete mode 100644 docs/文件上传接口文档.md rename ruoyi-modules/ruoyi-chat/docs/{mcp-api-spec.md => MCP工具模块接口文档.md} (100%) diff --git a/README.md b/README.md index e63365d4..e9c7c082 100644 --- a/README.md +++ b/README.md @@ -62,7 +62,7 @@ ## 🛠️ 技术架构 ### 核心框架 -- **后端架构**：Spring Boot 4.0 + Spring ai 2.0 + Langchain4j +- **后端架构**：Spring Boot 3.5.8 + Langchain4j - **数据存储**：MySQL 8.0 + Redis + 向量数据库（Milvus/Weaviate/Qdrant） - **前端技术**：Vue 3 + Vben Admin + element-plus-x - **安全认证**：Sa-Token + JWT 双重保障 @@ -189,12 +189,6 @@ docker-compose -f docker-compose-all.yaml restart [服务名] **👉 [完整使用文档](https://doc.pandarobot.chat)** -遇到知识库或 RAG 回答异常问题？ - -**👉 [RAG 回答异常排查手册](docs/troubleshooting/rag-failures.md)** - ---- - ## 🤝 参与贡献 我们热烈欢迎社区贡献！无论您是资深开发者还是初学者，都可以为项目贡献力量 💪 diff --git a/README_EN.md b/README_EN.md index 5c5c024b..00564414 100644 --- a/README_EN.md +++ b/README_EN.md @@ -65,7 +65,7 @@ ## 🛠️ Technical Architecture ### Core Framework -- **Backend**: Spring Boot 4.0 + Spring AI 2.0 + Langchain4j +- **Backend**: Spring Boot 3.5.8 + Langchain4j - **Data Storage**: MySQL 8.0 + Redis + Vector Databases (Milvus/Weaviate/Qdrant) - **Frontend**: Vue 3 + Vben Admin + element-plus-x - **Security**: Sa-Token + JWT dual-layer security @@ -192,12 +192,6 @@ Want to learn more about installation, deployment, configuration, and secondary **👉 [Complete Documentation](https://doc.pandarobot.chat)** -Experiencing issues with knowledge base or RAG responses? - -**👉 [RAG Troubleshooting Guide](docs/troubleshooting/rag-failures.md)** - ---- - ## 🤝 Contributing We warmly welcome community contributions! Whether you are a seasoned developer or just getting started, you can contribute to the project 💪 diff --git a/docs/troubleshooting/rag-failures.md b/docs/troubleshooting/rag-failures.md deleted file mode 100644 index fdcadefe..00000000 --- a/docs/troubleshooting/rag-failures.md +++ /dev/null @@ -1,352 +0,0 @@ - - -# RAG 常见故障排查（16 问题清单） - -当知识库已经接入，系统也能正常回答，但结果仍然出现命中错误、引用旧内容、推理漂移、跨轮次失忆，或部署后表面可用但实际异常时，最常见的问题不是“模型不行”，而是**不同层的故障被混在一起处理**。 - -这份页面不重新发明一套新方法。 -它直接使用一份固定的 **16 问题清单** 作为排查主轴，让你先把问题标到正确的 **No.X**，再决定下一步查哪里、改哪里，而不是一次性乱改检索、模型、切块、会话和部署配置。 - -这份清单的核心目的只有一个： - -**先把问题放进正确的故障域，再做修复。** - -快速导航： -[这页怎么用](#how-to-use) | [标签说明](#legend) | [常见症状入口](#symptoms) | [16 问题清单](#map16) | [按层排查](#by-layer) | - ---- - - - -## 一、这页怎么用 - -这不是一篇“从头到尾照着做”的传统教程。 -它更像一张固定的 RAG 故障地图，作用是先帮助你**判断故障属于哪一种类型**。 - -建议按下面顺序使用： - -### 1. 先看现象，不要先改配置 - -先回答两个问题： - -1. 你看到的故障，最像哪一种症状 -2. 这个故障更像发生在输入检索层、推理层、状态层，还是部署层 - -在还没判断层级之前，不要先一起改这些东西： - -- 检索条数 -- 切块大小 -- 会话配置 -- 模型参数 -- 部署顺序 -- 依赖服务 - -如果先全部一起动，问题通常只会更难定位。 - -### 2. 先给问题打上 No.X 标签 - -这份页面最重要的动作，不是“立刻修好”，而是先做一件小事： - -**给当前问题贴上最接近的 No.X。** - -例如： - -- 检索结果看起来相似，但其实答非所问，先看 `No.1` 或 `No.5` -- 切块是对的，但结论还是错，先看 `No.2` -- 系统回答很自信，但没有根据，先看 `No.4` -- 刚部署完就炸，先看 `No.14` 到 `No.16` - -### 3. 一次只排一个故障域 - -同一个表面现象，背后可能是不同层的问题。 -例如“答案不对”既可能是： - -- `No.1` 检索漂移 -- `No.2` 理解塌陷 -- `No.4` 自信乱答 -- `No.8` 根本看不到错误路径 - -所以这张表的用法不是“多选全改”，而是： - -**先挑最接近的一项，优先验证这一项是否成立。** - -[返回顶部](#top) | [下一节：标签说明](#legend) - ---- - - - -## 二、标签说明 - -这份 16 问题清单本身已经带有层级 / 标签结构。 -这些标签不是装饰，而是用来帮助你快速判断故障发生在哪一层。 - -### 1. 层级标签 - -- `[IN]`：输入与检索 - 输入、切块、召回、语义匹配、可见性问题 - -- `[RE]`：推理与规划 - 理解、推理、归纳、逻辑链、抽象处理问题 - -- `[ST]`：状态与上下文 - 会话、记忆、上下文连续性、多代理状态问题 - -- `[OP]`：基础设施与部署 - 启动顺序、依赖就绪、部署锁死、预部署状态问题 - -### 2. `{OBS}` 标签 - -带 `{OBS}` 的项，通常都和“**你是否看得见问题是怎么坏掉的**”有关。 -它们往往不是单纯回答错误，而是： - -- 错误路径不可见 -- 漂移过程不可见 -- 状态熔化过程不可见 -- 多代理覆盖过程不可见 - -所以一旦你发现“我知道结果错，但我根本看不到它是怎么错的”，通常就已经很接近 `{OBS}` 类问题了。 - -### 3. 为什么要保留这些标签 - -因为同样叫“答错了”，实际含义完全不同。 - -例如： - -- `[IN]` 的答错，常常是**拿错材料** -- `[RE]` 的答错，常常是**拿对材料但理解错** -- `[ST]` 的答错，常常是**前文断掉、状态漂移** -- `[OP]` 的答错，常常是**系统根本没在完整状态下运行** - -如果不先分层，就会掉进典型的 RAG 地狱： -表面在改答案，实际上在盲修。 - -[返回顶部](#top) | [下一节：常见症状入口](#symptoms) - ---- - - - -## 三、常见症状入口 - -如果你现在还不知道该从哪一项开始，就先从症状入口反查。 - -### 1. 检索返回了错误内容，或看起来相关但其实不回答问题 - -这类问题最常见的是： -“有命中，但命中的不是该用的内容。” - -优先看： - -- [No.1](#no1) `幻觉与切块漂移` -- [No.5](#no5) `语义 ≠ 向量嵌入` -- [No.8](#no8) `调试是一个黑箱` - -### 2. 切块本身是对的，但最终答案还是错的 - -这类问题不是简单没检索到，而是后面那层坏了。 - -优先看： - -- [No.2](#no2) `解释塌陷` -- [No.4](#no4) `虚张声势 / 过度自信` -- [No.6](#no6) `逻辑塌陷与恢复` - -### 3. 多步任务一开始正常，后面越来越偏 - -这类问题通常不是单点错误，而是中途漂移或熔化。 - -优先看： - -- [No.3](#no3) `长推理链` -- [No.6](#no6) `逻辑塌陷与恢复` -- [No.9](#no9) `熵塌陷` - -### 4. 多轮对话后开始失忆，跨轮次接不上 - -这类问题一般已经进入状态层。 - -优先看： - -- [No.7](#no7) `跨会话记忆断裂` -- [No.9](#no9) `熵塌陷` -- [No.13](#no13) `多代理混乱` - -### 5. 遇到抽象、逻辑、规则、符号关系就崩 - -这类问题通常不是检索空，而是推理结构扛不住。 - -优先看： - -- [No.11](#no11) `符号塌陷` -- [No.12](#no12) `哲学递归` - -### 6. 你根本不知道错在哪一层，只知道结果不对 - -这类问题先不要乱调参数。 -先解决“不可见”的问题。 - -优先看： - -- [No.8](#no8) `调试是一个黑箱` - -### 7. 刚部署完最容易炸，首轮调用异常，重启后偶尔恢复 - -这类问题通常不在答案逻辑，而在部署状态。 - -优先看： - -- [No.14](#no14) `引导启动顺序` -- [No.15](#no15) `部署死锁` -- [No.16](#no16) `预部署塌陷` - -[返回顶部](#top) | [下一节：16 问题清单](#map16) - ---- - - - -## 四、16 问题清单（固定主表） - -下面这 16 项按固定顺序使用。 -不要先重组，不要先混类，先判断最接近哪一个 **No.X**。 - -| # | 问题域（含层级/标签） | 会坏在哪里 | -|---|---|---| -| 1 | `[IN] 幻觉与切块漂移 {OBS}` | 检索返回错误/无关内容 | -| 2 | `[RE] 解释塌陷` | 切块是对的，逻辑是错的 | -| 3 | `[RE] 长推理链 {OBS}` | 在多步任务中逐步漂移 | -| 4 | `[RE] 虚张声势 / 过度自信` | 自信但没有根据的回答 | -| 5 | `[IN] 语义 ≠ 向量嵌入 {OBS}` | 余弦匹配 ≠ 真实语义 | -| 6 | `[RE] 逻辑塌陷与恢复 {OBS}` | 走入死胡同，需要受控重置 | -| 7 | `[ST] 跨会话记忆断裂` | 线索丢失，没有连续性 | -| 8 | `[IN] 调试是一个黑箱 {OBS}` | 看不到故障路径 | -| 9 | `[ST] 熵塌陷` | 注意力熔化，输出失去连贯性 | -| 10 | `[RE] 创造力冻结` | 平直、字面化输出 | -| 11 | `[RE] 符号塌陷` | 抽象/逻辑性提示词失效 | -| 12 | `[RE] 哲学递归` | 自我引用循环、悖论陷阱 | -| 13 | `[ST] 多代理混乱 {OBS}` | 代理互相覆盖或使逻辑错位 | -| 14 | `[OP] 引导启动顺序` | 依赖未就绪时服务先启动 | -| 15 | `[OP] 部署死锁` | 基础设施中的循环等待 | -| 16 | `[OP] 预部署塌陷 {OBS}` | 首次调用时版本错配 / 缺少密钥 | - -这张表是主表。 -如果你时间很少，只做一件事也行： - -**先从这 16 项里选出最接近的一项。** - -[返回顶部](#top) | [下一节：按层排查](#by-layer) - ---- - - - -## 五、按层排查：不要改错层 - -这一节不重写 16 项，只是告诉你： -当你已经选到某个 No.X 时，第一眼应该优先查哪一层。 - -### A. `[IN]` 层：先确认你拿到的是不是对的材料 - -对应编号： - -- [No.1](#no1) -- [No.5](#no5) -- [No.8](#no8) - -这层最常见的误判是： - -“我以为系统理解错了，其实它一开始就拿错了东西。” - -如果你命中了弱相关片段、表面相似文本、错误切块，后面推理再强也没用。 -所以 `[IN]` 层优先看的是： - -1. 原始召回内容到底是什么 -2. 命中的片段是否只是“相似”，而不是“正确” -3. 你是否能看到检索过程，还是整个过程像黑箱 - -这层如果没先排好，后面的推理诊断通常会失真。 - -### B. `[RE]` 层：材料可能是对的，但系统用错了 - -对应编号： - -- [No.2](#no2) -- [No.3](#no3) -- [No.4](#no4) -- [No.6](#no6) -- [No.10](#no10) -- [No.11](#no11) -- [No.12](#no12) - -这层最常见的误判是： - -“我以为是检索坏了，其实是后面理解、归纳、逻辑链坏了。” - -例如： - -- 切块是对的，但结论错了 → 常见是 `No.2` -- 多步任务中途开始偏 → 常见是 `No.3` -- 回答很笃定，但完全站不住 → 常见是 `No.4` -- 遇到抽象规则就崩 → 常见是 `No.11` -- 陷入循环解释 → 常见是 `No.12` - -如果 `[IN]` 层已经基本没问题，答案还是不对，就应该优先回到 `[RE]` 层判断是哪一种塌陷。 - -### C. `[ST]` 层：单轮正常，不代表状态层正常 - -对应编号： - -- [No.7](#no7) -- [No.9](#no9) -- [No.13](#no13) - -这层最常见的误判是： - -“单轮看起来还行，所以我以为系统没问题。” - -其实很多 RAG 地狱不是单轮错误，而是： - -- 多轮之后前文断掉 -- 上下文越来越乱 -- 多角色、多代理之间互相覆盖 - -如果你发现： - -- 第一轮没事，后面越来越歪 -- 切换角色后前面的约束消失 -- 多个步骤之间状态彼此污染 - -那就不要再只盯着检索条数了，应该直接回到 `[ST]` 层看 `No.7 / No.9 / No.13`。 - -### D. `[OP]` 层：别把部署问题误诊成回答问题 - -对应编号： - -- [No.14](#no14) -- [No.15](#no15) -- [No.16](#no16) - -这层最常见的误判是： - -“答案不稳定，所以我先去调模型或检索。” - -但如果系统根本没有在完整状态下启动，所有上层表现都会像鬼打墙。 -尤其是这些情况： - -- 依赖还没就绪，服务先起了 → `No.14` -- 多个组件互相等待，长期半可用 → `No.15` -- 首次调用就因为版本、密钥、环境没对齐而塌陷 → `No.16` - -只要你看到“刚部署最容易出事”“首轮异常最严重”“重启后暂时恢复”，就要优先怀疑 `[OP]` 层，而不是先改提示词或参数。 - -[返回顶部](#top) | - ---- - - - - -## 六、快速返回 - -[返回顶部](#top) | [这页怎么用](#how-to-use) | [标签说明](#legend) | [常见症状入口](#symptoms) | [16 问题清单](#map16) | [按层排查](#by-layer) diff --git a/docs/文件上传接口文档.md b/docs/文件上传接口文档.md deleted file mode 100644 index c84a9258..00000000 --- a/docs/文件上传接口文档.md +++ /dev/null @@ -1,42 +0,0 @@ -## 接口信息 - -**接口路径**: `POST /resource/oss/upload` -**请求类型**: `multipart/form-data` -**权限要求**: `system:oss:upload` -**业务类型**: [INSERT] - -### 接口描述 -上传OSS对象存储接口，用于将文件上传到对象存储服务。 - -### 请求参数 -| 参数名 | 类型 | 必填 | 说明 | -| ---- | ------------- | ---- | ------ | -| file | MultipartFile | 是 | 要上传的文件 | - -### 请求头 -- `Content-Type`: `multipart/form-data` - -### 返回值 -返回 `R` 类型，包含以下字段： -| 字段名 | 类型 | 说明 | -| -------- | ------ | ------- | -| url | String | 文件访问URL | -| fileName | String | 原始文件名 | -| ossId | String | 文件ID | - -### 响应示例 -```json -{ - "code": 200, - "msg": "操作成功", - "data": { - "url": "fileid://xxx", - "fileName": "example.jpg", - "ossId": "123" - } -} -``` - - -### 异常情况 -- 当上传文件为空时，返回错误信息："上传文件不能为空" diff --git a/ruoyi-modules/ruoyi-chat/docs/mcp-api-spec.md b/ruoyi-modules/ruoyi-chat/docs/MCP工具模块接口文档.md similarity index 100% rename from ruoyi-modules/ruoyi-chat/docs/mcp-api-spec.md rename to ruoyi-modules/ruoyi-chat/docs/MCP工具模块接口文档.md