8.2 · 组件系统架构（Component System Architecture）

组件系统架构（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/infiniflow/ragflow/8.2-component-system-architecture

翻译时间：2026-05-27T08:44:27.393Z

翻译模型：deepseek-chat

原文字符数：12806

项目：RAGFlow (ragflow)

---

组件系统架构

相关源文件

以下文件被用作生成此维基页面的上下文：

• agent/canvas.py
• agent/component/__init__.py
• agent/component/agent_with_tools.py
• agent/component/base.py
• agent/component/categorize.py
• agent/component/llm.py
• agent/tools/base.py
• common/mcp_tool_call_conn.py
• rag/prompts/generator.py
• web/src/constants/agent.tsx
• web/src/pages/agent/canvas/index.tsx
• web/src/pages/agent/canvas/node/dropdown/accordion-operators.tsx
• web/src/pages/agent/canvas/node/dropdown/operator-item-list.tsx
• web/src/pages/agent/canvas/node/extractor-node.tsx
• web/src/pages/agent/constant/index.tsx
• web/src/pages/agent/context.ts
• web/src/pages/agent/form-sheet/form-config-map.tsx
• web/src/pages/agent/hooks/use-add-node.ts
• web/src/pages/agent/hooks/use-show-drawer.tsx
• web/src/pages/agent/log-sheet/index.tsx
• web/src/pages/agent/operator-icon.tsx

目的与范围

本文档描述了构成 RAGFlow 的 Agent 和工作流系统基础的组件系统架构。组件是 Canvas 工作流的构建块——它们是自包含、可配置的单元，用于执行特定任务，例如大语言模型（LLM）调用、检索、分类和文档生成。本页面涵盖基类、参数校验、组件工厂模式和动态注册。

有关组件在工作流中如何编排的信息，请参阅 Canvas 引擎与 DSL。有关特定内置组件的详细信息，请参阅 内置组件。

---

组件类层次结构

组件系统建立在 agent/component/base.py 中定义的两个基础抽象类之上，所有组件都继承自这两个类：用于配置的 ComponentParamBase 和用于执行逻辑的 ComponentBase。

类层次结构图

graph TB
    subgraph "基类"
        ABC["ABC（Python 抽象基类）"]
        CPB["ComponentParamBase<br/>[agent/component/base.py:40]"]
        CB["ComponentBase<br/>[agent/component/base.py:365]"]
    end

    subgraph "参数实体"
        LP["LLMParam<br/>[agent/component/llm.py:34]"]
        AP["AgentParam<br/>[agent/component/agent_with_tools.py:39]"]
        TP["ToolParamBase<br/>[agent/tools/base.py:29]"]
        CP["CategorizeParam<br/>[agent/component/categorize.py:30]"]
    end

    subgraph "执行实体"
        LC["LLM<br/>[agent/component/llm.py:83]"]
        AC["Agent<br/>[agent/component/agent_with_tools.py:73]"]
        TC["ToolBase<br/>[agent/tools/base.py:136]"]
        CC["Categorize<br/>[agent/component/categorize.py:98]"]
    end

    ABC --> CPB
    ABC --> CB

    CPB --> LP
    CPB --> AP
    CPB --> TP
    CPB --> CP

    CB --> LC
    CB --> AC
    CB --> TC
    CB --> CC

    LC -. "使用" .-> LP
    AC -. "使用" .-> AP
    TC -. "使用" .-> TP
    CC -. "使用" .-> CP

来源： agent/component/base.py:40-365, agent/component/llm.py:34-83, agent/component/agent_with_tools.py:39-73, agent/component/categorize.py:30-98, agent/tools/base.py:29-136

---

ComponentParamBase：参数校验与配置

ComponentParamBase 定义了参数模式和校验规则。每个组件都有一个关联的参数类，用于处理运行时配置与默认值的合并。

核心属性

