agentic_huge_data_base / wiki
页面 RAGFlow · 8.7 Canvas API 与管理·DeepWiki 中文全文译文
DeepWiki 中文译文 / RAGFlow / 8.7

8.7 · Canvas API 与管理

复杂文档理解与引用检索 · 聚焦本章的模块关系、源码依据与实现要点。

项目RAGFlow 章节8.7 状态全文译文 模块界面与交互、测试、发布与运维、入库与解析、系统架构
项目要点页2.5 参考项目 项目章节目录RAGFlow DeepWiki 原始章节Canvas API and Management 上一章8.6 下一章9
源码线索
  • .gitignore
  • api/apps/restful_apis/agent_api.py
  • api/db/services/canvas_service.py
  • api/db/services/conversation_service.py
  • bin/.gitkeep
  • deepdoc/parser/mineru_parser.py
  • test/testcases/test_http_api/test_session_management/test_agent_completions.py
  • test/testcases/test_http_api/test_session_management/test_agent_sessions.py
  • test/testcases/test_http_api/test_session_management/test_chat_completions.py
  • test/testcases/test_http_api/test_session_management/test_session_sdk_routes_unit.py
模块标签
  • 界面与交互
  • 测试、发布与运维
  • 入库与解析
  • 系统架构
  • 检索、召回与索引

章节正文

Canvas API 与管理

原始 DeepWiki 页面https://deepwiki.com/infiniflow/ragflow/8.7-canvas-api-and-management

Canvas API 与管理

相关源文件

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

  • .gitignore
  • api/apps/restful_apis/agent_api.py
  • api/db/services/canvas_service.py
  • api/db/services/conversation_service.py
  • bin/.gitkeep
  • deepdoc/parser/mineru_parser.py
  • test/testcases/test_http_api/test_session_management/test_agent_completions.py
  • test/testcases/test_http_api/test_session_management/test_agent_sessions.py
  • test/testcases/test_http_api/test_session_management/test_chat_completions.py
  • test/testcases/test_http_api/test_session_management/test_session_sdk_routes_unit.py
  • test/testcases/test_web_api/test_agent_app/test_agents_webhook_unit.py
  • web/.eslintrc.cjs
  • web/src/components/collapse.tsx
  • web/src/components/embed-dialog/index.tsx
  • web/src/components/floating-chat-widget.tsx
  • web/src/components/home-card.tsx
  • web/src/components/next-message-item/group-button.tsx
  • web/src/components/pdf-drawer/hooks.ts
  • web/src/components/pdf-drawer/index.tsx
  • web/src/components/ui/sheet.tsx
  • web/src/hooks/use-agent-request.ts
  • web/src/interfaces/database/agent.ts
  • web/src/pages/agent/form-sheet/next.tsx
  • web/src/pages/agent/form/code-form/expanded-editor.tsx
  • web/src/pages/agent/form/code-form/index.tsx
  • web/src/pages/agent/form/code-form/monaco-config.ts
  • web/src/pages/agent/form/code-form/next-variable.tsx
  • web/src/pages/agent/form/code-form/schema.ts
  • web/src/pages/agent/form/code-form/use-values.ts
  • web/src/pages/agent/form/code-form/use-watch-change.ts
  • web/src/pages/agent/gobal-variable-sheet/index.tsx
  • web/src/pages/agent/hooks.tsx
  • web/src/pages/agent/hooks/use-build-dsl.ts
  • web/src/pages/agent/hooks/use-save-graph.ts
  • web/src/pages/agent/hooks/use-send-shared-message.ts
  • web/src/pages/agent/hooks/use-watch-form-change.ts
  • web/src/pages/agent/index.tsx
  • web/src/pages/agent/utils/build-output-list.ts
  • web/src/pages/agents/agent-card.tsx
  • web/src/pages/agents/agent-dropdown.tsx
  • web/src/services/agent-service.ts

本文档描述了 Canvas 工作流的 HTTP API 端点和管理操作。Canvas 工作流（也称为 Agent 或 DataFlow）是可视化工作流定义，支持创建、执行、版本管理和共享。关于 Canvas 执行内部机制的详细信息，请参见 Canvas 引擎与 DSL。关于组件架构，请参见 组件系统架构。

范围：本文涵盖 REST API 层、Canvas 持久化的数据库服务、会话管理、版本管理以及运行时状态处理。

API 路由结构

Canvas API 按功能组划分为模板管理、CRUD 操作和执行操作。这些功能主要在后台实现，并通过 SDK 和 Web 前端暴露。系统经过了大规模重构，以统一遵循 RESTful 规范。

标题：Canvas API 架构（代码实体）

RAGFlow · API 路由结构 · 图 1
RAGFlow · API 路由结构 · 图 1

