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

这段时间我继续推进的重点不再是“五 Agent 流程能不能跑”而是把它进一步从“工作流演示”推进成“真正可用的知识引擎”。如果说前一个阶段解决的是五 Agent 的职责拆分,Curator / Editor 结果正式入库,个人知识库数据库 paperflowdb 的搭建,那么这一阶段解决的就是知识库继续往下一层怎么走的问题入库之后知识内容如何变成可向量检索、可语义召回、可支撑问答的知识对象。围绕这个目标我这阶段主要做了三件事把 Agent 产出的知识卡片真正写入 embedding 层而不是只停留在 pf_paper 和 pf_paper_chunk。把历史 embedding 没落库的问题定位出来并修掉完成数据补偿回填。把 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 chunkpf_paper_embedding 还是空的这说明问题不是工作流没跑而是 embedding 持久化这一步出了问题。我检查以后发现接入的 embedding 服务端对单批请求条数有限制而之前代码没有控制批量大小。所以我把 embedding 批量写入改成最多 10 条一批。还有一条报错信息是embedding dim mismatch: expected1536, actual1024这说明数据库 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 增长到 48agent-workflow chunk 总数也是 48两者已经一一对应五、Sage能力边界替换在之前的版本里Sage 主要做两类问答PDF 局部问答在当前 PDF 的 block 中做关键词匹配工作流内问答在 approved existing_library 的论文卡片中做文本重叠排序它没有真正使用 pf_paper_embedding不适合直接作为 Java AI chat 的知识底座更像工作流内部的演示节点而不是正式知识引擎节点因此这次我新增了 KnowledgeSageAgent它的逻辑变成如果有问题优先尝试从数据库检索知识 chunk如果知识库召回成功就基于这些上下文回答如果知识库召回失败再回退到旧的本地卡片匹配逻辑六、知识库检索混合召回增强单路向量召回有两个常见问题结果容易重复以及某些弱 chunk比如标题或者低价值说明也可能被错误抬高所以我在 PaperflowDbService.retrieve_knowledge_chunks(...) 这一层继续做了召回增强。1. 支持 paper_id 过滤现在 Sage 的知识库检索支持两种模式全知识库问答指定论文范围内问答这一步很重要因为后续 Java 前端里肯定会出现两类问答场景在知识库全局提问在某篇论文详情页针对当前论文提问如果没有 paper_id 过滤第二类场景就会很难做干净。2. 改成 embedding 全文检索双路召回现在不是只走向量检索而是同时做embedding 相似度召回和tsvector 全文检索召回然后把两路结果融合。这样做的目的是把两种能力都利用起来向量检索负责语义相关性全文检索负责显式关键词命中。这会比纯 embedding 更稳也比纯关键词更像真正的 RAG 检索器。3. 做了融合排序我在融合阶段保留了embedding_scoretext_scorehybrid_scoreretrieval_source这样后面不仅能召回还能解释“这个 chunk 是怎么被召回上来的”。为了后续调试和答辩都更清楚如果检索不好用我可以明确知道问题出在向量召回不准还是全文召回太弱还是融合策略有偏差4. 加了 MMR 去重混合召回之后如果不做去重很容易出现 topK 全是高度相似的 chunk比如同一篇论文里的TitleAbstractAgent SummaryTeaser它们共享很多关键词如果不处理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_paperAgent chunk 写入 pf_paper_chunkAgent workflow embedding 写入 pf_paper_embedding历史 embedding 回填能力/internal/rag/qa 基于知识库向量检索回答paper_id 范围过滤embedding 全文检索混合召回MMR 去重chunk 质量加权/v1/chat/completions 普通问答接到知识库 RAG这些能力。