From 227f49a0cc5a9073e88445dc2055b340a5fce89c Mon Sep 17 00:00:00 2001 From: kurokobo Date: Sat, 26 Oct 2024 11:43:47 +0900 Subject: [PATCH] docs: improve api documentation for advanced chat and workflow (#9882) --- .../template/template_advanced_chat.en.mdx | 8 +- .../template/template_advanced_chat.zh.mdx | 5 +- .../develop/template/template_workflow.en.mdx | 76 +++++++++++++++++++ .../develop/template/template_workflow.zh.mdx | 74 ++++++++++++++++++ 4 files changed, 158 insertions(+), 5 deletions(-) diff --git a/web/app/components/develop/template/template_advanced_chat.en.mdx b/web/app/components/develop/template/template_advanced_chat.en.mdx index 71fa7c1a09..7d80367ce4 100644 --- a/web/app/components/develop/template/template_advanced_chat.en.mdx +++ b/web/app/components/develop/template/template_advanced_chat.en.mdx @@ -47,7 +47,9 @@ Chat applications support session persistence, allowing previous chat history to 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. Default `{}` + 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. + If the variable is of file type, specify an object that has the keys described in `files` below. + Default `{}` The mode of response return, supporting: @@ -307,8 +309,8 @@ Chat applications support session persistence, allowing previous chat history to /> - 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. + Upload a file for use when sending messages, enabling multimodal understanding of images and text. + Supports any formats that are supported by your application. Uploaded files are for use by the current end-user only. ### Request Body diff --git a/web/app/components/develop/template/template_advanced_chat.zh.mdx b/web/app/components/develop/template/template_advanced_chat.zh.mdx index 32dcec135b..690d700f05 100755 --- a/web/app/components/develop/template/template_advanced_chat.zh.mdx +++ b/web/app/components/develop/template/template_advanced_chat.zh.mdx @@ -46,6 +46,7 @@ import { Row, Col, Properties, Property, Heading, SubProperty } from '../md.tsx' 允许传入 App 定义的各变量值。 inputs 参数包含了多组键值对（Key/Value pairs），每组的键对应一个特定变量，每组的值则是该变量的具体值。 + 如果变量是文件类型，请指定一个包含以下 `files` 中所述键的对象。 默认 `{}` @@ -317,8 +318,8 @@ import { Row, Col, Properties, Property, Heading, SubProperty } from '../md.tsx' /> - 上传文件（目前仅支持图片）并在发送消息时使用，可实现图文多模态理解。 - 支持 png, jpg, jpeg, webp, gif 格式。 + 上传文件并在发送消息时使用，可实现图文多模态理解。 + 支持您的应用程序所支持的所有格式。 上传的文件仅供当前终端用户使用。 ### Request Body diff --git a/web/app/components/develop/template/template_workflow.en.mdx b/web/app/components/develop/template/template_workflow.en.mdx index db39e61e36..6cb02bf844 100644 --- a/web/app/components/develop/template/template_workflow.en.mdx +++ b/web/app/components/develop/template/template_workflow.en.mdx @@ -44,6 +44,7 @@ Workflow applications offers non-session support and is ideal for translation, a 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. + If the variable is of File type, specify an object that has the keys described in `files` below. - `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)). @@ -328,6 +329,81 @@ Workflow applications offers non-session support and is ideal for translation, a --- + + + + Upload a file for use when sending messages, enabling multimodal understanding of images and text. + Supports any formats that are supported by your workflow. + 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, + } + ``` + + + + +--- + + + + 上传文件并在发送消息时使用，可实现图文多模态理解。 + 支持您的工作流程所支持的任何格式。 + 上传的文件仅供当前终端用户使用。 + + ### Request Body + 该接口需使用 `multipart/form-data` 进行请求。 + + + 要上传的文件。 + + + 用户标识，用于定义终端用户的身份，必须和发送消息接口传入 user 保持一致。 + + + + ### Response + 成功上传后，服务器会返回文件的 ID 和相关信息。 + - `id` (uuid) ID + - `name` (string) 文件名 + - `size` (int) 文件大小（byte） + - `extension` (string) 文件后缀 + - `mime_type` (string) 文件 mime-type + - `created_by` (uuid) 上传人 ID + - `created_at` (timestamp) 上传时间 + + ### Errors + - 400，`no_file_uploaded`，必须提供文件 + - 400，`too_many_files`，目前只接受一个文件 + - 400，`unsupported_preview`，该文件不支持预览 + - 400，`unsupported_estimate`，该文件不支持估算 + - 413，`file_too_large`，文件太大 + - 415，`unsupported_file_type`，不支持的扩展名，当前只接受文档类文件 + - 503，`s3_connection_failed`，无法连接到 S3 服务 + - 503，`s3_permission_denied`，无权限上传文件到 S3 + - 503，`s3_file_too_large`，文件超出 S3 大小限制 + + + + + + ```bash {{ title: 'cURL' }} + curl -X POST '${props.appDetail.api_base_url}/files/upload' \ + --header 'Authorization: Bearer {api_key}' \ + --form 'file=@"/path/to/file"' + ``` + + + + + ```json {{ title: 'Response' }} + { + "id": "72fa9618-8f89-4a37-9b33-7e1178a24a67", + "name": "example.png", + "size": 1024, + "extension": "png", + "mime_type": "image/png", + "created_by": 123, + "created_at": 1577836800, + } + ``` + + + +--- +