PaperFlow 项目进展记录：从 Embedding 落库到知识库 RAG 问答链打通

这段时间我继续推进的重点，不再是“五 Agent 流程能不能跑”，而是把它进一步从“工作流演示”推进成“真正可用的知识引擎”。

如果说前一个阶段解决的是：五 Agent 的职责拆分,Curator / Editor 结果正式入库,个人知识库数据库 paperflowdb 的搭建,那么这一阶段解决的，就是知识库继续往下一层怎么走的问题：

入库之后，知识内容如何变成可向量检索、可语义召回、可支撑问答的知识对象。

围绕这个目标，我这阶段主要做了三件事：

1. 把 Agent 产出的知识卡片真正写入 embedding 层，而不是只停留在 pf_paper 和 pf_paper_chunk。
2. 把历史 embedding 没落库的问题定位出来并修掉，完成数据补偿回填。
3. 把 Sage 从“卡片关键词匹配”升级成“基于 pf_paper_embedding 的知识库 RAG 问答”，并进一步接到 /v1/chat/completions，让 Java 侧普通 AI chat 真正能通过 Python 知识引擎访问知识库。

这意味着 PaperFlow 的知识流转已经从：搜索 -> 审核 -> 编辑 -> 入库继续推进到了：入库 -> chunk 化 -> embedding 化 -> RAG 检索 -> 知识问答

一、为什么这阶段必须先补 Embedding，而不是直接继续做聊天接口

前一阶段我已经把五 Agent 的产出正式沉淀到了数据库里：Curator / Editor 通过的论文进入 pf_paper,Agent 生成的结构化 chunk 写入 pf_paper_chunk,Pathfinder 的学习路径进入 pf_learning_plan,工作流运行记录进入 pf_agent_run

这说明当时系统已经具备了“把论文处理结果转成结构化知识对象”的能力。但是，如果只停在这里，知识库本质上还是一个“结构化内容库”，还不能算真正的“知识检索库”。

原因很直接：Sage 后续如果要做真正的知识问答，就不能只靠：标题关键词命中,摘要字符串重叠和本地卡片拼接，这种方式顶多能做弱检索，做不到真正的语义召回。

尤其是后面如果要支持这些能力，用户自然语言追问，跨论文证据拼接，学习路径中的概念追问

以及Java 外层 AI chat 调知识库，那么知识库中的 chunk 就必须完成向量化，进入可计算、可召回的状态。所以这一阶段的本质目标其实不是“接个 embedding API”，而是把知识库从：存储结构化内容推进到能够真正支撑 RAG 的语义知识库

二、这次先补的是 Agent 输出后的 Embedding 自动写入

这一阶段我在 Python 知识引擎里加入了 embedding 持久化能力，做法包括：新增 EmbeddingClient，在 PaperflowDbService 中注入 embedding client,在 upsert_agent_outputs(...) 完成 pf_paper / pf_paper_chunk 写入后，继续触发 embedding 写入只对 agent-workflow 来源的 chunk 做 embedding,并将结果正式写入 pf_paper_embedding

这样之后，五 Agent 输出的知识对象不再只是“可展示的卡片”，而是会继续变成可语义召回的知识块以及后续 RAG 的证据单元甚至Java 上层 AI chat 可间接访问的知识底座

这里我对知识库结构的理解也更清楚了：

• pf_paper 负责论文级对象
• pf_paper_chunk 负责检索粒度
• pf_paper_embedding 负责语义表示

这个三层结构出来之后，PaperFlow 的知识库才真正开始具备“知识引擎”的基础。

三、Embedding 没落库的问题

这次开发里，真正花时间的部分不是“写 embedding 代码”，而是“把 embedding 为什么没写进去这件事彻底查清楚”。我在服务器上重启 paperflow-knowledge.service 后，重新调用了 /internal/plans/generate，工作流接口返回 200，说明五 Agent 主流程本身是通的。

但是进一步查库后发现：pf_paper_chunk 里已经有 agent-workflow chunk，pf_paper_embedding 还是空的，这说明问题不是工作流没跑，而是 embedding 持久化这一步出了问题。

我检查以后发现接入的 embedding 服务端对单批请求条数有限制，而之前代码没有控制批量大小。所以我把 embedding 批量写入改成最多 10 条一批。

还有一条报错信息是：embedding dim mismatch: expected=1536, actual=1024

这说明数据库 schema 固定用的是 vector(1536)，但当前接入的 Qwen text-embedding-v4 返回的是 1024 维。考虑到当前项目阶段更强调稳定推进，而不是频繁动库，我最后选择了保持 schema 不动，在 embedding 适配层做维度处理，也就是把 1024 维的 embedding 自动补齐到 1536 维，再写入 pf_paper_embedding