属性	描述	定义位置
inputs	字典，定义预期的输入参数及其类型。	agent/component/base.py:43
outputs	字典，存储执行后的输出值和类型。	agent/component/base.py:44
max_retries	失败时的重试次数（默认值：0）。	agent/component/base.py:46
delay_after_error	重试之间的等待秒数（默认值：2.0）。	agent/component/base.py:47

参数更新与校验

agent/component/base.py 中的 update(conf) 方法执行从配置字典到参数对象的递归更新 agent/component/base.py:127-187。它会跟踪哪些参数是"用户提供的"，哪些是默认值，并处理已废弃的参数 agent/component/base.py:130-141。

每个参数类都必须实现 check() 方法来强制执行约束。例如：

• LLMParam.check() 校验 temperature、presence_penalty 和 max_tokens 是否为有效的数值，并且 llm_id 不为空 agent/component/llm.py:53-61。
• CategorizeParam.check() 确保提供了 category_description，并且为每个类别定义了"To"目标 agent/component/categorize.py:42-49。
• AgentParam 继承自 LLMParam 和 ToolParamBase，结合了大语言模型（LLM）设置和工具元数据的校验 agent/component/agent_with_tools.py:39-71。

来源： agent/component/base.py:40-187, agent/component/llm.py:53-61, agent/component/categorize.py:42-49, agent/component/agent_with_tools.py:39-71

---

组件工厂模式与动态注册

RAGFlow 使用动态发现机制在运行时注册和加载组件。这避免了硬编码导入，并允许通过向 agent/component/ 目录添加新文件来轻松扩展系统。

动态发现过程

agent/component/__init__.py 文件会自动扫描目录以查找组件模块并提取类：

1. _import_submodules()：遍历 agent/component/ 中的文件，跳过 base.py 和私有文件 agent/component/__init__.py:25-35。
2. _extract_classes_from_module()：使用 inspect.getmembers() 查找模块中的所有类，并将它们添加到全局 __all_classes 注册表中 agent/component/__init__.py:37-42。
3. component_class(class_name)：一个工厂函数，用于在三个模块中搜索类名：agent.component、agent.tools 和 rag.flow agent/component/__init__.py:51-59。

DSL 加载与组件实例化

agent/canvas.py 中的 Graph.load() 方法使用此工厂从 DSL 实例化组件：

sequenceDiagram
    participant G as "Graph [agent/canvas.py]"
    participant F as "component_class [agent/component/__init__.py]"
    participant P as "参数类"
    participant C as "组件类"

    G->>F: "component_class('LLMParam')"
    F-->>G: "LLMParam 类"
    G->>P: "实例化并更新(params)"
    P->>P: "check() 校验"
    G->>F: "component_class('LLM')"
    F-->>G: "LLM 类"
    G->>C: "实例化(graph, id, param)"
    C-->>G: "组件对象"

来源： agent/component/__init__.py:22-59, agent/canvas.py:96-109

---

可视化发现到代码实体的映射

此图桥接了高层 DSL 概念与实现它们的具体 Python 类之间的差距。

graph LR
    subgraph "DSL 结构 [agent/canvas.py]"
        DSL_Comp["components[id]"]
        DSL_Obj["obj"]
        DSL_Params["params"]
    end

    subgraph "Python 实体空间"
        Factory["component_class()<br/>[agent/component/__init__.py:51]"]
        BaseComp["ComponentBase<br/>[agent/component/base.py:365]"]
        BaseParam["ComponentParamBase<br/>[agent/component/base.py:40]"]
    end

    subgraph "具体实现"
        LLM_C["LLM [agent/component/llm.py]"]
        Agent_C["Agent [agent/component/agent_with_tools.py]"]
        Cat_C["Categorize [agent/component/categorize.py]"]
    end

    DSL_Comp -- "包含" --> DSL_Obj
    DSL_Obj -- "名称由" --> Factory
    Factory -- "返回" --> BaseComp
    DSL_Params -- "更新" --> BaseParam
    BaseComp -- "由...实现" --> LLM_C
    BaseComp -- "由...实现" --> Agent_C
    BaseComp -- "由...实现" --> Cat_C

