Doc (#2910)

* feat: add app chat openapi (#2908) * add chat openapi * create question guide openapi * change auth method * add chat openapi doc * delete unused code * feat: chat openapi doc * rerank doc * add chat detail openapi & doc * update chat openapi doc --------- Co-authored-by: heheer <heheer@sealos.io> Co-authored-by: heheer <1239331448@qq.com>
2025-07-21 11:43:56 +00:00 · 2024-10-14 10:26:57 +08:00
parent 27ef4dc8ea
commit d55ccc9f64
28 changed files with 897 additions and 83 deletions
--- a/docSite/content/zh-cn/docs/development/configuration.md
+++ b/docSite/content/zh-cn/docs/development/configuration.md
@@ -227,6 +227,27 @@ weight: 708
 }
 ```

+### ReRank 接入（硅基流动）
+
+有免费的 `bge-reranker-v2-m3` 模型可以使用。
+
+1. 注册硅基流动账号: https://siliconflow.cn/
+2. 进入控制台，获取 API key: https://cloud.siliconflow.cn/account/ak
+3. 修改 FastGPT 配置文件
+
+```json
+{
+    "reRankModels": [
+        {
+            "model": "BAAI/bge-reranker-v2-m3", // 这里的model需要对应 siliconflow 的模型名
+            "name": "BAAI/bge-reranker-v2-m3",
+            "requestUrl": "https://api.siliconflow.cn/v1/rerank",
+            "requestAuth": "siliconflow 上申请的 key"
+        }
+    ]
+}
+```
+
 ### ReRank 接入（Cohere）

 这个重排模型对中文不是很好，不如 bge 的好用。
@@ -239,7 +260,7 @@ weight: 708
    "reRankModels": [
        {
            "model": "rerank-multilingual-v2.0", // 这里的model需要对应 cohere 的模型名
-            "name": "检索重排", // 随意
+            "name": "rerank-multilingual-v2.0",
            "requestUrl": "https://api.cohere.ai/v1/rerank",
            "requestAuth": "Coherer上申请的key"
        }
--- a/docSite/content/zh-cn/docs/development/openapi/chat.md
+++ b/docSite/content/zh-cn/docs/development/openapi/chat.md
@@ -7,13 +7,15 @@ toc: true
 weight: 852
 ---

+# 发起对话
+
 {{% alert icon="🤖 " context="success" %}}
 * 该接口的 API Key 需使用`应用特定的 key`，否则会报错。  

 * 有些包调用时，`BaseUrl`需要添加`v1`路径，有些不需要，如果出现404情况，可补充`v1`重试。
 {{% /alert %}}

-## 发起对话(简易应用和工作流)
+## 请求简易应用和工作流

 对话接口兼容`GPT`的接口！如果你的项目使用的是标准的`GPT`官方接口，可以直接通过修改`BaseUrl`和 `Authorization`来访问 FastGpt 应用，不过需要注意下面几个规则：

@@ -24,12 +26,12 @@ weight: 852

 ### 请求

-{{< tabs tabTotal="2" >}}
-{{< tab tabName="请求示例" >}}
+{{< tabs tabTotal="3" >}}
+{{< tab tabName="基础请求示例" >}}
 {{< markdownify >}}

 ```bash
-curl --location --request POST 'https://api.fastgpt.in/api/v1/chat/completions' \
+curl --location --request POST 'http://localhost:3000/api/v1/chat/completions' \
 --header 'Authorization: Bearer fastgpt-xxxxxx' \
 --header 'Content-Type: application/json' \
 --data-raw '{
@@ -42,8 +44,49 @@ curl --location --request POST 'https://api.fastgpt.in/api/v1/chat/completions'
    },
    "messages": [
        {
+            "role": "user",
            "content": "导演是谁",
-            "role": "user"
+        }
+    ]
+}'
+```
+
+{{< /markdownify >}}
+{{< /tab >}}
+
+{{< tab tabName="图片/文件请求示例" >}}
+{{< markdownify >}}
+
+* 仅`messages`有部分区别，其他参数一致。
+* 目前不支持上次文件，需上传到自己的对象存储中，获取对应的文件链接。
+
+```bash
+curl --location --request POST 'http://localhost:3000/api/v1/chat/completions' \
+--header 'Authorization: Bearer fastgpt-xxxxxx' \
+--header 'Content-Type: application/json' \
+--data-raw '{
+    "chatId": "abcd",
+    "stream": false,
+    "messages": [
+        {
+            "role": "user",
+            "content": [
+                {
+                    "type": "text",
+                    "text": "导演是谁"
+                },
+                {
+                    "type": "image_url",
+                    "image_url": {
+                        "url": "图片链接"
+                    }
+                },
+                {
+                    "type": "file_url",
+                    "name": "文件名",
+                    "url": "文档链接，支持 txt md html word pdf ppt csv excel"
+                }
+            ]
        }
    ]
 }'
