Redis on XEDCZQ的博客

MapAI：RAG 1.0 系统架构与痛点复盘

Wed, 27 May 2026 15:46:26 +0800

MapAI：RAG 1.0 系统架构与痛点复盘

这篇笔记整理我在 MapAI 早期版本里实现的一套 RAG 1.0 架构。它已经具备了完整的上传、清洗、切片、向量化、检索和问答闭环，但从今天回头看，很多设计还是明显带着“先跑起来”的 1.0 痕迹。

这份复盘的重点不是讲一个完美方案，而是把老版本真实的构造流程、运行方式和后续暴露出来的问题讲清楚，方便后面继续演进到更稳的 RAG 2.0。

RAG 1.0 总览

整个系统可以分成两条主链路：

数据入库链路：负责把用户上传的原始文件清洗、切片并写入向量库。
检索推理链路：负责在用户提问时召回相关 Chunk，并交给大模型做最终回答。

对应到接口层，分别是：

POST /api/rag/upload
POST /api/rag/chat

数据流管道

当用户调用 POST /api/rag/upload 上传文件时，系统会依次经过下面 5 步完成处理：

[文件上传]
 -> 1. SHA-256 去重
 -> 2. Apache Tika 文本提取
 -> 3. 动态语义分片
 -> 4. DashScope 向量化
 -> 5. Redis 持久化

SHA-256 去重

系统会先计算文件哈希值，在同一个知识库 KB 内实现秒传与去重。

这样做的目标很直接：

避免同一份文件被重复写入。
节省 Redis 存储空间和向量化成本。
降低重复 Chunk 对检索排序造成的噪声。

这一步本质上是“知识库内去重”，而不是全局跨库去重，所以它能保证当前 KB 里的数据相对干净，但也意味着多个 KB 之间仍可能保留相同内容。

文本提取

原始文件上传后，系统使用 Apache Tika 做统一文本解析，把不同格式的文件都转成纯文本 String。

当时支持的主要格式包括：

PDF
DOCX
MD
TXT
CSV
XLSX
JSON

这个设计的好处是前面统一输入，后面的切片和 Embedding 都只面对字符串，不需要对每种文档格式分别写检索逻辑。

代价也很明显：一旦进入纯文本阶段，很多原始结构信息就丢了，比如表格、标题层级、字段列关系和单元格边界。

动态语义分片

RAG 1.0 的切片策略已经不是最原始的固定长度截断，但本质仍然属于“规则驱动的半语义切片”。

核心参数：

minSize = 180
targetSize = 700
maxSize = 1000

切分优先级：

优先按双换行拆段落：\n\s*\n+
如果段落仍然过长，再按结束标点拆句子：。！？；;.!?
如果还拆不开，就按 maxSize 硬切

组装逻辑：

累积文本达到 targetSize 后，输出为一个独立 Chunk。
如果尾部碎片小于 minSize，则强行并到上一个 Chunk，尽量保证语义完整。

这套方案在 1.0 阶段已经比“纯 500 字一刀切”强不少，因为它至少知道先看段落和句子边界，但它仍然不是严格意义上的语义切片。

向量化与写入

每个切好的文本块最终会被封装为统一的 Document 结构：

Document {
 id(UUID),
 text,
 metadata: {
 kb_name,
 file_name,
 chunk_index
 }
}

Embedding 模型使用的是阿里云 DashScope，把文本转换成稠密向量后写入 Redis 向量索引：

rag_vector_index_v1

这一层本质是一次 Vector Upsert，完成后系统就具备了按向量相似度检索 Chunk 的能力。

Redis 持久化设计

除了向量索引本身，RAG 1.0 还在 Redis 中额外保留了一套辅助元数据，方便文件管理和关键词兜底。

文件列表：

rag:kb:{kbName}:files

这里通常用 Hash 结构，保存文件名和基础属性映射。

原始全文：

rag:kb:{kbName}:file:{base64}:text

这里通常用 String 结构，保留该文件的完整纯文本内容，用于后续兜底搜索。

Chunk 索引：

rag:kb:{kbName}:file:{base64}:chunks

这里通常用 Set 结构，保存该文件下所有 Chunk ID。

这种设计的好处是简单、直接、落地快。缺点是索引和元数据结构开始变多以后，后期维护成本会上升，而且 Redis 同时承担“向量库 + 文件目录 + 原文仓库”三种角色，边界不够清晰。

检索与推理管道

当用户调用 POST /api/rag/chat 进行对话时，请求会先经过检索层，再进入生成层。

可以粗略拆成两段：

