docs: improve api documentation for advanced chat and workflow (#9882)

2025-08-12 02:09:02 +08:00 · 2024-10-26 11:43:47 +09:00 · 2024-10-26 11:43:47 +09:00 · 227f49a0cc
commit 227f49a0cc
parent a17f169e01
4 changed files with 158 additions and 5 deletions
--- 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
      </Property>
      <Property name='inputs' type='object' key='inputs'>
          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 `{}`
      </Property>
      <Property name='response_mode' type='string' key='response_mode'>
        The mode of response return, supporting:
@ -307,8 +309,8 @@ Chat applications support session persistence, allowing previous chat history to
 />
 <Row>
  <Col>
-  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
--- 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'
      <Property name='inputs' type='object' key='inputs'>
        允许传入 App 定义的各变量值。
        inputs 参数包含了多组键值对（Key/Value pairs），每组的键对应一个特定变量，每组的值则是该变量的具体值。
+        如果变量是文件类型，请指定一个包含以下 `files` 中所述键的对象。
        默认 `{}`
      </Property>
      <Property name='response_mode' type='string' key='response_mode'>
@ -317,8 +318,8 @@ import { Row, Col, Properties, Property, Heading, SubProperty } from '../md.tsx'
 />
 <Row>
  <Col>
-    上传文件（目前仅支持图片）并在发送消息时使用，可实现图文多模态理解。
-    支持 png, jpg, jpeg, webp, gif 格式。
+    上传文件并在发送消息时使用，可实现图文多模态理解。
+    支持您的应用程序所支持的所有格式。
    <i>上传的文件仅供当前终端用户使用。</i>

    ### Request Body
--- 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

 ---

+<Heading
+  url='/files/upload'
+  method='POST'
+  title='File Upload'
+  name='#file-upload'
+/>
+<Row>
+  <Col>
+  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
+
+
+  </Col>
+  <Col sticky>
+  ### Request Example
+  <CodeGroup title="Request" tag="POST" label="/files/upload" targetCode={`curl -X POST '${props.appDetail.api_base_url}/files/upload' \\\n--header 'Authorization: Bearer {api_key}' \\\n--form 'file=@localfile;type=image/[png|jpeg|jpg|webp|gif] \\\n--form 'user=abc-123'`}>
+
+    ```bash {{ title: 'cURL' }}
+    curl -X POST '${props.appDetail.api_base_url}/files/upload' \
+    --header 'Authorization: Bearer {api_key}' \
+    --form 'file=@"/path/to/file"'
+    ```
+
+    </CodeGroup>
+
+
+  ### Response Example
+  <CodeGroup title="Response">
+    ```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,
+    }
+  ```
+  </CodeGroup>
+  </Col>
+</Row>
+
+---
+
 <Heading
  url='/parameters'
  method='GET'
--- a/web/app/components/develop/template/template_workflow.zh.mdx
+++ b/web/app/components/develop/template/template_workflow.zh.mdx
@ -42,6 +42,7 @@ Workflow 应用无会话支持，适合用于翻译/文章写作/总结 AI 等
      - `inputs` (object) Required
        允许传入 App 定义的各变量值。
        inputs 参数包含了多组键值对（Key/Value pairs），每组的键对应一个特定变量，每组的值则是该变量的具体值。
+        如果变量是文件类型，请指定一个包含以下 `files` 中所述键的对象。
      - `response_mode` (string) Required
        返回响应模式，支持：
        - `streaming` 流式模式（推荐）。基于 SSE（**[Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events)**）实现类似打字机输出方式的流式返回。
@ -324,6 +325,79 @@ Workflow 应用无会话支持，适合用于翻译/文章写作/总结 AI 等

 ---

+<Heading
+  url='/files/upload'
+  method='POST'
+  title='上传文件'
+  name='#files-upload'
+/>
+<Row>
+  <Col>
+    上传文件并在发送消息时使用，可实现图文多模态理解。
+    支持您的工作流程所支持的任何格式。
+    <i>上传的文件仅供当前终端用户使用。</i>
+
+    ### Request Body
+    该接口需使用  `multipart/form-data` 进行请求。
+    <Properties>
+      <Property name='file' type='file' key='file'>
+        要上传的文件。
+      </Property>
+      <Property name='user' type='string' key='user'>
+          用户标识，用于定义终端用户的身份，必须和发送消息接口传入 user 保持一致。
+      </Property>
+    </Properties>
+
+    ### 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 大小限制
+  </Col>
+  <Col sticky>
+
+    <CodeGroup title="Request" tag="POST" label="/files/upload" targetCode={`curl -X POST '${props.appDetail.api_base_url}/files/upload' \\\n--header 'Authorization: Bearer {api_key}' \\\n--form 'file=@localfile;type=image/[png|jpeg|jpg|webp|gif] \\\n--form 'user=abc-123'`}>
+
+    ```bash {{ title: 'cURL' }}
+    curl -X POST '${props.appDetail.api_base_url}/files/upload' \
+    --header 'Authorization: Bearer {api_key}' \
+    --form 'file=@"/path/to/file"'
+    ```
+
+    </CodeGroup>
+
+    <CodeGroup title="Response">
+    ```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,
+    }
+    ```
+    </CodeGroup>
+  </Col>
+</Row>
+---
+
 <Heading
  url='/parameters'
  method='GET'