来源：api/apps/restful_apis/agent_api.py:32-52、api/db/services/canvas_service.py:44-45、api/db/services/conversation_service.py:33-35、api/apps/sdk/session.py:54-140

Canvas 生命周期管理

创建与更新 Canvas

Canvas 的创建和更新涉及持久化定义图的领域特定语言（DSL）。系统使用 UserCanvasService 管理 UserCanvas 模型记录。访问权限通过 _require_canvas_access_sync 和 _require_canvas_owner_sync 等装饰器严格控制 api/apps/restful_apis/agent_api.py:71-97。

请求流程：

  1. 通过 UserCanvasService.query 校验所有权 api/apps/restful_apis/agent_api.py:94-95。
  2. 在 user_canvas 表中保存或更新记录 api/db/services/canvas_service.py:44-45。
  3. 通过 UserCanvasVersionService 创建或更新版本快照 api/db/services/canvas_service.py:27-27。
  4. 系统通过 CanvasReplicaService 支持"副本"机制，用于管理冗余或扩展的 Agent 实例 api/apps/restful_apis/agent_api.py:36-36。
检索 Canvas

系统提供多种方式来列出和检索 Canvas，支持按类别（Agent 与 DataFlow）和租户权限进行过滤。

服务方法用途实现位置
get_list租户的分页列表api/db/services/canvas_service.py:47-63
get_by_canvas_id详细视图，包含用户昵称和头像api/db/services/canvas_service.py:99-125
get_by_tenant_ids团队/共享访问的过滤列表api/db/services/canvas_service.py:142-185
get_all_agents_by_tenant_ids检索团队所有允许访问的 Agentapi/db/services/canvas_service.py:67-95

来源：api/db/services/canvas_service.py:42-195、api/apps/restful_apis/agent_api.py:71-97

Canvas 执行与会话

会话初始化

会话（对话）跟踪与 Agent Canvas 的多轮交互。当用户开始聊天时，create_agent_session 会初始化环境。

  • DSL 检索：通过 get_agent_dsl_with_release 根据 release_mode 是否激活来获取 DSL api/apps/sdk/session.py:65。
  • Canvas 重置：实例化 Canvas 对象并调用 canvas.reset() 为执行做准备 api/apps/sdk/session.py:72-73。
  • 开场白生成：使用 canvas.get_prologue() 填充初始消息 api/apps/sdk/session.py:82。
对话处理

ConversationService 和 API4ConversationService 负责管理聊天历史的持久化。

  1. 创建：使用 get_uuid() 生成唯一的 session_id api/apps/sdk/session.py:71。
  2. 持久化：逐轮消息被结构化并保存。系统使用 structure_answer 格式化引用并处理"思考"块（例如 <think>）api/db/services/conversation_service.py:73-110。
  3. 引用跟踪：引用和检索到的片段存储在 reference 字段中，使用 chunks_format 格式化 api/db/services/conversation_service.py:80-82。
  4. 规范化：前端和 SDK 使用 _normalize_agent_session 将后端数据库记录转换为标准化的 JSON 结构以供显示 api/apps/restful_apis/agent_api.py:116-145。

标题：Agent 会话执行（代码实体）

RAGFlow · 对话处理 · 图 2
RAGFlow · 对话处理 · 图 2

来源：api/apps/sdk/session.py:54-87、api/db/services/conversation_service.py:73-110、api/apps/restful_apis/agent_api.py:116-145

版本与模板管理

版本管理系统

UserCanvasVersionService 维护 DSL 快照的历史记录。

  • 发布模式：用户可以在草稿 DSL 和"已发布"版本之间切换。get_agent_dsl_with_release 通过检查 user_canvas_version 表中的 release 标志来处理此逻辑 api/apps/sdk/session.py:65。
  • 最新版本：系统跟踪版本标题，以提供当前正在执行的迭代的上下文 api/apps/sdk/session.py:77。
模板管理

模板为各种 Agent 类型提供初始 DSL。

  • CanvasTemplateService：管理 CanvasTemplate 模型 api/db/services/canvas_service.py:32-34。
  • DataFlowTemplateService：用于以工作流为中心的 Agent 的模板服务别名 api/db/services/canvas_service.py:35-39。
前端管理界面

React 前端提供了管理这些实体的全面界面：

  • AgentCanvas：用于编辑的主 React Flow 提供者 web/src/pages/agent/index.tsx:44。
  • VersionDialog：允许用户查看和切换已保存的版本 web/src/pages/agent/index.tsx:71。
  • FormSheet：一个滑出面板，使用 FormConfigMap 配置单个节点参数 web/src/pages/agent/form-sheet/next.tsx:49。

来源：api/db/services/canvas_service.py:32-43、api/apps/sdk/session.py:57-83、web/src/pages/agent/index.tsx:44-71、web/src/pages/agent/form-sheet/next.tsx:37-60