diff --git a/web/app/components/develop/doc.tsx b/web/app/components/develop/doc.tsx index d3fc9b29bd..ade695e314 100644 --- a/web/app/components/develop/doc.tsx +++ b/web/app/components/develop/doc.tsx @@ -24,15 +24,18 @@ const Doc = ({ appDetail }: IDocProps) => { return (
+ {(appDetail?.mode === 'chat' || appDetail?.mode === 'agent-chat') && ( + locale !== LanguagesSupported[1] ? : + )} + {appDetail?.mode === 'advanced-chat' && ( + locale !== LanguagesSupported[1] ? : + )} {appDetail?.mode === 'workflow' && ( locale !== LanguagesSupported[1] ? : )} {appDetail?.mode === 'completion' && ( locale !== LanguagesSupported[1] ? : )} - {(appDetail?.mode !== 'completion' && appDetail?.mode !== 'workflow') && ( - locale !== LanguagesSupported[1] ? : - )}
) } diff --git a/web/app/components/develop/template/template_advanced_chat.en.mdx b/web/app/components/develop/template/template_advanced_chat.en.mdx new file mode 100644 index 0000000000..86d15608b3 --- /dev/null +++ b/web/app/components/develop/template/template_advanced_chat.en.mdx @@ -0,0 +1,1059 @@ +import { CodeGroup } from '../code.tsx' +import { Row, Col, Properties, Property, Heading, SubProperty, Paragraph } from '../md.tsx' + +# Advanced Chat App API + +Chat applications support session persistence, allowing previous chat history to be used as context for responses. This can be applicable for chatbots, customer service AI, etc. + +
+ ### Base URL + + ```javascript + ``` + + + ### 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: + + + ```javascript + Authorization: Bearer {API_KEY} + + ``` + +
+ +--- + + + + + Send a request to the chat application. + + ### Request Body + + + + User Input/Question content + + + 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 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. + + + 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. + + + Converation ID, to continue the conversation based on previous chat records, it is necessary to pass the previous message's conversation_id. + + + 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`) + + + Auto-generate title, default is `true`. + If set to `false`, can achieve async title generation by calling the conversation rename API and setting `auto_generate` to `true`. + + + + ### Response + When response_mode is blocking, return a CompletionResponse object. + When response_mode is streaming, return a ChunkCompletionResponse stream. + + ### ChatCompletionResponse + Returns the complete App result, `Content-Type` is `application/json`. + - `message_id` (string) Unique message ID + - `conversation_id` (string) Conversation ID + - `mode` (string) App mode, fixed as `chat` + - `answer` (string) Complete response content + - `metadata` (object) Metadata + - `usage` (Usage) Model usage information + - `retriever_resources` (array[RetrieverResource]) Citation and Attribution List + - `created_at` (int) Message creation timestamp, e.g., 1705395332 + + ### ChunkChatCompletionResponse + 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: + + ```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: message` LLM returns text chunk event, i.e., the complete text is output in a chunked fashion. + - `task_id` (string) Task ID, used for request tracking and the below Stop Generate API + - `message_id` (string) Unique message ID + - `conversation_id` (string) Conversation ID + - `answer` (string) LLM returned text chunk content + - `created_at` (int) Creation timestamp, e.g., 1705395332 + - `event: message_file` Message file event, a new file has created by tool + - `id` (string) File unique ID + - `type` (string) File type，only allow "image" currently + - `belongs_to` (string) Belongs to, it will only be an 'assistant' here + - `url` (string) Remote url of file + - `conversation_id` (string) Conversation ID + - `event: message_end` Message end event, receiving this event means streaming has ended. + - `task_id` (string) Task ID, used for request tracking and the below Stop Generate API + - `message_id` (string) Unique message ID + - `conversation_id` (string) Conversation ID + - `metadata` (object) Metadata + - `usage` (Usage) Model usage information + - `retriever_resources` (array[RetrieverResource]) Citation and Attribution List + - `event: message_replace` Message content replacement event. + When output content moderation is enabled, if the content is flagged, then the message content will be replaced with a preset reply through this event. + - `task_id` (string) Task ID, used for request tracking and the below Stop Generate API + - `message_id` (string) Unique message ID + - `conversation_id` (string) Conversation ID + - `answer` (string) Replacement content (directly replaces all LLM reply text) + - `created_at` (int) Creation timestamp, e.g., 1705395332 + - `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 + - `node_type` (string) type of node + - `title` (string) name 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 + - `node_type` (string) type of node + - `title` (string) name 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) default 0 + - `created_at` (timestamp) start time + - `finished_at` (timestamp) end time + - `event: error` + Exceptions that occur during the streaming process will be output in the form of stream events, and reception of an error event will end the stream. + - `task_id` (string) Task ID, used for request tracking and the below Stop Generate API + - `message_id` (string) Unique message ID + - `status` (int) HTTP status code + - `code` (string) Error code + - `message` (string) Error message + - `event: ping` Ping event every 10 seconds to keep the connection alive. + + ### Errors + - 404, Conversation does not exists + - 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, `completion_request_error`, text generation failed + - 500, internal server error + + + + + + + ```bash {{ title: 'cURL' }} + curl -X POST '${props.appDetail.api_base_url}/chat-messages' \ + --header 'Authorization: Bearer {api_key}' \ + --header 'Content-Type: application/json' \ + --data-raw '{ + "inputs": {}, + "query": "eh", + "response_mode": "streaming", + "conversation_id": "1c7e55fb-1ba2-4e10-81b5-30addcea2276", + "user": "abc-123" + }' + ``` + + ### Blocking Mode + + ```json {{ title: 'Response' }} + { + "event": "message", + "message_id": "9da23599-e713-473b-982c-4328d4f5c78a", + "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", + "mode": "chat", + "answer": "iPhone 13 Pro Max specs are listed heere:...", + "metadata": { + "usage": { + "prompt_tokens": 1033, + "prompt_unit_price": "0.001", + "prompt_price_unit": "0.001", + "prompt_price": "0.0010330", + "completion_tokens": 128, + "completion_unit_price": "0.002", + "completion_price_unit": "0.001", + "completion_price": "0.0002560", + "total_tokens": 1161, + "total_price": "0.0012890", + "currency": "USD", + "latency": 0.7682376249867957 + }, + "retriever_resources": [ + { + "position": 1, + "dataset_id": "101b4c97-fc2e-463c-90b1-5261a4cdcafb", + "dataset_name": "iPhone", + "document_id": "8dd1ad74-0b5f-4175-b735-7d98bbbb4e00", + "document_name": "iPhone List", + "segment_id": "ed599c7f-2766-4294-9d1d-e5235a61270a", + "score": 0.98457545, + "content": "\"Model\",\"Release Date\",\"Display Size\",\"Resolution\",\"Processor\",\"RAM\",\"Storage\",\"Camera\",\"Battery\",\"Operating System\"\n\"iPhone 13 Pro Max\",\"September 24, 2021\",\"6.7 inch\",\"1284 x 2778\",\"Hexa-core (2x3.23 GHz Avalanche + 4x1.82 GHz Blizzard)\",\"6 GB\",\"128, 256, 512 GB, 1TB\",\"12 MP\",\"4352 mAh\",\"iOS 15\"" + } + ] + }, + "created_at": 1705407629 + } + ``` + + ### Streaming Mode + + ```streaming {{ title: 'Response' }} + 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}} + data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": " I", "created_at": 1679586595} + data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": "'m", "created_at": 1679586595} + data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": " glad", "created_at": 1679586595} + data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": " to", "created_at": 1679586595} + data: {"event": "message", "message_id": : "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": " meet", "created_at": 1679586595} + data: {"event": "message", "message_id": : "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": " you", "created_at": 1679586595} + data: {"event": "message_end", "id": "5e52ce04-874b-4d27-9045-b3bc80def685", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "metadata": {"usage": {"prompt_tokens": 1033, "prompt_unit_price": "0.001", "prompt_price_unit": "0.001", "prompt_price": "0.0010330", "completion_tokens": 135, "completion_unit_price": "0.002", "completion_price_unit": "0.001", "completion_price": "0.0002700", "total_tokens": 1168, "total_price": "0.0013030", "currency": "USD", "latency": 1.381760165997548, "retriever_resources": [{"position": 1, "dataset_id": "101b4c97-fc2e-463c-90b1-5261a4cdcafb", "dataset_name": "iPhone", "document_id": "8dd1ad74-0b5f-4175-b735-7d98bbbb4e00", "document_name": "iPhone List", "segment_id": "ed599c7f-2766-4294-9d1d-e5235a61270a", "score": 0.98457545, "content": "\"Model\",\"Release Date\",\"Display Size\",\"Resolution\",\"Processor\",\"RAM\",\"Storage\",\"Camera\",\"Battery\",\"Operating System\"\n\"iPhone 13 Pro Max\",\"September 24, 2021\",\"6.7 inch\",\"1284 x 2778\",\"Hexa-core (2x3.23 GHz Avalanche + 4x1.82 GHz Blizzard)\",\"6 GB\",\"128, 256, 512 GB, 1TB\",\"12 MP\",\"4352 mAh\",\"iOS 15\""}]}}} + ``` + + + + + +--- + + + + 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" + + + ### Request Example + + ```bash {{ title: 'cURL' }} + curl -X POST '${props.appDetail.api_base_url}/chat-messages/:task_id/stop' \ + -H 'Authorization: Bearer {api_key}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "user": "abc-123" + }' + ``` + + + ### Response Example + + ```json {{ title: 'Response' }} + { + "result": "success" + } + ``` + + + + +--- + + + + + End-users can provide feedback messages, facilitating application developers to optimize expected outputs. + + ### Path + + + Message ID + + + + ### Request Body + + + + Upvote as `like`, downvote as `dislike`, revoke upvote as `null` + + + User identifier, defined by the developer's rules, must be unique within the application. + + + + ### Response + - `result` (string) Always returns "success" + + + + + + ```bash {{ title: 'cURL' }} + curl -X POST '${props.appDetail.api_base_url}/messages/:message_id/feedbacks' \ + --header 'Authorization: Bearer {api_key}' \ + --header 'Content-Type: application/json' \ + --data-raw '{ + "rating": "like", + "user": "abc-123" + }' + ``` + + + + + ```json {{ title: 'Response' }} + { + "result": "success" + } + ``` + + + + +--- + + + + + Get next questions suggestions for the current message + + ### Path Params + + + + Message ID + + + + + + + + ```bash {{ title: 'cURL' }} + curl --location --request GET '${props.appDetail.api_base_url}/messages/{message_id}/suggested' \ + --header 'Authorization: Bearer ENTER-YOUR-SECRET-KEY' \ + --header 'Content-Type: application/json' \ + ``` + + + + + ```json {{ title: 'Response' }} + { + "result": "success", + "data": [ + "a", + "b", + "c" + ] + } + ``` + + + + +--- + + + + + Returns historical chat records in a scrolling load format, with the first page returning the latest `{limit}` messages, i.e., in reverse order. + + ### Query + + + + Conversation ID + + + 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. + + + The ID of the first chat record on the current page, default is null. + + + How many chat history messages to return in one request, default is 20. + + + + ### Response + - `data` (array[object]) Message list + - `id` (string) Message ID + - `conversation_id` (string) Conversation ID + - `inputs` (array[object]) User input parameters. + - `query` (string) User input / question content. + - `message_files` (array[object]) Message files + - `id` (string) ID + - `type` (string) File type, image for images + - `url` (string) Preview image URL + - `belongs_to` (string) belongs to，user orassistant + - `answer` (string) Response message content + - `created_at` (timestamp) Creation timestamp, e.g., 1705395332 + - `feedback` (object) Feedback information + - `rating` (string) Upvote as `like` / Downvote as `dislike` + - `retriever_resources` (array[RetrieverResource]) Citation and Attribution List + - `has_more` (bool) Whether there is a next page + - `limit` (int) Number of returned items, if input exceeds system limit, returns system limit amount + + + + + + + ```bash {{ title: 'cURL' }} + curl -X GET '${props.appDetail.api_base_url}/messages?user=abc-123&conversation_id=' + --header 'Authorization: Bearer {api_key}' + ``` + + + ### Response Example + + ```json {{ title: 'Response' }} + { + "limit": 20, + "has_more": false, + "data": [ + { + "id": "a076a87f-31e5-48dc-b452-0061adbbc922", + "conversation_id": "cd78daf6-f9e4-4463-9ff2-54257230a0ce", + "inputs": { + "name": "dify" + }, + "query": "iphone 13 pro", + "answer": "The iPhone 13 Pro, released on September 24, 2021, features a 6.1-inch display with a resolution of 1170 x 2532. It is equipped with a Hexa-core (2x3.23 GHz Avalanche + 4x1.82 GHz Blizzard) processor, 6 GB of RAM, and offers storage options of 128 GB, 256 GB, 512 GB, and 1 TB. The camera is 12 MP, the battery capacity is 3095 mAh, and it runs on iOS 15.", + "message_files": [], + "feedback": null, + "retriever_resources": [ + { + "position": 1, + "dataset_id": "101b4c97-fc2e-463c-90b1-5261a4cdcafb", + "dataset_name": "iPhone", + "document_id": "8dd1ad74-0b5f-4175-b735-7d98bbbb4e00", + "document_name": "iPhone List", + "segment_id": "ed599c7f-2766-4294-9d1d-e5235a61270a", + "score": 0.98457545, + "content": "\"Model\",\"Release Date\",\"Display Size\",\"Resolution\",\"Processor\",\"RAM\",\"Storage\",\"Camera\",\"Battery\",\"Operating System\"\n\"iPhone 13 Pro Max\",\"September 24, 2021\",\"6.7 inch\",\"1284 x 2778\",\"Hexa-core (2x3.23 GHz Avalanche + 4x1.82 GHz Blizzard)\",\"6 GB\",\"128, 256, 512 GB, 1TB\",\"12 MP\",\"4352 mAh\",\"iOS 15\"" + } + ], + "created_at": 1705569239, + } + ] + } + ``` + + + + +--- + + + + + Retrieve the conversation list for the current user, defaulting to the most recent 20 entries. + + ### Query + + + + 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. + + + The ID of the last record on the current page, default is null. + + + How many records to return in one request, default is the most recent 20 entries. + + + Return only pinned conversations as `true`, only non-pinned as `false` + + + + ### Response + - `data` (array[object]) List of conversations + - `id` (string) Conversation ID + - `name` (string) Conversation name, by default, is a snippet of the first question asked by the user in the conversation. + - `inputs` (array[object]) User input parameters. + - `introduction` (string) Introduction + - `created_at` (timestamp) Creation timestamp, e.g., 1705395332 + - `has_more` (bool) + - `limit` (int) Number of entries returned, if input exceeds system limit, system limit number is returned + + + + + + + ```bash {{ title: 'cURL' }} + curl -X GET '${props.appDetail.api_base_url}/conversations?user=abc-123&last_id=&limit=20' \ + --header 'Authorization: Bearer {api_key}' + ``` + + + + + ```json {{ title: 'Response' }} + { + "limit": 20, + "has_more": false, + "data": [ + { + "id": "10799fb8-64f7-4296-bbf7-b42bfbe0ae54", + "name": "New chat", + "inputs": { + "book": "book", + "myName": "Lucy" + }, + "status": "normal", + "created_at": 1679667915 + }, + { + "id": "hSIhXBhNe8X1d8Et" + // ... + } + ] + } + ``` + + + + +--- + + + + + Delete a conversation. + + ### Path + - `conversation_id` (string) Conversation ID + + ### Request Body + + + + The user identifier, defined by the developer, must ensure uniqueness within the application. + + + + ### Response + - `result` (string) Always returns "success" + + + + + + ```bash {{ title: 'cURL' }} + curl -X DELETE '${props.appDetail.api_base_url}/conversations/{convsation_id}' \ + --header 'Content-Type: application/json' \ + --header 'Accept: application/json' \ + --header 'Authorization: Bearer {api_key}' \ + --data '{ + "user": "abc-123" + }' + ``` + + + + + ```json {{ title: 'Response' }} + { + "result": "success" + } + ``` + + + + +--- + + + + ### Request Body + + + + The name of the conversation. This parameter can be omitted if `auto_generate` is set to `true`. + + + Automatically generate the title, default is `false` + + + The user identifier, defined by the developer, must ensure uniqueness within the application. + + + + ### Response + - `id` (string) Conversation ID + - `name` (string) Conversation name + - `inputs` array[object] User input parameters. + - `introduction` (string) Introduction + - `created_at` (timestamp) Creation timestamp, e.g., 1705395332 + + + + + + ```bash {{ title: 'cURL' }} + curl -X POST '${props.appDetail.api_base_url}/conversations/:conversation_id/name' \ + --header 'Content-Type: application/json' \ + --header 'Authorization: Bearer {api_key}' \ + --data-raw '{ + "name": "", + "user": "abc-123" + }' + ``` + + + + + ```json {{ title: 'Response' }} + { + "id": "cd78daf6-f9e4-4463-9ff2-54257230a0ce", + "name": "Chat vs AI", + "inputs": {}, + "introduction": "", + "created_at": 1705569238 + } + ``` + + + + +--- + + + + + This endpoint requires a multipart/form-data request. + + ### Request Body + + + + Audio file. + Supported formats: `['mp3', 'mp4', 'mpeg', 'mpga', 'm4a', 'wav', 'webm']` + File size limit: 15MB + + + User identifier, defined by the developer's rules, must be unique within the application. + + + + ### Response + - `text` (string) Output text + + + + + + + ```bash {{ title: 'cURL' }} + curl -X POST '${props.appDetail.api_base_url}/conversations/name' \ + --header 'Authorization: Bearer {api_key}' \ + --form 'file=@localfile;type=audio/mp3' + ``` + + + + + ```json {{ text: 'hello' }} + { + "text": "" + } + ``` + + + + +--- + + + + + Text to speech. + + ### Request Body + + + + Speech generated content。 + + + The user identifier, defined by the developer, must ensure uniqueness within the app. + + + Whether to enable streaming output, true、false。 + + + + + + + + ```bash {{ title: 'cURL' }} + curl --location --request POST '${props.appDetail.api_base_url}/text-to-audio' \ + --header 'Authorization: Bearer ENTER-YOUR-SECRET-KEY' \ + --form 'file=Hello Dify;user=abc-123;streaming=false' + ``` + + + + + ```json {{ title: 'headers' }} + { + "Content-Type": "audio/wav" + } + ``` + + + + +--- + + + + + 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 + - `opening_statement` (string) Opening statement + - `suggested_questions` (array[string]) List of suggested questions for the opening + - `suggested_questions_after_answer` (object) Suggest questions after enabling the answer. + - `enabled` (bool) Whether it is enabled + - `speech_to_text` (object) Speech to text + - `enabled` (bool) Whether it is enabled + - `retriever_resource` (object) Citation and Attribution + - `enabled` (bool) Whether it is enabled + - `annotation_reply` (object) Annotation reply + - `enabled` (bool) Whether it is enabled + - `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) + + + + + + + ```bash {{ title: 'cURL' }} + curl -X GET '${props.appDetail.api_base_url}/parameters?user=abc-123' \ + --header 'Authorization: Bearer {api_key}' + ``` + + + + + ```json {{ title: 'Response' }} + { + "opening_statement": "Hello!", + "suggested_questions_after_answer": { + "enabled": true + }, + "speech_to_text": { + "enabled": true + }, + "retriever_resource": { + "enabled": true + }, + "annotation_reply": { + "enabled": true + }, + "user_input_form": [ + { + "paragraph": { + "label": "Query", + "variable": "query", + "required": true, + "default": "" + } + } + ], + "file_upload": { + "image": { + "enabled": false, + "number_limits": 3, + "detail": "high", + "transfer_methods": [ + "remote_url", + "local_file" + ] + } + }, + "system_parameters": { + "image_file_size_limit": "10" + } + } + ``` + + + +--- + + + + + Used to get icons of tools in this application + ### Query + + + + User identifier, defined by the developer's rules, must be unique within the application. + + + ### Response + - `tool_icons`(object[string]) tool icons + - `tool_name` (string) + - `icon` (object|string) + - (object) icon object + - `background` (string) background color in hex format + - `content`(string) emoji + - (string) url of icon + + + + ```bash {{ title: 'cURL' }} + curl -X GET '${props.appDetail.api_base_url}/meta?user=abc-123' \ + -H 'Authorization: Bearer {api_key}' + ``` + + + + + ```json {{ title: 'Response' }} + { + "tool_icons": { + "dalle2": "https://cloud.dify.ai/console/api/workspaces/current/tool-provider/builtin/dalle/icon", + "api_tool": { + "background": "#252525", + "content": "\ud83d\ude01" + } + } + } + ``` + + + diff --git a/web/app/components/develop/template/template_advanced_chat.zh.mdx b/web/app/components/develop/template/template_advanced_chat.zh.mdx new file mode 100644 index 0000000000..51dccc26de --- /dev/null +++ b/web/app/components/develop/template/template_advanced_chat.zh.mdx @@ -0,0 +1,1079 @@ +import { CodeGroup } from '../code.tsx' +import { Row, Col, Properties, Property, Heading, SubProperty } from '../md.tsx' + +# 工作流编排对话型应用 API + +对话应用支持会话持久化，可将之前的聊天记录作为上下进行回答，可适用于聊天/客服 AI 等。 + +
+ ### 基础 URL + + ```javascript + ``` + + + ### 鉴权 + + Service API 使用 `API-Key` 进行鉴权。 + **强烈建议开发者把 `API-Key` 放在后端存储，而非分享或者放在客户端存储，以免 `API-Key` 泄露，导致财产损失。** + 所有 API 请求都应在 **`Authorization`** HTTP Header 中包含您的 `API-Key`，如下所示： + + + ```javascript + Authorization: Bearer {API_KEY} + ``` + +
+ +--- + + + + + 创建会话消息。 + + ### Request Body + + + + 用户输入/提问内容。 + + + 允许传入 App 定义的各变量值。 + inputs 参数包含了多组键值对（Key/Value pairs），每组的键对应一个特定变量，每组的值则是该变量的具体值。 + 默认 `{}` + + + - `streaming` 流式模式（推荐）。基于 SSE（**[Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events)**）实现类似打字机输出方式的流式返回。 + - `blocking` 阻塞模式，等待执行完毕后返回结果。（请求若流程较长可能会被中断）。 + 由于 Cloudflare 限制，请求会在 100 秒超时无返回后中断。 + + + 用户标识，用于定义终端用户的身份，方便检索、统计。 + 由开发者定义规则，需保证用户标识在应用内唯一。 + + + （选填）会话 ID，需要基于之前的聊天记录继续对话，必须传之前消息的 conversation_id。 + + + 上传的文件。 + - `type` (string) 支持类型：图片 `image`（目前仅支持图片格式） 。 + - `transfer_method` (string) 传递方式: + - `remote_url`: 图片地址。 + - `local_file`: 上传文件。 + - `url` 图片地址。（仅当传递方式为 `remote_url` 时）。 + - `upload_file_id` 上传文件 ID。（仅当传递方式为 `local_file `时）。 + + + （选填）自动生成标题，默认 `true`。 若设置为 `false`，则可通过调用会话重命名接口并设置 `auto_generate` 为 `true` 实现异步生成标题。 + + + + ### Response + + 当 `response_mode` 为 `blocking` 时，返回 ChatCompletionResponse object。 + 当 `response_mode` 为 `streaming`时，返回 ChunkChatCompletionResponse object 流式序列。 + + ### ChatCompletionResponse + + 返回完整的 App 结果，`Content-Type` 为 `application/json`。 + - `message_id` (string) 消息唯一 ID + - `conversation_id` (string) 会话 ID + - `mode` (string) App 模式，固定为 chat + - `answer` (string) 完整回复内容 + - `metadata` (object) 元数据 + - `usage` (Usage) 模型用量信息 + - `retriever_resources` (array[RetrieverResource]) 引用和归属分段列表 + - `created_at` (int) 消息创建时间戳，如：1705395332 + + ### ChunkChatCompletionResponse + 返回 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 + ``` + + + 流式块中根据 event 不同，结构也不同： + - `event: message` LLM 返回文本块事件，即：完整的文本以分块的方式输出。 + - `task_id` (string) 任务 ID，用于请求跟踪和下方的停止响应接口 + - `message_id` (string) 消息唯一 ID + - `conversation_id` (string) 会话 ID + - `answer` (string) LLM 返回文本块内容 + - `created_at` (int) 创建时间戳，如：1705395332 + - `event: message_file` 文件事件，表示有新文件需要展示 + - `id` (string) 文件唯一ID + - `type` (string) 文件类型，目前仅为image + - `belongs_to` (string) 文件归属，user或assistant，该接口返回仅为 `assistant` + - `url` (string) 文件访问地址 + - `conversation_id` (string) 会话ID + - `event: message_end` 消息结束事件，收到此事件则代表流式返回结束。 + - `task_id` (string) 任务 ID，用于请求跟踪和下方的停止响应接口 + - `message_id` (string) 消息唯一 ID + - `conversation_id` (string) 会话 ID + - `metadata` (object) 元数据 + - `usage` (Usage) 模型用量信息 + - `retriever_resources` (array[RetrieverResource]) 引用和归属分段列表 + - `event: message_replace` 消息内容替换事件。 + 开启内容审查和审查输出内容时，若命中了审查条件，则会通过此事件替换消息内容为预设回复。 + - `task_id` (string) 任务 ID，用于请求跟踪和下方的停止响应接口 + - `message_id` (string) 消息唯一 ID + - `conversation_id` (string) 会话 ID + - `answer` (string) 替换内容（直接替换 LLM 所有回复文本） + - `created_at` (int) 创建时间戳，如：1705395332 + - `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 + - `node_type` (string) 节点类型 + - `title` (string) 节点名称 + - `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: error` + 流式输出过程中出现的异常会以 stream event 形式输出，收到异常事件后即结束。 + - `task_id` (string) 任务 ID，用于请求跟踪和下方的停止响应接口 + - `message_id` (string) 消息唯一 ID + - `status` (int) HTTP 状态码 + - `code` (string) 错误码 + - `message` (string) 错误消息 + - `event: ping` 每 10s 一次的 ping 事件，保持连接存活。 + + ### Errors + - 404，对话不存在 + - 400，`invalid_param`，传入参数异常 + - 400，`app_unavailable`，App 配置不可用 + - 400，`provider_not_initialize`，无可用模型凭据配置 + - 400，`provider_quota_exceeded`，模型调用额度不足 + - 400，`model_currently_not_support`，当前模型不可用 + - 400，`completion_request_error`，文本生成失败 + - 500，服务内部异常 + + + + + + + + ```bash {{ title: 'cURL' }} + curl -X POST '${props.appDetail.api_base_url}/chat-messages' \ + -H 'Authorization: Bearer {api_key}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "inputs": { + "name": "dify" + }, + "query": "What are the specs of the iPhone 13 Pro Max?", + "conversation_id": "101b4c97-fc2e-463c-90b1-5261a4cdcafb", + "response_mode": "streaming", + "user": "abc-123", + "files": [ + { + "type": "image", + "transfer_method": "remote_url", + "url": "https://cloud.dify.ai/logo/logo-site.png" + } + ] + }' + ``` + + + ### 阻塞模式 + + ```json {{ title: 'Response' }} + { + "event": "message", + "message_id": "9da23599-e713-473b-982c-4328d4f5c78a", + "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", + "mode": "chat", + "answer": "iPhone 13 Pro Max specs are listed heere:...", + "metadata": { + "usage": { + "prompt_tokens": 1033, + "prompt_unit_price": "0.001", + "prompt_price_unit": "0.001", + "prompt_price": "0.0010330", + "completion_tokens": 128, + "completion_unit_price": "0.002", + "completion_price_unit": "0.001", + "completion_price": "0.0002560", + "total_tokens": 1161, + "total_price": "0.0012890", + "currency": "USD", + "latency": 0.7682376249867957 + }, + "retriever_resources": [ + { + "position": 1, + "dataset_id": "101b4c97-fc2e-463c-90b1-5261a4cdcafb", + "dataset_name": "iPhone", + "document_id": "8dd1ad74-0b5f-4175-b735-7d98bbbb4e00", + "document_name": "iPhone List", + "segment_id": "ed599c7f-2766-4294-9d1d-e5235a61270a", + "score": 0.98457545, + "content": "\"Model\",\"Release Date\",\"Display Size\",\"Resolution\",\"Processor\",\"RAM\",\"Storage\",\"Camera\",\"Battery\",\"Operating System\"\n\"iPhone 13 Pro Max\",\"September 24, 2021\",\"6.7 inch\",\"1284 x 2778\",\"Hexa-core (2x3.23 GHz Avalanche + 4x1.82 GHz Blizzard)\",\"6 GB\",\"128, 256, 512 GB, 1TB\",\"12 MP\",\"4352 mAh\",\"iOS 15\"" + } + ] + }, + "created_at": 1705407629 + } + ``` + + ### 流式模式 + + ```streaming {{ title: 'Response' }} + 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}} + data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": " I", "created_at": 1679586595} + data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": "'m", "created_at": 1679586595} + data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": " glad", "created_at": 1679586595} + data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": " to", "created_at": 1679586595} + data: {"event": "message", "message_id": : "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": " meet", "created_at": 1679586595} + data: {"event": "message", "message_id": : "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": " you", "created_at": 1679586595} + data: {"event": "message_end", "id": "5e52ce04-874b-4d27-9045-b3bc80def685", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "metadata": {"usage": {"prompt_tokens": 1033, "prompt_unit_price": "0.001", "prompt_price_unit": "0.001", "prompt_price": "0.0010330", "completion_tokens": 135, "completion_unit_price": "0.002", "completion_price_unit": "0.001", "completion_price": "0.0002700", "total_tokens": 1168, "total_price": "0.0013030", "currency": "USD", "latency": 1.381760165997548, "retriever_resources": [{"position": 1, "dataset_id": "101b4c97-fc2e-463c-90b1-5261a4cdcafb", "dataset_name": "iPhone", "document_id": "8dd1ad74-0b5f-4175-b735-7d98bbbb4e00", "document_name": "iPhone List", "segment_id": "ed599c7f-2766-4294-9d1d-e5235a61270a", "score": 0.98457545, "content": "\"Model\",\"Release Date\",\"Display Size\",\"Resolution\",\"Processor\",\"RAM\",\"Storage\",\"Camera\",\"Battery\",\"Operating System\"\n\"iPhone 13 Pro Max\",\"September 24, 2021\",\"6.7 inch\",\"1284 x 2778\",\"Hexa-core (2x3.23 GHz Avalanche + 4x1.82 GHz Blizzard)\",\"6 GB\",\"128, 256, 512 GB, 1TB\",\"12 MP\",\"4352 mAh\",\"iOS 15\""}]}}} + ``` + + + + +--- + + + + 上传文件（目前仅支持图片）并在发送消息时使用，可实现图文多模态理解。 + 支持 png, jpg, jpeg, webp, gif 格式。 + 上传的文件仅供当前终端用户使用。 + + ### 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, + } + ``` + + + +--- + + + + 仅支持流式模式。 + ### Path + - `task_id` (string) 任务 ID，可在流式返回 Chunk 中获取 + + ### Request Body + - `user` (string) Required + 用户标识，用于定义终端用户的身份，必须和发送消息接口传入 user 保持一致。 + ### Response + - `result` (string) 固定返回 success + + + + ```bash {{ title: 'cURL' }} + curl -X POST '${props.appDetail.api_base_url}/chat-messages/:task_id/stop' \ + -H 'Authorization: Bearer {api_key}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "user": "abc-123" + }' + ``` + + + + + ```json {{ title: 'Response' }} + { + "result": "success" + } + ``` + + + +--- + + + + + 消息终端用户反馈、点赞，方便应用开发者优化输出预期。 + + ### Path Params + + + 消息 ID + + + + ### Request Body + + + + 点赞 like, 点踩 dislike, 撤销点赞 null + + + 用户标识，由开发者定义规则，需保证用户标识在应用内唯一。 + + + + ### Response + - `result` (string) 固定返回 success + + + + + + ```bash {{ title: 'cURL' }} + curl -X POST '${props.appDetail.api_base_url}/messages/:message_id/feedbacks' \ + --header 'Authorization: Bearer {api_key}' \ + --header 'Content-Type: application/json' \ + --data-raw '{ + "rating": "like", + "user": "abc-123" + }' + ``` + + + + + ```json {{ title: 'Response' }} + { + "result": "success" + } + ``` + + + + +--- + + + + + 获取下一轮建议问题列表。 + + ### Path Params + + + + Message ID + + + + + + + + ```bash {{ title: 'cURL' }} + curl --location --request GET '${props.appDetail.api_base_url}/messages/{message_id}/suggested' \ + --header 'Authorization: Bearer ENTER-YOUR-SECRET-KEY' \ + --header 'Content-Type: application/json' \ + ``` + + + + + ```json {{ title: 'Response' }} + { + "result": "success", + "data": [ + "a", + "b", + "c" + ] + } + ``` + + + + +--- + +--- + + + + + 滚动加载形式返回历史聊天记录，第一页返回最新 `limit` 条，即：倒序返回。 + + ### Query + + + + 会话 ID + + + 用户标识，由开发者定义规则，需保证用户标识在应用内唯一。 + + + 当前页第一条聊天记录的 ID，默认 null + + + 一次请求返回多少条聊天记录，默认 20 条。 + + + + ### Response + - `data` (array[object]) 消息列表 + - `id` (string) 消息 ID + - `conversation_id` (string) 会话 ID + - `inputs` (array[object]) 用户输入参数。 + - `query` (string) 用户输入 / 提问内容。 + - `message_files` (array[object]) 消息文件 + - `id` (string) ID + - `type` (string) 文件类型，image 图片 + - `url` (string) 预览图片地址 + - `belongs_to` (string) 文件归属方，user 或 assistant + - `answer` (string) 回答消息内容 + - `created_at` (timestamp) 创建时间 + - `feedback` (object) 反馈信息 + - `rating` (string) 点赞 like / 点踩 dislike + - `retriever_resources` (array[RetrieverResource]) 引用和归属分段列表 + - `has_more` (bool) 是否存在下一页 + - `limit` (int) 返回条数，若传入超过系统限制，返回系统限制数量 + + + ### Request Example + + + ```bash {{ title: 'cURL' }} + curl -X GET '${props.appDetail.api_base_url}/messages?user=abc-123&conversation_id=' + --header 'Authorization: Bearer {api_key}' + ``` + + + + ### Response Example + + ```json {{ title: 'Response' }} + { + "limit": 20, + "has_more": false, + "data": [ + { + "id": "a076a87f-31e5-48dc-b452-0061adbbc922", + "conversation_id": "cd78daf6-f9e4-4463-9ff2-54257230a0ce", + "inputs": { + "name": "dify" + }, + "query": "iphone 13 pro", + "answer": "The iPhone 13 Pro, released on September 24, 2021, features a 6.1-inch display with a resolution of 1170 x 2532. It is equipped with a Hexa-core (2x3.23 GHz Avalanche + 4x1.82 GHz Blizzard) processor, 6 GB of RAM, and offers storage options of 128 GB, 256 GB, 512 GB, and 1 TB. The camera is 12 MP, the battery capacity is 3095 mAh, and it runs on iOS 15.", + "message_files": [], + "feedback": null, + "retriever_resources": [ + { + "position": 1, + "dataset_id": "101b4c97-fc2e-463c-90b1-5261a4cdcafb", + "dataset_name": "iPhone", + "document_id": "8dd1ad74-0b5f-4175-b735-7d98bbbb4e00", + "document_name": "iPhone List", + "segment_id": "ed599c7f-2766-4294-9d1d-e5235a61270a", + "score": 0.98457545, + "content": "\"Model\",\"Release Date\",\"Display Size\",\"Resolution\",\"Processor\",\"RAM\",\"Storage\",\"Camera\",\"Battery\",\"Operating System\"\n\"iPhone 13 Pro Max\",\"September 24, 2021\",\"6.7 inch\",\"1284 x 2778\",\"Hexa-core (2x3.23 GHz Avalanche + 4x1.82 GHz Blizzard)\",\"6 GB\",\"128, 256, 512 GB, 1TB\",\"12 MP\",\"4352 mAh\",\"iOS 15\"" + } + ], + "created_at": 1705569239 + } + ] + } + ``` + + + ### Response Example(智能助手) + + ```json {{ title: 'Response' }} + { + "limit": 20, + "has_more": false, + "data": [ + { + "id": "d35e006c-7c4d-458f-9142-be4930abdf94", + "conversation_id": "957c068b-f258-4f89-ba10-6e8a0361c457", + "inputs": {}, + "query": "draw a cat", + "answer": "I have generated an image of a cat for you. Please check your messages to view the image.", + "message_files": [ + { + "id": "976990d2-5294-47e6-8f14-7356ba9d2d76", + "type": "image", + "url": "http://127.0.0.1:5001/files/tools/976990d2-5294-47e6-8f14-7356ba9d2d76.png?timestamp=1705988524&nonce=55df3f9f7311a9acd91bf074cd524092&sign=z43nMSO1L2HBvoqADLkRxr7Biz0fkjeDstnJiCK1zh8=", + "belongs_to": "assistant" + } + ], + "feedback": null, + "retriever_resources": [], + "created_at": 1705988187 + } + ] + } + ``` + + + + +--- + + + + + 获取当前用户的会话列表，默认返回最近的 20 条。 + + ### Query + + + + 用户标识，由开发者定义规则，需保证用户标识在应用内唯一。 + + + 当前页最后面一条记录的 ID，默认 null + + + 一次请求返回多少条记录 + + + 只返回置顶 true，只返回非置顶 false + + + + ### Response + - `data` (array[object]) 会话列表 + - `id` (string) 会话 ID + - `name` (string) 会话名称，默认为会话中用户最开始问题的截取。 + - `inputs` (array[object]) 用户输入参数。 + - `introduction` (string) 开场白 + - `created_at` (timestamp) 创建时间 + - `has_more` (bool) + - `limit` (int) 返回条数，若传入超过系统限制，返回系统限制数量 + + + + + + + ```bash {{ title: 'cURL' }} + curl -X GET '${props.appDetail.api_base_url}/conversations?user=abc-123&last_id=&limit=20' \ + --header 'Authorization: Bearer {api_key}' + ``` + + + + + ```json {{ title: 'Response' }} + { + "limit": 20, + "has_more": false, + "data": [ + { + "id": "10799fb8-64f7-4296-bbf7-b42bfbe0ae54", + "name": "New chat", + "inputs": { + "book": "book", + "myName": "Lucy" + }, + "status": "normal", + "created_at": 1679667915 + }, + { + "id": "hSIhXBhNe8X1d8Et" + // ... + } + ] + } + ``` + + + + +--- + + + + 删除会话。 + + ### Path + - `conversation_id` (string) 会话 ID + + ### Request Body + + + + 用户标识，由开发者定义规则，需保证用户标识在应用内唯一。 + + + + ### Response + - `result` (string) 固定返回 success + + + + + + ```bash {{ title: 'cURL' }} + curl -X DELETE '${props.appDetail.api_base_url}/conversations/{convsation_id}' \ + --header 'Content-Type: application/json' \ + --header 'Accept: application/json' \ + --header 'Authorization: Bearer {api_key}' \ + --data '{ + "user": "abc-123" + }' + ``` + + + + + ```json {{ title: 'Response' }} + { + "result": "success" + } + ``` + + + + +--- + + + + + 对会话进行重命名，会话名称用于显示在支持多会话的客户端上。 + + ### Request Body + + + + 名称，若 `auto_generate` 为 `true` 时，该参数可不传。 + + + 自动生成标题，默认 false。 + + + 用户标识，由开发者定义规则，需保证用户标识在应用内唯一。 + + + + ### Response + - `id` (string) 会话 ID + - `name` (string) 会话名称 + - `inputs` array[object] 用户输入参数。 + - `introduction` (string) 开场白 + - `created_at` (timestamp) 创建时间 + + + + + + ```bash {{ title: 'cURL' }} + curl -X POST '${props.appDetail.api_base_url}/conversations/:conversation_id/name' \ + --header 'Authorization: Bearer {api_key}' \ + --header 'Content-Type: application/json' \ + --data-raw '{ + "name": "", + "user": "abc-123" + }' + ``` + + + + + ```json {{ title: 'Response' }} + { + "result": "success" + } + ``` + + + + +--- + + + + + ### Request Body + 该接口需使用 `multipart/form-data` 进行请求。 + + + 语音文件。 + 支持格式：`['mp3', 'mp4', 'mpeg', 'mpga', 'm4a', 'wav', 'webm']` + 文件大小限制：15MB + + + 用户标识，由开发者定义规则，需保证用户标识在应用内唯一。 + + + + ### Response + - `text` (string) 输出文字 + + + + + + ```bash {{ title: 'cURL' }} + curl -X POST '${props.appDetail.api_base_url}/conversations/name' \ + --header 'Authorization: Bearer {api_key}' \ + --form 'file=@localfile;type=audio/mp3' + ``` + + + + + ```json {{ title: 'Response' }} + { + "text": "hello" + } + ``` + + + + +--- + + + + + 文字转语音。 + + ### Request Body + + + + 语音生成内容。 + + + 用户标识，由开发者定义规则，需保证用户标识在应用内唯一。 + + + 是否启用流式输出true、false。 + + + + + + + + ```bash {{ title: 'cURL' }} + curl --location --request POST '${props.appDetail.api_base_url}/text-to-audio' \ + --header 'Authorization: Bearer ENTER-YOUR-SECRET-KEY' \ + --form 'file=你好Dify;user=abc-123;streaming=false' + ``` + + + + + ```json {{ title: 'headers' }} + { + "Content-Type": "audio/wav" + } + ``` + + + + +--- + + + + + 用于进入页面一开始，获取功能开关、输入参数名称、类型及默认值等使用。 + + ### Query + + + + 用户标识，由开发者定义规则，需保证用户标识在应用内唯一。 + + + + ### Response + - `opening_statement` (string) 开场白 + - `suggested_questions` (array[string]) 开场推荐问题列表 + - `suggested_questions_after_answer` (object) 启用回答后给出推荐问题。 + - `enabled` (bool) 是否开启 + - `speech_to_text` (object) 语音转文本 + - `enabled` (bool) 是否开启 + - `retriever_resource` (object) 引用和归属 + - `enabled` (bool) 是否开启 + - `annotation_reply` (object) 标记回复 + - `enabled` (bool) 是否开启 + - `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） + + + + + + ```bash {{ title: 'cURL' }} + curl -X GET '${props.appDetail.api_base_url}/parameters?user=abc-123' \ + --header 'Authorization: Bearer {api_key}' + ``` + + + + + ```json {{ title: 'Response' }} + { + "introduction": "nice to meet you", + "user_input_form": [ + { + "text-input": { + "label": "a", + "variable": "a", + "required": true, + "max_length": 48, + "default": "" + } + }, + { + // ... + } + ], + "file_upload": { + "image": { + "enabled": true, + "number_limits": 3, + "transfer_methods": [ + "remote_url", + "local_file" + ] + } + } + } + ``` + + + + +--- + + + + + 用于获取工具icon + ### Query + + + + 用户标识，由开发者定义规则，需保证用户标识在应用内唯一。 + + + ### Response + - `tool_icons`(object[string]) 工具图标 + - `工具名称` (string) + - `icon` (object|string) + - (object) 图标 + - `background` (string) hex格式的背景色 + - `content`(string) emoji + - (string) 图标URL + + + + ```bash {{ title: 'cURL' }} + curl -X GET '${props.appDetail.api_base_url}/meta?user=abc-123' \ + -H 'Authorization: Bearer {api_key}' + ``` + + + + + ```json {{ title: 'Response' }} + { + "tool_icons": { + "dalle2": "https://cloud.dify.ai/console/api/workspaces/current/tool-provider/builtin/dalle/icon", + "api_tool": { + "background": "#252525", + "content": "\ud83d\ude01" + } + } + } + ``` + + +