刘欢の博客

先看废弃前的设计：两种”接入方式” × 任意”检索来源”#

core/rag 包里除了 RetrieveConfig，Knowledge 接口、RAGMode 枚举、GenericRAGHook、KnowledgeRetrievalTools、DocumentMetadata 全部标了同一行 @Deprecated(forRemoval=true, since="2.0.0")。也就是说不是某一个类的问题，是整个 RAG 子系统要被拿掉。但拿掉之前，这套设计其实挺讲道理，值得先看懂再看它为什么被砍。

RAGMode 定义了两种把检索结果”喂”给 Agent 的方式：

1
public enum RAGMode {
2
    GENERIC,  // 每次推理前自动检索并注入，Agent感知不到，无脑喂
3
    AGENTIC,  // Agent自己决定要不要检索，通过Tool调用
4
    NONE
5
}

GENERIC 模式靠 GenericRAGHook 实现，钩在 PreCallEvent 上，每次调用模型前先摸一把最后一条用户消息去检索，检索失败就静默降级、不阻塞主流程：

1
return knowledge.retrieve(query, defaultConfig)
2
        .flatMap(retrievedDocs -> { /* 把结果包成一条 <retrieved_knowledge> 消息插进去 */ })
3
        .onErrorResume(error -> {
4
            log.warn("Generic RAG retrieval failed: {}", error.getMessage(), error);
5
            return Mono.just(event);   // 挂了就当没检索过，继续走原流程
6
        });

AGENTIC 模式靠 KnowledgeRetrievalTools 实现，本质是注册一个叫 retrieve_knowledge 的工具，让 Agent 自己判断”这轮要不要查知识库”，还顺手把 Agent 当前的对话历史自动塞进检索配置，给支持多轮上下文改写的知识库（比如百炼）用：

1
@Tool(name = "retrieve_knowledge", description = "...Use this tool when you need to find specific information...")
2
public String retrieveKnowledge(String query, Integer limit, Agent agent, RuntimeContext ctx) {
3
    List<Msg> conversationHistory = ...; // 从agent当前状态里顺手带出对话历史
4
    RetrieveConfig config = defaultConfig.mutate().limit(limit).conversationHistory(conversationHistory).build();
5
    return knowledge.retrieve(query, config).map(this::formatDocumentsForTool).block();
6
}

这个设计好在哪：“怎么接入 Agent 循环”（自动注入 vs 主动调用）和”谁来做检索”（自建向量库 / RAGFlow / Dify / Bailian / Haystack）被拆成了两个独立维度。Knowledge 只是个接口，SimpleKnowledge、RAGFlowKnowledge、DifyKnowledge、BailianKnowledge、HayStackKnowledge 都实现它——换检索来源只是换一个 Knowledge 实现，GenericRAGHook/KnowledgeRetrievalTools 这层代码完全不用碰。这跟我在 RAGFlow 里看到的 DocStoreConnection 抽象是同一种思路：把易变的部分（谁来检索）藏在接口后面，稳定的部分（怎么接进主流程）不动。

再看为什么要砍：不是否定 RAG，是否定”RAG 该有专属子系统”#

我去翻了这几个类的提交记录，找到那次打上 forRemoval=true 的 commit，说明写得很直白：

1
Stage E: mark legacy modules @Deprecated(forRemoval=true, since="2.0.0")
2

3
- core/memory/* → use AgentState.context + ContextCompressor
4
- core/pipeline/* → use Reactor Flux composition + middleware
5
- core/plan/*     → use state/TaskContext
6
- core/rag/*      → integrate via middleware/tool layer
7
- core/session/*  → use storage/StorageBase + state/AgentState.sessionId
8
- core/hook/*      → use MiddlewareBase hooks

这次不是单独针对 RAG 下的判断，是一次性把 7 个自成一派的子系统（memory/pipeline/plan/rag/session/hook/tracing）全部拆掉，统一收进一套通用的 middleware/tool 组合模型里。core/rag 只是这次”大扫除”里的一个受害者，判词是”integrate via middleware/tool layer”——翻译过来就是：RAG 不该在框架里长出自己专属的 Hook 类型（GenericRAGHook）、自己专属的 Tool 类（KnowledgeRetrievalTools）、自己专属的 Config 类（RetrieveConfig），它就应该是通用 middleware/tool 机制的一个普通用例，跟做限流、做重试、做压缩没有本质区别，不值得框架为它单开一整套抽象。

有个细节能佐证这个判断没有反悔：RAGFlowKnowledge、DifyKnowledge、BailianKnowledge 这几个平台适配器类本身没有被标 @Deprecated——它们只是实现了一个快要被移除的接口，等新的 middleware/tool 层落地后，大概率是把 retrieve() 这行调用平移过去，“该把解析和检索外包给专业平台”这个判断本身完好保留，被否定的只是”框架要不要为它单独造一套接入机制”。我又去翻了 agentscope-harness 模块，那边已经有一堆 CompactionMiddleware、MemoryFlushMiddleware、AsyncToolMiddleware，但还没看到专门的 RAG middleware——说明这条迁移路径写在了 commit 里，但工程上还没走完，是个正在进行时的重构。

这件事让我对”专业分工”这四个字有了更具体的认知：agentscope-java 判断”文档解析+切分+混合检索”这活儿它自己不该管，交给 RAGFlow/Dify/Bailian 这类专门系统去做；同时它也判断”RAG 怎么接进 Agent 循环”这活儿也不该有专属抽象，交给框架统一的 middleware/tool 机制去做——两层判断加起来，才是”该交给专业系统的交给专业系统，该收归统一机制的收归统一机制”，而不是我一开始简单理解的”RAG 不做了”。