diff --git a/web/app/components/develop/template/template_workflow.en.mdx b/web/app/components/develop/template/template_workflow.en.mdx index 09b46f7e35..769e2b25bd 100644 --- a/web/app/components/develop/template/template_workflow.en.mdx +++ b/web/app/components/develop/template/template_workflow.en.mdx @@ -75,7 +75,7 @@ Workflow applications offers non-session support and is ideal for translation, a - `error` (string) Optional reason of error - `elapsed_time` (float) Optional total seconds to be used - `total_tokens` (int) Optional tokens to be used - - `total_steps` (int) defualt 0 + - `total_steps` (int) default 0 - `created_at` (timestamp) start time - `finished_at` (timestamp) end time @@ -140,7 +140,7 @@ Workflow applications offers non-session support and is ideal for translation, a - `error` (string) Optional reason of error - `elapsed_time` (float) Optional total seconds to be used - `total_tokens` (int) Optional tokens to be used - - `total_steps` (int) defualt 0 + - `total_steps` (int) default 0 - `created_at` (timestamp) start time - `finished_at` (timestamp) end time - `event: text_chunk` Output text in chunks @@ -219,79 +219,6 @@ Workflow applications offers non-session support and is ideal for translation, a ---- - - - - Upload a file (currently only images are supported) for use when sending messages, enabling multimodal understanding of images and text. - Supports png, jpg, jpeg, webp, gif formats. - Uploaded files are for use by the current end-user only. - - ### Request Body - This interface requires a `multipart/form-data` request. - - `file` (File) Required - The file to be uploaded. - - `user` (string) Required - User identifier, defined by the developer's rules, must be unique within the application. - - ### Response - After a successful upload, the server will return the file's ID and related information. - - `id` (uuid) ID - - `name` (string) File name - - `size` (int) File size (bytes) - - `extension` (string) File extension - - `mime_type` (string) File mime-type - - `created_by` (uuid) End-user ID - - `created_at` (timestamp) Creation timestamp, e.g., 1705395332 - - ### Errors - - 400, `no_file_uploaded`, a file must be provided - - 400, `too_many_files`, currently only one file is accepted - - 400, `unsupported_preview`, the file does not support preview - - 400, `unsupported_estimate`, the file does not support estimation - - 413, `file_too_large`, the file is too large - - 415, `unsupported_file_type`, unsupported extension, currently only document files are accepted - - 503, `s3_connection_failed`, unable to connect to S3 service - - 503, `s3_permission_denied`, no permission to upload files to S3 - - 503, `s3_file_too_large`, file exceeds S3 size limit - - 500, internal server error - - - - - ### Request Example - - - ```bash {{ title: 'cURL' }} - curl -X POST '${props.appDetail.api_base_url}/files/upload' \ - --header 'Authorization: Bearer {api_key}' \ - --form 'file=@"/path/to/file"' - ``` - - - - - ### Response Example - - ```json {{ title: 'Response' }} - { - "id": "72fa9618-8f89-4a37-9b33-7e1178a24a67", - "name": "example.png", - "size": 1024, - "extension": "png", - "mime_type": "image/png", - "created_by": "6ad1ab0a-73ff-4ac1-b9e4-cdb312f71f13", - "created_at": 1577836800, - } - ``` - - - --- ### Base URL @@ -14,10 +14,9 @@ Workflow applications offers non-session support and is ideal for translation, a ### Authentication - The Service API uses `API-Key` authentication. - **Strongly recommend storing your API Key on the server-side, not shared or stored on the client-side, to avoid possible API-Key leakage that can lead to serious consequences.** - - For all API requests, include your API Key in the `Authorization`HTTP Header, as shown below: + Dify Service API 使用 `API-Key` 进行鉴权。 + **强烈建议开发者把 `API-Key` 放在后端存储,而非分享或者放在客户端存储,以免 `API-Key` 泄露,导致财产损失。** + 所有 API 请求都应在 **`Authorization`** HTTP Header 中包含您的 `API-Key`,如下所示: ```javascript @@ -32,139 +31,138 @@ Workflow applications offers non-session support and is ideal for translation, a - Execute workflow, cannot be executed without a published workflow. + 执行 workflow,没有已发布的 workflow,不可执行。 ### Request Body - `inputs` (object) Required - Allows the entry of various variable values defined by the App. - The `inputs` parameter contains multiple key/value pairs, with each key corresponding to a specific variable and each value being the specific value for that variable. - The workflow application requires at least one key/value pair to be inputted. + 允许传入 App 定义的各变量值。 + inputs 参数包含了多组键值对(Key/Value pairs),每组的键对应一个特定变量,每组的值则是该变量的具体值。 - `response_mode` (string) Required - The mode of response return, supporting: - - `streaming` Streaming mode (recommended), implements a typewriter-like output through SSE ([Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events)). - - `blocking` Blocking mode, returns result after execution is complete. (Requests may be interrupted if the process is long) - Due to Cloudflare restrictions, the request will be interrupted without a return after 100 seconds. + 返回响应模式,支持: + - `streaming` 流式模式(推荐)。基于 SSE(**[Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events)**)实现类似打字机输出方式的流式返回。 + - `blocking` 阻塞模式,等待执行完毕后返回结果。(请求若流程较长可能会被中断)。 + 由于 Cloudflare 限制,请求会在 100 秒超时无返回后中断。 - `user` (string) Required - User identifier, used to define the identity of the end-user for retrieval and statistics. - Should be uniquely defined by the developer within the application. + 用户标识,用于定义终端用户的身份,方便检索、统计。 + 由开发者定义规则,需保证用户标识在应用内唯一。 - `files` (array[object]) Optional - File list, suitable for inputting files (images) combined with text understanding and answering questions, available only when the model supports Vision capability. - - `type` (string) Supported type: `image` (currently only supports image type) - - `transfer_method` (string) Transfer method, `remote_url` for image URL / `local_file` for file upload - - `url` (string) Image URL (when the transfer method is `remote_url`) - - `upload_file_id` (string) Uploaded file ID, which must be obtained by uploading through the File Upload API in advance (when the transfer method is `local_file`) + 文件列表,适用于传入文件(图片)结合文本理解并回答问题,仅当模型支持 Vision 能力时可用。 + - `type` (string) 支持类型:图片 `image`(目前仅支持图片格式)。 + - `transfer_method` (string) 传递方式,`remote_url` 图片地址 / `local_file` 上传文件 + - `url` (string) 图片地址(仅当传递方式为 `remote_url` 时) + - `upload_file_id` (string) (string) 上传文件 ID(仅当传递方式为 `local_file` 时) ### Response - When `response_mode` is `blocking`, return a CompletionResponse object. - When `response_mode` is `streaming`, return a ChunkCompletionResponse stream. + 当 `response_mode` 为 `blocking` 时,返回 CompletionResponse object。 + 当 `response_mode` 为 `streaming`时,返回 ChunkCompletionResponse object 流式序列。 ### CompletionResponse - Returns the App result, `Content-Type` is `application/json`. - - `log_id` (string) Unique log ID - - `task_id` (string) Task ID, used for request tracking and the below Stop Generate API - - `data` (object) detail of result - - `id` (string) ID of workflow execution - - `workflow_id` (string) ID of relatied workflow - - `status` (string) status of execution, `running` / `succeeded` / `failed` / `stopped` - - `outputs` (json) Optional content of output - - `error` (string) Optional reason of error - - `elapsed_time` (float) Optional total seconds to be used - - `total_tokens` (int) Optional tokens to be used - - `total_steps` (int) defualt 0 - - `created_at` (timestamp) start time - - `finished_at` (timestamp) end time + 返回完整的 App 结果,`Content-Type` 为 `application/json` 。 + - `log_id` (string) 日志 ID + - `task_id` (string) 任务 ID,用于请求跟踪和下方的停止响应接口 + - `data` (object) 详细内容 + - `id` (string) workflow 执行 ID + - `workflow_id` (string) 关联 Workflow ID + - `status` (string) 执行状态, `running` / `succeeded` / `failed` / `stopped` + - `outputs` (json) Optional 输出内容 + - `error` (string) Optional 错误原因 + - `elapsed_time` (float) Optional 耗时(s) + - `total_tokens` (int) Optional 总使用 tokens + - `total_steps` (int) 总步数(冗余),默认 0 + - `created_at` (timestamp) 开始时间 + - `finished_at` (timestamp) 结束时间 ### ChunkCompletionResponse - Returns the stream chunks outputted by the App, `Content-Type` is `text/event-stream`. - Each streaming chunk starts with `data:`, separated by two newline characters `\n\n`, as shown below: + 返回 App 输出的流式块,`Content-Type` 为 `text/event-stream`。 + 每个流式块均为 data: 开头,块之间以 `\n\n` 即两个换行符分隔,如下所示: ```streaming {{ title: 'Response' }} data: {"event": "message", "task_id": "900bbd43-dc0b-4383-a372-aa6e6c414227", "id": "663c5084-a254-4040-8ad3-51f2a3c1a77c", "answer": "Hi", "created_at": 1705398420}\n\n ``` - The structure of the streaming chunks varies depending on the `event`: - - `event: workflow_started` workflow starts execution - - `task_id` (string) Task ID, used for request tracking and the below Stop Generate API - - `workflow_run_id` (string) Unique ID of workflow execution - - `event` (string) fixed to `workflow_started` - - `data` (object) detail - - `id` (string) Unique ID of workflow execution - - `workflow_id` (string) ID of relatied workflow - - `sequence_number` (int) Self-increasing serial number, self-increasing in the App, starting from 1 - - `created_at` (timestamp) Creation timestamp, e.g., 1705395332 - - `event: node_started` node execution started - - `task_id` (string) Task ID, used for request tracking and the below Stop Generate API - - `workflow_run_id` (string) Unique ID of workflow execution - - `event` (string) fixed to `node_started` - - `data` (object) detail - - `id` (string) Unique ID of workflow execution - - `node_id` (string) ID of node - - `index` (int) Execution sequence number, used to display Tracing Node sequence - - `predecessor_node_id` (string) optional Prefix node ID, used for canvas display execution path - - `inputs` (array[object]) Contents of all preceding node variables used in the node - - `created_at` (timestamp) timestamp of start, e.g., 1705395332 - - `event: node_finished` node execution ends, success or failure in different states in the same event - - `task_id` (string) Task ID, used for request tracking and the below Stop Generate API - - `workflow_run_id` (string) Unique ID of workflow execution - - `event` (string) fixed to `node_finished` - - `data` (object) detail - - `id` (string) Unique ID of workflow execution - - `node_id` (string) ID of node - - `index` (int) Execution sequence number, used to display Tracing Node sequence - - `predecessor_node_id` (string) optional Prefix node ID, used for canvas display execution path - - `inputs` (array[object]) Contents of all preceding node variables used in the node - - `process_data` (json) Optional node process data - - `outputs` (json) Optional content of output - - `status` (string) status of execution, `running` / `succeeded` / `failed` / `stopped` - - `error` (string) Optional reason of error - - `elapsed_time` (float) Optional total seconds to be used - - `execution_metadata` (json) meta data - - `total_tokens` (int) optional tokens to be used - - `total_price` (decimal) optional Total cost - - `currency` (string) optional e.g. `USD` / `RMB` - - `created_at` (timestamp) timestamp of start, e.g., 1705395332 - - `event: workflow_finished` workflow execution ends, success or failure in different states in the same event - - `task_id` (string) Task ID, used for request tracking and the below Stop Generate API - - `workflow_run_id` (string) Unique ID of workflow execution - - `event` (string) fixed to `workflow_finished` - - `data` (object) detail - - `id` (string) ID of workflow execution - - `workflow_id` (string) ID of relatied workflow - - `status` (string) status of execution, `running` / `succeeded` / `failed` / `stopped` - - `outputs` (json) Optional content of output - - `error` (string) Optional reason of error - - `elapsed_time` (float) Optional total seconds to be used - - `total_tokens` (int) Optional tokens to be used - - `total_steps` (int) defualt 0 - - `created_at` (timestamp) start time - - `finished_at` (timestamp) end time - - `event: text_chunk` Output text in chunks - - `task_id` (string) Task ID, used for request tracking and the below Stop Generate API - - `workflow_run_id` (string) Unique ID of workflow execution - - `event` (string) fixed to `text_chunk` - - `data` (object) detail - - `text` (string) Output text in chunks - - `event: text_replace` Output text replacement - - `task_id` (string) Task ID, used for request tracking and the below Stop Generate API - - `workflow_run_id` (string) Unique ID of workflow execution - - `event` (string) fixed to `text_replacement` - - `data` (object) detail - - `text` (string) Output text in chunks - - `event: ping` Ping event every 10 seconds to keep the connection alive. + 流式块中根据 `event` 不同,结构也不同,包含以下类型: + - `event: workflow_started` workflow 开始执行 + - `task_id` (string) 任务 ID,用于请求跟踪和下方的停止响应接口 + - `workflow_run_id` (string) workflow 执行 ID + - `event` (string) 固定为 `workflow_started` + - `data` (object) 详细内容 + - `id` (string) workflow 执行 ID + - `workflow_id` (string) 关联 Workflow ID + - `sequence_number` (int) 自增序号,App 内自增,从 1 开始 + - `created_at` (timestamp) 开始时间 + - `event: node_started` node 开始执行 + - `task_id` (string) 任务 ID,用于请求跟踪和下方的停止响应接口 + - `workflow_run_id` (string) workflow 执行 ID + - `event` (string) 固定为 `node_started` + - `data` (object) 详细内容 + - `id` (string) workflow 执行 ID + - `node_id` (string) 节点 ID + - `index` (int) 执行序号,用于展示 Tracing Node 顺序 + - `predecessor_node_id` (string) 前置节点 ID,用于画布展示执行路径 + - `inputs` (array[object]) 节点中所有使用到的前置节点变量内容 + - `created_at` (timestamp) 开始时间 + - `event: node_finished` node 执行结束,成功失败同一事件中不同状态 + - `task_id` (string) 任务 ID,用于请求跟踪和下方的停止响应接口 + - `workflow_run_id` (string) workflow 执行 ID + - `event` (string) 固定为 `node_finished` + - `data` (object) 详细内容 + - `id` (string) node 执行 ID + - `node_id` (string) 节点 ID + - `index` (int) 执行序号,用于展示 Tracing Node 顺序 + - `predecessor_node_id` (string) optional 前置节点 ID,用于画布展示执行路径 + - `inputs` (array[object]) 节点中所有使用到的前置节点变量内容 + - `process_data` (json) Optional 节点过程数据 + - `outputs` (json) Optional 输出内容 + - `status` (string) 执行状态 `running` / `succeeded` / `failed` / `stopped` + - `error` (string) Optional 错误原因 + - `elapsed_time` (float) Optional 耗时(s) + - `execution_metadata` (json) 元数据 + - `total_tokens` (int) optional 总使用 tokens + - `total_price` (decimal) optional 总费用 + - `currency` (string) optional 货币,如 `USD` / `RMB` + - `created_at` (timestamp) 开始时间 + - `event: workflow_finished` workflow 执行结束,成功失败同一事件中不同状态 + - `task_id` (string) 任务 ID,用于请求跟踪和下方的停止响应接口 + - `workflow_run_id` (string) workflow 执行 ID + - `event` (string) 固定为 `workflow_finished` + - `data` (object) 详细内容 + - `id` (string) workflow 执行 ID + - `workflow_id` (string) 关联 Workflow ID + - `status` (string) 执行状态 `running` / `succeeded` / `failed` / `stopped` + - `outputs` (json) Optional 输出内容 + - `error` (string) Optional 错误原因 + - `elapsed_time` (float) Optional 耗时(s) + - `total_tokens` (int) Optional 总使用 tokens + - `total_steps` (int) 总步数(冗余),默认 0 + - `created_at` (timestamp) 开始时间 + - `finished_at` (timestamp) 结束时间 + - `event: text_chunk` 输出文本块 + - `task_id` (string) 任务 ID,用于请求跟踪和下方的停止响应接口 + - `workflow_run_id` (string) workflow 执行 ID + - `event` (string) 固定为 `text_chunk` + - `data` (object) 详细内容 + - `text` (string) 输出文本块 + - `event: text_replace` 输出文本替换 + - `task_id` (string) 任务 ID,用于请求跟踪和下方的停止响应接口 + - `workflow_run_id` (string) workflow 执行 ID + - `event` (string) 固定为 `text_replacement` + - `data` (object) 详细内容 + - `text` (string) 输出文本块 + - `event: ping` 每 10s 一次的 ping 事件,保持连接存活。 ### Errors - - 400, `invalid_param`, abnormal parameter input - - 400, `app_unavailable`, App configuration unavailable - - 400, `provider_not_initialize`, no available model credential configuration - - 400, `provider_quota_exceeded`, model invocation quota insufficient - - 400, `model_currently_not_support`, current model unavailable - - 400, `workflow_request_error`, workflow execution failed - - 500, internal server error + - 400,`invalid_param`,传入参数异常 + - 400,`app_unavailable`,App 配置不可用 + - 400,`provider_not_initialize`,无可用模型凭据配置 + - 400,`provider_quota_exceeded`,模型调用额度不足 + - 400,`model_currently_not_support`,当前模型不可用 + - 400,`workflow_request_error`,workflow 执行失败 + - 500,服务内部异常 @@ -219,109 +217,36 @@ Workflow applications offers non-session support and is ideal for translation, a ---- - - - - Upload a file (currently only images are supported) for use when sending messages, enabling multimodal understanding of images and text. - Supports png, jpg, jpeg, webp, gif formats. - Uploaded files are for use by the current end-user only. - - ### Request Body - This interface requires a `multipart/form-data` request. - - `file` (File) Required - The file to be uploaded. - - `user` (string) Required - User identifier, defined by the developer's rules, must be unique within the application. - - ### Response - After a successful upload, the server will return the file's ID and related information. - - `id` (uuid) ID - - `name` (string) File name - - `size` (int) File size (bytes) - - `extension` (string) File extension - - `mime_type` (string) File mime-type - - `created_by` (uuid) End-user ID - - `created_at` (timestamp) Creation timestamp, e.g., 1705395332 - - ### Errors - - 400, `no_file_uploaded`, a file must be provided - - 400, `too_many_files`, currently only one file is accepted - - 400, `unsupported_preview`, the file does not support preview - - 400, `unsupported_estimate`, the file does not support estimation - - 413, `file_too_large`, the file is too large - - 415, `unsupported_file_type`, unsupported extension, currently only document files are accepted - - 503, `s3_connection_failed`, unable to connect to S3 service - - 503, `s3_permission_denied`, no permission to upload files to S3 - - 503, `s3_file_too_large`, file exceeds S3 size limit - - 500, internal server error - - - - - ### Request Example - - - ```bash {{ title: 'cURL' }} - curl -X POST '${props.appDetail.api_base_url}/files/upload' \ - --header 'Authorization: Bearer {api_key}' \ - --form 'file=@"/path/to/file"' - ``` - - - - - ### Response Example - - ```json {{ title: 'Response' }} - { - "id": "72fa9618-8f89-4a37-9b33-7e1178a24a67", - "name": "example.png", - "size": 1024, - "extension": "png", - "mime_type": "image/png", - "created_by": "6ad1ab0a-73ff-4ac1-b9e4-cdb312f71f13", - "created_at": 1577836800, - } - ``` - - - --- - Only supported in streaming mode. - ### Path - - `task_id` (string) Task ID, can be obtained from the streaming chunk return - ### Request Body - - `user` (string) Required - User identifier, used to define the identity of the end-user, must be consistent with the user passed in the send message interface. - ### Response - - `result` (string) Always returns "success" + 仅支持流式模式。 + ### Path + - `task_id` (string) 任务 ID,可在流式返回 Chunk 中获取 + ### Request Body + - `user` (string) Required + 用户标识,用于定义终端用户的身份,必须和发送消息接口传入 user 保持一致。 + ### Response + - `result` (string) 固定返回 "success" - ### Request Example - - ```bash {{ title: 'cURL' }} - curl -X POST '${props.appDetail.api_base_url}/workflows/:task_id/stop' \ - -H 'Authorization: Bearer {api_key}' \ - -H 'Content-Type: application/json' \ - --data-raw '{ - "user": "abc-123" - }' - ``` + ### Request Example + + ```bash {{ title: 'cURL' }} + curl -X POST '${props.appDetail.api_base_url}/workflows/:task_id/stop' \ + -H 'Authorization: Bearer {api_key}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "user": "abc-123" + }' + ``` ### Response Example @@ -340,47 +265,47 @@ Workflow applications offers non-session support and is ideal for translation, a - Used at the start of entering the page to obtain information such as features, input parameter names, types, and default values. + 用于进入页面一开始,获取功能开关、输入参数名称、类型及默认值等使用。 ### Query - User identifier, defined by the developer's rules, must be unique within the application. + 用户标识,由开发者定义规则,需保证用户标识在应用内唯一。 ### Response - - `user_input_form` (array[object]) User input form configuration - - `text-input` (object) Text input control - - `label` (string) Variable display label name - - `variable` (string) Variable ID - - `required` (bool) Whether it is required - - `default` (string) Default value - - `paragraph` (object) Paragraph text input control - - `label` (string) Variable display label name - - `variable` (string) Variable ID - - `required` (bool) Whether it is required - - `default` (string) Default value - - `select` (object) Dropdown control - - `label` (string) Variable display label name - - `variable` (string) Variable ID - - `required` (bool) Whether it is required - - `default` (string) Default value - - `options` (array[string]) Option values - - `file_upload` (object) File upload configuration - - `image` (object) Image settings - Currently only supports image types: `png`, `jpg`, `jpeg`, `webp`, `gif` - - `enabled` (bool) Whether it is enabled - - `number_limits` (int) Image number limit, default is 3 - - `transfer_methods` (array[string]) List of transfer methods, remote_url, local_file, must choose one - - `system_parameters` (object) System parameters - - `image_file_size_limit` (string) Image file upload size limit (MB) + - `user_input_form` (array[object]) 用户输入表单配置 + - `text-input` (object) 文本输入控件 + - `label` (string) 控件展示标签名 + - `variable` (string) 控件 ID + - `required` (bool) 是否必填 + - `default` (string) 默认值 + - `paragraph` (object) 段落文本输入控件 + - `label` (string) 控件展示标签名 + - `variable` (string) 控件 ID + - `required` (bool) 是否必填 + - `default` (string) 默认值 + - `select` (object) 下拉控件 + - `label` (string) 控件展示标签名 + - `variable` (string) 控件 ID + - `required` (bool) 是否必填 + - `default` (string) 默认值 + - `options` (array[string]) 选项值 + - `file_upload` (object) 文件上传配置 + - `image` (object) 图片设置 + 当前仅支持图片类型:`png`, `jpg`, `jpeg`, `webp`, `gif` + - `enabled` (bool) 是否开启 + - `number_limits` (int) 图片数量限制,默认 3 + - `transfer_methods` (array[string]) 传递方式列表,remote_url , local_file,必选一个 + - `system_parameters` (object) 系统参数 + - `image_file_size_limit` (string) 图片文件上传大小限制(MB)