agentic_huge_data_base / wiki
页面 Dify · 9.3 工作流执行 API·DeepWiki 中文全文译文
DeepWiki 中文译文 / Dify / 9.3

9.3 · 工作流执行 API（Workflow Execution API）

应用编排与外部知识接入 · 聚焦本章的模块关系、源码依据与实现要点。

项目Dify 章节9.3 状态全文译文 模块接口与服务契约、文档对象与元数据、工作流与编排、界面与交互
项目要点页2.5 参考项目 项目章节目录Dify DeepWiki 原始章节Workflow Execution API 上一章9.2 下一章9.4
源码线索
  • api/AGENTS.md
  • api/controllers/API_SCHEMA_GUIDE.md
  • api/controllers/common/schema.py
  • api/controllers/console/app/advanced_prompt_template.py
  • api/controllers/console/app/completion.py
  • api/controllers/console/app/conversation.py
  • api/controllers/console/app/conversation_variables.py
  • api/controllers/console/app/mcp_server.py
  • api/controllers/console/app/message.py
  • api/controllers/console/app/model_config.py
模块标签
  • 接口与服务契约
  • 文档对象与元数据
  • 工作流与编排
  • 界面与交互
  • 系统架构

章节正文

工作流执行 API

原始 DeepWiki 页面https://deepwiki.com/langgenius/dify/9.3-workflow-execution-api

工作流执行 API

相关源文件

以下文件为本 Wiki 页面的生成提供了上下文：

  • api/AGENTS.md
  • api/controllers/API_SCHEMA_GUIDE.md
  • api/controllers/common/schema.py
  • api/controllers/console/app/advanced_prompt_template.py
  • api/controllers/console/app/completion.py
  • api/controllers/console/app/conversation.py
  • api/controllers/console/app/conversation_variables.py
  • api/controllers/console/app/mcp_server.py
  • api/controllers/console/app/message.py
  • api/controllers/console/app/model_config.py
  • api/controllers/console/app/site.py
  • api/controllers/console/app/statistic.py
  • api/controllers/console/app/workflow.py
  • api/controllers/console/app/workflow_app_log.py
  • api/controllers/console/app/workflow_statistic.py
  • api/controllers/console/datasets/rag_pipeline/rag_pipeline_workflow.py
  • api/controllers/console/explore/completion.py
  • api/controllers/console/explore/recommended_app.py
  • api/controllers/console/explore/workflow.py
  • api/controllers/service_api/app/completion.py
  • api/controllers/service_api/app/workflow.py
  • api/controllers/web/completion.py
  • api/controllers/web/workflow.py
  • api/dev/generate_fastopenapi_specs.py
  • api/openapi/markdown/console-swagger.md
  • api/openapi/markdown/service-swagger.md
  • api/openapi/markdown/web-swagger.md
  • api/services/advanced_prompt_template_service.py
  • api/services/app_model_config_service.py
  • api/services/auth/api_key_auth_service.py
  • api/services/workflow/workflow_converter.py
  • api/services/workflow_app_service.py
  • api/tests/test_containers_integration_tests/controllers/console/datasets/rag_pipeline/test_rag_pipeline_workflow.py
  • api/tests/unit_tests/controllers/common/test_schema.py
  • api/tests/unit_tests/controllers/console/app/test_mcp_server_response.py
  • api/tests/unit_tests/controllers/console/app/test_workflow.py
  • api/tests/unit_tests/controllers/console/datasets/rag_pipeline/test_rag_pipeline_workflow.py
  • api/tests/unit_tests/controllers/service_api/app/test_workflow.py
  • web/app/components/rag-pipeline/hooks/use-pipeline-config.ts
  • web/app/components/workflow-app/hooks/use-workflow-init.ts
  • web/service/use-workflow.ts
  • web/service/workflow.ts

目的与范围

本文档记录了通过 POST /workflows/run 端点以编程方式执行工作流应用的服务 API。Dify 中的工作流应用是无状态的单次执行图，专为翻译、内容生成和数据处理等任务设计。与聊天应用不同，工作流应用在执行之间不会维护对话历史。

本节涵盖请求结构、输入变量处理（包括多模态文件）、流式事件序列以及后端中的执行追踪实现。

工作流执行端点

端点概述

POST /workflows/run

该端点执行工作流的已发布版本。它在服务 API 控制器的 WorkflowApi 类中定义。

