8.1 · Canvas 引擎与 DSL（Canvas Engine and DSL）

Canvas 引擎与 DSL

Canvas 引擎与 DSL

相关源文件

本章引用的主要源码文件：

• agent/canvas.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/app/picture.py
• rag/flow/chunker/__init__.py
• rag/flow/chunker/schema.py
• rag/flow/parser/parser.py
• rag/flow/parser/pdf_chunk_metadata.py
• rag/flow/parser/utils.py
• rag/flow/tests/dsl_examples/general_pdf_all.json
• rag/flow/tokenizer/schema.py
• rag/flow/tokenizer/tokenizer.py
• rag/prompts/generator.py
• web/src/pages/agent/canvas/edge/index.tsx
• web/src/pages/agent/canvas/node/handle.tsx
• web/src/pages/agent/constant/pipeline.tsx
• web/src/pages/agent/form/parser-form/common-form-fields.tsx
• web/src/pages/agent/form/parser-form/index.tsx
• web/src/pages/agent/form/parser-form/pdf-form-fields.tsx
• web/src/pages/agent/form/parser-form/spreadsheet-form-fields.tsx
• web/src/pages/agent/form/parser-form/text-html-form-fields.tsx
• web/src/pages/agent/form/parser-form/word-form-fields.tsx
• web/src/pages/agent/store.ts
• web/src/pages/agent/utils.ts

Canvas 引擎是 RAGFlow 的工作流执行系统，它通过基于图的领域特定语言（DSL）来编排 AI 智能体的交互。本文档涵盖了 Graph 和 Canvas 类的实现、DSL 结构、变量解析以及工作流持久化机制。

DSL 结构

Canvas DSL 是一种基于 JSON 的模式，它定义了工作流的完整状态和连接关系。每个 canvas 都表示为一个可序列化和存储的 DSL 对象。

核心 DSL 模式

DSL 遵循在 agent/canvas.py:43-82 中定义的以下结构：

{
  "components": {
    "begin": {
      "obj": {
        "component_name": "Begin",
        "params": {}
      },
      "downstream": ["retrieval_0"],
      "upstream": []
    },
    "retrieval_0": {
      "obj": {
        "component_name": "Retrieval",
        "params": {}
      },
      "downstream": ["generate_0"],
      "upstream": ["begin"]
    }
  },
  "history": [],
  "path": ["begin"],
  "retrieval": {"chunks": [], "doc_aggs": []},
  "globals": {
    "sys.query": "",
    "sys.user_id": "tenant_id",
    "sys.conversation_turns": 0,
    "sys.files": []
  }
}

DSL 字段：

组件定义： components 对象中的每个条目包含：

• obj：组件实例数据，包含 component_name 和 params agent/canvas.py:48-51。
• downstream：后续组件的 ID 列表 agent/canvas.py:52。
• upstream：前置组件的 ID 列表 agent/canvas.py:53。

来源： agent/canvas.py:43-111

Canvas 和 Graph 类层次结构

类图：自然语言空间到代码实体空间

此图将概念上的工作流实体映射到实现它们的特定 Python 类和方法。

来源： agent/canvas.py:43-838, agent/component/base.py:40-188

Graph 类实现

Graph 类 agent/canvas.py:43-281 提供了基础的图基础设施：

关键职责：

• DSL 加载：load() 方法 agent/canvas.py:96-111 实例化组件对象。它使用 component_class(name + "Param") 创建参数对象，并使用 component_class(name) 创建组件本身 agent/canvas.py:101-109。
• 变量解析：使用正则表达式模式解析诸如 {sys.query} 或 {component_id@output} 之类的表达式 agent/canvas.py:168-193。
• 任务管理：跟踪执行状态，并通过 task_id 处理取消操作 agent/canvas.py:91。它通过 has_canceled(self.task_id) 监控取消状态 agent/canvas.py:35。

Canvas 类实现

Canvas 类 agent/canvas.py:283-838 扩展了 Graph，用于处理特定于对话的逻辑：

对话上下文：

• 历史管理：get_history(window_size) 检索最近 $N$ 轮的对话 agent/canvas.py:330-341。
• 全局变量：管理 sys.* 变量，包括 sys.query、sys.user_id 和 sys.files agent/canvas.py:286-293。
• 引用跟踪：add_reference() 存储检索到的片段，用于生成引用 agent/canvas.py:756-764。它使用 rag.prompts.generator 中的 chunks_format 来规范化片段数据 agent/canvas.py:40。

来源： agent/canvas.py:43-111, 168-193, 283-341, 756-764, rag/prompts/generator.py:40-63

执行模型

Canvas 引擎使用基于路径的执行模型，工作流通过组件的有向图进行推进。

组件实例化与校验

在 load() 期间，引擎会对组件参数进行严格校验：

1. 它使用 component_class 工厂获取参数类 agent/canvas.py:101。
2. 它使用 DSL 中的值更新参数对象 agent/canvas.py:103。
3. 它调用 param.check() agent/canvas.py:105。例如，LLMParam 的检查会确保提供了模型 ID 和提示词 agent/component/llm.py:53-60。

动态路由与控制流

执行并非严格线性的。某些组件可以动态改变路径：

来源： agent/canvas.py:96-111, agent/component/llm.py:53-60, agent/component/agent_with_tools.py:110-113, agent/component/categorize.py:157-158

变量与数据流

RAGFlow 使用基于字符串的插值系统在组件之间传递数据。

变量解析逻辑

get_variable_value 方法 agent/canvas.py:195-237 解析三种类型的变量：

1. 系统变量：以 sys. 为前缀（例如 sys.query）。
2. 环境变量：以 env. 为前缀。
3. 组件输出：使用 @ 语法（例如 retrieval_0@content）。

# 组件输出的内部解析 [agent/canvas.py:199-202]
cpn_id, var_nm = exp.split("@")
cpn = self.get_component(cpn_id)
# ...
root_val = cpn["obj"].output(root_key)

数据流图：变量插值

此图展示了数据如何从系统流入组件，以及如何通过 Canvas 引擎在组件之间流动。

来源： agent/canvas.py:168-237, agent/component/base.py:284-301

持久化与序列化

工作流以 DSL 字符串的形式存储在数据库中，并在运行时重新构建。

序列化与版本控制

Graph.__str__ 方法 agent/canvas.py:113-132 处理将图序列化回 DSL JSON 字符串的过程。它会遍历所有已加载的组件，并调用它们各自的 __str__ 方法，这些方法会使用 ComponentParamBase 中的 as_dict() 方法 agent/component/base.py:99-125。

为确保数据完整性，RAGFlow 实现了一个规范化步骤：

1. 规范化：在加载 DSL 之前，通过 normalize_chunker_dsl 对其进行规范化，以处理遗留模式的转换 agent/canvas.py:89。

前端 DSL 构建

前端使用 web/src/pages/agent/utils.ts 中的工具函数，将可视化图形转换为后端期望的 DSL。

来源： agent/canvas.py:113-132, agent/component/base.py:99-125, web/src/pages/agent/utils.ts:56-163