在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

langgenius/dify

菜单

工作流 API 端点

相关源文件

本文档提供了 Dify 中工作流 API 端点的全面文档，这些端点允许开发人员以编程方式执行、监控和管理工作流。这些端点是服务 API 层的一部分，允许外部应用程序与 Dify 的工作流功能集成。

有关聊天 API 端点的信息，请参阅 聊天 API 端点。有关完成 API 端点的信息，请参阅 完成 API 端点。

工作流 API 概述

工作流 API 提供了允许开发人员与 Dify 的工作流编排系统交互的端点。Dify 中的工作流代表一系列作为节点有向图组织的复杂操作，每个节点执行特定任务，如文本生成、数据处理或外部服务集成。

来源

身份验证

所有工作流 API 端点均使用 API 密钥进行身份验证。对于所有请求，您必须在 Authorization HTTP 标头中包含您的 API 密钥。

Authorization: Bearer {API_KEY}

强烈建议您将 API 密钥存储在服务器端，并且不要在客户端共享或存储，以防止潜在的安全漏洞。

来源

工作流执行端点

执行工作流

POST /workflows/run

此端点允许您执行已发布的（published）工作流。

请求体

参数类型必填描述
inputs对象是一个用于工作流的输入变量字典。键对应于工作流中定义的变量名，值对应于这些变量的相应值。
response_mode字符串是响应模式：可以是 streaming（推荐）或 blocking。
user字符串是用户标识符，用于定义最终用户。

对于文件输入，值应为具有以下结构的对象的列表

响应

响应格式取决于 response_mode 参数。

阻塞模式：返回具有以下结构的 JSON 对象。

流式模式：返回 SSE（服务器发送事件）流，包含多个事件，包括：

  • workflow_started：指示工作流执行已开始。
  • node_started：指示工作流节点已开始执行。
  • text_chunk：来自工作流节点的文本片段输出。
  • node_finished：指示工作流节点已完成执行。
  • workflow_finished：指示工作流执行已完成。
  • tts_message：TTS 音频流事件（如果适用）。
  • tts_message_end：TTS 音频流结束事件（如果适用）。
  • ping：周期性 ping 事件，用于保持连接活动。

来源

工作流执行流程

下图说明了工作流执行过程以及在流式传输模式下发送的事件。

工作流执行事件流程

来源

工作流控制端点

停止工作流执行

POST /workflows/{task_id}/stop

此端点允许您停止正在运行的工作流执行。

请求体

参数类型必填描述
user字符串是用户标识符，必须与执行请求中使用的标识符匹配。

响应

来源

获取工作流运行详情

GET /workflows/{workflow_run_id}

此端点用于检索特定工作流运行的详细信息。

响应

来源

带工作流集成的高级聊天

Dify 中的高级聊天应用程序可以将工作流执行作为其对话流程的一部分进行集成。在使用高级聊天 API（POST /chat-messages）时，工作流相关事件会包含在流式响应中。

聊天 API 中的工作流集成

高级聊天中的工作流事件

当高级聊天应用程序包含工作流执行时，流式响应将包含这些特定于工作流的事件：

事件描述数据结构
workflow_started工作流执行开始包含 workflow_run_id、workflow_id、sequence_number。
node_started单个工作流节点开始包含 node_id、node_type、title、inputs。
node_finished单个工作流节点完成包含 outputs、status、elapsed_time、execution_metadata。
workflow_finished工作流执行完成包含 outputs、status、total_tokens、total_steps。

高级聊天工作流响应示例

data: {"event": "workflow_started", "task_id": "abc-123", "workflow_run_id": "run-456", "data": {"id": "run-456", "workflow_id": "wf-789", "sequence_number": 1, "created_at": 1679586595}}

data: {"event": "node_started", "task_id": "abc-123", "workflow_run_id": "run-456", "data": {"node_id": "llm-node-1", "node_type": "llm", "title": "Text Analysis", "index": 1, "inputs": {"text": "user input"}}}

