8.7 · Canvas API 与管理（Canvas API and Management）

复杂文档理解与引用检索 · 本章是 RAGFlow DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目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

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

翻译模型：deepseek-chat

原文字符数：11384

项目：RAGFlow (ragflow)

---

Canvas API 与管理

API 路由结构

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

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

graph TB
    subgraph "自然语言空间"
        Sessions["聊天会话"]
        Agents["AI Agent/Canvas"]
        History["消息历史"]
    end

    subgraph "代码实体空间"
        AgentAPI["api/apps/restful_apis/agent_api.py"]
        SessionAPI["api/apps/sdk/session.py"]
        ReplicaSvc["api/apps/services/canvas_replica_service.py"]
        CanvasSvc["api/db/services/canvas_service.py"]
        ConvSvc["api/db/services/conversation_service.py"]
        APIConvSvc["api/db/services/api_service.py"]
        CanvasModel["api/db/db_models.py:UserCanvas"]
    end

    Sessions --> SessionAPI
    Agents --> AgentAPI
    History --> APIConvSvc

    AgentAPI --> ReplicaSvc
    SessionAPI --> ConvSvc
    ConvSvc --> CanvasModel
    ReplicaSvc --> CanvasSvc

来源：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。

请求流程：

通过 UserCanvasService.query 校验所有权 api/apps/restful_apis/agent_api.py:94-95。
在 user_canvas 表中保存或更新记录 api/db/services/canvas_service.py:44-45。
通过 UserCanvasVersionService 创建或更新版本快照 api/db/services/canvas_service.py:27-27。
系统通过 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`	检索团队所有允许访问的 Agent	`api/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 负责管理聊天历史的持久化。

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

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

sequenceDiagram
    participant SDK as "ragflow_sdk/modules/session.py"
    participant SessionAPI as "api/apps/sdk/session.py"
    participant Canvas as "agent/canvas.py:Canvas"
    participant ConvSvc as "api/db/services/conversation_service.py"
    participant DB as "api/db/db_models.py:API4Conversation"

    SDK->>SessionAPI: create_agent_session(agent_id)
    SessionAPI->>Canvas: Canvas(dsl, tenant_id, agent_id)
    Canvas->>Canvas: reset()
    SessionAPI->>ConvSvc: ConversationService.save(...)
    SessionAPI->>DB: API4ConversationService.save(...)
    SessionAPI-->>SDK: {id: session_id, message: prologue}

来源：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