四、补写历史 embedding 回填能力

由于我上个阶段先生成了一批chunk，这次写的embedding生成又是紧跟在chunk生成以后的，所以上次生成的chunk就没有对应embedding生成，因此这一阶段我又补了一条内部补偿能力：

/internal/embeddings/backfill

它做的事情是：找出还没有 embedding 的 agent-workflow chunk，按当前 provider / model 重新生成 embedding，补写回 pf_paper_embedding

最终验证结果是：pf_paper_embedding 从 0 增长到 48，agent-workflow chunk 总数也是 48两者已经一一对应

五、Sage能力边界替换

在之前的版本里，Sage 主要做两类问答：

1. PDF 局部问答
   在当前 PDF 的 block 中做关键词匹配

2. 工作流内问答
   在 approved + existing_library 的论文卡片中做文本重叠排序

它没有真正使用 pf_paper_embedding，不适合直接作为 Java AI chat 的知识底座，更像工作流内部的演示节点，而不是正式知识引擎节点

因此这次我新增了 KnowledgeSageAgent，

它的逻辑变成：如果有问题，优先尝试从数据库检索知识 chunk，如果知识库召回成功，就基于这些上下文回答，如果知识库召回失败，再回退到旧的本地卡片匹配逻辑

六、知识库检索混合召回增强

单路向量召回有两个常见问题：结果容易重复以及某些弱 chunk，比如标题或者低价值说明，也可能被错误抬高，所以我在 PaperflowDbService.retrieve_knowledge_chunks(...) 这一层继续做了召回增强。

1. 支持 paper_id 过滤

现在 Sage 的知识库检索支持两种模式：全知识库问答，指定论文范围内问答

这一步很重要，因为后续 Java 前端里肯定会出现两类问答场景：

1. 在知识库全局提问
2. 在某篇论文详情页针对当前论文提问

如果没有 paper_id 过滤，第二类场景就会很难做干净。

2. 改成 embedding + 全文检索双路召回

现在不是只走向量检索，而是同时做：embedding 相似度召回和tsvector 全文检索召回

然后把两路结果融合。这样做的目的，是把两种能力都利用起来：向量检索负责语义相关性，全文检索负责显式关键词命中。这会比纯 embedding 更稳，也比纯关键词更像真正的 RAG 检索器。

3. 做了融合排序

我在融合阶段保留了：embedding_score，text_score，hybrid_score，retrieval_source

这样后面不仅能召回，还能解释“这个 chunk 是怎么被召回上来的”。为了后续调试和答辩都更清楚：如果检索不好用，我可以明确知道问题出在向量召回不准还是全文召回太弱还是融合策略有偏差

4. 加了 MMR 去重

混合召回之后，如果不做去重，很容易出现 topK 全是高度相似的 chunk，比如同一篇论文里的：Title，Abstract，Agent Summary，Teaser

它们共享很多关键词，如果不处理，Sage 最终拿到的上下文虽然数量很多，但信息密度并不高。

所以我又补了一层 MMR，目标就是让召回结果在相关性和多样性之间取得平衡。

5. 加了 chunk 质量加权

在实测中我又发现一个问题：
如果完全依赖相似度排序，Title 有时候会排太高，Curator Notes 这类弱证据也可能混进来。

所以我又加了一层 chunk 质量权重：Abstract / paragraph 加分，Agent Summary / Abstract section 加分，Title 降权，Teaser 轻微降权，Curator Notes 降权，过短内容降权

七、/v1/chat/completions接入知识库 RAG

我把 /v1/chat/completions 的处理逻辑分成两类：

第一类：response_format = json_object

这类请求仍然走 Pathfinder 学习计划生成逻辑。也就是说，学习路径这条线还保留原有职责。

第二类：普通文本问答

这类请求现在不再直接调用一个通用聊天模型，而是：提取最后一条用户问题，进入 five_agent_workflow.answer_knowledge(...)，从 Python 侧知识库做 RAG 检索，返回答案和引用来源。

我们测试整个系统可行性时Java端直接调用API的普通 AI chat，现在变成了通过 Python 知识引擎访问你的个人知识库。

结束语

如果只看“个人知识库 + Embedding + Sage + RAG”这一层，目前已经完成了：

• Agent 输出写入 pf_paper
• Agent chunk 写入 pf_paper_chunk
• Agent workflow embedding 写入 pf_paper_embedding
• 历史 embedding 回填能力
• /internal/rag/qa 基于知识库向量检索回答
• paper_id 范围过滤
• embedding + 全文检索混合召回
• MMR 去重
• chunk 质量加权
• /v1/chat/completions 普通问答接到知识库 RAG

这些能力。