阶段 A：检索与过滤，主要由 KnowledgeBaseService 负责
阶段 B：上下文组装与推理，主要由 RagChatService 负责

阶段 A：检索与过滤

过采样计算

为了降低多知识库混查时目标数据被稀释的风险，系统不会直接只取 topK 条结果，而是先放大召回范围：

$$ \text{fetchK} = \text{clamp}(\text{topK} \times 30, 60, 200) $$

也就是：

最少取 60
最多取 200
中间按 topK * 30 放大

这个思路本身是对的，它相当于承认“第一次粗召回不够准”，所以先多捞一点数据回来再做过滤。

多租户隔离过滤

RAG 1.0 的多知识库隔离不是在向量搜索阶段完成的，而是在向量搜索之后做“后置过滤”。

流程大致是：

先从 Redis Set 里取当前 KB 的合法 allowedIds
再执行向量库 similaritySearch
最后对结果做双重保险过滤，并截断到 topK

过滤逻辑可以写成：

$$ \text{Filter: } \text{id} \in \text{allowedIds} \lor \text{meta.kb\_name} == \text{kbName} $$

最后再执行：

limit(topK)

这一步保证了逻辑上的多租户隔离，但因为它是“检索后过滤”，所以当全局数据规模变大时，会出现明显的稀疏化问题。

关键词兜底

如果向量检索结果为空，系统不会直接返回“查不到”，而是退化成原文扫描。

具体做法是：

从 Redis 里的原始全文读取文本
做大小写不敏感的子串匹配
命中后返回相关内容作为兜底结果

这一步的价值主要在于：

防止冷启动时 Embedding 质量不稳定
防止专有名词、缩写或新词没有被向量很好表示
至少让系统在“完全搜不到”的情况下还能给一个兜底结果

但它本质上还是非常弱的字符串匹配，能力上和真正的信息检索差得很远。

阶段 B：上下文组装与推理

上下文拼接

在检索阶段拿到 docs[] 后，系统会把这些召回文本拼接成 context，再注入最终提示词。

这一步是典型的 RAG prompt 组装逻辑：

检索层负责找到候选证据
Prompt 层负责把证据组织给大模型
大模型在此基础上完成回答

LLM 裁判任务

RAG 1.0 的提示词里，大模型不只是回答问题，还被要求扮演一个“情报查询问答节点”。

它需要同时承担三件事：

做相关性校验
基于已给出的知识库内容作答
拦截幻觉和无依据扩写

这意味着同一次调用里，LLM 既是生成器，又承担了一部分检索判断职责。

结构化输出

为了让后端更稳定地消费结果，系统会约束大模型输出固定 JSON，再由后端解析后返回给用户：

{
 "related": true,
 "reply": "大模型基于知识库给出的回答...",
 "reason": "判断相关或不相关的逻辑解释"
}

这个设计在工程上很实用，因为后端不需要再从一大段自然语言中猜测模型到底是“拒答”还是“回答成功”。

RAG 1.0 的核心痛点

RAG 1.0 最大的问题不是“完全不能用”，而是它虽然把流程跑通了，但很多关键环节都还是 1.0 的折中方案。一旦文档规模、知识库数量或问题复杂度上去，问题就会集中暴露。

痛点 1：分片策略仍然机械化

现状：

虽然切片时已经考虑段落和标点
但本质仍然是围绕 700 / 1000 字目标做规则凑字数
Chunk 之间没有 Overlap

后果：

物理边界上的上下句容易被切断
参数表、说明表、列表型内容可能被一分为二
上下文连续性不够，影响后续召回和回答质量

后续方向：

改成真正的 Semantic Chunking
或至少引入 10% ~ 15% 的滚动窗口重叠区

痛点 2：全局向量搜索 + 后置过滤

现状：

系统先在全量索引里搜索
再用当前 KB 的合法 ID 集合做后置过滤

后果：

当总知识库规模变大时，fetchK 即使放大到 200
也可能先被其他知识库的高相似内容占满
最后过滤完之后，当前 KB 的有效结果几乎没有，甚至直接搜空

这本质上就是“目标知识被全局噪声稀释”。

后续方向：

改成 Pre-Filtering
在向量检索阶段就基于 kb_name 或其他元数据做过滤
把相似度计算范围直接收缩到当前知识库内部

痛点 3：关键词兜底过弱

现状：

向量检索失败后，只能退化成大小写不敏感的原文子串匹配

后果：

不能处理同义词
不能处理缩写
不能处理近义表达
专有术语换一种说法后就直接未命中

比如：