@@ -269,7 +312,6 @@ event取值：
 {{< /tabs >}}


-
 ## 请求插件

 插件的接口与对话接口一致，仅请求参数略有区别，有以下规定：
@@ -455,8 +497,728 @@ event取值：
 {{< /tab >}}
 {{< /tabs >}}

-## 使用案例

- [接入 NextWeb/ChatGPT web 等应用](/docs/course/openapi)
- [接入 onwechat](/docs/use-cases/onwechat)
- [接入 飞书](/docs/course/feishu)
+
+# 对话 CRUD
+
+{{% alert icon="🤖 " context="success" %}}
+* 以下接口可使用任意`API Key`调用。  
+* 4.8.12 以上版本才能使用
+{{% /alert %}}
+
+**重要字段**
+
+* chatId - 指一个应用下，某一个对话窗口的 ID
+* dataId - 指一个对话窗口下，某一个对话记录的 ID
+
+## 历史记录
+
+### 获取某个应用历史记录
+
+{{< tabs tabTotal="3" >}}
+{{< tab tabName="请求示例" >}}
+{{< markdownify >}}
+
+```bash
+curl --location --request POST 'http://localhost:3000/api/core/chat/getHistories' \
+--header 'Authorization: Bearer {{apikey}}' \
+--header 'Content-Type: application/json' \
+--data-raw '{
+    "appId": "appId",
+    "offset": 0,
+    "pageSize": 20
+}'
+```
+
+{{< /markdownify >}}
+{{< /tab >}}
+
+{{< tab tabName="参数说明" >}}
+{{< markdownify >}}
+
+{{% alert icon=" " context="success" %}}
+- appId - 应用 Id
+- offset - 偏移量，即从第几条数据开始取
+- pageSize - 记录数量
+{{% /alert %}}
+
+{{< /markdownify >}}
+{{< /tab >}}
+
+{{< tab tabName="响应示例" >}}
+{{< markdownify >}}
+
+```json
+{
+    "code": 200,
+    "statusText": "",
+    "message": "",
+    "data": {
+        "list": [
+            {
+                "chatId": "usdAP1GbzSGu",
+                "updateTime": "2024-10-13T03:29:05.779Z",
+                "appId": "66e29b870b24ce35330c0f08",
+                "customTitle": "",
+                "title": "你好",
+                "top": false
+            },
+            {
+                "chatId": "lC0uTAsyNBlZ",
+                "updateTime": "2024-10-13T03:22:19.950Z",
+                "appId": "66e29b870b24ce35330c0f08",
+                "customTitle": "",
+                "title": "测试",
+                "top": false
+            }
+        ],
+        "total": 2
+    }
+}
+```
+
+{{< /markdownify >}}
+{{< /tab >}}
+{{< /tabs >}}
+
+### 修改某个对话的标题
+
+{{< tabs tabTotal="3" >}}
+{{< tab tabName="请求示例" >}}
+{{< markdownify >}}
+
+```bash
+curl --location --request POST 'http://localhost:3000/api/core/chat/updateHistory' \
+--header 'Authorization: Bearer {{apikey}}' \
+--header 'Content-Type: application/json' \
+--data-raw '{
+    "appId": "appId",
+    "chatId": "chatId",
+    "customTitle": "自定义标题"
+}'
+```
+
+{{< /markdownify >}}
+{{< /tab >}}
+
+{{< tab tabName="参数说明" >}}
+{{< markdownify >}}
+
+{{% alert icon=" " context="success" %}}
+- appId - 应用 Id
+- chatId - 历史记录 Id
+- customTitle - 自定义对话名
+{{% /alert %}}
+
+{{< /markdownify >}}
+{{< /tab >}}
+
+{{< tab tabName="响应示例" >}}
+{{< markdownify >}}
+
+```json
+{
+    "code": 200,
+    "statusText": "",
+    "message": "",
+    "data": null
+}
+```
+
+{{< /markdownify >}}
+{{< /tab >}}
+{{< /tabs >}}
+
+### 置顶 / 取消置顶
+{{< tabs tabTotal="3" >}}
+{{< tab tabName="请求示例" >}}
+{{< markdownify >}}
+
+```bash
+curl --location --request POST 'http://localhost:3000/api/core/chat/updateHistory' \
+--header 'Authorization: Bearer {{apikey}}' \
+--header 'Content-Type: application/json' \
+--data-raw '{
+    "appId": "appId",
+    "chatId": "chatId",
+    "top": true
+}'
+```
+
+{{< /markdownify >}}
+{{< /tab >}}
+
+{{< tab tabName="参数说明" >}}
+{{< markdownify >}}
+
+{{% alert icon=" " context="success" %}}
+- appId - 应用Id
+- chatId - 历史记录 Id
+- top - 是否置顶，ture 置顶，false 取消置顶
+{{% /alert %}}
+
+{{< /markdownify >}}
+{{< /tab >}}
+
+{{< tab tabName="响应示例" >}}
+{{< markdownify >}}
+
+```json
+{
+    "code": 200,
+    "statusText": "",
+    "message": "",
+    "data": null
+}
+```
+
+{{< /markdownify >}}
+{{< /tab >}}
+{{< /tabs >}}
+
+### 删除某个历史记录
+
+{{< tabs tabTotal="3" >}}
+{{< tab tabName="请求示例" >}}
+{{< markdownify >}}
+
+```bash
+curl --location --request DELETE 'http://localhost:3000/api/core/chat/delHistory?chatId={{chatId}}&appId={{appId}}' \
+--header 'Authorization: Bearer {{apikey}}'
+```
+
+{{< /markdownify >}}
+{{< /tab >}}
+
+{{< tab tabName="参数说明" >}}
+{{< markdownify >}}
+
+{{% alert icon=" " context="success" %}}
+- appId - 应用 Id
+- chatId - 历史记录 Id
+{{% /alert %}}
+
+{{< /markdownify >}}
+{{< /tab >}}
+
+{{< tab tabName="响应示例" >}}
+{{< markdownify >}}
+
+```json
+{
+    "code": 200,
+    "statusText": "",
+    "message": "",
+    "data": null
+}
+```
+
+{{< /markdownify >}}
+{{< /tab >}}
+{{< /tabs >}}
+
+### 清空所有历史记录
+
+{{< tabs tabTotal="3" >}}
+{{< tab tabName="请求示例" >}}
+{{< markdownify >}}
+
+```bash
+curl --location --request DELETE 'http://localhost:3000/api/core/chat/clearHistories?appId={{appId}}' \
+--header 'Authorization: Bearer {{apikey}}'
+```
+
+{{< /markdownify >}}
+{{< /tab >}}
+
+{{< tab tabName="参数说明" >}}
+{{< markdownify >}}
+
+{{% alert icon=" " context="success" %}}
+- appId - 应用 Id
+{{% /alert %}}
+
+{{< /markdownify >}}
+{{< /tab >}}
+
+{{< tab tabName="响应示例" >}}
+{{< markdownify >}}
+
+```json
+{
+    "code": 200,
+    "statusText": "",
+    "message": "",
+    "data": null
+}
+```
+
+{{< /markdownify >}}
+{{< /tab >}}
+{{< /tabs >}}
+
+## 对话记录
+
+指的是某个 chatId 下的对话记录操作。
+
+### 获取单个对话初始化信息
+
+{{< tabs tabTotal="3" >}}
+{{< tab tabName="请求示例" >}}
+{{< markdownify >}}
+
+```bash
+curl --location --request GET 'http://localhost:3000/api/core/chat/init?appId={{appId}}&chatId={{chatId}}' \
+--header 'Authorization: Bearer {{apikey}}'
+```
+{{< /markdownify >}}
+{{< /tab >}}
+
+{{< tab tabName="参数说明" >}}
+{{< markdownify >}}
+
+{{% alert icon=" " context="success" %}}
+- appId - 应用 Id
+- chatId - 历史记录 Id
+{{% /alert %}}
+
+{{< /markdownify >}}
+{{< /tab >}}
+
+{{< tab tabName="响应示例" >}}
+{{< markdownify >}}
+```json
+{
+    "code": 200,
+    "statusText": "",
+    "message": "",
+    "data": {
+        "chatId": "sPVOuEohjo3w",
+        "appId": "66e29b870b24ce35330c0f08",
+        "variables": {
+
+        },
+        "app": {
+            "chatConfig": {
+                "questionGuide": true,
+                "ttsConfig": {
+                    "type": "web"
+                },
+                "whisperConfig": {
+                    "open": false,
+                    "autoSend": false,
+                    "autoTTSResponse": false
+                },
+                "chatInputGuide": {
+                    "open": false,
+                    "textList": [
+
+                    ],
+                    "customUrl": ""
+                },
+                "instruction": "",
+                "variables": [
+
+                ],
+                "fileSelectConfig": {
+                    "canSelectFile": true,
+                    "canSelectImg": true,
+                    "maxFiles": 10
+                },
+                "_id": "66f1139aaab9ddaf1b5c596d",
+                "welcomeText": ""
+            },
+            "chatModels": [
+                "GPT-4o-mini"
+            ],
+            "name": "测试",
+            "avatar": "/imgs/app/avatar/workflow.svg",
+            "intro": "",
+            "type": "advanced",
+            "pluginInputs": [
+
+            ]
+        }
+    }
+}
+```
+
+{{< /markdownify >}}
+{{< /tab >}}
+{{< /tabs >}}
+
+### 获取对话记录列表
+
+{{< tabs tabTotal="3" >}}
+{{< tab tabName="请求示例" >}}
+{{< markdownify >}}
+
+```bash
+curl --location --request POST 'http://localhost:3000/api/core/chat/getPaginationRecords' \
+--header 'Authorization: Bearer {{apikey}}' \
+--header 'Content-Type: application/json' \
+--data-raw '{
+    "appId": "appId",
+    "chatId": "chatId",
+    "offset": 0,
+    "pageSize": 10,
+    "loadCustomFeedbacks": true
+}'
+```
+
+{{< /markdownify >}}
+{{< /tab >}}
+
+{{< tab tabName="参数说明" >}}
+{{< markdownify >}}
+
+{{% alert icon=" " context="success" %}}
+- appId - 应用 Id
+- chatId - 历史记录 Id
+- offset - 偏移量
+- pageSize - 记录数量
+- loadCustomFeedbacks - 是否读取自定义反馈（可选）
+{{% /alert %}}
+
+{{< /markdownify >}}
+{{< /tab >}}
+
+{{< tab tabName="响应示例" >}}
+{{< markdownify >}}
+
+```json
+{
+    "code": 200,
+    "statusText": "",
+    "message": "",
+    "data": {
+        "list": [
+            {
+                "_id": "670b84e6796057dda04b0fd2",
+                "dataId": "jzqdV4Ap1u004rhd2WW8yGLn",
+                "obj": "Human",
+                "value": [
+                    {
+                        "type": "text",
+                        "text": {
+                            "content": "你好"
+                        }
+                    }
+                ],
+                "customFeedbacks": [
+
+                ]
+            },
+            {
+                "_id": "670b84e6796057dda04b0fd3",
+                "dataId": "x9KQWcK9MApGdDQH7z7bocw1",
+                "obj": "AI",
+                "value": [
+                    {
+                        "type": "text",
+                        "text": {
+                            "content": "你好！有什么我可以帮助你的吗？"
+                        }
+                    }
+                ],
+                "customFeedbacks": [
+
+                ],
+                "llmModuleAccount": 1,
+                "totalQuoteList": [
+
+                ],
+                "totalRunningTime": 2.42,
+                "historyPreviewLength": 2
+            }
+        ],
+        "total": 2
+    }
+}
+```
+
+{{< /markdownify >}}
+{{< /tab >}}
+{{< /tabs >}}
+
+### 获取单个对话记录运行详情
+
+{{< tabs tabTotal="3" >}}
+{{< tab tabName="请求示例" >}}
+{{< markdownify >}}
+
+```bash
+curl --location --request GET 'http://localhost:3000/api/core/chat/getResData?appId={{appId}}&chatId={{chatId}}&dataId={{dataId}}' \
+--header 'Authorization: Bearer {{apikey}}'
+```
+
+{{< /markdownify >}}
+{{< /tab >}}
+
+{{< tab tabName="参数说明" >}}
+{{< markdownify >}}
+
+{{% alert icon=" " context="success" %}}
+- appId - 应用 Id
+- chatId - 对话 Id
+- dataId - 对话记录 Id
+{{% /alert %}}
+
+{{< /markdownify >}}
+{{< /tab >}}
+
+{{< tab tabName="响应示例" >}}
+{{< markdownify >}}
+
+```json
+{
+    "code": 200,
+    "statusText": "",
+    "message": "",
+    "data": [
+        {
+            "id": "mVlxkz8NfyfU",
+            "nodeId": "448745",
+            "moduleName": "common:core.module.template.work_start",
+            "moduleType": "workflowStart",
+            "runningTime": 0
+        },
+        {
+            "id": "b3FndAdHSobY",
+            "nodeId": "z04w8JXSYjl3",
+            "moduleName": "AI 对话",
+            "moduleType": "chatNode",
+            "runningTime": 1.22,
+            "totalPoints": 0.02475,
+            "model": "GPT-4o-mini",
+            "tokens": 75,
+            "query": "测试",
+            "maxToken": 2000,
+            "historyPreview": [
+                {
+                    "obj": "Human",
+                    "value": "你好"
+                },
+                {
+                    "obj": "AI",
+                    "value": "你好！有什么我可以帮助你的吗？"
+                },
+                {
+                    "obj": "Human",
+                    "value": "测试"
+                },
+                {
+                    "obj": "AI",
+                    "value": "测试成功！请问你有什么具体的问题或者需要讨论的话题吗？"
+                }
+            ],
+            "contextTotalLen": 4
+        }
+    ]
+}
+```
+
+{{< /markdownify >}}
+{{< /tab >}}
+{{< /tabs >}}
+
+
+### 删除对话记录
+
+{{< tabs tabTotal="3" >}}
+{{< tab tabName="请求示例" >}}
+{{< markdownify >}}
+
+```bash
+curl --location --request DELETE 'http://localhost:3000/api/core/chat/item/delete?contentId={{contentId}}&chatId={{chatId}}&appId={{appId}}' \
+--header 'Authorization: Bearer {{apikey}}'
+```
+
+{{< /markdownify >}}
+{{< /tab >}}
+
+{{< tab tabName="参数说明" >}}
+{{< markdownify >}}
+
+{{% alert icon=" " context="success" %}}
+- appId - 应用 Id
+- chatId - 历史记录 Id
+- contentId - 对话记录 Id
+{{% /alert %}}
+
+{{< /markdownify >}}
+{{< /tab >}}
+
+{{< tab tabName="响应示例" >}}
+{{< markdownify >}}
+
+```json
+{
+    "code": 200,
+    "statusText": "",
+    "message": "",
+    "data": null
+}
+```
+
+{{< /markdownify >}}
+{{< /tab >}}
+{{< /tabs >}}
+
+### 点赞 / 取消点赞
+
+{{< tabs tabTotal="3" >}}
+{{< tab tabName="请求示例" >}}
+{{< markdownify >}}
+
+```bash
+curl --location --request POST 'http://localhost:3000/api/core/chat/feedback/updateUserFeedback' \
+--header 'Authorization: Bearer {{apikey}}' \
+--header 'Content-Type: application/json' \
+--data-raw '{
+    "appId": "appId",
+    "chatId": "chatId",
+    "dataId": "dataId",
+    "userGoodFeedback": "yes"
+}'
+```
+
+{{< /markdownify >}}
+{{< /tab >}}
+
+{{< tab tabName="参数说明" >}}
+{{< markdownify >}}
+
+{{% alert icon=" " context="success" %}}
+- appId - 应用 Id
+- chatId - 历史记录 Id
+- dataId - 对话记录 Id
+- userGoodFeedback - 用户点赞时的信息（可选），取消点赞时不填此参数即可
+{{% /alert %}}
+
+{{< /markdownify >}}
+{{< /tab >}}
+
+{{< tab tabName="响应示例" >}}
+{{< markdownify >}}
+
+```json
+{
+    "code": 200,
+    "statusText": "",
+    "message": "",
+    "data": null
+}
+```
+
+{{< /markdownify >}}
+{{< /tab >}}
+{{< /tabs >}}
+
+### 点踩 / 取消点踩
+
+{{< tabs tabTotal="3" >}}
+{{< tab tabName="请求示例" >}}
+{{< markdownify >}}
+
+```bash
+curl --location --request POST 'http://localhost:3000/api/core/chat/feedback/updateUserFeedback' \
+--header 'Authorization: Bearer {{apikey}}' \
+--header 'Content-Type: application/json' \
+--data-raw '{
+    "appId": "appId",
+    "chatId": "chatId",
+    "dataId": "dataId",
+    "userBadFeedback": "yes"
+}'
+```
+
+{{< /markdownify >}}
+{{< /tab >}}
+
+{{< tab tabName="参数说明" >}}
+{{< markdownify >}}
+
+{{% alert icon=" " context="success" %}}
+- appId - 应用 Id
+- chatId - 历史记录 Id
+- dataId - 对话记录 Id
+- userBadFeedback - 用户点踩时的信息（可选），取消点踩时不填此参数即可
+{{% /alert %}}
+
+{{< /markdownify >}}
+{{< /tab >}}
+
+{{< tab tabName="响应示例" >}}
+{{< markdownify >}}
+
+```json
+{
+    "code": 200,
+    "statusText": "",
+    "message": "",
+    "data": null
+}
+```
+{{< /markdownify >}}
+{{< /tab >}}
+{{< /tabs >}}
+
+## 猜你想问
+
+{{< tabs tabTotal="3" >}}
+{{< tab tabName="请求示例" >}}
+{{< markdownify >}}
+
+```bash
+curl --location --request POST 'http://localhost:3000/api/core/ai/agent/createQuestionGuide' \
+--header 'Authorization: Bearer {{apikey}}' \
+--header 'Content-Type: application/json' \
+--data-raw '{
+    "messages":[
+        {
+            "role": "user",
+            "content": "你好"
+        },
+        {
+            "role": "assistant",
+            "content": "你好！有什么我可以帮助你的吗？"
+        }
+    ]
+}'
+```
+
+{{< /markdownify >}}
+{{< /tab >}}
+
+{{< tab tabName="参数说明" >}}
+{{< markdownify >}}
+
+{{% alert icon=" " context="success" %}}
+- messages - 对话消息，提供给 AI 的消息记录
+{{% /alert %}}
+
+{{< /markdownify >}}
+{{< /tab >}}
+
+{{< tab tabName="响应示例" >}}
+{{< markdownify >}}
+
+```json
+{
+    "code": 200,
+    "statusText": "",
+    "message": "",
+    "data": [
+        "你对AI有什么看法？",
+        "想了解AI的应用吗？",
+        "你希望AI能做什么？"
+    ]
+}
+```
+{{< /markdownify >}}
+{{< /tab >}}
+{{< /tabs >}}
+
+
+
--- a/docSite/content/zh-cn/docs/development/openapi/dataset.md
+++ b/docSite/content/zh-cn/docs/development/openapi/dataset.md
@@ -22,7 +22,7 @@ weight: 853
 **新例子**

 ```bash
-curl --location --request POST 'https://api.fastgpt.in/api/support/wallet/usage/createTrainingUsage' \
+curl --location --request POST 'http://localhost:3000/api/support/wallet/usage/createTrainingUsage' \
 --header 'Authorization: Bearer {{apikey}}' \
 --header 'Content-Type: application/json' \
 --data-raw '{
@@ -34,7 +34,7 @@ curl --location --request POST 'https://api.fastgpt.in/api/support/wallet/usage/
 **x例子**

 ```bash
-curl --location --request POST 'https://api.fastgpt.in/api/support/wallet/bill/createTrainingBill' \
+curl --location --request POST 'http://localhost:3000/api/support/wallet/bill/createTrainingBill' \
 --header 'Authorization: Bearer {{apikey}}' \
 --header 'Content-Type: application/json' \
 --data-raw '{