Dify-14: 工作流API端点-优快云博客

本文链接：https://blog.youkuaiyun.com/uncle_ll/article/details/149722653

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

工作流 API 概述

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

身份验证

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

Authorization: Bearer {API_KEY}

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

工作流执行端点

执行工作流

端点：POST /workflows/run
此端点允许执行已发布的工作流。

请求体：

参数	类型	必填	描述
inputs	object	是	工作流的输入变量字典。键对应于工作流中定义的变量名，值是这些变量的相应值。
response_mode	string	是	响应模式：“streaming”（推荐）或 “blocking”。
user	string	是	用于定义终端用户身份的用户标识符。

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

{
  "type": "document|image|audio|video|custom",
  "transfer_method": "remote_url|local_file",
  "url": "https://example.com/file.jpg",  // 当 transfer_method 为 remote_url 时
  "upload_file_id": "file-id"  // 当 transfer_method 为 local_file 时
}

响应：响应格式取决于response_mode 参数：

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

{
  "workflow_run_id": "workflow-run-id",
  "task_id": "task-id",
  "data": {
    "id": "workflow-execution-id",
    "workflow_id": "workflow-id",
    "status": "succeeded|failed|stopped",
    "outputs": {},
    "error": "error message (if any)",
    "elapsed_time": 1.23,
    "total_tokens": 1000,
    "total_steps": 5,
    "created_at": 1705395332,
    "finished_at": 1705395335
  }
}

流式模式：返回包含多个事件的 SSE（服务器发送事件）流，包括：
workflow_started：表示工作流执行已开始。
- node_started：表示工作流节点已开始执行。
node_finished：表示工作流节点已完成执行。
- workflow_finished：表示工作流执行已完成。
- tts_message：TTS 音频流事件（如果适用）。
- tts_message_end：TTS 音频流结束事件（如果适用）。

工作流执行过程

以下图表说明了工作流执行过程以及流式模式下发送的事件：

工作流控制端点

停止工作流执行

端点：POST /workflows/{task_id}/stop
此端点允许停止正在运行的工作流执行。

请求体：

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

响应：

{
  "result": "success"
}

获取工作流运行详情

端点：GET /workflows/{workflow_run_id}
此端点检索特定工作流运行的详细信息。

响应：

{
  "id": "workflow-run-id",
  "workflow_id": "workflow-id",
  "status": "running|succeeded|failed|stopped",
  "inputs": {},
  "outputs": {},
  "error": "error message (if any)",
  "total_steps": 5,
  "total_tokens": 1000,
  "created_at": 1705395332,
  "finished_at": 1705395335,
  "elapsed_time": 1.23
}

与聊天应用程序的集成

工作流可以与 Dify 中的聊天应用程序集成。当工作流作为聊天交互的一部分执行时，聊天 API 端点将在其流式响应中包含与工作流相关的事件。

在高级聊天 API 中，以下与工作流相关的事件可以包含在流式响应中：

workflow_started：表示工作流已开始执行。
node_started：表示工作流节点已开始执行。
node_finished：表示工作流节点已完成执行。
workflow_finished：表示工作流已完成执行。

这些事件的结构与工作流执行端点中描述的相同。

工作流中的文件处理

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

远程 URL：提供文件的 URL，Dify 将下载并处理它。
本地文件：首先使用文件上传 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 请求，包含以下字段：

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

响应：

{
  "id": "file-id",
  "name": "example.png",
  "size": 1024,
  "extension": "png",
  "mime_type": "image/png",
  "created_by": "user-id",
  "created_at": 1577836800
}

错误处理

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

状态码	错误码	描述
400	invalid_param	请求中的参数无效
400	app_unavailable	应用配置不可用
400	provider_not_initialize	没有可用的模型凭证配置
400	provider_quota_exceeded	模型调用配额已超出
400	model_currently_not_support	当前模型不可用
400	workflow_request_error	工作流执行失败
500	-	内部服务器错误

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

示例请求

curl -X POST 'https://api.dify.ai/v1/workflows/run' \
--header 'Authorization: Bearer {api_key}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "inputs": {
        "text_input": "Analyze this text for sentiment",
        "files": [
            {
                "type": "document",
                "transfer_method": "local_file",
                "upload_file_id": "72fa9618-8f89-4a37-9b33-7e1178a24a67"
            }
        ]
    },
    "response_mode": "streaming",
    "user": "user-123"
}'

示例流式响应

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}}