文档里写的是 DDG
用户问的是“驱逐舰”

这类场景下，子串匹配基本没有任何容错能力。

后续方向：

引入 BM25
或构建倒排索引 Inverted Index
配合中文分词器，做真正的 Hybrid Search

痛点 4：缺少重排机制

现状：

向量库返回结果后，只依据 Embedding 相似度粗排
粗排结果直接塞给 LLM

后果：

前几个 Chunk 可能带有较多低相关噪声
真正包含标准答案的 Chunk 可能被挤到后面
一旦上下文窗口有限，LLM 很容易“迷失在中间”

后续方向：

在检索后增加 Reranker
比如 BGE-Reranker
对候选结果做二次精排
再结合分数阈值做动态截断

痛点 5：LLM 既当运动员又当裁判

现状：

单次调用里，LLM 同时做“相关性判断”和“答案生成”

后果：

只要检索结果“不够完美但有点相关”
LLM 就可能直接判定 related: false
结果是部分可用信息被浪费，系统容错率很低

后续方向：

把相关性判断前置到检索阶段
由 Reranker 或轻量分类模型做相关性过滤
让大模型专注于信息整合和自然语言生成

痛点 6：固定切片参数 + 缺乏评估体系

现状：

不区分文档类型，统一用一套切片参数
参数密集的表格、叙事文档、结构化 JSON 被同样处理
同时没有标准召回评估

后果：

短文档或高密度文档容易被切坏
系统效果无法量化
后续优化变成“靠感觉调参”

后续方向：

针对不同文件类型使用差异化切片策略
表格类文档采用结构化切片
建立标准问题对 Ground Truth
评估 Recall@10、MRR 等指标

从今天回看 RAG 1.0

如果用一句话概括这套老版架构，我会说：

它已经完成了“能上传、能检索、能回答”的最小闭环，但很多关键模块仍停留在规则驱动、后置修补和弱评估阶段。

RAG 1.0 最宝贵的价值，不是它有多先进，而是它把问题暴露得足够具体：

切片为什么会影响召回
全局搜索为什么会造成稀疏化
为什么不能只靠向量检索兜底一切
为什么 LLM 不能既做检索判断又做最终回答
为什么没有评估体系的优化几乎等于盲调

这些坑踩出来之后，后面的 RAG 2.0 才会更有方向。

小结

MapAI 的 RAG 1.0 已经具备了完整的数据入库和问答链路：上传文件后完成去重、解析、切片、向量化和 Redis 持久化；用户提问时完成召回、过滤、上下文组装和 JSON 化回答。

但它的核心问题也很清楚：切片不够语义化、检索过滤顺序不合理、兜底检索太弱、缺少重排、LLM 职责过重、效果无法量化。对一个 1.0 系统来说，这其实很正常。真正重要的是把问题讲清楚，然后让下一版架构不再重复这些老坑。

Web 登录验证码规范：从老后台排查到 Redis 一次性校验

Sat, 20 Jun 2026 00:00:00 +0800

Web 登录验证码规范：从老后台排查到 Redis 一次性校验

这篇笔记记录我最近围绕 Web 管理端登录验证码做的一次完整排查和改造。事情的起点很简单：我想确认老服务器上的后台验证码到底是不是“真的在校验”，以及新版 web_3 应该把验证码流程收敛成什么样，才算一套真正完整的登录安全链路。

这次我主要做了三件事：

排查老服务器 yzdwx.yizhoudao.net/admin/ 的验证码真实逻辑
确认老 Web 是否真的启用了 Redis
在本地 web_3 里把管理端验证码改成“后端生成 + Redis 存储 + 后端一次性校验”

最后的结论也很明确：老后台页面上虽然有验证码，但登录流程里没有真正校验它；新版 web_3 已经改成标准的 Redis 验证码闭环。

我为什么要单独整理这篇笔记

验证码这种东西很容易出现一种假安全状态：页面上明明有输入框，也有验证码图片，前端看起来一切都在，但真正决定安全性的不是页面上有没有控件，而是后端登录逻辑到底有没有做验证，以及验证结果有没有被一次性消费。

这次排查让我更确定一件事：登录验证码必须按“生成、存储、提交、校验、销毁”这五步闭环来设计，缺任何一步都不算真正落地。

老服务器后台验证码的真实逻辑

这次我先通过 SSH 登录老服务器，只做了只读排查，没有改线上代码，也没有重启服务。

我定位到的站点信息是：