data: {"event": "node_finished", "task_id": "abc-123", "workflow_run_id": "run-456", "data": {"node_id": "llm-node-1", "status": "succeeded", "outputs": {"result": "analysis complete"}, "elapsed_time": 1.2}}

data: {"event": "message", "message_id": "msg-123", "conversation_id": "conv-456", "answer": "Based on the analysis...", "created_at": 1679586597}

data: {"event": "workflow_finished", "task_id": "abc-123", "workflow_run_id": "run-456", "data": {"status": "succeeded", "total_tokens": 150, "total_steps": 3}}

来源

文件处理工作流

工作流支持文件输入，这些文件可以被工作流节点处理。文件可以通过两种方式提供：

  1. 远程 URL：您提供文件的 URL，Dify 将下载并处理它。
  2. 本地文件：您首先使用文件上传 API 上传文件，然后在工作流执行请求中提供文件 ID。

支持的文件类型

类别支持的扩展名
文档TXT, MD, MARKDOWN, PDF, HTML, XLSX, XLS, DOCX, CSV, EML, MSG, PPTX, PPT, XML, EPUB
图片JPG, JPEG, PNG, GIF, WEBP, SVG
音频MP3, M4A, WAV, WEBM, AMR
视频MP4, MOV, MPEG, MPGA
自定义其他文件类型

文件上传 API

POST /files/upload

此端点允许您上传文件供工作流执行使用。

请求

这是一个 multipart/form-data 请求，包含以下字段：

字段类型必填描述
filefile是要上传的文件
user字符串是用户标识符

响应

来源

错误处理

工作流 API 可能返回以下错误：

状态码错误代码描述
400invalid_param请求中的参数无效
400app_unavailable应用程序配置不可用
400provider_not_initialize没有可用的模型凭据配置
400provider_quota_exceeded已超出模型调用配额
400model_currently_not_support当前模型不可用
400workflow_request_error工作流执行失败
500Internal server error

来源

工作流 API 请求/响应完整示例

示例请求

流式响应示例

data: {"event": "workflow_started", "task_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "workflow_run_id": "5ad498-f0c7-4085-b384-88cbe6290", "data": {"id": "5ad498-f0c7-4085-b384-88cbe6290", "workflow_id": "dfjasklfjdslag", "sequence_number": 1, "created_at": 1679586595}}

data: {"event": "node_started", "task_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "workflow_run_id": "5ad498-f0c7-4085-b384-88cbe6290", "data": {"id": "5ad498-f0c7-4085-b384-88cbe6290", "node_id": "dfjasklfjdslag", "node_type": "start", "title": "Start", "index": 0, "predecessor_node_id": "fdljewklfklgejlglsd", "inputs": {}, "created_at": 1679586595}}

data: {"event": "node_finished", "task_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "workflow_run_id": "5ad498-f0c7-4085-b384-88cbe6290", "data": {"id": "5ad498-f0c7-4085-b384-88cbe6290", "node_id": "dfjasklfjdslag", "node_type": "start", "title": "Start", "index": 0, "predecessor_node_id": "fdljewklfklgejlglsd", "inputs": {}, "outputs": {}, "status": "succeeded", "elapsed_time": 0.324, "execution_metadata": {"total_tokens": 63127864, "total_price": 2.378, "currency": "USD"}, "created_at": 1679586595}}

data: {"event": "workflow_finished", "task_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "workflow_run_id": "5ad498-f0c7-4085-b384-88cbe6290", "data": {"id": "5ad498-f0c7-4085-b384-88cbe6290", "workflow_id": "dfjasklfjdslag", "outputs": {}, "status": "succeeded", "elapsed_time": 0.324, "total_tokens": 63127864, "total_steps": "1", "created_at": 1679586595, "finished_at": 1679976595}}

来源

结论

工作流 API 端点提供了一种强大的方式，可以将 Dify 的工作流编排功能集成到您的应用程序中。通过使用这些端点，您可以以编程方式执行复杂的工作流、监控其进度并检索其结果。

有关在 Dify UI 中创建和管理工作流的更多信息，请参阅 工作流系统 文档中的工作流系统。