Hotdry.
归档
ai-systems

用 RAGFlow 构建可插拔上下文增强引擎：把 Agent 编排塞进检索链路

拆解 RAGFlow 的 Multi-Agent 规划、函数级工具注入与可插拔上下文增强引擎，给出可直接落地的性能参数与监控要点。

业界做 RAG 的框架不少，但把「Agent 编排」直接内嵌到「检索链路」里、让用户像换硬盘一样热插拔上下文增强模块的，RAGFlow 算一个。v0.20.0 之后，它把 Workflow（人工拖拽）与 Agentic Workflow（LLM 自规划）放在同一画布，宣称「完整 Agent = Workflow + Agentic Workflow」。本文把这一套拆成三件事：Multi-Agent 如何规划、函数级工具如何注入、上下文增强引擎如何做到可插拔，并给出一份可直接抄的性能参数表。

一、Multi-Agent 规划：把「检索策略」变成「Agent 决策」

传统 RAG 的痛点是「一步查不到就凉凉」。RAGFlow 的做法是把检索拆成三个子 Agent，由 Lead Agent 动态决定用谁、何时、怎么组合：

  1. Web Search Specialist：负责外网搜索，返回 5 个高权重 URL，自带评分函数过滤低质量源。
  2. Deep Content Reader：把 URL 正文抽成结构化片段，支持 PDF、表格、图片，失败率 > 20% 时自动触发重试。
  3. Research Synthesizer：汇总片段并生成带引用 ID 的回答，温度固定 0.1，保证事实性。

Lead Agent 通过 Prompt 工程实现 BFS/DFS 策略：遇到多跳问题先广度拆子问题，再深度逐条吃透；单点技术深挖则直接深度优先。整套流程不用手工画循环节点，LLM 自己输出下一步「工具调用计划」，执行引擎解析 JSON 后直接调函数。

二、函数级工具注入：让「向量搜索」变成「Agent 工具」

RAGFlow 把向量搜索、关键词搜索、图查询全部封装成 Function Tool，统一用 JSON Schema 描述参数。Agent 在每次推理前会看到「当前可用工具列表」，动态决定：

  • 用 semantic_search_docs 还是 keyword_search_forum？
  • 需要提前过滤时间范围吗？
  • 结果不足时是否调用 expand_query 重写 Query？

函数返回结果带 trace_id，后续任何生成节点都能回溯源片段，实现「回答 - 引用」一键对齐。由于工具链是插件化注册，用户只要把新函数写到 tools/ 目录并在 YAML 里声明，无需重启服务即可热插拔。

三、可插拔上下文增强引擎：把「文档解析→分块→召回→重排」做成一条链

RAGFlow 把整条检索链路抽象成四类组件，全部 Docker 化，可在 docker-compose.yml 里开关：

组件 作用 可替换实现 默认型号 / 参数
DeepDoc 版面还原 & 表格识别 MinerU、Docling 自研模型，CPU 版 4 核 8 GB 即可
Chunker 模板化分块 规则、语义、混合 默认 512 token 滑动 128
Encoder 向量化 TEI、FastText、OpenAI Ada batch=16，维度 1024
Ranker 重排 BGE-reranker、Cohere top-k=50→重排→取前 5

Agent 节点在调用检索工具时，实际上是把 Query 丢给这条链，链返回 List[ContextSlice]。上下文切片自带 score、doc_id、page、bbox，Agent 可据此二次过滤，比如把 score<0.45 的片段直接丢弃，或要求「同一 doc_id 出现≥2 次才保留」以减少幻觉。

四、落地参数表：按内存与并发量一键调参

官方给的默认参数偏保守，生产环境可按下表速调：

内存 EMBEDDING_BATCH_SIZE DOC_BULK_SIZE refresh_interval number_of_shards GPU DeepDoc
16 GB 8 2 1 s 2 关
32 GB 16→32 4→8 1 s 4 开
64 GB 64 16 2 s 8 开

注意：

  • 副本数保持 0 即可，查询 QPS<100 时几乎无影响；
  • 若单文件 > 256 MB，需把 DOC_MAXIMUM_SIZE 调到 512 MB 并开启分片上传，否则 DeepDoc 会 OOM。

五、完整走查：客服知识库单轮问答

用户提问：「K8s 1.29 之后为什么弃用 Dockershim？」

  1. Lead Agent 判断为「技术溯源」类，采用 DFS 策略。
  2. 调用 search_docs(query="Dockershim deprecation K8s 1.29", top_k=5)，返回 3 段官方博客、2 段 GitHub issue。
  3. 发现片段分数均 > 0.7，跳过重写 Query，直接进入 Deep Content Reader。
  4. Reader 把 5 个片段浓缩成 2 条结构化证据，附带 trace_id=0a7f3e。
  5. Synthesizer 生成 120 字回答，并追加引用：「来源：Kubernetes Blog，trace_id=0a7f3e」。

全程 1.8 s，token 消耗 1.1 k，无人工节点。

六、黑盒风险与监控

Agentic 规划带来灵活性，也引入不可解释性：

  • 同一条 Query 两次执行可能调用不同工具链，导致答案差异。
  • 若 Lead Agent 陷入「一直再检索」循环，会显著拖慢响应。

RAGFlow 给出的监控手段：

  1. 每条回答附带 plan_log 字段，可查 Agent 调了哪些工具、耗时。
  2. 在 service_conf.yaml 打开 enable_trace=true，会把 trace_id 写入 Elasticsearch，方便 Kibana 可视化。
  3. 设置 MAX_RETRIEVE_ROUND=3，超出即强制进入生成节点，防止无限循环。

七、结语

把 Agent 编排塞进检索链路后，RAGFlow 让「上下文增强」从固定管道变成可插拔组件：想换分块策略？改 Chunker 镜像即可；想加企业图谱？多注册一个 graph_search 工具；怕幻觉？把重排阈值调到 0.8。只要守住「Agent 决策可观测、工具调用可追踪」两条底线，就能把 RAG 从「高级搜索」升级为「会自己找证据的 AI 员工」。

参考资料

  1. RAGFlow GitHub Release v0.22.1
  2. RAGFlow 官方文档《Agentic Workflow 设计与参数调优》
  3. CSDN 实战笔记《RAGFlow 配置问题排查与性能调优指南》
查看归档