域名 yzdwx.yizhoudao.net 对应站点目录：/www/wwwroot/yzdwx5.weitaibei.com/public_html
应用入口：/www/wwwroot/yzdwx5.weitaibei.com/public_html/index.php
实际业务代码目录：/www/wwwroot/yzdwx5.weitaibei.com/system/application

接着我去看后台登录页模板，确认页面上确实有验证码输入框和验证码图片。页面会请求：

/captcha

点击刷新时会请求：

/captcha?random=...

这个路由最终来自 ThinkPHP 的验证码包。继续往下追，我确认到：

验证码图片确实是后端生成的
验证码答案会写入 Session
不是写在前端，也不是直接写入 Redis

更关键的是，我继续追到后台登录控制器之后发现，老后台登录方法虽然接收了 $verify 参数，但实际逻辑里只做了这些事：

用户名判空
密码判空
调用 rbaclogin(...)

我没有看到任何真正的验证码校验逻辑，比如：

captcha_check($verify)
validate(...captcha...)
手动对比验证码答案

所以老服务器后台验证码的真实情况其实是：

页面上有验证码
后端也会生成验证码图片
验证码答案保存在 session
但登录业务流程里没有真正校验它

这意味着老版本后台的验证码大概率属于一种“界面还在，但校验已经失效或被漏掉”的状态。

我是怎么确认这件事的

这次排查不是靠猜，也不是只看前端页面，而是按一条比较稳的链路逐步确认的。

我先确认 SSH 和站点目录：

先通过本机 SSH 别名连到服务器
查 Nginx 配置，确认 yzdwx.yizhoudao.net 实际指向哪个目录
查 PHP-FPM 和 Nginx 运行状态

然后我再往应用层追：

找后台登录模板
找 /captcha 路由来源
找验证码生成逻辑
找验证码校验逻辑

最后我再去看后台登录控制器：

看 login() 方法是否真正调用了验证码校验
结果是没有

这个顺序的好处是不会被页面表现误导。只要登录控制器里没有执行验证码校验，那页面上验证码画得再完整，也只是“视觉存在”，不是“安全生效”。

老 Web 到底有没有用 Redis

这部分我也专门确认了一遍，因为很多项目都会出现一种情况：代码里带着 Redis 封装类，但线上根本没启用。

这次我的结论是：

代码仓里确实有 Redis 工具类
但线上这套老 Web 没查到业务代码实际调用它
服务器本身也没发现 Redis 服务在运行

我当时主要查了几类证据：

ThinkPHP 的 session 配置
PHP 的 session.save_handler
/tmp 下是否存在大量 sess_* 文件
服务器上是否有 redis-server
是否有 redis-cli
是否监听了 6379

最终确认到的事实是：

Session 默认驱动不是 Redis
PHP 当前会话处理器是 files
/tmp 下确实存在大量 sess_* 文件
服务器上没发现 Redis 进程
没发现 6379 监听
也没发现 Redis 二进制

所以更准确的说法不是“老项目完全没有 Redis”，而是：

老项目带过 Redis 封装代码，但当前运行中的老站没有实际启用 Redis，后台验证码也不在 Redis 里。

老版本验证码的问题到底出在哪

如果用一句话概括老后台的问题，我会说：

它的问题不是“验证码生成失败”，而是“验证码没有进入真正的登录校验链路”。

也就是说，旧系统表面上像是有验证码防护，但真正的登录安全流程里并没有用到它。这个问题比“没有验证码”更隐蔽，因为产品、测试甚至开发自己都可能先被页面骗过去。

从规范角度看，老版本至少有两个明显缺口：

验证码答案存进了 Session，但登录接口没有校验
验证码不是一次性消费，即使以后补校验，也容易留下复用问题

我在本地 web_3 改成了什么逻辑

确认完老系统问题之后，我在本地 web_3 管理端把验证码流程改成了完整的后端闭环。

现在的流程是：

前端请求 GET /api/admin/login/captcha
后端生成： captchaId 4 位验证码 Base64 PNG 图片
后端把验证码答案写入 Redis
前端只展示图片，同时保留 captchaId
用户登录时，前端提交： username userpwd captchaId captchaCode
后端先去 Redis 校验验证码
校验时使用 getAndDelete
读取成功后立即删除

这个设计意味着一个验证码只有一次尝试机会。

无论最终登录成功还是失败，这个验证码都会失效，不会继续留在系统里被重复提交。

新版验证码链路的核心规范

结合这次改造，我把 Web 登录验证码应该遵守的规范总结成下面这几条。

规范 1：验证码必须由后端生成