来源： agent/canvas.py:43-109, agent/component/__init__.py:51-59, agent/component/base.py:40-365, agent/component/agent_with_tools.py:73, agent/component/categorize.py:98

---

ComponentBase：执行与数据流

ComponentBase 是所有可执行组件的抽象基类。它提供了同步和异步执行、变量解析和状态管理的框架。

执行框架

组件在 _invoke()（同步）或 _invoke_async()（异步）中实现逻辑。基类提供了处理计时、错误日志记录和输出存储的包装器：

• invoke(**kwargs)：包装同步执行 agent/component/base.py:407-419。
• invoke_async(**kwargs)：包装异步执行，对非协程函数使用 thread_pool_exec 以防止阻塞事件循环 agent/component/base.py:421-447。

变量解析与数据流

组件通过 Graph（Canvas）对象与全局状态交互。agent/canvas.py 中的 get_value_with_variable(value) 方法使用正则表达式模式（如 {{sys.query}} 或 {{component_id@variable}}）解析字符串中的变量引用 agent/canvas.py:168-193。

变量使用 Graph.get_variable_value(exp) 解析 agent/canvas.py:195-240，该方法支持：

• 系统变量：sys.query、sys.user_id 等 agent/canvas.py:198
• 环境变量：env.VAR_NAME agent/canvas.py:169。
• 组件输出：component_id@variable_name agent/canvas.py:199。
• 嵌套路径：通过点符号访问深层字段（例如 agent_0@structured.answer）agent/canvas.py:209-236。

数据流图

graph LR
    subgraph "上游组件 (retrieval_0)"
        Out["outputs['json']<br/>[agent/component/base.py:44]"]
    end

    subgraph "Graph (Canvas)"
        VarRes["get_variable_value('retrieval_0@json')<br/>[agent/canvas.py:195]"]
    end

    subgraph "下游组件 (llm_0)"
        In["_param.prompts<br/>'{retrieval_0@json}'"]
        GetIn["get_value_with_variable()<br/>[agent/canvas.py:168]"]
    end

    Out -.-> VarRes
    VarRes -.-> GetIn
    GetIn -.-> In

来源： agent/component/base.py:407-447, agent/canvas.py:168-240

---

智能体与大语言模型（LLM）集成

Agent 组件通过将大语言模型（LLM）能力与工具执行相结合，展示了高级组件架构。

• 工具绑定：Agent 组件从其参数初始化工具，通过 component_class 解析它们 agent/component/agent_with_tools.py:133-145。它将这些工具绑定到 LLMBundle 以启用函数调用 agent/component/agent_with_tools.py:112-113。
• MCP 集成：通过创建 MCPToolCallSession 对象并将其工具绑定到大语言模型（LLM），支持模型上下文协议（MCP）服务器 agent/component/agent_with_tools.py:101-109。
• 消息格式化：使用 message_fit_in 确保提示词和历史记录适合模型的 Token 限制 agent/component/agent_with_tools.py:115-120, rag/prompts/generator.py:68-125。

来源： agent/component/agent_with_tools.py:73-145, rag/prompts/generator.py:68-125

---

错误处理与取消

组件架构包含用于任务管理和故障恢复的内置机制。

取消检查

长时间运行的组件必须定期调用 check_if_canceled() agent/component/base.py:396-405。此方法检查：

1. _canvas.is_canceled() 标志 agent/canvas.py:270-271。
2. has_canceled(task_id) 服务，该服务在 Redis 中查找取消标志 agent/canvas.py:35。

异常处理

如果在 _invoke 期间发生异常，基类会：

1. 记录异常 agent/component/base.py:416。
2. 使用错误消息设置 _ERROR 输出键 agent/component/base.py:414。
3. 支持 exception_goto 参数，用于在失败时重定向工作流执行 agent/component/base.py:50。

来源： agent/component/base.py:393-419, agent/canvas.py:270-271, api/db/services/task_service.py:35