关键特性：

  • 无状态：每次执行都是独立的，不使用 conversation_id api/controllers/service_api/app/workflow.py:216-220。
  • 输入驱动：需要 inputs 映射到起始节点的变量 api/controllers/service_api/app/workflow.py:55-56。
  • 可追踪：支持 trace_id 用于端到端的分布式追踪 api/controllers/service_api/app/workflow.py:230-231。

来源：api/controllers/service_api/app/workflow.py:216-250，api/openapi/markdown/service-swagger.md:1-50

请求结构

请求参数

下图展示了 API 请求参数到 AppGenerateService 和 WorkflowAppService 内部逻辑的映射关系。

Dify · 请求参数 · 图 1
Dify · 请求参数 · 图 1
输入变量 (inputs)

inputs 参数接受工作流 DSL 中定义的键值对。后端会在执行前根据工作流的配置对这些输入进行校验 api/controllers/service_api/app/workflow.py:228-235。

文件对象结构

当传递文件时（例如用于视觉分析或文档分析），files 数组包含具有以下结构的字典：

  • type：document、image、audio、video 或 custom。
  • transfer_method：remote_url 或 local_file。
  • url：如果使用 remote_url 则必填。
  • upload_file_id：如果使用 local_file 则必填（通过 /files/upload 获取）。

来源：api/controllers/service_api/app/workflow.py:55-56，api/controllers/common/controller_schemas.py:100-115

响应模式

阻塞模式 (blocking)

API 会等待整个图执行完成，然后返回 WorkflowRunResponse api/controllers/service_api/app/workflow.py:93-110。

  • 载荷：包含 workflow_run_id、status（succeeded/failed）以及从 WorkflowRun 模型中提取的最终 outputs 字典 api/controllers/service_api/app/workflow.py:174-199。

来源：api/controllers/service_api/app/workflow.py:174-200，api/services/app_generate_service.py:124-133

流式模式 (流式)

API 返回 text/event-stream。对于长时间运行的工作流，建议使用此模式以提供实时反馈。

Dify · 流式模式 ( 流式 ) · 图 2
Dify · 流式模式 ( 流式 ) · 图 2

来源：api/controllers/service_api/app/workflow.py:245-250，api/services/app_generate_service.py:41-85

执行事件与追踪

事件定义
事件类型描述关键数据字段
workflow_started执行已初始化。workflow_run_id、created_at
node_started特定节点开始执行。node_id、node_type、inputs
node_finished节点执行完成。outputs、elapsed_time、execution_metadata
workflow_finished整个图执行完成。outputs、total_tokens、total_steps
error执行因异常而中断。code、message
节点追踪元数据

node_finished 事件包含 execution_metadata，这对可观测性至关重要。该元数据在工作流运行期间捕获，并存储在 WorkflowRun 模型中 api/models/workflow.py:200-220。

来源：api/controllers/service_api/app/workflow.py:93-110，api/services/workflow_app_service.py:100-120

分布式追踪 (trace_id)

Dify 支持传递 trace_id，以便将工作流执行与外部可观测性工具（如 Langfuse 或 LangSmith）关联起来。WorkflowApi 使用 get_external_trace_id 辅助函数提取外部追踪 ID api/controllers/service_api/app/workflow.py:230-231。

解析优先级：

  1. 请求头：X-Trace-Id api/core/helper/trace_id_helper.py:10-15
  2. 查询字符串：?trace_id=...
  3. 请求体：{ "trace_id": "..." }

来源：api/core/helper/trace_id_helper.py:5-25，api/controllers/service_api/app/workflow.py:230-235

错误处理

执行过程中遇到的错误会以标准 HTTP 状态码（阻塞模式）或 error 事件（流式模式）的形式返回。

异常类HTTP 状态码含义
BadRequest400参数无效或 JSON 格式错误 api/controllers/service_api/app/workflow.py:11。
ProviderQuotaExceededError400模型提供商的额度或配额已耗尽 api/controllers/service_api/app/workflow.py:22。
WorkflowNotFoundError404请求的工作流 ID 不存在 api/controllers/service_api/app/workflow.py:48。
InternalServerError500引擎中发生了意外错误 api/controllers/service_api/app/workflow.py:11。

WorkflowApi 使用 validate_app_token 和错误映射逻辑，将核心引擎异常包装为用户友好的 HTTP 响应 api/controllers/service_api/app/workflow.py:216-250。

来源：api/controllers/service_api/app/workflow.py:17-25，api/controllers/service_api/app/error.py:1-30