验证码图片、验证码答案和 captchaId 都必须由后端统一生成。前端只负责展示，不参与答案生成，也不保存正确答案。

这样可以避免前端暴露正确结果，保证校验基准只存在于服务端。

规范 2：验证码答案必须保存在短期存储中

这次我选的是 Redis。它很适合这种短时、一次性、低价值但安全敏感的数据。

相比 session/file，Redis 更适合后续扩展：

可以设置 TTL
可以做原子删除
可以支持多机共享
可以承接登录风控类临时状态

规范 3：登录接口必须在鉴权前先校验验证码

验证码校验不能放在一个“看起来有，但不影响主流程”的边缘位置。它必须在用户名密码真正进入登录鉴权前完成。

也就是说，顺序应该是：

先校验验证码
再校验账号密码
最后建立登录态

如果验证码失败，后面的账号密码逻辑就不应该继续执行。

规范 4：验证码必须一次性消费

这次我专门用了 getAndDelete 这种读取即删除的方式，目的是确保验证码永远只能用一次。

这个约束非常重要，因为如果验证码校验通过后不立刻销毁，就可能出现：

同一验证码被重复利用
自动化脚本反复撞同一个验证码
失败重试时复用旧验证码

一次性消费是验证码机制真正生效的关键之一。

规范 5：成功和失败都要失效

很多人只会在“登录成功”时删验证码，但这其实还不够。

更稳的做法是：

校验成功后立即删除
校验失败也要删除

因为验证码本来就是一次挑战，不应该允许用户拿着同一个 captchaId 连续试很多次。

这次改成 Redis 后，我认为最实际的好处

这次改造给我的直接感受，不是“技术更高级了”，而是整个登录安全链路终于闭合了。

主要好处有这些：

逻辑闭环完整

老版本是“有验证码页面，但登录不校验”。

现在变成了：

后端生成
后端存储
前端展示
后端校验
一次性消费

这才是一条完整的安全链路。

不再依赖本地 session 文件

老站的验证码答案实际落在 session/file 和 /tmp sess_* 上。

这套方案虽然在单机环境里能跑，但它天然更偏运行时实现，不够适合后续扩展。Redis 对这类短期临时数据更合适，也更容易观察和控制。

一次性验证码更自然

Redis 很适合实现这种需求：

TTL 过期
getAndDelete
成功失败都删除

这些语义在验证码场景里非常自然，不需要绕很多额外逻辑。

多机部署更友好

如果以后不是单机，而是多台 Web 共同处理请求，那么 session/file 很容易出现跨机器不一致问题。

Redis 作为共享存储，可以让所有 Web 节点读到同一份验证码状态，这对后续扩容非常关键。

后续风控能力更容易接上

验证码逻辑进入 Redis 之后，很多安全相关能力也更容易继续往上加，比如：

短信验证码
登录失败次数限制
风控计数
临时 token
AI/RAG 相关短期缓存

从工程上看，这相当于把“登录临时态”统一收进了一个更适合治理的位置。

这次我顺手做的配套工作

为了让新版 web_3 本地链路真正跑通，这次我还顺手处理了几项配套问题：

本地临时启动了一个 Redis，监听 127.0.0.1:6379
修了 backend-java 启动时的 YAML 配置问题
清理了后端端口占用
把管理端前端改成支持局域网访问，监听 0.0.0.0:9511
调整了登录页移动端和窄屏适配

这些改动虽然不是验证码主逻辑，但它们决定了整个方案能不能从“代码写好了”真正走到“本地完整跑通”。

我最后得出的规范结论

这次排查和改造之后，我对 Web 登录验证码的规范要求基本固定成下面这套：

验证码必须由后端生成
验证码答案必须只保存在后端
前端只展示图片和提交 captchaId
登录接口必须先校验验证码，再校验账号密码
验证码必须一次性消费
成功失败都必须失效
短期验证码优先放 Redis，而不是依赖本地 session 文件

如果少了其中任何一条，我都不会认为这套验证码是真正“规范落地”的。

小结

一句话总结这次工作：

老服务器后台验证码是 ThinkPHP 后端生成、保存到 Session，但后台登录代码里没有真正校验它；老服务器当前也没有实际运行 Redis。新版 web_3 则已经改成标准的 Redis 验证码流程：后端生成、Redis 保存、前端展示、后端校验、一次性消费、成功失败都删除。

对我来说，这次最重要的收获不是“把验证码改成 Redis”这么简单，而是把验证码这件事从“页面上看起来有”推进到了“后端链路真正闭环”。只有做到这一点，验证码才不是装饰，而是登录安全的一部分。