mirror of
https://github.com/langgenius/dify.git
synced 2024-11-16 19:59:50 +08:00
497 lines
15 KiB
Plaintext
497 lines
15 KiB
Plaintext
import { CodeGroup } from '../code.tsx'
|
||
import { Row, Col, Properties, Property, Heading, SubProperty } from '../md.tsx'
|
||
|
||
# 对话型应用 API
|
||
|
||
可用于大部分场景的对话型应用，采用一问一答模式与用户持续对话。要开始一个对话请调用 chat-messages 接口，通过继续传入返回的 conversation_id 可持续保持该会话。**[开始前请阅读 !! 什么是 Bearer Token ？](https://swagger.io/docs/specification/authentication/bearer-authentication/)**
|
||
|
||
<div>
|
||
### 鉴权
|
||
|
||
Dify Service API 使用 `API-Key` 进行鉴权。
|
||
|
||
建议开发者把 `API-Key` 放在后端存储，而非分享或者放在客户端存储，以免 `API-Key` 泄露，导致财产损失。
|
||
|
||
所有 API 请求都应在 **`Authorization`** HTTP Header 中包含您的 `API-Key`，如下所示：
|
||
|
||
<CodeGroup title="Code">
|
||
```javascript
|
||
Authorization: Bearer {API_KEY}
|
||
|
||
```
|
||
</CodeGroup>
|
||
</div>
|
||
|
||
---
|
||
|
||
<Heading
|
||
url='/chat-messages'
|
||
method='POST'
|
||
title='发送对话消息'
|
||
name='#Create-Chat-Message'
|
||
/>
|
||
<Row>
|
||
<Col>
|
||
创建会话消息，或基于此前的对话继续发送消息。
|
||
|
||
### Request Body
|
||
|
||
<Properties>
|
||
<Property name='inputs' type='object' key='inputs'>
|
||
（选填）以键值对方式提供用户输入字段，与提示词编排中的变量对应。Key 为变量名称，Value 是参数值。如果字段类型为 Select，传入的 Value 需为预设选项之一。
|
||
<ul>
|
||
{!!props.variables.length && props.variables.map(
|
||
val => (
|
||
<SubProperty name={val.key} type={val.type} key={val.key}>
|
||
{val.name ? `${val.name}` : ''}
|
||
</SubProperty>
|
||
)
|
||
)}
|
||
</ul>
|
||
</Property>
|
||
<Property name='query' type='string' key='query'>
|
||
用户输入/提问内容
|
||
</Property>
|
||
<Property name='response_mode' type='string' key='response_mode'>
|
||
- blocking 阻塞型，等待执行完毕后返回结果。（请求若流程较长可能会被中断）
|
||
- streaming 流式返回。基于 SSE（**[Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events)**）实现流式返回。
|
||
</Property>
|
||
<Property name='conversation_id' type='string' key='conversation_id'>
|
||
（必填）<strong>‼️ 会话标识符，首次对话为 conversation_id: "" ‼️</strong>，如果要继续对话请传入上下文返回的 conversation_id
|
||
</Property>
|
||
<Property name='user' type='string' key='user'>
|
||
用户标识，由开发者定义规则，需保证用户标识在应用内唯一。
|
||
</Property>
|
||
</Properties>
|
||
</Col>
|
||
<Col sticky>
|
||
|
||
<CodeGroup title="Request" tag="POST" label="/chat-messages" targetCode={`curl --location --request POST '${props.appDetail.api_base_url}/chat-messages' \\\n--header 'Authorization: Bearer ENTER-YOUR-SECRET-KEY' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n "inputs": ${JSON.stringify(props.inputs)},\n "query": "eh",\n "response_mode": "streaming",\n "conversation_id": "",\n "user": "abc-123"\n}'\n`}>
|
||
|
||
```bash {{ title: 'cURL' }}
|
||
curl --location --request POST 'https://cloud.langgenius.dev/api/chat-messages' \
|
||
--header 'Authorization: Bearer ENTER-YOUR-SECRET-KEY' \
|
||
--header 'Content-Type: application/json' \
|
||
--data-raw '{
|
||
"inputs": {},
|
||
"query": "eh",
|
||
"response_mode": "streaming",
|
||
"conversation_id": "",
|
||
"user": "abc-123"
|
||
}'
|
||
```
|
||
|
||
</CodeGroup>
|
||
### blocking
|
||
<CodeGroup title="Response">
|
||
```json {{ title: 'Response' }}
|
||
{
|
||
"answer": "Hi, is there anything I can help you?",
|
||
"conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2",
|
||
"created_at": 1679587005,
|
||
"id": "059f87d9-15c0-473a-870c-fde95cdcc1e4"
|
||
}
|
||
```
|
||
</CodeGroup>
|
||
### streaming
|
||
<CodeGroup title="Response">
|
||
```streaming {{ title: 'Response' }}
|
||
data: {"id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": " I", "created_at": 1679586595}
|
||
data: {"id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "answer": " I", "created_at": 1679586595}
|
||
```
|
||
</CodeGroup>
|
||
</Col>
|
||
</Row>
|
||
|
||
---
|
||
|
||
<Heading
|
||
url='/messages/{message_id}/feedbacks'
|
||
method='POST'
|
||
title='消息反馈（点赞）'
|
||
name='#feedbacks'
|
||
/>
|
||
<Row>
|
||
<Col>
|
||
代表最终用户对返回消息进行评价，可以点赞与点踩，该数据将在“日志与标注”页中可见，并用于后续的模型微调。
|
||
|
||
### Path Params
|
||
<Properties>
|
||
<Property name='message_id' type='string' key='message_id'>
|
||
消息 ID
|
||
</Property>
|
||
</Properties>
|
||
|
||
### Request Body
|
||
|
||
<Properties>
|
||
<Property name='rating' type='string' key='rating'>
|
||
like 或 dislike， 空值为撤销
|
||
</Property>
|
||
<Property name='user' type='string' key='user'>
|
||
用户标识，由开发者定义规则，需保证用户标识在应用内唯一。
|
||
</Property>
|
||
</Properties>
|
||
</Col>
|
||
<Col sticky>
|
||
|
||
<CodeGroup title="Request" tag="POST" label="/messages/{message_id}/feedbacks" targetCode={`curl --location --request POST '${props.appDetail.api_base_url}/messages/{message_id}/feedbacks \\\n--header 'Authorization: Bearer ENTER-YOUR-SECRET-KEY' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n "rating": "like",\n "user": "abc-123"\n}'`}>
|
||
|
||
```bash {{ title: 'cURL' }}
|
||
curl --location --request POST 'https://cloud.langgenius.dev/api/messages/{message_id}/feedbacks' \
|
||
--header 'Authorization: Bearer ENTER-YOUR-SECRET-KEY' \
|
||
--header 'Content-Type: application/json' \
|
||
--data-raw '{
|
||
"rating": "like",
|
||
"user": "abc-123"
|
||
}'
|
||
```
|
||
|
||
</CodeGroup>
|
||
|
||
<CodeGroup title="Response">
|
||
```json {{ title: 'Response' }}
|
||
{
|
||
"has_more": false,
|
||
"data": [
|
||
{
|
||
"id": "WAz8eIbvDR60rouK",
|
||
"username": "FrankMcCallister",
|
||
"phone_number": "1-800-759-3000",
|
||
"avatar_url": "https://assets.protocol.chat/avatars/frank.jpg",
|
||
"display_name": null,
|
||
"conversation_id": "xgQQXg3hrtjh7AvZ",
|
||
"created_at": 692233200
|
||
},
|
||
{
|
||
"id": "hSIhXBhNe8X1d8Et"
|
||
// ...
|
||
}
|
||
]
|
||
}
|
||
```
|
||
</CodeGroup>
|
||
</Col>
|
||
</Row>
|
||
|
||
---
|
||
|
||
<Heading
|
||
url='/messages'
|
||
method='GET'
|
||
title='获取会话历史消息'
|
||
name='#messages'
|
||
/>
|
||
<Row>
|
||
<Col>
|
||
滚动加载形式返回历史聊天记录，第一页返回最新 `limit` 条，加载更多时，返回 `first_id` 之前的 `limit` 条。
|
||
|
||
### Query
|
||
|
||
<Properties>
|
||
<Property name='conversation_id' type='string' key='conversation_id'>
|
||
会话 ID
|
||
</Property>
|
||
<Property name='first_id' type='string' key='first_id'>
|
||
当前页第一条聊天记录的 ID，默认 none
|
||
</Property>
|
||
<Property name='limit' type='int' key='limit'>
|
||
一次请求返回多少条聊天记录
|
||
</Property>
|
||
<Property name='user' type='string' key='user'>
|
||
用户标识，由开发者定义规则，需保证用户标识在应用内唯一。
|
||
</Property>
|
||
</Properties>
|
||
</Col>
|
||
<Col sticky>
|
||
|
||
<CodeGroup title="Request" tag="GET" label="/messages" targetCode={`curl --location --request GET '${props.appDetail.api_base_url}/messages?user=abc-123&conversation_id=' \\\n--header 'Authorization: Bearer ENTER-YOUR-SECRET-KEY'`}>
|
||
|
||
```bash {{ title: 'cURL' }}
|
||
curl --location --request GET 'https://cloud.langgenius.dev/api/messages?user=abc-123&conversation_id='
|
||
--header 'Authorization: Bearer ENTER-YOUR-SECRET-KEY'
|
||
```
|
||
|
||
</CodeGroup>
|
||
|
||
<CodeGroup title="Response">
|
||
```json {{ title: 'Response' }}
|
||
{
|
||
"has_more": false,
|
||
"data": [
|
||
{
|
||
"id": "WAz8eIbvDR60rouK",
|
||
"conversation_id": "xgQQXg3hrtjh7AvZ",
|
||
"inputs": {},
|
||
"query": "...",
|
||
"answer": "...",
|
||
"feedback": "like",
|
||
"created_at": 692233200
|
||
},
|
||
{
|
||
"id": "hSIhXBhNe8X1d8Et"
|
||
// ...
|
||
}
|
||
]
|
||
}
|
||
```
|
||
</CodeGroup>
|
||
</Col>
|
||
</Row>
|
||
|
||
---
|
||
|
||
<Heading
|
||
url='/conversations'
|
||
method='GET'
|
||
title='获取会话列表'
|
||
name='#conversations'
|
||
/>
|
||
<Row>
|
||
<Col>
|
||
获取当前用户的会话列表，默认返回最近的 20 条。
|
||
|
||
### Query
|
||
|
||
<Properties>
|
||
<Property name='last_id' type='string' key='last_id'>
|
||
当前页最后面一条记录的 ID，默认 none
|
||
</Property>
|
||
<Property name='limit' type='int' key='limit'>
|
||
一次请求返回多少条记录
|
||
</Property>
|
||
<Property name='user' type='string' key='user'>
|
||
用户标识，由开发者定义规则，需保证用户标识在应用内唯一。
|
||
</Property>
|
||
</Properties>
|
||
</Col>
|
||
<Col sticky>
|
||
|
||
<CodeGroup title="Request" tag="GET" label="/conversations" targetCode={`curl --location --request GET '${props.appDetail.api_base_url}/conversations?user=abc-123&last_id=&limit=20'\\\n--header 'Authorization: Bearer ENTER-YOUR-SECRET-KEY'`}>
|
||
|
||
```bash {{ title: 'cURL' }}
|
||
curl --location --request GET 'https://cloud.langgenius.dev/api/conversations?user=abc-123&last_id=&limit=20' \
|
||
--header 'Authorization: Bearer ENTER-YOUR-SECRET-KEY'
|
||
```
|
||
|
||
</CodeGroup>
|
||
|
||
<CodeGroup title="Response">
|
||
```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"
|
||
// ...
|
||
}
|
||
]
|
||
}
|
||
```
|
||
</CodeGroup>
|
||
</Col>
|
||
</Row>
|
||
|
||
---
|
||
|
||
<Heading
|
||
url='/conversations/{converation_id}/name'
|
||
method='POST'
|
||
title='会话重命名'
|
||
name='#rename'
|
||
/>
|
||
<Row>
|
||
<Col>
|
||
对会话进行重命名，会话名称用于显示在支持多会话的客户端上。
|
||
|
||
### Request Body
|
||
|
||
<Properties>
|
||
<Property name='name' type='string' key='name'>
|
||
新的名称
|
||
</Property>
|
||
<Property name='user' type='string' key='user'>
|
||
用户标识，由开发者定义规则，需保证用户标识在应用内唯一。
|
||
</Property>
|
||
</Properties>
|
||
</Col>
|
||
<Col sticky>
|
||
|
||
<CodeGroup title="Request" tag="POST" label="/conversations/{converation_id}/name" targetCode={`curl --location --request POST '${props.appDetail.api_base_url}/conversations/name' \\\n--header 'Authorization: Bearer ENTER-YOUR-SECRET-KEY' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{ \n "name": "", \n "user": "abc-123"\n}'`}>
|
||
|
||
```bash {{ title: 'cURL' }}
|
||
curl --location --request POST 'https://cloud.langgenius.dev/api/conversations/{converation_id}/name' \
|
||
--header 'Authorization: Bearer ENTER-YOUR-SECRET-KEY' \
|
||
--header 'Content-Type: application/json' \
|
||
--data-raw '{
|
||
"name": "",
|
||
"user": "abc-123"
|
||
}'
|
||
```
|
||
|
||
</CodeGroup>
|
||
|
||
<CodeGroup title="Response">
|
||
```json {{ title: 'Response' }}
|
||
{
|
||
"result": "success"
|
||
}
|
||
```
|
||
</CodeGroup>
|
||
</Col>
|
||
</Row>
|
||
|
||
---
|
||
|
||
<Heading
|
||
url='/conversations/{converation_id}'
|
||
method='DELETE'
|
||
title='删除会话'
|
||
name='#delete'
|
||
/>
|
||
<Row>
|
||
<Col>
|
||
删除会话。
|
||
|
||
### Request Body
|
||
|
||
<Properties>
|
||
<Property name='user' type='string' key='user'>
|
||
用户标识，由开发者定义规则，需保证用户标识在应用内唯一。
|
||
</Property>
|
||
</Properties>
|
||
</Col>
|
||
<Col sticky>
|
||
|
||
<CodeGroup title="Request" tag="DELETE" label="/conversations/{converation_id}" targetCode={`curl --location --request DELETE '${props.appDetail.api_base_url}/conversations/{conversation_id}' \\\n--header 'Authorization: Bearer ENTER-YOUR-SECRET-KEY' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{ \n "user": "abc-123"\n}'`}>
|
||
|
||
```bash {{ title: 'cURL' }}
|
||
curl --location --request DELETE 'https://cloud.langgenius.dev/api/conversations/{convsation_id}' \
|
||
--header 'Content-Type: application/json' \
|
||
--header 'Accept: application/json' \
|
||
--header 'Authorization: Bearer ENTER-YOUR-SECRET-KEY' \
|
||
--data '{
|
||
"user": "abc-123"
|
||
}'
|
||
```
|
||
|
||
</CodeGroup>
|
||
|
||
<CodeGroup title="Response">
|
||
```json {{ title: 'Response' }}
|
||
{
|
||
"result": "success"
|
||
}
|
||
```
|
||
</CodeGroup>
|
||
</Col>
|
||
</Row>
|
||
|
||
---
|
||
|
||
<Heading
|
||
url='/audio-to-text'
|
||
method='POST'
|
||
title='语音转文字'
|
||
name='#audio'
|
||
/>
|
||
<Row>
|
||
<Col>
|
||
语音转文字，仅支持 openai 模型。
|
||
|
||
### Request Body
|
||
|
||
<Properties>
|
||
<Property name='file' type='file' key='file'>
|
||
语音文件。
|
||
文件上传当前限制为 15 MB，并且支持以下输入文件类型：mp3、mp4、mpeg、mpga、m4a、wav 和 webm。
|
||
</Property>
|
||
</Properties>
|
||
</Col>
|
||
<Col sticky>
|
||
|
||
<CodeGroup title="Request" tag="POST" label="/audio-to-text" targetCode={`curl --location --request POST '${props.appDetail.api_base_url}/audio-to-text' \\\n--header 'Authorization: Bearer ENTER-YOUR-SECRET-KEY' \\\n--form 'file=@localfile;type=audio/[mp3|mp4|mpeg|mpga|m4a|wav|webm]`}>
|
||
|
||
```bash {{ title: 'cURL' }}
|
||
curl --location --request POST 'https://cloud.langgenius.dev/api/conversations/name' \
|
||
--header 'Authorization: Bearer ENTER-YOUR-SECRET-KEY' \
|
||
--form 'file=@localfile;type=audio/mp3'
|
||
```
|
||
|
||
</CodeGroup>
|
||
|
||
<CodeGroup title="Response">
|
||
```json {{ title: 'Response' }}
|
||
{
|
||
"text": ""
|
||
}
|
||
```
|
||
</CodeGroup>
|
||
</Col>
|
||
</Row>
|
||
|
||
---
|
||
|
||
<Heading
|
||
url='/parameters'
|
||
method='GET'
|
||
title='获取应用配置信息'
|
||
name='#rename'
|
||
/>
|
||
<Row>
|
||
<Col>
|
||
获取已配置的 Input 参数，包括变量名、字段名称、类型与默认值。通常用于客户端加载后显示这些字段的表单或填入默认值。
|
||
|
||
### Query
|
||
|
||
<Properties>
|
||
<Property name='user' type='string' key='user'>
|
||
用户标识，由开发者定义规则，需保证用户标识在应用内唯一。
|
||
</Property>
|
||
</Properties>
|
||
</Col>
|
||
<Col sticky>
|
||
|
||
<CodeGroup title="Request" tag="GET" label="/parameters" targetCode={` curl --location --request GET '${props.appDetail.api_base_url}/parameters'\\\n--header 'Authorization: Bearer ENTER-YOUR-SECRET-KEY'`}>
|
||
|
||
```bash {{ title: 'cURL' }}
|
||
curl --location --request GET 'https://cloud.langgenius.dev/api/parameters?user=abc-123' \
|
||
--header 'Authorization: Bearer ENTER-YOUR-SECRET-KEY'
|
||
```
|
||
|
||
</CodeGroup>
|
||
|
||
<CodeGroup title="Response">
|
||
```json {{ title: 'Response' }}
|
||
{
|
||
"introduction": "nice to meet you",
|
||
"variables": [
|
||
{
|
||
"key": "book",
|
||
"name": "book",
|
||
"description": null,
|
||
"type": "string",
|
||
"default": null,
|
||
"options": null
|
||
},
|
||
{
|
||
// ...
|
||
}
|
||
]
|
||
}
|
||
```
|
||
</CodeGroup>
|
||
</Col>
|
||
</Row>
|