项目三|企业知识库问答:Agentic RAG(检索作为模型的工具)
2024.10 – 2025.05企业交付 本文件是该项目的完整版。主简历只保留 5 条能力点,其余细节、边界与追问预案在此。
一、为什么标签是 Agentic RAG,不是「RAG 全链路」
代码里检索没有预置在链路里,它是模型手里的一个工具:
const agent = createAgent({
tools: [createSearchTool(hybrid, kbId, allowedDocIds, docRepo),
createGraphQueryTool(graph, allowedDocIds)],
systemPrompt: '你是一个知识库问答助手。回答时引用来源。如果信息不足,如实告知用户。',
})src/knowledge/chat/chat.service.ts:117-131
查不查、查几次、要不要顺带查图谱,由模型决定。 这是与 naive RAG(切一次 → 拼上下文 → 回答)的本质区别:
| naive RAG | Agentic RAG(本项目) | |
|---|---|---|
| 检索时机 | 固定,回答前必查 | 模型决定,可不查或多次查 |
| 检索次数 | 1 次 | 视问题复杂度 |
| 查询改写 | 无 / 固定策略 | 模型在工具调用里自己改写 query |
| 检索源选择 | 写死 | 两个工具,模型选 |
| 证据不足时 | 照样生成 | 提示词约束「如实告知」 |
注意:这也解释了为什么这个项目里的「记忆分层」不属于 RAG 考点——它是 Agent 侧的上下文工程。放在这个项目里是因为同一个服务,不是因为它属于检索。
二、完整叙述(主简历已压缩,此处为原稿)
业务背景:企业内部文档(PDF / Office / 纯文本)上传后自动清洗、切块、建索引;员工用自然语言提问,Agent 调检索工具拿证据再作答,答案标注章节来源,可见范围由权限服务给出的文档集合限定。
核心难点:
- 定长切分不可用,且页码在转换环节就没了——定长会把整张表拦腰截断、把一节结论拆进两个块,引用落地即失效;更麻烦的是 PDF 经工具转成 Markdown 后本身不再带页码。解法:自写 Markdown AST 解析 → 按标题层级建 region → 小于 200 token 的小节按层级合并(避免一堆碎块)→ 自适应切分(目标 1200、上限 2000 token),代码块超 100 行按空行切、仍超 50 行再均分而不是按字硬切;每块带章节路径、起止行号、前后块指针与 5 类语义标签(正文 / 代码 / 表格 / 列表 / 提示块),引用落在「哪一节、第几行」,不承诺页码。
- 两路分数量纲不可比——向量路给的是余弦相似度
1 − (<=>),关键词路给的是 ES 原生_score,两者没有共同刻度,加权求和等于用两把尺子量同一根棍子。解法:RRF 按排名融合(K=30,每路各取 20),同一块被两路命中则累加1/(K+rank)并标记来源;单路异常降级为单路而不是整查失败。两路分工明确——关键词补向量对精确字面(专有名词、编号、代码)不敏感的短板,向量补关键词只会字面命中的短板。 - 权限不能在结果上补——先检索再剔除,越权内容已经进过上下文,模型就有机会说出来。解法:可访问文档集合下推成检索期过滤条件——向量路拼进 SQL 的
IN、关键词路拼进 ES 的terms;更关键的是这个集合在创建工具时闭包注入,不出现在工具入参里,模型没有通道去改它。 - 上下文随对话线性膨胀——全量历史喂进去,成本与走神同步上涨。解法:三层记忆——Redis 滑窗存本轮上下文、DB 最近 19 条兜底、超过 14 条触发摘要中间件只保留 6 条;长期记忆另走 Mem0 双层(用户级 / 会话级),写入前由分类器判定该不该记、记在哪一层,不搞「什么都记」。
- 入库是长事务,不能阻塞上传——解析一份 PDF 可能几十秒。解法:任务队列 + 五段可观测流水(抽取 / 切块 / 落库 / 建索引 / 抽实体),每段单独落状态;索引阶段并行提交并用
allSettled收敛,单块失败记进错误列表而不推翻整篇文档,重跑以任务为粒度重入。
核心工作:
- 清洗是责任链而不是一坨正则:6 个清洗器(HTML 标签 / 乱码 / 空白规整 / 页眉页脚 / 噪声模式 / 编码统一)按配置组链,基础链与增强链分开开关,单个清洗器异常不阻塞整条链。
- 图谱不并入默认链路:Neo4j 实体关系查询覆盖窄、代价高,独立成第二个工具由模型按需调用,避免把简单问题复杂化。
- 引用要能落到块:检索结果附带文档标题 / 类型 / 分块数等元信息,按文档 ID 并发取、用
allSettled收敛、失败返回 null——元信息是加分项,不能因为它挂掉整次检索。
项目成果:92 个 TS 模块 / 5820 行;两路召回 + RRF(K=30);pgvector 与 ES 双索引;入库五段流水异步化,索引部分失败不阻塞文档可用。
边界:页码出处实际为空——
pageRef字段链路齐全但入库调用处未传值,恒为 null,能落地的只有章节路径与行号;权限判定源目前是知识库级(userId未参与过滤,文档级 ACL 表待接),下推机制已就位、判定逻辑未接;小区域合并会把并列出现的两节标题拼成一条路径,是已知瑕疵;零测试,检索质量靠抽样人工核对;未上 cross-encoder 重排(延迟预算不够,RRF 已解决量纲问题);扫描件 OCR 未做。
三、主简历压缩版(5 条)
- Agentic 检索:检索不是预置链路,而是模型手里的两个工具——
search_knowledge(混合召回)与query_graph(实体关系)。查不查、查几次、要不要顺带查图谱,由模型按问题复杂度自己决定;证据不足时按提示词如实告知,不硬编。 - 切分保留结构:自写 Markdown AST 解析,按标题层级建 region,小于 200 token 的小节按层级合并,再自适应切到 1200 / 上限 2000 token;代码块超 100 行按空行切、仍超 50 行再均分,不按字硬切。每块带章节路径、起止行号、前后块指针与 5 类语义标签(正文 / 代码 / 表格 / 列表 / 提示块)——引用落在「哪一节、第几行」。
- 两路融合用 RRF:向量路给余弦相似度、关键词路给 ES
_score,两者没有共同刻度,加权求和等于用两把尺子量同一根棍子。改按排名融合(K=30,每路取 20),双路命中累加1/(K+rank)并标记来源;单路异常降级为单路,不让整查失败。 - 权限下推 + 闭包注入:可访问文档集合拼进 SQL 的
IN与 ES 的terms,不是检索完再剔除——后者会让越权内容先进上下文;该集合在创建工具时闭包注入,不出现在工具入参里,模型没有通道去改。 - 记忆分三层,写入要判定:Redis 滑窗存本轮上下文、DB 最近 19 条兜底、超过 14 条触发摘要只留 6 条;长期记忆走 Mem0 双层(用户 / 会话),写入前由分类器判定该不该记、记哪层,不搞「什么都记」。
四、面试追问预案
Q1:Agentic RAG 比普通 RAG 好在哪?成本呢?
好在它能处理「一次检索答不了」的问题——比如需要先查制度再查流程,或者第一轮检索没命中要换个说法再查。普通 RAG 只有一次机会,打不中就编。成本是不确定:模型可能查三次也可能不查,token 消耗和延迟方差都变大。所以这个方案的前提是能接受方差;如果是高并发低延迟场景,固定一次检索 + 好一点的 rerank 更划算。
Q2:那你怎么控制它别查起来没完?
目前靠三点:工具返回带分数,模型能看到哪次召回质量差;系统提示写着「信息不足就如实告知」;以及单次工具返回的正文截断在 2000 字符,避免一次塞爆。没有硬性的轮次上限是一个缺口——真要上生产,得在 agent 层加一个「最多调 N 次检索」的约束。
Q3:RRF 的 K 为什么是 30?
K 决定「排名靠前」的权重差异有多陡。K 小的时候第 1 名和第 5 名差距很大,K 大的时候趋于平缓。30 是常用起点,效果在这个量级的语料上够用,也没做过系统调参——这是经验值,不是调出来的最优值,我不会假装它是。
Q4:为什么不直接加权求和?
因为两路分数量纲不同。向量路是
1 - 余弦距离,值域大概 0~1;ES 的_score是无上界的相关性分。硬加权就是拿两把不同刻度的尺子量同一根棍子,权重只能靠试。RRF 只看排名不看原始分数,天然绕开这个问题——代价是丢掉了「分差信息」,比如两路都是第一名但向量路远超第二名,RRF 看不到。
Q5:权限为什么要闭包注入,不能作为工具参数?
参数是模型写的。如果
allowed_doc_ids是一个工具入参,模型完全可以填一个更宽的集合——它不一定有恶意,可能只是「为了让检索有结果」。所以可访问集合在创建工具时注入、不进 schema。这跟账本精灵里「归属字段不进参数通道」是同一条原则,用了两次。
Q6:权限判定现在是什么状态?
下推机制是完整的——集合进了 SQL 的
IN和 ES 的terms,模型改不了。但判定源还是知识库级:getAllowedDocIds只按kbId查文档、没用到userId,代码里留着 TODO。文档级 ACL 表没接,这是这个项目最实在的一处窟窿,我不会说它已经按部门隔离了。
Q7:引用为什么没有页码?
PDF 是先经工具转成 Markdown 再切块的,Markdown 本身没有页码概念,页码在转换那一步就没了。所以引用落在「章节路径 + 起止行号」。要做页码得换成「按页解析 + 页码随块传递」,那是另一条解析链路,当时没做。不承诺页码,是不想让引用看起来精确、实际是猜的。
Q8:这个项目最弱的地方?
零测试。
src下没有任何 spec 文件,检索质量靠抽样人工核对。所以我能讲清机制,但讲不了「recall 提升了多少」——没建标注集,任何效果数字都是编的。另外小区域合并会把并列出现的两节标题拼成一条路径,这是已知瑕疵。
五、主动承认的边界(不要等被问)
| 边界 | 说明 |
|---|---|
| 页码恒为 null | pageRef 链路齐全但入库调用未传值;PDF→Markdown 本身丢页码 |
| 权限判定是知识库级 | getAllowedDocIds 未用 userId,文档级 ACL 待接;下推机制已就位 |
| 零测试 | 无 spec 文件,无标注集,效果数字不可给 |
| 无检索轮次上限 | Agentic 检索的自由度没有硬约束 |
| 小区域合并瑕疵 | 并列章节的 headingPath 取并集,会拼出假路径 |
| 无 cross-encoder 重排 | 延迟预算不够;RRF 已解决量纲问题 |
| 无 OCR | 扫描件不支持 |
六、数据出处
| 数字 | 出处 |
|---|---|
| 92 个 TS 模块 / 5820 行 | find src -name "*.ts" 计数 |
| Agentic(createAgent + 工具) | chat.service.ts:117-131 |
| RRF K=30 / 每路 20 | hybrid.retriever.ts:19-20 |
| 200 / 1200 / 2000 token | chunker.ts:55-57 |
| 代码块 100 / 50 行 | chunker.ts:58-59 |
| 5 类块类型 | chunker.ts:32 ChunkType |
| 权限闭包注入 | search.tool.ts:45-50 |
IN / terms 下推 | vector.retriever.ts:56-59 / keyword.retriever.ts:43-44 |
| 19 条 / 14 / 6 | chat.service.ts:84 / :127-128 |
| 6 个清洗器 | content-cleaner.service.ts:44-49 |
| 五段流水 | document-worker.service.ts:63-67 |
| 页码未传值 | document-worker.service.ts:86 chunker.chunk(cleanedText) |
| 权限 TODO | document-permissions.service.ts:16-24 |
