Skip to content

赵月辉 / fastgpt-migrated

Go to a project
Commit 1992b76a by Archer Committed by GitHub
Options

perf: openapi doc (#7025) 

* perf: openapi doc

* fix: resolve openapi docs mdx build
parent 81b0cad5
Showing with 1489 additions and 1343 deletions
document/content/openapi/app.en.mdx
......@@ -10,87 +10,86 @@ description: FastGPT OpenAPI Application Interface
![alt text](../../public/imgs/image-120.png)
## Log API
### Get Cumulative Run Results
### Get Application Overall Statistics
<Tabs items={["Request Example","Response Example","Parameters"]}>
<Tab value="Request Example">
<Tab value="Request Example">
```bash
curl --location --request GET 'https://cloud.fastgpt.cn/api/proApi/core/app/logs/getTotalData?appId=68c46a70d950e8850ae564ba' \
```bash
curl --location --request GET 'https://cloud.fastgpt.cn/api/proApi/core/app/logs/getTotalData?appId=68c46a70d950e8850ae564ba' \
--header 'Authorization: Bearer apikey'
```
</Tab>
<Tab value="Response Example">
```bash
{
"code": 200,
"statusText": "",
"message": "",
"data": {
"totalUsers": 0,
"totalChats": 0,
"totalPoints": 0
}
}
```
```
</Tab>
</Tab>
<Tab value="Parameters">
<Tab value="Response Example">
<div>
**Request Parameters:**
- appId: Application ID
```bash
{
"code": 200,
"statusText": "",
"message": "",
"data": {
"totalUsers": 0,
"totalChats": 0,
"totalPoints": 0
}
}
```
**Response Parameters:**
- totalUsers: Total number of users
- totalChats: Total number of conversations
- totalPoints: Total points consumed
</div>
</Tab>
</Tab>
<Tab value="Parameters">
**Request Parameters:**
- appId: Application ID
**Response Parameters:**
- totalUsers: Total number of users
- totalChats: Total number of conversations
- totalPoints: Total points consumed
</Tab>
</Tabs>
### Get Application Log Dashboard
### Get Application Chart Data
<Tabs items={["Request Example","Response Example","Parameters"]}>
<Tab value="Request Example">
```bash
```bash
curl --location --request POST 'https://cloud.fastgpt.cn/api/proApi/core/app/logs/getChartData' \
--header 'Authorization: Bearer apikey' \
--header 'Content-Type: application/json' \
--data-raw '{
"appId": "68c46a70d950e8850ae564ba",
"dateStart": "2025-09-19T16:00:00.000Z",
"dateEnd": "2025-09-27T15:59:59.999Z",
"offset": 1,
"source": [
"test",
"online",
"share",
"api",
"cronJob",
"team",
"feishu",
"official_account",
"wecom",
"mcp"
],
"userTimespan": "day",
"chatTimespan": "day",
"appTimespan": "day"
"appId": "68c46a70d950e8850ae564ba",
"dateStart": "2025-09-19T16:00:00.000Z",
"dateEnd": "2025-09-27T15:59:59.999Z",
"offset": 1,
"source": [
"test",
"online",
"share",
"api",
"cronJob",
"team",
"feishu",
"official_account",
"wecom",
"mcp"
],
"userTimespan": "day",
"chatTimespan": "day",
"appTimespan": "day"
}'
```
```
</Tab>
......@@ -156,14 +155,15 @@ curl --location --request POST 'https://cloud.fastgpt.cn/api/proApi/core/app/log
<Tab value="Parameters">
**Request Parameters:**
- appId: Application ID
- dateStart: Start time
- dateEnd: End time
- source: Log source
- offset: User retention offset
- userTimespan: User data timespan //day|week|month|quarter
- chatTimespan: Chat data timespan //day|week|month|quarter
- appTimespan: Application data timespan //day|week|month|quarter
- offset: User retention offset. The unit follows userTimespan
- userTimespan: User data timespan //day|week|month|quarter
- chatTimespan: Chat data timespan //day|week|month|quarter
- appTimespan: Application data timespan //day|week|month|quarter
**Response Parameters:**
......
document/content/openapi/app.mdx
......@@ -10,87 +10,86 @@ description: FastGPT OpenAPI 应用接口
![alt text](../../public/imgs/image-120.png)
## 日志接口
### 获取累积运行结果
### 获取应用总体数据统计
<Tabs items={["请求示例","响应示例","参数说明"]}>
<Tab value="请求示例">
<Tab value="请求示例">
```bash
curl --location --request GET 'https://cloud.fastgpt.cn/api/proApi/core/app/logs/getTotalData?appId=68c46a70d950e8850ae564ba' \
```bash
curl --location --request GET 'https://cloud.fastgpt.cn/api/proApi/core/app/logs/getTotalData?appId=68c46a70d950e8850ae564ba' \
--header 'Authorization: Bearer apikey'
```
</Tab>
<Tab value="响应示例">
```bash
{
"code": 200,
"statusText": "",
"message": "",
"data": {
"totalUsers": 0,
"totalChats": 0,
"totalPoints": 0
}
}
```
```
</Tab>
</Tab>
<Tab value="参数说明">
<Tab value="响应示例">
<div>
**入参：**
- appId: 应用Id
```bash
{
"code": 200,
"statusText": "",
"message": "",
"data": {
"totalUsers": 0,
"totalChats": 0,
"totalPoints": 0
}
}
```
**出参：**
- totalUsers: 累积使用用户数量
- totalChats: 累积对话数量
- totalPoints: 累积积分消耗
</div>
</Tab>
</Tab>
<Tab value="参数说明">
**入参：**
- appId: 应用 ID
**出参：**
- totalUsers: 累积使用用户数量
- totalChats: 累积对话数量
- totalPoints: 累积积分消耗
</Tab>
</Tabs>
### 获取应用日志看板
### 获取应用图表数据
<Tabs items={["请求示例","响应示例","参数说明"]}>
<Tab value="请求示例">
```bash
```bash
curl --location --request POST 'https://cloud.fastgpt.cn/api/proApi/core/app/logs/getChartData' \
--header 'Authorization: Bearer apikey' \
--header 'Content-Type: application/json' \
--data-raw '{
"appId": "68c46a70d950e8850ae564ba",
"dateStart": "2025-09-19T16:00:00.000Z",
"dateEnd": "2025-09-27T15:59:59.999Z",
"offset": 1,
"source": [
"test",
"online",
"share",
"api",
"cronJob",
"team",
"feishu",
"official_account",
"wecom",
"mcp"
],
"userTimespan": "day",
"chatTimespan": "day",
"appTimespan": "day"
"appId": "68c46a70d950e8850ae564ba",
"dateStart": "2025-09-19T16:00:00.000Z",
"dateEnd": "2025-09-27T15:59:59.999Z",
"offset": 1,
"source": [
"test",
"online",
"share",
"api",
"cronJob",
"team",
"feishu",
"official_account",
"wecom",
"mcp"
],
"userTimespan": "day",
"chatTimespan": "day",
"appTimespan": "day"
}'
```
```
</Tab>
......@@ -156,14 +155,15 @@ curl --location --request POST 'https://cloud.fastgpt.cn/api/proApi/core/app/log
<Tab value="参数说明">
**入参：**
- appId: 应用Id
- appId: 应用 ID
- dateStart: 开始时间
- dateEnd: 结束时间
- source: 日志来源
- offset: 用户留存偏移量
- userTimespan: 用户数据时间跨度 //day｜week｜month｜quarter
- chatTimespan: 对话数据时间跨度 //day｜week｜month｜quarter
- appTimespan: 应用数据时间跨度 //day｜week｜month｜quarter
- offset: 用户留存偏移量，单位随 userTimespan 变化
- userTimespan: 用户数据时间跨度 //day｜week｜month｜quarter
- chatTimespan: 对话数据时间跨度 //day｜week｜month｜quarter
- appTimespan: 应用数据时间跨度 //day｜week｜month｜quarter
**出参：**
......@@ -192,4 +192,4 @@ curl --location --request POST 'https://cloud.fastgpt.cn/api/proApi/core/app/log
</Tab>
</Tabs>
\ No newline at end of file
</Tabs>
document/content/openapi/chat.en.mdx
......@@ -20,98 +20,96 @@ You can find the AppId in your application details URL.
The `v1` chat API is compatible with the `GPT` interface! If you're using the standard `GPT` official API, you can access FastGPT by simply changing the `BaseUrl` and `Authorization`. However, note these rules:
* Parameters like `model` and `temperature` are ignored. These values are determined by your workflow configuration.
* Won't return actual `Token` consumed. If needed, set `detail=true` and manually calculate `tokens` from `responseData`.
- Parameters like `model` and `temperature` are ignored. These values are determined by your workflow configuration.
- Won't return actual `Token` consumed. If needed, set `detail=true` and manually calculate `tokens` from `responseData`.
### Request
<Tabs items={["Basic Request Example","Image/File Request Example","Parameters"]}>
<Tab value="Basic Request Example">
```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": "my_chatId",
"stream": false,
"detail": false,
"responseChatItemId": "my_responseChatItemId",
"variables": {
"uid": "asdfadsfasfd2323",
"name": "张三"
},
"messages": [
{
"role": "user",
"content": "导演是谁"
}
]
}'
```
<Tab value="Basic Request Example">
</Tab>
```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": "my_chatId",
"stream": false,
"detail": false,
"responseChatItemId": "my_responseChatItemId",
"variables": {
"uid": "asdfadsfasfd2323",
"name": "张三"
},
"messages": [
{
"role": "user",
"content": "导演是谁"
}
]
}'
```
<Tab value="Image/File Request Example">
</Tab>
- Only `messages` differs slightly; other parameters are the same.
- Direct file uploads are not supported. Upload files to your object storage and provide the URL.
<Tab value="Image/File Request Example">
```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"
}
]
}
]
}'
```
- Only `messages` differs slightly; other parameters are the same.
- Direct file uploads are not supported. Upload files to your object storage and provide the URL.
</Tab>
```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"
}
]
}
]
}'
```
<Tab value="Parameters">
</Tab>
<Tab value="Parameters">
<div>
- headers.Authorization: Bearer [apikey]
- chatId: string | undefined 。
- 为时（不传入），不使用 FastGpt 提供的上下文功能，完全通过传入的 messages 构建上下文。
- 为`非空字符串`时，意味着使用 chatId 进行对话，自动从 FastGpt 数据库取历史记录，并使用 messages数组最后一个内容作为用户问题，其余 message 会被忽略。请自行确保 chatId唯一，长度小于250，通常可以是自己系统的对话框ID。
- messages: 结构与[GPT接口](https://platform.openai.com/docs/api-reference/chat/object) chat模式一致。
- responseChatItemId: string | undefined 。如果传入，则会将该值作为本次对话的响应消息的 ID，FastGPT会自动将该 ID 存入数据库。请确保，在当前`chatId`下，`responseChatItemId`是唯一的。
- detail:是否返回中间值（模块状态，响应的完整结果等），`stream模式`下会通过`event`进行区分，`非stream模式`结果保存在`responseData`中。
- variables: 模块变量，一个对象，会替换模块中，输入框内容里的`[key]`
</div>
</Tab>
- chatId: string | undefined.
- Empty or omitted: FastGPT context is not used, and context is built entirely from `messages`.
- Non-empty string: uses `chatId` for the chat, automatically reads history from the FastGPT database, and uses only the last item in `messages` as the user question. Other messages are ignored. Make sure `chatId` is unique and shorter than 250 characters.
- messages: Same structure as [GPT chat messages](https://platform.openai.com/docs/api-reference/chat/object).
- responseChatItemId: string | undefined. If provided, FastGPT uses it as the response message ID and stores it in the database. Make sure it is unique under the current `chatId`.
- detail: Whether to return intermediate values. In `stream` mode, they are separated by `event`; in non-stream mode, they are stored in `responseData`.
- variables: Module variables. This object replaces `[key]` placeholders in input fields.
</Tab>
</Tabs>
### Response
<Tabs items={['detail=false,stream=false 响应','detail=false,stream=true 响应','detail=true,stream=false 响应','detail=true,stream=true 响应','Event Values']}>
<Tab value="detail=false, stream=false Response">
<Tab value="detail=false, stream=false Response">
```json
{
......@@ -135,8 +133,8 @@ The `v1` chat API is compatible with the `GPT` interface! If you're using the st
}
```
</Tab>
<Tab value="detail=false, stream=true Response">
</Tab>
<Tab value="detail=false, stream=true Response">
```bash
data: {"id":"","object":"","created":0,"choices":[{"delta":{"content":""},"index":0,"finish_reason":null}]}
......@@ -148,8 +146,8 @@ data: {"id":"","object":"","created":0,"choices":[{"delta":{"content":"影"},"in
data: {"id":"","object":"","created":0,"choices":[{"delta":{"content":"《"},"index":0,"finish_reason":null}]}
```
</Tab>
<Tab value="detail=true, stream=false Response">
</Tab>
<Tab value="detail=true, stream=false Response">
```json
{
......@@ -238,8 +236,8 @@ data: {"id":"","object":"","created":0,"choices":[{"delta":{"content":"《"},"in
}
```
</Tab>
<Tab value="detail=true, stream=true Response">
</Tab>
<Tab value="detail=true, stream=true Response">
```bash
event: flowNodeStatus
......@@ -273,8 +271,8 @@ event: flowResponses
data: [{"moduleName":"知识库搜索","moduleType":"datasetSearchNode","runningTime":1.78},{"question":"导演是谁","quoteList":[{"id":"654f2e49b64caef1d9431e8b","q":"电影《铃芽之旅》的导演是谁？","a":"电影《铃芽之旅》的导演是新海诚!","indexes":[{"type":"qa","dataId":"3515487","text":"电影《铃芽之旅》的导演是谁？","_id":"654f2e49b64caef1d9431e8c","defaultIndex":true}],"datasetId":"646627f4f7b896cfd8910e38","collectionId":"653279b16cd42ab509e766e8","sourceName":"data (81).csv","sourceId":"64fd3b6423aa1307b65896f6","score":0.8935586214065552},{"id":"6552e14c50f4a2a8e632af11","q":"导演是谁？","a":"电影《铃芽之旅》的导演是新海诚。","indexes":[{"defaultIndex":true,"type":"qa","dataId":"3644565","text":"导演是谁？\n电影《铃芽之旅》的导演是新海诚。","_id":"6552e14dde5cc7ba3954e417"}],"datasetId":"646627f4f7b896cfd8910e38","collectionId":"653279b16cd42ab509e766e8","sourceName":"data (81).csv","sourceId":"64fd3b6423aa1307b65896f6","score":0.8890955448150635},{"id":"654f34a0b64caef1d946337e","q":"本作的主人公是谁？","a":"本作的主人公是名叫铃芽的少女。","indexes":[{"type":"qa","dataId":"3515541","text":"本作的主人公是谁？","_id":"654f34a0b64caef1d946337f","defaultIndex":true}],"datasetId":"646627f4f7b896cfd8910e38","collectionId":"653279b16cd42ab509e766e8","sourceName":"data (81).csv","sourceId":"64fd3b6423aa1307b65896f6","score":0.8738770484924316},{"id":"654f3002b64caef1d944207a","q":"电影《铃芽之旅》男主角是谁？","a":"电影《铃芽之旅》男主角是宗像草太，由松村北斗配音。","indexes":[{"type":"qa","dataId":"3515538","text":"电影《铃芽之旅》男主角是谁？","_id":"654f3002b64caef1d944207b","defaultIndex":true}],"datasetId":"646627f4f7b896cfd8910e38","collectionId":"653279b16cd42ab509e766e8","sourceName":"data (81).csv","sourceId":"64fd3b6423aa1307b65896f6","score":0.8607980012893677},{"id":"654f2fc8b64caef1d943fd46","q":"电影《铃芽之旅》的编剧是谁？","a":"新海诚是本片的编剧。","indexes":[{"defaultIndex":true,"type":"qa","dataId":"3515550","text":"电影《铃芽之旅》的编剧是谁？22","_id":"654f2fc8b64caef1d943fd47"}],"datasetId":"646627f4f7b896cfd8910e38","collectionId":"653279b16cd42ab509e766e8","sourceName":"data (81).csv","sourceId":"64fd3b6423aa1307b65896f6","score":0.8468944430351257}],"moduleName":"AI 对话","moduleType":"chatNode","runningTime":1.86}]
```
</Tab>
<Tab value="Event Values">
</Tab>
<Tab value="Event Values">
event取值：
......@@ -288,7 +286,7 @@ event取值：
- updateVariables: 更新变量
- error: 报错
</Tab>
</Tab>
</Tabs>
### Response
......@@ -298,7 +296,7 @@ If your workflow contains interactive nodes, still call this API with `detail=tr
When calling a workflow with interactive nodes, if an interactive node is encountered, it returns immediately with this info:
<Tabs items={['User Selection','Form Input']}>
<Tab value="User Selection">
<Tab value="User Selection">
```json
{
......@@ -321,8 +319,8 @@ When calling a workflow with interactive nodes, if an interactive node is encoun
}
```
</Tab>
<Tab value="Form Input">
</Tab>
<Tab value="Form Input">
```json
{
......@@ -369,7 +367,7 @@ When calling a workflow with interactive nodes, if an interactive node is encoun
}
```
</Tab>
</Tab>
</Tabs>
### Continue Interactive Node
......@@ -377,7 +375,7 @@ When calling a workflow with interactive nodes, if an interactive node is encoun
After receiving interactive node info, render your UI to guide user input or selection. Then call this API again to continue the workflow. Use this format:
<Tabs items={['User Selection','Form Input']}>
<Tab value="User Selection">
<Tab value="User Selection">
For user selection, simply pass the selected value to messages.
......@@ -398,8 +396,8 @@ curl --location --request POST 'http://localhost:3000/api/v1/chat/completions' \
}'
```
</Tab>
<Tab value="Form Input">
</Tab>
<Tab value="Form Input">
Form input is slightly more complex. Serialize the input as a JSON string for `messages`. Object keys match form keys, values are user inputs. Ensure `chatId` is consistent.
......@@ -420,7 +418,7 @@ curl --location --request POST 'http://localhost:3000/api/v1/chat/completions' \
}'
```
</Tab>
</Tab>
</Tabs>
## Request Plugin
......@@ -451,7 +449,7 @@ curl --location --request POST 'http://localhost:3000/api/v1/chat/completions' \
### Response
<Tabs items={['detail=true,stream=false 响应','detail=true,stream=true 响应','Output Retrieval']}>
<Tab value="detail=true, stream=false Response">
<Tab value="detail=true, stream=false Response">
- Find plugin output by locating `moduleType=pluginOutput` in `responseData`. Its `pluginOutput` contains the output.
- Stream output is still available via `choices`.
......@@ -515,8 +513,8 @@ curl --location --request POST 'http://localhost:3000/api/v1/chat/completions' \
}
```
</Tab>
<Tab value="detail=true, stream=true Response">
</Tab>
<Tab value="detail=true, stream=true Response">
- Get plugin output by deserializing the `event=flowResponses` string into an array. Find `moduleType=pluginOutput` element; its `pluginOutput` contains the output.
- Stream output works the same as chat API.
......@@ -580,8 +578,8 @@ event: flowResponses
data: [{"nodeId":"fdDgXQ6SYn8v","moduleName":"AI 对话","moduleType":"chatNode","totalPoints":0.033,"model":"FastAI-3.5","tokens":33,"query":"你好","maxToken":2000,"historyPreview":[{"obj":"Human","value":"你好"},{"obj":"AI","value":"你好！有什么可以帮助你的吗？"}],"contextTotalLen":2,"runningTime":1.42},{"nodeId":"pluginOutput","moduleName":"插件输出","moduleType":"pluginOutput","totalPoints":0,"pluginOutput":{"result":"你好！有什么可以帮助你的吗？"},"runningTime":0}]
```
</Tab>
<Tab value="Output Retrieval">
</Tab>
<Tab value="Output Retrieval">
event取值：
......@@ -595,25 +593,25 @@ event取值：
- updateVariables: 更新变量
- error: 报错
</Tab>
</Tab>
</Tabs>
# Chat CRUD
* The following APIs can be called with any `API Key`.
* 4.8.12 and above
- The following APIs can be called with any `API Key`.
- 4.8.12 and above
****Important Fields****
\***\*Important Fields\*\***
- chatId - The ID of a conversation window under an application
- dataId - The ID of a chat record under a conversation window
## History
## History Management
## History
### Get History List
<Tabs items={['Request Example','Parameters','Response Example']}>
<Tab value="Request Example">
<Tab value="Request Example">
```bash
curl --location --request POST 'http://localhost:3000/api/core/chat/history/getHistories' \
......@@ -627,19 +625,17 @@ curl --location --request POST 'http://localhost:3000/api/core/chat/history/getH
}'
```
</Tab>
<Tab value="Parameters">
</Tab>
<Tab value="Parameters">
<div>
- appId - Application ID
- offset - Offset (starting position)
- pageSize - Number of records
- source - Chat source. source=api means get API-created chats only (excludes web UI chats)
</div>
- source - Chat source. `source=api` means get API-created chats only (excludes web UI chats)
</Tab>
</Tab>
<Tab value="Response Example" >
<Tab value="Response Example" >
```json
{
......@@ -670,16 +666,16 @@ curl --location --request POST 'http://localhost:3000/api/core/chat/history/getH
}
```
</Tab>
</Tab>
</Tabs>
### Update Chat Title
### Update History Title
<Tabs items={['Request Example','Parameters','Response Example']}>
<Tab value="Request Example">
<Tab value="Request Example">
```bash
curl --location --request POST 'http://localhost:3000/api/core/chat/history/updateHistory' \
curl --location --request PUT 'http://localhost:3000/api/core/chat/history/updateHistory' \
--header 'Authorization: Bearer [apikey]' \
--header 'Content-Type: application/json' \
--data-raw '{
......@@ -689,19 +685,17 @@ curl --location --request POST 'http://localhost:3000/api/core/chat/history/upda
}'
```
</Tab>
</Tab>
<Tab value="Parameters" >
<Tab value="Parameters" >
<div>
- appId - Application ID
- chatId - History ID
- customTitle - Custom chat title
</div>
</Tab>
</Tab>
<Tab value="Response Example" >
<Tab value="Response Example" >
```json
{
......@@ -712,16 +706,16 @@ curl --location --request POST 'http://localhost:3000/api/core/chat/history/upda
}
```
</Tab>
</Tab>
</Tabs>
### Pin / Unpin
### Update History Pin Status
<Tabs items={['Request Example','Parameters','Response Example']}>
<Tab value="Request Example">
<Tab value="Request Example">
```bash
curl --location --request POST 'http://localhost:3000/api/core/chat/history/updateHistory' \
curl --location --request PUT 'http://localhost:3000/api/core/chat/history/updateHistory' \
--header 'Authorization: Bearer [apikey]' \
--header 'Content-Type: application/json' \
--data-raw '{
......@@ -731,19 +725,17 @@ curl --location --request POST 'http://localhost:3000/api/core/chat/history/upda
}'
```
</Tab>
</Tab>
<Tab value="Parameters" >
<Tab value="Parameters" >
<div>
- appId - Application ID
- chatId - History ID
- top - Whether to pin. true = pin, false = unpin
</div>
</Tab>
</Tab>
<Tab value="Response Example" >
<Tab value="Response Example" >
```json
{
......@@ -754,31 +746,29 @@ curl --location --request POST 'http://localhost:3000/api/core/chat/history/upda
}
```
</Tab>
</Tab>
</Tabs>
## History
### Delete a History Record
<Tabs items={['Request Example','Parameters','Response Example']}>
<Tab value="Request Example">
<Tab value="Request Example">
```bash
curl --location --request DELETE 'http://localhost:3000/api/core/chat/history/delHistory?chatId=[chatId]&appId=[appId]' \
--header 'Authorization: Bearer [apikey]'
```
</Tab>
</Tab>
<Tab value="Parameters" >
<Tab value="Parameters" >
<div>
- appId - Application ID
- chatId - History ID
</div>
</Tab>
</Tab>
<Tab value="Response Example" >
<Tab value="Response Example" >
```json
{
......@@ -789,32 +779,30 @@ curl --location --request DELETE 'http://localhost:3000/api/core/chat/history/de
}
```
</Tab>
</Tab>
</Tabs>
## History
### Clear App History Records
Only clears chat history created via API Key. Does not clear history from web UI, share links, or other sources.
<Tabs items={['Request Example','Parameters','Response Example']}>
<Tab value="Request Example">
<Tab value="Request Example">
```bash
curl --location --request DELETE 'http://localhost:3000/api/core/chat/history/clearHistories?appId=[appId]' \
--header 'Authorization: Bearer [apikey]'
```
</Tab>
</Tab>
<Tab value="Parameters" >
<Tab value="Parameters" >
<div>
- appId - Application ID
</div>
</Tab>
</Tab>
<Tab value="Response Example" >
<Tab value="Response Example" >
```json
{
......@@ -825,89 +813,87 @@ curl --location --request DELETE 'http://localhost:3000/api/core/chat/history/cl
}
```
</Tab>
</Tab>
</Tabs>
## Chat Records
Operations on chat records under a specific chatId.
### Get Chat Initialization Info
### Get Chat Box Basic Info
<Tabs items={['Request Example','Parameters','Response Example']}>
<Tab value="Request Example">
<Tab value="Request Example">
```bash
curl --location --request GET 'http://localhost:3000/api/core/chat/init?appId=[appId]&chatId=[chatId]' \
--header 'Authorization: Bearer [apikey]'
```
```bash
curl --location --request GET 'http://localhost:3000/api/core/chat/init?appId=[appId]&chatId=[chatId]' \
--header 'Authorization: Bearer [apikey]'
```
</Tab>
</Tab>
<Tab value="Parameters" >
<Tab value="Parameters" >
<div>
- appId - Application ID
- chatId - History ID
</div>
</Tab>
<Tab value="Response Example">
```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": ""
</Tab>
<Tab value="Response Example">
```json
{
"code": 200,
"statusText": "",
"message": "",
"data": {
"chatId": "sPVOuEohjo3w",
"appId": "66e29b870b24ce35330c0f08",
"variables": {},
"app": {
"chatConfig": {
"questionGuide": true,
"ttsConfig": {
"type": "web"
},
"chatModels": ["GPT-4o-mini"],
"name": "测试",
"avatar": "/imgs/app/avatar/workflow.svg",
"intro": "",
"type": "advanced",
"pluginInputs": []
}
"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": []
}
}
```
}
```
</Tab>
</Tab>
</Tabs>
## Chat Records
<Tabs items={['Request Example','Parameters','Response Example']}>
<Tab value="Request Example">
<Tab value="Request Example">
```bash
curl --location --request POST 'http://localhost:3000/api/core/chat/getPaginationRecords' \
......@@ -922,21 +908,19 @@ curl --location --request POST 'http://localhost:3000/api/core/chat/getPaginatio
}'
```
</Tab>
</Tab>
<Tab value="Parameters" >
<Tab value="Parameters" >
<div>
- appId - Application ID
- chatId - History ID
- offset - Offset
- pageSize - Number of records
- loadCustomFeedbacks - Whether to load custom feedbacks (optional)
</div>
</Tab>
</Tab>
<Tab value="Response Example" >
<Tab value="Response Example" >
```json
{
......@@ -980,32 +964,30 @@ curl --location --request POST 'http://localhost:3000/api/core/chat/getPaginatio
}
```
</Tab>
</Tab>
</Tabs>
## Chat Records
<Tabs items={['Request Example','Parameters','Response Example']}>
<Tab value="Request Example">
<Tab value="Request Example">
```bash
curl --location --request GET 'http://localhost:3000/api/core/chat/getResData?appId=[appId]&chatId=[chatId]&dataId=[dataId]' \
--header 'Authorization: Bearer [apikey]'
```
</Tab>
</Tab>
<Tab value="Parameters" >
<Tab value="Parameters" >
<div>
- appId - Application ID
- chatId - Chat ID
- dataId - Chat Record ID
</div>
</Tab>
</Tab>
<Tab value="Response Example" >
<Tab value="Response Example" >
```json
{
......@@ -1055,32 +1037,30 @@ curl --location --request GET 'http://localhost:3000/api/core/chat/getResData?ap
}
```
</Tab>
</Tab>
</Tabs>
## Chat Records
<Tabs items={['Request Example','Parameters','Response Example']}>
<Tab value="Request Example" >
<Tab value="Request Example" >
```bash
curl --location --request DELETE 'http://localhost:3000/api/core/chat/item/delete?contentId=[contentId]&chatId=[chatId]&appId=[appId]' \
curl --location --request DELETE 'http://localhost:3000/api/core/chat/record/delete?contentId=[contentId]&chatId=[chatId]&appId=[appId]' \
--header 'Authorization: Bearer [apikey]'
```
</Tab>
</Tab>
<Tab value="Parameters" >
<Tab value="Parameters" >
<div>
- appId - Application ID
- chatId - History ID
- contentId - Chat Record ID
</div>
</Tab>
</Tab>
<Tab value="Response Example" >
<Tab value="Response Example" >
```json
{
......@@ -1091,13 +1071,13 @@ curl --location --request DELETE 'http://localhost:3000/api/core/chat/item/delet
}
```
</Tab>
</Tab>
</Tabs>
### Like / Unlike
<Tabs items={['Request Example','Parameters','Response Example']}>
<Tab value="Request Example">
<Tab value="Request Example">
```bash
curl --location --request POST 'http://localhost:3000/api/core/chat/feedback/updateUserFeedback' \
......@@ -1111,20 +1091,18 @@ curl --location --request POST 'http://localhost:3000/api/core/chat/feedback/upd
}'
```
</Tab>
</Tab>
<Tab value="Parameters" >
<Tab value="Parameters" >
<div>
- appId - Application ID
- chatId - History ID
- dataId - Chat Record ID
- userGoodFeedback - User feedback when liking (optional). Omit to unlike.
</div>
</Tab>
</Tab>
<Tab value="Response Example" >
<Tab value="Response Example" >
```json
{
......@@ -1135,13 +1113,13 @@ curl --location --request POST 'http://localhost:3000/api/core/chat/feedback/upd
}
```
</Tab>
</Tab>
</Tabs>
### Dislike / Remove Dislike
<Tabs items={['Request Example','Parameters','Response Example']}>
<Tab value="Request Example">
<Tab value="Request Example">
```bash
curl --location --request POST 'http://localhost:3000/api/core/chat/feedback/updateUserFeedback' \
......@@ -1155,20 +1133,18 @@ curl --location --request POST 'http://localhost:3000/api/core/chat/feedback/upd
}'
```
</Tab>
</Tab>
<Tab value="Parameters" >
<Tab value="Parameters" >
<div>
- appId - Application ID
- chatId - History ID
- dataId - Chat Record ID
- userBadFeedback - User feedback when disliking (optional). Omit to remove dislike.
</div>
</Tab>
</Tab>
<Tab value="Response Example" >
<Tab value="Response Example" >
```json
{
......@@ -1179,7 +1155,7 @@ curl --location --request POST 'http://localhost:3000/api/core/chat/feedback/upd
}
```
</Tab>
</Tab>
</Tabs>
## Question Suggestions
......@@ -1189,7 +1165,7 @@ curl --location --request POST 'http://localhost:3000/api/core/chat/feedback/upd
The new question suggestion feature requires both appId and chatId parameters. It automatically fetches the last 6 conversation turns from chatId as context.
<Tabs items={['Request Example','Parameters','Response Example']}>
<Tab value="Request Example">
<Tab value="Request Example">
```bash
curl --location --request POST 'http://localhost:3000/api/core/ai/agent/v2/createQuestionGuide' \
......@@ -1206,9 +1182,9 @@ curl --location --request POST 'http://localhost:3000/api/core/ai/agent/v2/creat
}'
```
</Tab>
</Tab>
<Tab value="Parameters" >
<Tab value="Parameters" >
| 参数名 | 类型 | 必填 | 说明 |
| ------------- | ------ | ---- | ---------------------------------------------------------- |
......@@ -1228,9 +1204,9 @@ type CreateQuestionGuideParams = OutLinkChatAuthProps & {
};
```
</Tab>
</Tab>
<Tab value="Response Example" >
<Tab value="Response Example" >
```json
{
......@@ -1241,5 +1217,5 @@ type CreateQuestionGuideParams = OutLinkChatAuthProps & {
}
```
</Tab>
</Tab>
</Tabs>
document/content/openapi/chat.mdx
......@@ -11,107 +11,106 @@ description: FastGPT OpenAPI 对话接口
# 发起对话
- 该接口的 API Key 需使用`应用特定的 key`，否则会报错。
- 有些包调用时，`BaseUrl`需要添加`v1`路径，有些不需要，如果出现404情况，可补充`v1`重试。
- 该接口的 API Key 需使用 `应用特定的 key`，否则会报错。
- 有些包调用时，`BaseUrl` 需要添加 `v1` 路径，有些不需要，如果出现 404 情况，可补充 `v1` 重试。
{/* * 对话现在有`v1`和`v2`两个接口，可以按需使用，v2 自 4.9.4 版本新增，v1 接口同时不再维护 */}
## 请求对话 Agent 和工作流
`v1`对话接口兼容`GPT`的接口！如果你的项目使用的是标准的`GPT`官方接口，可以直接通过修改`BaseUrl`和 `Authorization`来访问 FastGpt 应用，不过需要注意下面几个规则：
`v1` 对话接口兼容 `GPT` 的接口！如果你的项目使用的是标准的 `GPT` 官方接口，可以直接通过修改 `BaseUrl` 和 `Authorization` 来访问 FastGpt 应用，不过需要注意下面几个规则：
* 传入的`model`，`temperature`等参数字段均无效，这些字段由编排决定，不会根据 API 参数改变。
* 不会返回实际消耗`Token`值，如果需要，可以设置`detail=true`，并手动计算 `responseData` 里的`tokens`值。
- 传入的 `model`，`temperature` 等参数字段均无效，这些字段由编排决定，不会根据 API 参数改变。
- 不会返回实际消耗 `Token` 值，如果需要，可以设置 `detail=true`，并手动计算 `responseData` 里的 `tokens` 值。
### 请求
<Tabs items={["基础请求示例","图片/文件请求示例","参数说明"]}>
<Tab value="基础请求示例">
```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": "my_chatId",
"stream": false,
"detail": false,
"responseChatItemId": "my_responseChatItemId",
"variables": {
"uid": "asdfadsfasfd2323",
"name": "张三"
},
"messages": [
{
"role": "user",
"content": "导演是谁"
}
]
}'
```
<Tab value="基础请求示例">
</Tab>
```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": "my_chatId",
"stream": false,
"detail": false,
"responseChatItemId": "my_responseChatItemId",
"variables": {
"uid": "asdfadsfasfd2323",
"name": "张三"
},
"messages": [
{
"role": "user",
"content": "导演是谁"
}
]
}'
```
<Tab value="图片/文件请求示例">
</Tab>
- 仅`messages`有部分区别，其他参数一致。
- 目前不支持上传文件，需上传到自己的对象存储中，获取对应的文件链接。
<Tab value="图片/文件请求示例">
```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"
}
]
}
]
}'
```
- 仅 `messages` 有部分区别，其他参数一致。
- 目前不支持上传文件，需上传到自己的对象存储中，获取对应的文件链接。
</Tab>
```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"
}
]
}
]
}'
```
<Tab value="参数说明">
</Tab>
<Tab value="参数说明">
<div>
- headers.Authorization: Bearer [apikey]
- chatId: string | undefined 。
- chatId: string | undefined。
- 为时（不传入），不使用 FastGpt 提供的上下文功能，完全通过传入的 messages 构建上下文。
- 为`非空字符串`时，意味着使用 chatId 进行对话，自动从 FastGpt 数据库取历史记录，并使用 messages数组最后一个内容作为用户问题，其余 message 会被忽略。请自行确保 chatId唯一，长度小于250，通常可以是自己系统的对话框ID。
- messages: 结构与[GPT接口](https://platform.openai.com/docs/api-reference/chat/object) chat模式一致。
- responseChatItemId: string | undefined 。如果传入，则会将该值作为本次对话的响应消息的 ID，FastGPT会自动将该 ID 存入数据库。请确保，在当前`chatId`下，`responseChatItemId`是唯一的。
- detail:是否返回中间值（模块状态，响应的完整结果等），`stream模式`下会通过`event`进行区分，`非stream模式`结果保存在`responseData`中。
- variables: 模块变量，一个对象，会替换模块中，输入框内容里的`[key]`
</div>
</Tab>
- 为 `非空字符串` 时，意味着使用 chatId 进行对话，自动从 FastGpt 数据库取历史记录，并使用 messages 数组最后一个内容作为用户问题，其余 message 会被忽略。请自行确保 chatId 唯一，长度小于 250，通常可以是自己系统的对话框 ID。
- messages: 结构与 [GPT 接口](https://platform.openai.com/docs/api-reference/chat/object) chat 模式一致。
- responseChatItemId: string | undefined。如果传入，则会将该值作为本次对话的响应消息的 ID，FastGPT 会自动将该 ID 存入数据库。请确保，在当前 `chatId` 下，`responseChatItemId` 是唯一的。
- detail: 是否返回中间值（模块状态，响应的完整结果等），`stream 模式` 下会通过 `event` 进行区分，`非 stream 模式` 结果保存在 `responseData` 中。
- variables: 模块变量，一个对象，会替换模块中，输入框内容里的 `[key]`
</Tab>
</Tabs>
### 响应
<Tabs items={['detail=false,stream=false 响应','detail=false,stream=true 响应','detail=true,stream=false 响应','detail=true,stream=true 响应','event值']}>
<Tab value="detail=false,stream=false 响应">
<Tab value="detail=false,stream=false 响应">
```json
{
......@@ -135,8 +134,8 @@ description: FastGPT OpenAPI 对话接口
}
```
</Tab>
<Tab value="detail=false,stream=true 响应">
</Tab>
<Tab value="detail=false,stream=true 响应">
```bash
data: {"id":"","object":"","created":0,"choices":[{"delta":{"content":""},"index":0,"finish_reason":null}]}
......@@ -148,8 +147,8 @@ data: {"id":"","object":"","created":0,"choices":[{"delta":{"content":"影"},"in
data: {"id":"","object":"","created":0,"choices":[{"delta":{"content":"《"},"index":0,"finish_reason":null}]}
```
</Tab>
<Tab value="detail=true,stream=false 响应">
</Tab>
<Tab value="detail=true,stream=false 响应">
```json
{
......@@ -238,8 +237,8 @@ data: {"id":"","object":"","created":0,"choices":[{"delta":{"content":"《"},"in
}
```
</Tab>
<Tab value="detail=true,stream=true 响应">
</Tab>
<Tab value="detail=true,stream=true 响应">
```bash
event: flowNodeStatus
......@@ -273,10 +272,10 @@ event: flowResponses
data: [{"moduleName":"知识库搜索","moduleType":"datasetSearchNode","runningTime":1.78},{"question":"导演是谁","quoteList":[{"id":"654f2e49b64caef1d9431e8b","q":"电影《铃芽之旅》的导演是谁？","a":"电影《铃芽之旅》的导演是新海诚!","indexes":[{"type":"qa","dataId":"3515487","text":"电影《铃芽之旅》的导演是谁？","_id":"654f2e49b64caef1d9431e8c","defaultIndex":true}],"datasetId":"646627f4f7b896cfd8910e38","collectionId":"653279b16cd42ab509e766e8","sourceName":"data (81).csv","sourceId":"64fd3b6423aa1307b65896f6","score":0.8935586214065552},{"id":"6552e14c50f4a2a8e632af11","q":"导演是谁？","a":"电影《铃芽之旅》的导演是新海诚。","indexes":[{"defaultIndex":true,"type":"qa","dataId":"3644565","text":"导演是谁？\n电影《铃芽之旅》的导演是新海诚。","_id":"6552e14dde5cc7ba3954e417"}],"datasetId":"646627f4f7b896cfd8910e38","collectionId":"653279b16cd42ab509e766e8","sourceName":"data (81).csv","sourceId":"64fd3b6423aa1307b65896f6","score":0.8890955448150635},{"id":"654f34a0b64caef1d946337e","q":"本作的主人公是谁？","a":"本作的主人公是名叫铃芽的少女。","indexes":[{"type":"qa","dataId":"3515541","text":"本作的主人公是谁？","_id":"654f34a0b64caef1d946337f","defaultIndex":true}],"datasetId":"646627f4f7b896cfd8910e38","collectionId":"653279b16cd42ab509e766e8","sourceName":"data (81).csv","sourceId":"64fd3b6423aa1307b65896f6","score":0.8738770484924316},{"id":"654f3002b64caef1d944207a","q":"电影《铃芽之旅》男主角是谁？","a":"电影《铃芽之旅》男主角是宗像草太，由松村北斗配音。","indexes":[{"type":"qa","dataId":"3515538","text":"电影《铃芽之旅》男主角是谁？","_id":"654f3002b64caef1d944207b","defaultIndex":true}],"datasetId":"646627f4f7b896cfd8910e38","collectionId":"653279b16cd42ab509e766e8","sourceName":"data (81).csv","sourceId":"64fd3b6423aa1307b65896f6","score":0.8607980012893677},{"id":"654f2fc8b64caef1d943fd46","q":"电影《铃芽之旅》的编剧是谁？","a":"新海诚是本片的编剧。","indexes":[{"defaultIndex":true,"type":"qa","dataId":"3515550","text":"电影《铃芽之旅》的编剧是谁？22","_id":"654f2fc8b64caef1d943fd47"}],"datasetId":"646627f4f7b896cfd8910e38","collectionId":"653279b16cd42ab509e766e8","sourceName":"data (81).csv","sourceId":"64fd3b6423aa1307b65896f6","score":0.8468944430351257}],"moduleName":"AI 对话","moduleType":"chatNode","runningTime":1.86}]
```
</Tab>
<Tab value="event值">
</Tab>
<Tab value="event值">
event取值：
event 取值：
- answer: 返回给客户端的文本（最终会算作回答）
- fastAnswer: 指定回复返回给客户端的文本（最终会算作回答）
......@@ -288,17 +287,17 @@ event取值：
- updateVariables: 更新变量
- error: 报错
</Tab>
</Tab>
</Tabs>
### 交互节点响应
如果工作流中包含交互节点，依然是调用该 API 接口，需要设置`detail=true`，并可以从`event=interactive`的数据中获取交互节点的配置信息。如果是`stream=false`，则可以从 choice 中获取`type=interactive`的元素，获取交互节点的选择信息。
如果工作流中包含交互节点，依然是调用该 API 接口，需要设置 `detail=true`，并可以从 `event=interactive` 的数据中获取交互节点的配置信息。如果是 `stream=false`，则可以从 choice 中获取 `type=interactive` 的元素，获取交互节点的选择信息。
当你调用一个带交互节点的工作流时，如果工作流遇到了交互节点，那么会直接返回，你可以得到下面的信息：
<Tabs items={['用户选择','表单输入']}>
<Tab value="用户选择">
<Tab value="用户选择">
```json
{
......@@ -321,8 +320,8 @@ event取值：
}
```
</Tab>
<Tab value="表单输入">
</Tab>
<Tab value="表单输入">
```json
{
......@@ -369,7 +368,7 @@ event取值：
}
```
</Tab>
</Tab>
</Tabs>
### 交互节点继续运行
......@@ -377,7 +376,7 @@ event取值：
紧接着上一节，当你接收到交互节点信息后，可以根据这些数据进行 UI 渲染，引导用户输入或选择相关信息。然后需要再次发起对话，来继续工作流。调用的接口与仍是该接口，你需要按以下格式来发起请求：
<Tabs items={['用户选择','表单输入']}>
<Tab value="用户选择">
<Tab value="用户选择">
对于用户选择，你只需要直接传递一个选择的结果给 messages 即可。
......@@ -398,10 +397,10 @@ curl --location --request POST 'http://localhost:3000/api/v1/chat/completions' \
}'
```
</Tab>
<Tab value="表单输入">
</Tab>
<Tab value="表单输入">
表单输入稍微麻烦一点，需要将输入的内容，以对象形式并序列化成字符串，作为`messages`的值。对象的 key 对应表单的 key，value 为用户输入的值。务必确保`chatId`是一致的。
表单输入稍微麻烦一点，需要将输入的内容，以对象形式并序列化成字符串，作为 `messages` 的值。对象的 key 对应表单的 key，value 为用户输入的值。务必确保 `chatId` 是一致的。
```bash
curl --location --request POST 'http://localhost:3000/api/v1/chat/completions' \
......@@ -420,18 +419,18 @@ curl --location --request POST 'http://localhost:3000/api/v1/chat/completions' \
}'
```
</Tab>
</Tab>
</Tabs>
## 请求插件
插件的接口与对话接口一致，仅请求参数略有区别，有以下规定：
- 调用插件类型的应用时，接口默认为`detail`模式。
- 调用插件类型的应用时，接口默认为 `detail` 模式。
- 无需传入 `chatId`，因为插件只能运行一轮。
- 无需传入`messages`。
- 通过传递`variables`来代表插件的输入。
- 通过获取`pluginData`来获取插件输出。
- 无需传入 `messages`。
- 通过传递 `variables` 来代表插件的输入。
- 通过获取 `pluginData` 来获取插件输出。
### 请求示例
......@@ -451,10 +450,10 @@ curl --location --request POST 'http://localhost:3000/api/v1/chat/completions' \
### 响应示例
<Tabs items={['detail=true,stream=false 响应','detail=true,stream=true 响应','输出获取']}>
<Tab value="detail=true,stream=false 响应">
<Tab value="detail=true,stream=false 响应">
- 插件的输出可以通过查找`responseData`中, `moduleType=pluginOutput`的元素，其`pluginOutput`是插件的输出。
- 流输出，仍可以通过`choices`进行获取。
- 插件的输出可以通过查找 `responseData` 中, `moduleType=pluginOutput` 的元素，其 `pluginOutput` 是插件的输出。
- 流输出，仍可以通过 `choices` 进行获取。
```json
{
......@@ -515,10 +514,10 @@ curl --location --request POST 'http://localhost:3000/api/v1/chat/completions' \
}
```
</Tab>
<Tab value="detail=true,stream=true 响应">
</Tab>
<Tab value="detail=true,stream=true 响应">
- 插件的输出可以通过获取`event=flowResponses`中的字符串，并将其反序列化后得到一个数组。同样的，查找 `moduleType=pluginOutput`的元素，其`pluginOutput`是插件的输出。
- 插件的输出可以通过获取 `event=flowResponses` 中的字符串，并将其反序列化后得到一个数组。同样的，查找 `moduleType=pluginOutput` 的元素，其 `pluginOutput` 是插件的输出。
- 流输出，仍和对话接口一样获取。
```bash
......@@ -580,10 +579,10 @@ event: flowResponses
data: [{"nodeId":"fdDgXQ6SYn8v","moduleName":"AI 对话","moduleType":"chatNode","totalPoints":0.033,"model":"FastAI-3.5","tokens":33,"query":"你好","maxToken":2000,"historyPreview":[{"obj":"Human","value":"你好"},{"obj":"AI","value":"你好！有什么可以帮助你的吗？"}],"contextTotalLen":2,"runningTime":1.42},{"nodeId":"pluginOutput","moduleName":"插件输出","moduleType":"pluginOutput","totalPoints":0,"pluginOutput":{"result":"你好！有什么可以帮助你的吗？"},"runningTime":0}]
```
</Tab>
<Tab value="输出获取">
</Tab>
<Tab value="输出获取">
event取值：
event 取值：
- answer: 返回给客户端的文本（最终会算作回答）
- fastAnswer: 指定回复返回给客户端的文本（最终会算作回答）
......@@ -595,13 +594,13 @@ event取值：
- updateVariables: 更新变量
- error: 报错
</Tab>
</Tab>
</Tabs>
# 对话 CRUD
* 以下接口可使用任意`API Key`调用。
* 4.8.12 以上版本才能使用
- 以下接口可使用任意 `API Key` 调用。
- 4.8.12 以上版本才能使用
**重要字段**
......@@ -610,10 +609,10 @@ event取值：
## 历史记录
### 获取某个应用历史记录
### 获取历史记录列表
<Tabs items={['请求示例','参数说明','响应示例']}>
<Tab value="请求示例">
<Tab value="请求示例">
```bash
curl --location --request POST 'http://localhost:3000/api/core/chat/history/getHistories' \
......@@ -627,19 +626,17 @@ curl --location --request POST 'http://localhost:3000/api/core/chat/history/getH
}'
```
</Tab>
<Tab value="参数说明">
</Tab>
<Tab value="参数说明">
<div>
- appId - 应用 Id
- appId - 应用 ID
- offset - 偏移量，即从第几条数据开始取
- pageSize - 记录数量
- source - 对话源。source=api，表示获取通过 API 创建的对话（不会获取到页面上的对话记录）
</div>
</Tab>
</Tab>
<Tab value="响应示例" >
<Tab value="响应示例" >
```json
{
......@@ -670,16 +667,16 @@ curl --location --request POST 'http://localhost:3000/api/core/chat/history/getH
}
```
</Tab>
</Tab>
</Tabs>
### 修改某个对话的标题
### 修改历史记录标题
<Tabs items={['请求示例','参数说明','响应示例']}>
<Tab value="请求示例">
<Tab value="请求示例">
```bash
curl --location --request POST 'http://localhost:3000/api/core/chat/history/updateHistory' \
curl --location --request PUT 'http://localhost:3000/api/core/chat/history/updateHistory' \
--header 'Authorization: Bearer [apikey]' \
--header 'Content-Type: application/json' \
--data-raw '{
......@@ -689,19 +686,17 @@ curl --location --request POST 'http://localhost:3000/api/core/chat/history/upda
}'
```
</Tab>
</Tab>
<Tab value="参数说明" >
<Tab value="参数说明" >
<div>
- appId - 应用 Id
- chatId - 历史记录 Id
- appId - 应用 ID
- chatId - 历史记录 ID
- customTitle - 自定义对话名
</div>
</Tab>
</Tab>
<Tab value="响应示例" >
<Tab value="响应示例" >
```json
{
......@@ -712,16 +707,16 @@ curl --location --request POST 'http://localhost:3000/api/core/chat/history/upda
}
```
</Tab>
</Tab>
</Tabs>
### 置顶 / 取消置顶
### 修改历史记录置顶状态
<Tabs items={['请求示例','参数说明','响应示例']}>
<Tab value="请求示例">
<Tab value="请求示例">
```bash
curl --location --request POST 'http://localhost:3000/api/core/chat/history/updateHistory' \
curl --location --request PUT 'http://localhost:3000/api/core/chat/history/updateHistory' \
--header 'Authorization: Bearer [apikey]' \
--header 'Content-Type: application/json' \
--data-raw '{
......@@ -731,19 +726,17 @@ curl --location --request POST 'http://localhost:3000/api/core/chat/history/upda
}'
```
</Tab>
</Tab>
<Tab value="参数说明" >
<Tab value="参数说明" >
<div>
- appId - 应用Id
- chatId - 历史记录 Id
- top - 是否置顶，ture 置顶，false 取消置顶
</div>
- appId - 应用 ID
- chatId - 历史记录 ID
- top - 是否置顶，true 置顶，false 取消置顶
</Tab>
</Tab>
<Tab value="响应示例" >
<Tab value="响应示例" >
```json
{
......@@ -754,31 +747,29 @@ curl --location --request POST 'http://localhost:3000/api/core/chat/history/upda
}
```
</Tab>
</Tab>
</Tabs>
### 删除某个历史记录
### 删除单个历史记录
<Tabs items={['请求示例','参数说明','响应示例']}>
<Tab value="请求示例">
<Tab value="请求示例">
```bash
curl --location --request DELETE 'http://localhost:3000/api/core/chat/history/delHistory?chatId=[chatId]&appId=[appId]' \
--header 'Authorization: Bearer [apikey]'
```
</Tab>
</Tab>
<Tab value="参数说明" >
<Tab value="参数说明" >
<div>
- appId - 应用 Id
- chatId - 历史记录 Id
</div>
- appId - 应用 ID
- chatId - 历史记录 ID
</Tab>
</Tab>
<Tab value="响应示例" >
<Tab value="响应示例" >
```json
{
......@@ -789,32 +780,30 @@ curl --location --request DELETE 'http://localhost:3000/api/core/chat/history/de
}
```
</Tab>
</Tab>
</Tabs>
### 清空所有历史记录
### 清空应用历史记录
仅会情况通过 API Key 创建的对话历史记录，不会清空在线使用、分享链接等其他来源的对话历史记录。
<Tabs items={['请求示例','参数说明','响应示例']}>
<Tab value="请求示例">
<Tab value="请求示例">
```bash
curl --location --request DELETE 'http://localhost:3000/api/core/chat/history/clearHistories?appId=[appId]' \
--header 'Authorization: Bearer [apikey]'
```
</Tab>
</Tab>
<Tab value="参数说明" >
<Tab value="参数说明" >
<div>
- appId - 应用 Id
</div>
- appId - 应用 ID
</Tab>
</Tab>
<Tab value="响应示例" >
<Tab value="响应示例" >
```json
{
......@@ -825,89 +814,87 @@ curl --location --request DELETE 'http://localhost:3000/api/core/chat/history/cl
}
```
</Tab>
</Tab>
</Tabs>
## 对话记录
指的是某个 chatId 下的对话记录操作。
### 获取单个对话初始化信息
### 获取会话框基本信息
<Tabs items={['请求示例','参数说明','响应示例']}>
<Tab value="请求示例">
```bash
curl --location --request GET 'http://localhost:3000/api/core/chat/init?appId=[appId]&chatId=[chatId]' \
--header 'Authorization: Bearer [apikey]'
```
</Tab>
<Tab value="参数说明" >
<div>
- appId - 应用 Id
- chatId - 历史记录 Id
</div>
</Tab>
<Tab value="响应示例">
```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": ""
<Tab value="请求示例">
```bash
curl --location --request GET 'http://localhost:3000/api/core/chat/init?appId=[appId]&chatId=[chatId]' \
--header 'Authorization: Bearer [apikey]'
```
</Tab>
<Tab value="参数说明" >
- appId - 应用 ID
- chatId - 历史记录 ID
</Tab>
<Tab value="响应示例">
```json
{
"code": 200,
"statusText": "",
"message": "",
"data": {
"chatId": "sPVOuEohjo3w",
"appId": "66e29b870b24ce35330c0f08",
"variables": {},
"app": {
"chatConfig": {
"questionGuide": true,
"ttsConfig": {
"type": "web"
},
"chatModels": ["GPT-4o-mini"],
"name": "测试",
"avatar": "/imgs/app/avatar/workflow.svg",
"intro": "",
"type": "advanced",
"pluginInputs": []
}
"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": []
}
}
```
}
```
</Tab>
</Tab>
</Tabs>
### 获取对话记录列表
<Tabs items={['请求示例','参数说明','响应示例']}>
<Tab value="请求示例">
<Tab value="请求示例">
```bash
curl --location --request POST 'http://localhost:3000/api/core/chat/getPaginationRecords' \
......@@ -922,21 +909,19 @@ curl --location --request POST 'http://localhost:3000/api/core/chat/getPaginatio
}'
```
</Tab>
</Tab>
<Tab value="参数说明" >
<Tab value="参数说明" >
<div>
- appId - 应用 Id
- chatId - 历史记录 Id
- appId - 应用 ID
- chatId - 历史记录 ID
- offset - 偏移量
- pageSize - 记录数量
- loadCustomFeedbacks - 是否读取自定义反馈（可选）
</div>
</Tab>
</Tab>
<Tab value="响应示例" >
<Tab value="响应示例" >
```json
{
......@@ -979,32 +964,30 @@ curl --location --request POST 'http://localhost:3000/api/core/chat/getPaginatio
}
```
</Tab>
</Tab>
</Tabs>
### 获取单个对话记录运行详情
<Tabs items={['请求示例','参数说明','响应示例']}>
<Tab value="请求示例">
<Tab value="请求示例">
```bash
curl --location --request GET 'http://localhost:3000/api/core/chat/getResData?appId=[appId]&chatId=[chatId]&dataId=[dataId]' \
--header 'Authorization: Bearer [apikey]'
```
</Tab>
</Tab>
<Tab value="参数说明" >
<Tab value="参数说明" >
<div>
- appId - 应用 Id
- chatId - 对话 Id
- dataId - 对话记录 Id
</div>
- appId - 应用 ID
- chatId - 对话 ID
- dataId - 对话记录 ID
</Tab>
</Tab>
<Tab value="响应示例" >
<Tab value="响应示例" >
```json
{
......@@ -1054,32 +1037,30 @@ curl --location --request GET 'http://localhost:3000/api/core/chat/getResData?ap
}
```
</Tab>
</Tab>
</Tabs>
### 删除对话记录
<Tabs items={['请求示例','参数说明','响应示例']}>
<Tab value="请求示例" >
<Tab value="请求示例" >
```bash
curl --location --request DELETE 'http://localhost:3000/api/core/chat/item/delete?contentId=[contentId]&chatId=[chatId]&appId=[appId]' \
curl --location --request DELETE 'http://localhost:3000/api/core/chat/record/delete?contentId=[contentId]&chatId=[chatId]&appId=[appId]' \
--header 'Authorization: Bearer [apikey]'
```
</Tab>
</Tab>
<Tab value="参数说明" >
<Tab value="参数说明" >
<div>
- appId - 应用 Id
- chatId - 历史记录 Id
- contentId - 对话记录 Id
</div>
- appId - 应用 ID
- chatId - 历史记录 ID
- contentId - 对话记录 ID
</Tab>
</Tab>
<Tab value="响应示例" >
<Tab value="响应示例" >
```json
{
......@@ -1090,13 +1071,13 @@ curl --location --request DELETE 'http://localhost:3000/api/core/chat/item/delet
}
```
</Tab>
</Tab>
</Tabs>
### 点赞 / 取消点赞
<Tabs items={['请求示例','参数说明','响应示例']}>
<Tab value="请求示例">
<Tab value="请求示例">
```bash
curl --location --request POST 'http://localhost:3000/api/core/chat/feedback/updateUserFeedback' \
......@@ -1110,20 +1091,18 @@ curl --location --request POST 'http://localhost:3000/api/core/chat/feedback/upd
}'
```
</Tab>
</Tab>
<Tab value="参数说明" >
<Tab value="参数说明" >
<div>
- appId - 应用 Id
- chatId - 历史记录 Id
- dataId - 对话记录 Id
- appId - 应用 ID
- chatId - 历史记录 ID
- dataId - 对话记录 ID
- userGoodFeedback - 用户点赞时的信息（可选），取消点赞时不填此参数即可
</div>
</Tab>
</Tab>
<Tab value="响应示例" >
<Tab value="响应示例" >
```json
{
......@@ -1134,13 +1113,13 @@ curl --location --request POST 'http://localhost:3000/api/core/chat/feedback/upd
}
```
</Tab>
</Tab>
</Tabs>
### 点踩 / 取消点踩
<Tabs items={['请求示例','参数说明','响应示例']}>
<Tab value="请求示例">
<Tab value="请求示例">
```bash
curl --location --request POST 'http://localhost:3000/api/core/chat/feedback/updateUserFeedback' \
......@@ -1154,20 +1133,18 @@ curl --location --request POST 'http://localhost:3000/api/core/chat/feedback/upd
}'
```
</Tab>
</Tab>
<Tab value="参数说明" >
<Tab value="参数说明" >
<div>
- appId - 应用 Id
- chatId - 历史记录 Id
- dataId - 对话记录 Id
- appId - 应用 ID
- chatId - 历史记录 ID
- dataId - 对话记录 ID
- userBadFeedback - 用户点踩时的信息（可选），取消点踩时不填此参数即可
</div>
</Tab>
</Tab>
<Tab value="响应示例" >
<Tab value="响应示例" >
```json
{
......@@ -1178,7 +1155,7 @@ curl --location --request POST 'http://localhost:3000/api/core/chat/feedback/upd
}
```
</Tab>
</Tab>
</Tabs>
## 猜你想问
......@@ -1188,7 +1165,7 @@ curl --location --request POST 'http://localhost:3000/api/core/chat/feedback/upd
新版猜你想问，必须包含 appId 和 chatId 的参数才可以进行使用。会自动根据 chatId 去拉取最近 6 轮对话记录作为上下文来引导回答。
<Tabs items={['请求示例','参数说明','响应示例']}>
<Tab value="请求示例">
<Tab value="请求示例">
```bash
curl --location --request POST 'http://localhost:3000/api/core/ai/agent/v2/createQuestionGuide' \
......@@ -1205,14 +1182,14 @@ curl --location --request POST 'http://localhost:3000/api/core/ai/agent/v2/creat
}'
```
</Tab>
</Tab>
<Tab value="参数说明" >
<Tab value="参数说明" >
| 参数名 | 类型 | 必填 | 说明 |
| ------------- | ------ | ---- | ---------------------------------------------------------- |
| appId | string | ✅ | 应用 Id |
| chatId | string | ✅ | 对话 Id |
| appId | string | ✅ | 应用 ID |
| chatId | string | ✅ | 对话 ID |
| questionGuide | object | | 自定义配置，不传的话，则会根据 appId，取最新发布版本的配置 |
```ts
......@@ -1227,9 +1204,9 @@ type CreateQuestionGuideParams = OutLinkChatAuthProps & {
};
```
</Tab>
</Tab>
<Tab value="响应示例" >
<Tab value="响应示例" >
```json
{
......@@ -1240,5 +1217,5 @@ type CreateQuestionGuideParams = OutLinkChatAuthProps & {
}
```
</Tab>
</Tab>
</Tabs>
document/content/openapi/dataset.en.mdx
......@@ -3,14 +3,14 @@ title: Dataset API
description: FastGPT OpenAPI Dataset API
---
| How to Get Dataset ID (datasetId) | How to Get Collection ID (collection_id) |
| ----------------------------- | ----------------------------------- |
| ![](../../public/imgs/getDatasetId.jpg) | ![](../../public/imgs/getfile_id.webp) |
| How to Get Dataset ID (datasetId) | How to Get Collection ID (collection_id) |
| --------------------------------------- | ---------------------------------------- |
| ![](../../public/imgs/getDatasetId.jpg) | ![](../../public/imgs/getfile_id.webp) |
## Create Training Order
<Tabs items={['Request Example','Response Example']}>
<Tab value="Request Example" >
<Tab value="Request Example" >
**New Example**
......@@ -24,8 +24,8 @@ curl --location --request POST 'http://localhost:3000/api/support/wallet/usage/c
}'
```
</Tab>
<Tab value="Response Example" >
</Tab>
<Tab value="Response Example" >
data is the billId, which can be used for bill aggregation when adding dataset data.
......@@ -38,15 +38,15 @@ data is the billId, which can be used for bill aggregation when adding dataset d
}
```
</Tab>
</Tab>
</Tabs>
## Dataset
### Create a Dataset
### Create Knowledge Base
<Tabs items={['Request Example','Parameters','Response Example']}>
<Tab value="Request Example" >
<Tab value="Request Example" >
```bash
curl --location --request POST 'http://localhost:3000/api/core/dataset/create' \
......@@ -64,10 +64,8 @@ curl --location --request POST 'http://localhost:3000/api/core/dataset/create' \
}'
```
</Tab>
<Tab value="Parameters" >
<div>
</Tab>
<Tab value="Parameters" >
- parentId - Parent ID for building directory structure. Usually can be null or omitted.
- type - `dataset` or `folder`, represents regular dataset or folder. If not provided, creates a regular dataset.
......@@ -78,11 +76,9 @@ curl --location --request POST 'http://localhost:3000/api/core/dataset/create' \
- agentModel - Text processing model (recommended to leave empty, use system default)
- vlmModel - Image understanding model (recommended to leave empty, use system default)
</div>
</Tab>
</Tab>
<Tab value="Response Example" >
<Tab value="Response Example" >
```json
{
......@@ -93,13 +89,13 @@ curl --location --request POST 'http://localhost:3000/api/core/dataset/create' \
}
```
</Tab>
</Tab>
</Tabs>
### Get Dataset List
<Tabs items={['Request Example','Parameters','Response Example']}>
<Tab value="Request Example" >
<Tab value="Request Example" >
```bash
curl --location --request POST 'http://localhost:3000/api/core/dataset/list?parentId=' \
......@@ -110,16 +106,14 @@ curl --location --request POST 'http://localhost:3000/api/core/dataset/list?pare
}'
```
</Tab>
<Tab value="Parameters">
</Tab>
<Tab value="Parameters">
<div>
- parentId - Parent ID. Pass empty string or null to get datasets in the root directory
</div>
</Tab>
</Tab>
<Tab value="Response Example" >
<Tab value="Response Example" >
```json
{
......@@ -150,29 +144,27 @@ curl --location --request POST 'http://localhost:3000/api/core/dataset/list?pare
}
```
</Tab>
</Tab>
</Tabs>
### Get Dataset Details
### Get Knowledge Base Details
<Tabs items={['Request Example','Parameters','Response Example']}>
<Tab value="Request Example" >
<Tab value="Request Example" >
```bash
curl --location --request GET 'http://localhost:3000/api/core/dataset/detail?id=6593e137231a2be9c5603ba7' \
--header 'Authorization: Bearer {{authorization}}' \
```
</Tab>
<Tab value="Parameters" >
</Tab>
<Tab value="Parameters" >
<div>
- id: Dataset ID
</div>
</Tab>
</Tab>
<Tab value="Response Example" >
<Tab value="Response Example" >
```json
{
......@@ -212,29 +204,27 @@ curl --location --request GET 'http://localhost:3000/api/core/dataset/detail?id=
}
```
</Tab>
</Tab>
</Tabs>
### Delete a Dataset
### Delete Knowledge Base
<Tabs items={['Request Example','Parameters','Response Example']}>
<Tab value="Request Example" >
<Tab value="Request Example" >
```bash
curl --location --request DELETE 'http://localhost:3000/api/core/dataset/delete?id=65abc8729d1448617cba5df6' \
--header 'Authorization: Bearer {{authorization}}' \
```
</Tab>
<Tab value="Parameters" >
</Tab>
<Tab value="Parameters" >
<div>
- id: Dataset ID
</div>
</Tab>
</Tab>
<Tab value="Response Example" >
<Tab value="Response Example" >
```json
{
......@@ -245,7 +235,7 @@ curl --location --request DELETE 'http://localhost:3000/api/core/dataset/delete?
}
```
</Tab>
</Tab>
</Tabs>
## Collection
......@@ -254,33 +244,33 @@ curl --location --request DELETE 'http://localhost:3000/api/core/dataset/delete?
**Request**
| Parameter | Description | Required |
| ---------------- | ----------------------------------------------------------------------------------------------------------- | ---- |
| datasetId | Dataset ID | ✅ |
| parentId： | Parent ID. Defaults to root directory if not provided | |
| trainingType | Data processing method. chunk: split by text length; qa: Q&A extraction | ✅ |
| indexPrefixTitle | Whether to auto-generate title index | |
| customPdfParse | Whether to enable enhanced PDF parsing. Default false: disabled; true: enabled | |
| autoIndexes | Whether to auto-generate indexes (commercial version only) | |
| imageIndex | Whether to auto-generate image indexes (commercial version only) | |
| chunkSettingMode | Chunk parameter mode. auto: system default; custom: manual specification | |
| chunkSplitMode | Chunk split mode. size: split by length; char: split by character. Ineffective when chunkSettingMode=auto. | |
| chunkSize | Chunk size, default 1500. Ineffective when chunkSettingMode=auto. | |
| indexSize | Index size, default 512, must be less than index model max token. Ineffective when chunkSettingMode=auto. | |
| chunkSplitter | Custom highest priority split symbol. Won't split further unless exceeding file processing max context. Ineffective when chunkSettingMode=auto. | |
| qaPrompt | QA split prompt | |
| tags | Collection tags (string array) | |
| createTime | File creation time (Date / String) | |
| Parameter | Description | Required |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| datasetId | Dataset ID | ✅ |
| parentId： | Parent ID. Defaults to root directory if not provided | |
| trainingType | Data processing method. chunk: split by text length; qa: Q&A extraction | ✅ |
| indexPrefixTitle | Whether to auto-generate title index | |
| customPdfParse | Whether to enable enhanced PDF parsing. Default false: disabled; true: enabled | |
| autoIndexes | Whether to auto-generate indexes (commercial version only) | |
| imageIndex | Whether to auto-generate image indexes (commercial version only) | |
| chunkSettingMode | Chunk parameter mode. auto: system default; custom: manual specification | |
| chunkSplitMode | Chunk split mode. size: split by length; char: split by character. Ineffective when chunkSettingMode=auto. | |
| chunkSize | Chunk size, default 1500. Ineffective when chunkSettingMode=auto. | |
| indexSize | Index size, default 512, must be less than index model max token. Ineffective when chunkSettingMode=auto. | |
| chunkSplitter | Custom highest priority split symbol. Won't split further unless exceeding file processing max context. Ineffective when chunkSettingMode=auto. | |
| qaPrompt | QA split prompt | |
| tags | Collection tags (string array) | |
| createTime | File creation time (Date / String) | |
**Response**
- collectionId - New collection ID
- insertLen：Number of inserted chunks
### Create an Empty Collection
### Create Empty Collection/Folder
<Tabs items={['Request Example','Parameters','Response Example']}>
<Tab value="Request Example" >
<Tab value="Request Example" >
```bash
curl --location --request POST 'http://localhost:3000/api/core/dataset/collection/create' \
......@@ -297,22 +287,20 @@ curl --location --request POST 'http://localhost:3000/api/core/dataset/collectio
}'
```
</Tab>
<Tab value="Parameters" >
</Tab>
<Tab value="Parameters" >
<div>
- datasetId: Dataset ID(Required)
- parentId： Parent ID. Defaults to root directory if not provided
- datasetId: Dataset ID (required)
- parentId: Parent ID. Defaults to root directory if not provided
- name: Collection name (required)
- type:
- folder：Folder
- folder: Folder
- virtual: Virtual collection (manual collection)
- metadata： Metadata (not currently used)
</div>
- metadata: Metadata (not currently used)
</Tab>
</Tab>
<Tab value="Response Example" >
<Tab value="Response Example" >
data is the collection ID.
......@@ -325,7 +313,7 @@ data is the collection ID.
}
```
</Tab>
</Tab>
</Tabs>
### Create a Text Collection
......@@ -333,7 +321,7 @@ data is the collection ID.
Pass in text to create a collection. The text will be split accordingly.
<Tabs items={['Request Example','Parameters','Response Example']}>
<Tab value="Request Example" >
<Tab value="Request Example" >
```bash
curl --location --request POST 'http://localhost:3000/api/core/dataset/collection/create/text' \
......@@ -353,20 +341,18 @@ curl --location --request POST 'http://localhost:3000/api/core/dataset/collectio
}'
```
</Tab>
<Tab value="Parameters" >
</Tab>
<Tab value="Parameters" >
<div>
- text: Original text
- datasetId: Dataset ID(Required)
- parentId： Parent ID. Defaults to root directory if not provided
- datasetId: Dataset ID (required)
- parentId: Parent ID. Defaults to root directory if not provided
- name: Collection name (required)
- metadata： Metadata (not currently used)
</div>
- metadata: Metadata (not currently used)
</Tab>
</Tab>
<Tab value="Response Example" >
<Tab value="Response Example" >
data is the collection ID.
......@@ -387,7 +373,7 @@ data is the collection ID.
}
```
</Tab>
</Tab>
</Tabs>
### Create a Link Collection
......@@ -395,7 +381,7 @@ data is the collection ID.
Pass in a web link to create a collection. Content will be fetched from the webpage first, then split.
<Tabs items={['Request Example','Parameters','Response Example']}>
<Tab value="Request Example" >
<Tab value="Request Example" >
```bash
curl --location --request POST 'http://localhost:3000/api/core/dataset/collection/create/link' \
......@@ -416,19 +402,17 @@ curl --location --request POST 'http://localhost:3000/api/core/dataset/collectio
}'
```
</Tab>
<Tab value="Parameters" >
</Tab>
<Tab value="Parameters" >
<div>
- link: Web link
- datasetId: Dataset ID(Required)
- parentId： Parent ID. Defaults to root directory if not provided
- datasetId: Dataset ID (required)
- parentId: Parent ID. Defaults to root directory if not provided
- metadata.webPageSelector: Web page selector to specify which element to use as text (optional)
</div>
</Tab>
</Tab>
<Tab value="Response Example" >
<Tab value="Response Example" >
data is the collection ID.
......@@ -449,7 +433,7 @@ data is the collection ID.
}
```
</Tab>
</Tab>
</Tabs>
### Create a File Collection
......@@ -457,7 +441,7 @@ data is the collection ID.
Pass in a file to create a collection. File content will be read and split. Currently supports: pdf, docx, md, txt, html, csv.
<Tabs items={['Request Example','Parameters','Response Example']}>
<Tab value="Request Example" >
<Tab value="Request Example" >
When uploading via code, note that Chinese filenames need to be encoded to avoid garbled text.
......@@ -468,19 +452,17 @@ curl --location --request POST 'http://localhost:3000/api/core/dataset/collectio
--form 'data="{\"datasetId\":\"6593e137231a2be9c5603ba7\",\"parentId\":null,\"trainingType\":\"chunk\",\"chunkSize\":512,\"chunkSplitter\":\"\",\"qaPrompt\":\"\",\"metadata\":{}}"'
```
</Tab>
<Tab value="Parameters" >
</Tab>
<Tab value="Parameters" >
<div>
Use POST form-data format for upload. Contains file and data fields.
- file: File
- data: Dataset-related info (pass as serialized JSON). See "Common Creation Parameters" above
</div>
</Tab>
</Tab>
<Tab value="Response Example" >
<Tab value="Response Example" >
data is the collection ID.
......@@ -501,10 +483,10 @@ data is the collection ID.
}
```
</Tab>
</Tab>
</Tabs>
### Create an API Collection
### Create a Collection from an API Dataset (V1)
Pass in a file ID to create a collection. File content will be read and split. Currently supports: pdf, docx, md, txt, html, csv.
......@@ -534,18 +516,16 @@ curl --location --request POST 'http://localhost:3000/api/core/dataset/collectio
</Tab>
<Tab value="Parameters" >
<div>
Use POST form-data format for upload. Contains file and data fields.
- name: Collection name, recommended to use filename, required.
- apiFileId: File ID, required.
- datasetId: Dataset ID(Required)
- parentId： Parent ID. Defaults to root directory if not provided
- trainingType:Training mode (required)
- datasetId: Dataset ID (required)
- parentId: Parent ID. Defaults to root directory if not provided
- trainingType: Training mode (required)
- chunkSize: Length of each chunk (optional). chunk mode: 100~3000; qa mode: 4000~model max token (16k models usually recommended not to exceed 10000)
- chunkSplitter: Custom highest priority split symbol (optional)
- qaPrompt: QA split custom prompt (optional)
</div>
</Tab>
......@@ -576,7 +556,7 @@ data is the collection ID.
### Create an External File Collection (Commercial)
<Tabs items={['Request Example','Parameters','Response Example']}>
<Tab value="Request Example" >
<Tab value="Request Example" >
```bash
curl --location --request POST 'http://localhost:3000/api/proApi/core/dataset/collection/create/externalFileUrl' \
......@@ -599,20 +579,20 @@ curl --location --request POST 'http://localhost:3000/api/proApi/core/dataset/co
}'
```
</Tab>
</Tab>
<Tab value="Parameters" >
<Tab value="Parameters" >
| Parameter | Description | Required |
| --------------- | ------------------------------------ | ---- |
| externalFileUrl | File access URL (can be temporary) | ✅ |
| externalFileId | External file ID | |
| filename | Custom filename with extension | |
| createTime | File creation time (Date or ISO string both ok) | |
| Parameter | Description | Required |
| --------------- | ----------------------------------------------- | -------- |
| externalFileUrl | File access URL (can be temporary) | ✅ |
| externalFileId | External file ID | |
| filename | Custom filename with extension | |
| createTime | File creation time (Date or ISO string both ok) | |
</Tab>
</Tab>
<Tab value="Response Example" >
<Tab value="Response Example" >
data is the collection ID.
......@@ -633,13 +613,13 @@ data is the collection ID.
}
```
</Tab>
</Tab>
</Tabs>
### Get Collection List
<Tabs items={['Request Example','Parameters','Response Example']}>
<Tab value="Request Example" >
<Tab value="Request Example" >
```bash
curl --location --request POST 'http://localhost:3000/api/core/dataset/collection/listV2' \
......@@ -654,21 +634,19 @@ curl --location --request POST 'http://localhost:3000/api/core/dataset/collectio
}'
```
</Tab>
</Tab>
<Tab value="Parameters" >
<Tab value="Parameters" >
<div>
- offset: Offset
- pageSize: Items per page, max 30 (optional)
- datasetId: Dataset ID(Required)
- datasetId: Dataset ID (required)
- parentId: Parent ID (optional)
- searchText: Fuzzy search text (optional)
</div>
</Tab>
</Tab>
<Tab value="Response Example" >
<Tab value="Response Example" >
```json
{
......@@ -726,30 +704,28 @@ curl --location --request POST 'http://localhost:3000/api/core/dataset/collectio
}
```
</Tab>
</Tab>
</Tabs>
### Get Collection Details
<Tabs items={['Request Example','Parameters','Response Example']}>
<Tab value="Request Example" >
<Tab value="Request Example" >
```bash
curl --location --request GET 'http://localhost:3000/api/core/dataset/collection/detail?id=65abcfab9d1448617cba5f0d' \
--header 'Authorization: Bearer {{authorization}}' \
```
</Tab>
</Tab>
<Tab value="Parameters" >
<Tab value="Parameters" >
<div>
- id: Collection ID
</div>
</Tab>
</Tab>
<Tab value="Response Example" >
<Tab value="Response Example" >
```json
{
......@@ -792,18 +768,18 @@ curl --location --request GET 'http://localhost:3000/api/core/dataset/collection
}
```
</Tab>
</Tab>
</Tabs>
### Update Collection Info
### Update Dataset Collection Info
<Tabs items={['Request Example','Parameters','Response Example']}>
<Tab value="Request Example" >
<Tab value="Request Example" >
**Update Collection Info by Collection ID**
```bash
curl --location --request PUT 'http://localhost:3000/api/core/dataset/collection/update' \
curl --location --request POST 'http://localhost:3000/api/core/dataset/collection/update' \
--header 'Authorization: Bearer {{authorization}}' \
--header 'Content-Type: application/json' \
--data-raw '{
......@@ -819,7 +795,7 @@ curl --location --request PUT 'http://localhost:3000/api/core/dataset/collection
**Update Collection Info by External File ID**， Just replace id with datasetId and externalFileId.
```bash
curl --location --request PUT 'http://localhost:3000/api/core/dataset/collection/update' \
curl --location --request POST 'http://localhost:3000/api/core/dataset/collection/update' \
--header 'Authorization: Bearer {{authorization}}' \
--header 'Content-Type: application/json' \
--data-raw '{
......@@ -833,22 +809,20 @@ curl --location --request PUT 'http://localhost:3000/api/core/dataset/collection
}'
```
</Tab>
</Tab>
<Tab value="Parameters" >
<Tab value="Parameters" >
<div>
- id: Collection ID
- parentId: Update parent ID (optional)
- name: Update collection name (optional)
- tags: Update collection tags (optional)
- forbid: Update collection disabled status (optional)
- createTime: Update collection creation time (optional)
</div>
</Tab>
</Tab>
<Tab value="Response Example" >
<Tab value="Response Example" >
```json
{
......@@ -859,16 +833,16 @@ curl --location --request PUT 'http://localhost:3000/api/core/dataset/collection
}
```
</Tab>
</Tab>
</Tabs>
### Delete a Collection
### Delete Collection
<Tabs items={['Request Example','Parameters','Response Example']}>
<Tab value="Request Example" >
<Tab value="Request Example" >
```bash
curl --location --request POST 'http://localhost:3000/api/core/dataset/collection/delete' \
curl --location --request DELETE 'http://localhost:3000/api/core/dataset/collection/delete' \
--header 'Authorization: Bearer fastgpt-' \
--header 'Content-Type: application/json' \
--data-raw '{
......@@ -876,17 +850,15 @@ curl --location --request POST 'http://localhost:3000/api/core/dataset/collectio
}'
```
</Tab>
</Tab>
<Tab value="Parameters" >
<Tab value="Parameters" >
<div>
- collectionIds: Collection ID list
</div>
</Tab>
</Tab>
<Tab value="Response Example" >
<Tab value="Response Example" >
```json
{
......@@ -897,7 +869,7 @@ curl --location --request POST 'http://localhost:3000/api/core/dataset/collectio
}
```
</Tab>
</Tab>
</Tabs>
## Data
......@@ -906,37 +878,37 @@ curl --location --request POST 'http://localhost:3000/api/core/dataset/collectio
**Data Structure**
| Field | Type | Description | Required |
| ------------- | ------- | -------- | ---- |
| teamId | String | Team ID | ✅ |
| tmbId | String | Member ID | ✅ |
| datasetId | String | Dataset ID | ✅ |
| collectionId | String | CollectionID | ✅ |
| q | String | Primary data | ✅ |
| a | String | Auxiliary data | ✖ |
| fullTextToken | String | Tokenization | ✖ |
| indexes | Index[] | Vector indexes | ✅ |
| updateTime | Date | Update time | ✅ |
| chunkIndex | Number | Chunk index | ✖ |
| Field | Type | Description | Required |
| ------------- | ------- | -------------- | -------- |
| teamId | String | Team ID | ✅ |
| tmbId | String | Member ID | ✅ |
| datasetId | String | Dataset ID | ✅ |
| collectionId | String | CollectionID | ✅ |
| q | String | Primary data | ✅ |
| a | String | Auxiliary data | ✖ |
| fullTextToken | String | Tokenization | ✖ |
| indexes | Index[] | Vector indexes | ✅ |
| updateTime | Date | Update time | ✅ |
| chunkIndex | Number | Chunk index | ✖ |
**Index Structure**
Maximum 5 custom indexes per data group
| Field | Type | Description | Required |
| ------ | ------ | ------------------------------------------------------------------------------------------------------ | ---- |
| type | String | Optional index types: default-default index; custom-custom index; summary-summary index; question-question index; image-image index | |
| dataId | String | Associated vector ID. Pass this ID when updating data for incremental updates instead of full updates | |
| text | String | Text content | ✅ |
| Field | Type | Description | Required |
| ------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------- | -------- |
| type | String | Optional index types: default-default index; custom-custom index; summary-summary index; question-question index; image-image index | |
| dataId | String | Associated vector ID. Pass this ID when updating data for incremental updates instead of full updates | |
| text | String | Text content | ✅ |
`type` If not provided, defaults to `custom` index. A default index will also be created based on q/a. If a default index is provided, no additional one will be created.
### Batch Add Data to Collection
### Push Data to Training Queue
Note: Maximum 200 data groups per push.
<Tabs items={['Request Example','Parameters','Response Example']}>
<Tab value="Request Example" >
<Tab value="Request Example" >
```bash
curl --location --request POST 'http://localhost:3000/api/core/dataset/data/pushData' \
......@@ -968,24 +940,22 @@ curl --location --request POST 'http://localhost:3000/api/core/dataset/data/push
}'
```
</Tab>
</Tab>
<Tab value="Parameters" >
<Tab value="Parameters" >
<div>
- collectionId: Collection ID (required)
- trainingType:Training mode (required)
- trainingType: Training mode (required)
- prompt: Custom QA split prompt. Must follow template strictly. Recommended not to pass. (optional)
- data：(Specific data)
- q: Primary data（Required）
- a: Auxiliary data (optional)
- indexes: Custom indexes (optional). Can omit or pass empty array. By default, an index will be created from q and a.
</div>
- q: Primary data（Required）
- a: Auxiliary data (optional)
- indexes: Custom indexes (optional). Can omit or pass empty array. By default, an index will be created from q and a.
</Tab>
</Tab>
<Tab value="Response Example" >
<Tab value="Response Example" >
```json
{
......@@ -1000,9 +970,9 @@ curl --location --request POST 'http://localhost:3000/api/core/dataset/data/push
}
```
</Tab>
</Tab>
<Tab value="QA Prompt Template" >
<Tab value="QA Prompt Template" >
[theme] content can be replaced with the data theme. Default: They may contain multiple theme contents
......@@ -1022,14 +992,14 @@ A2:
My text:"""{{text}}"""
```
</Tab>
</Tab>
</Tabs>
### Get Collection Data List
<Tabs items={['Request Example','Parameters','Response Example']}>
<Tab value="Request Example" >
<Tab value="Request Example" >
```bash
curl --location --request POST 'http://localhost:3000/api/core/dataset/data/v2/list' \
......@@ -1043,20 +1013,18 @@ curl --location --request POST 'http://localhost:3000/api/core/dataset/data/v2/l
}'
```
</Tab>
</Tab>
<Tab value="Parameters" >
<Tab value="Parameters" >
<div>
- offset: Offset (optional)
- pageSize: Items per page, max 30 (optional)
- collectionId: Collection ID（Required）
- collectionId: Collection ID (required)
- searchText: Fuzzy search term (optional)
</div>
</Tab>
</Tab>
<Tab value="Response Example" >
<Tab value="Response Example" >
```json
{
......@@ -1087,30 +1055,28 @@ curl --location --request POST 'http://localhost:3000/api/core/dataset/data/v2/l
}
```
</Tab>
</Tab>
</Tabs>
### Get Single Data Details
<Tabs items={['Request Example','Parameters','Response Example']}>
<Tab value="Request Example" >
<Tab value="Request Example" >
```bash
curl --location --request GET 'http://localhost:3000/api/core/dataset/data/detail?id=65abd4b29d1448617cba61db' \
--header 'Authorization: Bearer {{authorization}}' \
```
</Tab>
</Tab>
<Tab value="Parameters" >
<Tab value="Parameters" >
<div>
- id: Data ID
</div>
</Tab>
</Tab>
<Tab value="Response Example" >
<Tab value="Response Example" >
```json
{
......@@ -1140,13 +1106,13 @@ curl --location --request GET 'http://localhost:3000/api/core/dataset/data/detai
}
```
</Tab>
</Tab>
</Tabs>
### Update Single Data
<Tabs items={['Request Example','Parameters','Response Example']}>
<Tab value="Request Example" >
<Tab value="Request Example" >
```bash
curl --location --request PUT 'http://localhost:3000/api/core/dataset/data/update' \
......@@ -1175,20 +1141,18 @@ curl --location --request PUT 'http://localhost:3000/api/core/dataset/data/updat
}'
```
</Tab>
</Tab>
<Tab value="Parameters" >
<Tab value="Parameters" >
<div>
- dataId: Data ID
- q: Primary data (optional)
- a: Auxiliary data (optional)
- indexes: Custom indexes (optional). See `Batch Add Data to Collection` for types. If custom indexes exist when created,
</div>
</Tab>
</Tab>
<Tab value="Response Example" >
<Tab value="Response Example" >
```json
{
......@@ -1199,30 +1163,28 @@ curl --location --request PUT 'http://localhost:3000/api/core/dataset/data/updat
}
```
</Tab>
</Tab>
</Tabs>
### Delete Single Data
<Tabs items={['Request Example','Parameters','Response Example']}>
<Tab value="Request Example" >
<Tab value="Request Example" >
```bash
curl --location --request DELETE 'http://localhost:3000/api/core/dataset/data/delete?id=65abd4b39d1448617cba624d' \
--header 'Authorization: Bearer {{authorization}}' \
```
</Tab>
</Tab>
<Tab value="Parameters" >
<Tab value="Parameters" >
<div>
- id: Data ID
</div>
</Tab>
</Tab>
<Tab value="Response Example" >
<Tab value="Response Example" >
```json
{
......@@ -1233,13 +1195,13 @@ curl --location --request DELETE 'http://localhost:3000/api/core/dataset/data/de
}
```
</Tab>
</Tab>
</Tabs>
## Search Test
<Tabs items={['Request Example','Parameters','Response Example']}>
<Tab value="Request Example" >
<Tab value="Request Example" >
```bash
curl --location --request POST 'http://localhost:3000/api/core/dataset/searchTest' \
......@@ -1259,11 +1221,10 @@ curl --location --request POST 'http://localhost:3000/api/core/dataset/searchTes
}'
```
</Tab>
</Tab>
<Tab value="Parameters" >
<Tab value="Parameters" >
<div>
- datasetId - Dataset ID
- text - Text to test
- limit - Maximum tokens
......@@ -1273,11 +1234,10 @@ curl --location --request POST 'http://localhost:3000/api/core/dataset/searchTes
- datasetSearchUsingExtensionQuery - Use query extension
- datasetSearchExtensionModel - Query extension model
- datasetSearchExtensionBg - Query extension background description
</div>
</Tab>
</Tab>
<Tab value="Response Example" >
<Tab value="Response Example" >
Returns top k results. limit is the maximum tokens, up to 20000 tokens.
......@@ -1301,5 +1261,5 @@ Returns top k results. limit is the maximum tokens, up to 20000 tokens.
}
```
</Tab>
</Tab>
</Tabs>
document/content/openapi/dataset.mdx
......@@ -3,14 +3,14 @@ title: 知识库接口
description: FastGPT OpenAPI 知识库接口
---
| 如何获取知识库ID（datasetId） | 如何获取文件集合ID（collection_id） |
| ----------------------------- | ----------------------------------- |
| ![](../../public/imgs/getDatasetId.jpg) | ![](../../public/imgs/getfile_id.webp) |
| 如何获取知识库 ID（datasetId） | 如何获取文件集合 ID（collection_id） |
| --------------------------------------- | -------------------------------------- |
| ![](../../public/imgs/getDatasetId.jpg) | ![](../../public/imgs/getfile_id.webp) |
## 创建训练订单
<Tabs items={['请求示例','响应示例']}>
<Tab value="请求示例" >
<Tab value="请求示例" >
**新例子**
......@@ -24,8 +24,8 @@ curl --location --request POST 'http://localhost:3000/api/support/wallet/usage/c
}'
```
</Tab>
<Tab value="响应示例" >
</Tab>
<Tab value="响应示例" >
data 为 billId，可用于添加知识库数据时进行账单聚合。
......@@ -38,15 +38,15 @@ data 为 billId，可用于添加知识库数据时进行账单聚合。
}
```
</Tab>
</Tab>
</Tabs>
## 知识库
### 创建一个知识库
### 创建知识库
<Tabs items={['请求示例','参数说明','响应示例']}>
<Tab value="请求示例" >
<Tab value="请求示例" >
```bash
curl --location --request POST 'http://localhost:3000/api/core/dataset/create' \
......@@ -64,13 +64,11 @@ curl --location --request POST 'http://localhost:3000/api/core/dataset/create' \
}'
```
</Tab>
<Tab value="参数说明" >
<div>
</Tab>
<Tab value="参数说明" >
- parentId - 父级ID，用于构建目录结构。通常可以为 null 或者直接不传。
- type - `dataset`或者`folder`，代表普通知识库和文件夹。不传则代表创建普通知识库。
- parentId - 父级 ID，用于构建目录结构。通常可以为 null 或者直接不传。
- type - `dataset` 或者 `folder`，代表普通知识库和文件夹。不传则代表创建普通知识库。
- name - 知识库名（必填）
- intro - 介绍（可选）
- avatar - 头像地址（可选）
......@@ -78,11 +76,9 @@ curl --location --request POST 'http://localhost:3000/api/core/dataset/create' \
- agentModel - 文本处理模型（建议传空，用系统默认的）
- vlmModel - 图片理解模型（建议传空，用系统默认的）
</div>
</Tab>
</Tab>
<Tab value="响应示例" >
<Tab value="响应示例" >
```json
{
......@@ -93,13 +89,13 @@ curl --location --request POST 'http://localhost:3000/api/core/dataset/create' \
}
```
</Tab>
</Tab>
</Tabs>
### 获取知识库列表
<Tabs items={['请求示例','参数说明','响应示例']}>
<Tab value="请求示例" >
<Tab value="请求示例" >
```bash
curl --location --request POST 'http://localhost:3000/api/core/dataset/list?parentId=' \
......@@ -110,16 +106,14 @@ curl --location --request POST 'http://localhost:3000/api/core/dataset/list?pare
}'
```
</Tab>
<Tab value="参数说明">
</Tab>
<Tab value="参数说明">
<div>
- parentId - 父级ID，传空字符串或者null，代表获取根目录下的知识库
</div>
- parentId - 父级 ID，传空字符串或者 null，代表获取根目录下的知识库
</Tab>
</Tab>
<Tab value="响应示例" >
<Tab value="响应示例" >
```json
{
......@@ -150,29 +144,27 @@ curl --location --request POST 'http://localhost:3000/api/core/dataset/list?pare
}
```
</Tab>
</Tab>
</Tabs>
### 获取知识库详情
<Tabs items={['请求示例','参数说明','响应示例']}>
<Tab value="请求示例" >
<Tab value="请求示例" >
```bash
curl --location --request GET 'http://localhost:3000/api/core/dataset/detail?id=6593e137231a2be9c5603ba7' \
--header 'Authorization: Bearer {{authorization}}' \
```
</Tab>
<Tab value="参数说明" >
</Tab>
<Tab value="参数说明" >
<div>
- id: 知识库的ID
</div>
- id: 知识库的 ID
</Tab>
</Tab>
<Tab value="响应示例" >
<Tab value="响应示例" >
```json
{
......@@ -212,29 +204,27 @@ curl --location --request GET 'http://localhost:3000/api/core/dataset/detail?id=
}
```
</Tab>
</Tab>
</Tabs>
### 删除一个知识库
### 删除知识库
<Tabs items={['请求示例','参数说明','响应示例']}>
<Tab value="请求示例" >
<Tab value="请求示例" >
```bash
curl --location --request DELETE 'http://localhost:3000/api/core/dataset/delete?id=65abc8729d1448617cba5df6' \
--header 'Authorization: Bearer {{authorization}}' \
```
</Tab>
<Tab value="参数说明" >
</Tab>
<Tab value="参数说明" >
<div>
- id: 知识库的ID
</div>
- id: 知识库的 ID
</Tab>
</Tab>
<Tab value="响应示例" >
<Tab value="响应示例" >
```json
{
......@@ -245,7 +235,7 @@ curl --location --request DELETE 'http://localhost:3000/api/core/dataset/delete?
}
```
</Tab>
</Tab>
</Tabs>
## 集合
......@@ -254,33 +244,33 @@ curl --location --request DELETE 'http://localhost:3000/api/core/dataset/delete?
**入参**
| 参数 | 说明 | 必填 |
| ---------------- | ----------------------------------------------------------------------------------------------------------- | ---- |
| datasetId | 知识库ID | ✅ |
| parentId | 父级ID，不填则默认为根目录 | |
| trainingType | 数据处理方式。chunk: 按文本长度进行分割;qa: 问答对提取 | ✅ |
| indexPrefixTitle | 是否自动生成标题索引 | |
| customPdfParse | 是否开启PDF增强解析, 默认 false: 关闭;true: 开启; | |
| autoIndexes | 是否自动生成索引(仅商业版支持) | |
| imageIndex | 是否自动生成图片索引(仅商业版支持) | |
| chunkSettingMode | 分块参数模式。auto: 系统默认参数; custom: 手动指定参数 | |
| chunkSplitMode | 分块拆分模式。size: 按长度拆分; char: 按字符拆分。chunkSettingMode=auto时不生效。 | |
| chunkSize | 分块大小，默认 1500。chunkSettingMode=auto时不生效。 | |
| indexSize | 索引大小，默认 512，必须小于索引模型最大token。chunkSettingMode=auto时不生效。 | |
| chunkSplitter | 自定义最高优先分割符号，除非超出文件处理最大上下文，否则不会进行进一步拆分。chunkSettingMode=auto时不生效。 | |
| qaPrompt | qa拆分提示词 | |
| tags | 集合标签（字符串数组） | |
| createTime | 文件创建时间（Date / String） | |
| 参数 | 说明 | 必填 |
| ---------------- | ------------------------------------------------------------------------------------------------------------ | ---- |
| datasetId | 知识库 ID | ✅ |
| parentId | 父级 ID，不填则默认为根目录 | |
| trainingType | 数据处理方式。chunk: 按文本长度进行分割;qa: 问答对提取 | ✅ |
| indexPrefixTitle | 是否自动生成标题索引 | |
| customPdfParse | 是否开启 PDF 增强解析, 默认 false: 关闭;true: 开启; | |
| autoIndexes | 是否自动生成索引(仅商业版支持) | |
| imageIndex | 是否自动生成图片索引(仅商业版支持) | |
| chunkSettingMode | 分块参数模式。auto: 系统默认参数; custom: 手动指定参数 | |
| chunkSplitMode | 分块拆分模式。size: 按长度拆分; char: 按字符拆分。chunkSettingMode=auto 时不生效。 | |
| chunkSize | 分块大小，默认 1500。chunkSettingMode=auto 时不生效。 | |
| indexSize | 索引大小，默认 512，必须小于索引模型最大 token。chunkSettingMode=auto 时不生效。 | |
| chunkSplitter | 自定义最高优先分割符号，除非超出文件处理最大上下文，否则不会进行进一步拆分。chunkSettingMode=auto 时不生效。 | |
| qaPrompt | qa 拆分提示词 | |
| tags | 集合标签（字符串数组） | |
| createTime | 文件创建时间（Date / String） | |
**出参**
- collectionId - 新建的集合ID
- collectionId - 新建的集合 ID
- insertLen：插入的块数量
### 创建一个空的集合
### 创建空集合/目录
<Tabs items={['请求示例','参数说明','响应示例']}>
<Tab value="请求示例" >
<Tab value="请求示例" >
```bash
curl --location --request POST 'http://localhost:3000/api/core/dataset/collection/create' \
......@@ -297,22 +287,20 @@ curl --location --request POST 'http://localhost:3000/api/core/dataset/collectio
}'
```
</Tab>
<Tab value="参数说明" >
</Tab>
<Tab value="参数说明" >
<div>
- datasetId: 知识库的ID(必填)
- parentId： 父级ID，不填则默认为根目录
- datasetId: 知识库的 ID（必填）
- parentId：父级 ID，不填则默认为根目录
- name: 集合名称（必填）
- type:
- folder：文件夹
- virtual：虚拟集合(手动集合)
- metadata： 元数据（暂时没啥用）
</div>
- virtual：虚拟集合（手动集合）
- metadata：元数据（暂时没啥用）
</Tab>
</Tab>
<Tab value="响应示例" >
<Tab value="响应示例" >
data 为集合的 ID。
......@@ -325,7 +313,7 @@ data 为集合的 ID。
}
```
</Tab>
</Tab>
</Tabs>
### 创建一个纯文本集合
......@@ -333,7 +321,7 @@ data 为集合的 ID。
传入一段文字，创建一个集合，会根据传入的文字进行分割。
<Tabs items={['请求示例','参数说明','响应示例']}>
<Tab value="请求示例" >
<Tab value="请求示例" >
```bash
curl --location --request POST 'http://localhost:3000/api/core/dataset/collection/create/text' \
......@@ -353,20 +341,18 @@ curl --location --request POST 'http://localhost:3000/api/core/dataset/collectio
}'
```
</Tab>
<Tab value="参数说明" >
</Tab>
<Tab value="参数说明" >
<div>
- text: 原文本
- datasetId: 知识库的ID(必填)
- parentId： 父级ID，不填则默认为根目录
- datasetId: 知识库的 ID（必填）
- parentId：父级 ID，不填则默认为根目录
- name: 集合名称（必填）
- metadata： 元数据（暂时没啥用）
</div>
- metadata：元数据（暂时没啥用）
</Tab>
</Tab>
<Tab value="响应示例" >
<Tab value="响应示例" >
data 为集合的 ID。
......@@ -384,7 +370,7 @@ data 为集合的 ID。
}
```
</Tab>
</Tab>
</Tabs>
### 创建一个链接集合
......@@ -392,7 +378,7 @@ data 为集合的 ID。
传入一个网络链接，创建一个集合，会先去对应网页抓取内容，再抓取的文字进行分割。
<Tabs items={['请求示例','参数说明','响应示例']}>
<Tab value="请求示例" >
<Tab value="请求示例" >
```bash
curl --location --request POST 'http://localhost:3000/api/core/dataset/collection/create/link' \
......@@ -413,19 +399,17 @@ curl --location --request POST 'http://localhost:3000/api/core/dataset/collectio
}'
```
</Tab>
<Tab value="参数说明" >
</Tab>
<Tab value="参数说明" >
<div>
- link: 网络链接
- datasetId: 知识库的ID(必填)
- parentId： 父级ID，不填则默认为根目录
- metadata.webPageSelector: 网页选择器，用于指定网页中的哪个元素作为文本(可选)
</div>
- datasetId: 知识库的 ID（必填）
- parentId：父级 ID，不填则默认为根目录
- metadata.webPageSelector: 网页选择器，用于指定网页中的哪个元素作为文本（可选）
</Tab>
</Tab>
<Tab value="响应示例" >
<Tab value="响应示例" >
data 为集合的 ID。
......@@ -443,7 +427,7 @@ data 为集合的 ID。
}
```
</Tab>
</Tab>
</Tabs>
### 创建一个文件集合
......@@ -451,7 +435,7 @@ data 为集合的 ID。
传入一个文件，创建一个集合，会读取文件内容进行分割。目前支持：pdf, docx, md, txt, html, csv。
<Tabs items={['请求示例','参数说明','响应示例']}>
<Tab value="请求示例" >
<Tab value="请求示例" >
使用代码上传时，请注意中文 filename 需要进行 encode 处理，否则容易乱码。
......@@ -462,19 +446,17 @@ curl --location --request POST 'http://localhost:3000/api/core/dataset/collectio
--form 'data="{\"datasetId\":\"6593e137231a2be9c5603ba7\",\"parentId\":null,\"trainingType\":\"chunk\",\"chunkSize\":512,\"chunkSplitter\":\"\",\"qaPrompt\":\"\",\"metadata\":{}}"'
```
</Tab>
<Tab value="参数说明" >
</Tab>
<Tab value="参数说明" >
<div>
需要使用 POST form-data 的格式上传。包含 file 和 data 两个字段。
- file: 文件
- data: 知识库相关信息（json序列化后传入）,参数说明见上方"通用创建参数说明"
</div>
- data: 知识库相关信息（json 序列化后传入）,参数说明见上方"通用创建参数说明"
</Tab>
</Tab>
<Tab value="响应示例" >
<Tab value="响应示例" >
data 为集合的 ID。
......@@ -492,10 +474,10 @@ data 为集合的 ID。
}
```
</Tab>
</Tab>
</Tabs>
### 创建一个API集合
### 通过 API 数据集创建集合（V1）
传入一个文件的 id，创建一个集合，会读取文件内容进行分割。目前支持：pdf, docx, md, txt, html, csv。
......@@ -525,18 +507,16 @@ curl --location --request POST 'http://localhost:3000/api/core/dataset/collectio
</Tab>
<Tab value="参数说明" >
<div>
需要使用 POST form-data 的格式上传。包含 file 和 data 两个字段。
- name: 集合名，建议就用文件名，必填。
- apiFileId: 文件的ID，必填。
- datasetId: 知识库的ID(必填)
- parentId： 父级ID，不填则默认为根目录
- apiFileId: 文件的 ID，必填。
- datasetId: 知识库的 ID(必填)
- parentId：父级 ID，不填则默认为根目录
- trainingType:训练模式（必填）
- chunkSize: 每个 chunk 的长度（可选）. chunk模式:100~3000; qa模式: 4000~模型最大token（16k模型通常建议不超过10000）
- chunkSize: 每个 chunk 的长度（可选）. chunk 模式:100~3000; qa 模式: 4000~ 模型最大 token（16k 模型通常建议不超过 10000）
- chunkSplitter: 自定义最高优先分割符号（可选）
- qaPrompt: qa拆分自定义提示词（可选）
</div>
- qaPrompt: qa 拆分自定义提示词（可选）
</Tab>
......@@ -564,7 +544,7 @@ data 为集合的 ID。
### 创建一个外部文件库集合（商业版）
<Tabs items={['请求示例','参数说明','响应示例']}>
<Tab value="请求示例" >
<Tab value="请求示例" >
```bash
curl --location --request POST 'http://localhost:3000/api/proApi/core/dataset/collection/create/externalFileUrl' \
......@@ -587,20 +567,20 @@ curl --location --request POST 'http://localhost:3000/api/proApi/core/dataset/co
}'
```
</Tab>
</Tab>
<Tab value="参数说明" >
<Tab value="参数说明" >
| 参数 | 说明 | 必填 |
| --------------- | ------------------------------------ | ---- |
| externalFileUrl | 文件访问链接（可以是临时链接） | ✅ |
| externalFileId | 外部文件ID | |
| externalFileId | 外部文件 ID | |
| filename | 自定义文件名，需要带后缀 | |
| createTime | 文件创建时间（Date ISO 字符串都 ok） | |
</Tab>
</Tab>
<Tab value="响应示例" >
<Tab value="响应示例" >
data 为集合的 ID。
......@@ -618,13 +598,13 @@ data 为集合的 ID。
}
```
</Tab>
</Tab>
</Tabs>
### 获取集合列表
<Tabs items={['请求示例','参数说明','响应示例']}>
<Tab value="请求示例" >
<Tab value="请求示例" >
```bash
curl --location --request POST 'http://localhost:3000/api/core/dataset/collection/listV2' \
......@@ -639,21 +619,19 @@ curl --location --request POST 'http://localhost:3000/api/core/dataset/collectio
}'
```
</Tab>
</Tab>
<Tab value="参数说明" >
<Tab value="参数说明" >
<div>
- offset: 偏移量
- pageSize: 每页数量，最大30（选填）
- datasetId: 知识库的ID(必填)
- parentId: 父级Id（选填）
- pageSize: 每页数量，最大 30（选填）
- datasetId: 知识库的 ID（必填）
- parentId: 父级 ID（选填）
- searchText: 模糊搜索文本（选填）
</div>
</Tab>
</Tab>
<Tab value="响应示例" >
<Tab value="响应示例" >
```json
{
......@@ -711,30 +689,28 @@ curl --location --request POST 'http://localhost:3000/api/core/dataset/collectio
}
```
</Tab>
</Tab>
</Tabs>
### 获取集合详情
<Tabs items={['请求示例','参数说明','响应示例']}>
<Tab value="请求示例" >
<Tab value="请求示例" >
```bash
curl --location --request GET 'http://localhost:3000/api/core/dataset/collection/detail?id=65abcfab9d1448617cba5f0d' \
--header 'Authorization: Bearer {{authorization}}' \
```
</Tab>
</Tab>
<Tab value="参数说明" >
<Tab value="参数说明" >
<div>
- id: 集合的ID
</div>
- id: 集合的 ID
</Tab>
</Tab>
<Tab value="响应示例" >
<Tab value="响应示例" >
```json
{
......@@ -777,18 +753,18 @@ curl --location --request GET 'http://localhost:3000/api/core/dataset/collection
}
```
</Tab>
</Tab>
</Tabs>
### 修改集合信息
### 更新数据集集合信息
<Tabs items={['请求示例','参数说明','响应示例']}>
<Tab value="请求示例" >
<Tab value="请求示例" >
**通过集合 ID 修改集合信息**
```bash
curl --location --request PUT 'http://localhost:3000/api/core/dataset/collection/update' \
curl --location --request POST 'http://localhost:3000/api/core/dataset/collection/update' \
--header 'Authorization: Bearer {{authorization}}' \
--header 'Content-Type: application/json' \
--data-raw '{
......@@ -801,10 +777,10 @@ curl --location --request PUT 'http://localhost:3000/api/core/dataset/collection
}'
```
**通过外部文件 ID 修改集合信息**， 只需要把 id 换成 datasetId 和 externalFileId。
**通过外部文件 ID 修改集合信息**，只需要把 ID 换成 datasetId 和 externalFileId。
```bash
curl --location --request PUT 'http://localhost:3000/api/core/dataset/collection/update' \
curl --location --request POST 'http://localhost:3000/api/core/dataset/collection/update' \
--header 'Authorization: Bearer {{authorization}}' \
--header 'Content-Type: application/json' \
--data-raw '{
......@@ -818,22 +794,20 @@ curl --location --request PUT 'http://localhost:3000/api/core/dataset/collection
}'
```
</Tab>
</Tab>
<Tab value="参数说明" >
<Tab value="参数说明" >
<div>
- id: 集合的ID
- parentId: 修改父级ID（可选）
- id: 集合的 ID
- parentId: 修改父级 ID（可选）
- name: 修改集合名称（可选）
- tags: 修改集合标签（可选）
- forbid: 修改集合禁用状态（可选）
- createTime: 修改集合创建时间（可选）
</div>
</Tab>
</Tab>
<Tab value="响应示例" >
<Tab value="响应示例" >
```json
{
......@@ -844,16 +818,16 @@ curl --location --request PUT 'http://localhost:3000/api/core/dataset/collection
}
```
</Tab>
</Tab>
</Tabs>
### 删除一个集合
### 删除集合
<Tabs items={['请求示例','参数说明','响应示例']}>
<Tab value="请求示例" >
<Tab value="请求示例" >
```bash
curl --location --request POST 'http://localhost:3000/api/core/dataset/collection/delete' \
curl --location --request DELETE 'http://localhost:3000/api/core/dataset/collection/delete' \
--header 'Authorization: Bearer fastgpt-' \
--header 'Content-Type: application/json' \
--data-raw '{
......@@ -861,17 +835,15 @@ curl --location --request POST 'http://localhost:3000/api/core/dataset/collectio
}'
```
</Tab>
</Tab>
<Tab value="参数说明" >
<Tab value="参数说明" >
<div>
- collectionIds: 集合的 ID 列表
</div>
</Tab>
</Tab>
<Tab value="响应示例" >
<Tab value="响应示例" >
```json
{
......@@ -882,46 +854,46 @@ curl --location --request POST 'http://localhost:3000/api/core/dataset/collectio
}
```
</Tab>
</Tab>
</Tabs>
## 数据
### 数据的结构
**Data结构**
**Data 结构**
| 字段 | 类型 | 说明 | 必填 |
| ------------- | ------- | -------- | ---- |
| teamId | String | 团队ID | ✅ |
| tmbId | String | 成员ID | ✅ |
| datasetId | String | 知识库ID | ✅ |
| collectionId | String | 集合ID | ✅ |
| q | String | 主要数据 | ✅ |
| a | String | 辅助数据 | ✖ |
| fullTextToken | String | 分词 | ✖ |
| indexes | Index[] | 向量索引 | ✅ |
| updateTime | Date | 更新时间 | ✅ |
| chunkIndex | Number | 分块下表 | ✖ |
| 字段 | 类型 | 说明 | 必填 |
| ------------- | ------- | --------- | ---- |
| teamId | String | 团队 ID | ✅ |
| tmbId | String | 成员 ID | ✅ |
| datasetId | String | 知识库 ID | ✅ |
| collectionId | String | 集合 ID | ✅ |
| q | String | 主要数据 | ✅ |
| a | String | 辅助数据 | ✖ |
| fullTextToken | String | 分词 | ✖ |
| indexes | Index[] | 向量索引 | ✅ |
| updateTime | Date | 更新时间 | ✅ |
| chunkIndex | Number | 分块下表 | ✖ |
**Index结构**
**Index 结构**
每组数据的自定义索引最多5个
每组数据的自定义索引最多 5 个
| 字段 | 类型 | 说明 | 必填 |
| ------ | ------ | ------------------------------------------------------------------------------------------------------ | ---- |
| type | String | 可选索引类型：default-默认索引; custom-自定义索引; summary-总结索引; question-问题索引; image-图片索引 | |
| dataId | String | 关联的向量ID，变更数据时候传入该 ID，会进行差量更新，而不是全量更新 | |
| text | String | 文本内容 | ✅ |
| 字段 | 类型 | 说明 | 必填 |
| ------ | ------ | ----------------------------------------------------------------------------------------------------------- | ---- |
| type | String | 可选索引类型：default- 默认索引; custom- 自定义索引; summary- 总结索引; question- 问题索引; image- 图片索引 | |
| dataId | String | 关联的向量 ID，变更数据时候传入该 ID，会进行差量更新，而不是全量更新 | |
| text | String | 文本内容 | ✅ |
`type` 不填则默认为 `custom` 索引，还会基于 q/a 组成一个默认索引。如果传入了默认索引，则不会额外创建。
### 为集合批量添加添加数据
### 推送数据到训练队列
注意，每次最多推送 200 组数据。
<Tabs items={['请求示例','参数说明','响应示例']}>
<Tab value="请求示例" >
<Tab value="请求示例" >
```bash
curl --location --request POST 'http://localhost:3000/api/core/dataset/data/pushData' \
......@@ -953,24 +925,22 @@ curl --location --request POST 'http://localhost:3000/api/core/dataset/data/push
}'
```
</Tab>
</Tab>
<Tab value="参数说明" >
<Tab value="参数说明" >
<div>
- collectionId: 集合ID（必填）
- collectionId: 集合 ID（必填）
- trainingType:训练模式（必填）
- prompt: 自定义 QA 拆分提示词，需严格按照模板，建议不要传入。（选填）
- data：（具体数据）
- q: 主要数据（必填）
- a: 辅助数据（选填）
- indexes: 自定义索引（选填）。可以不传或者传空数组，默认都会使用q和a组成一个索引。
</div>
- q: 主要数据（必填）
- a: 辅助数据（选填）
- indexes: 自定义索引（选填）。可以不传或者传空数组，默认都会使用 q 和 a 组成一个索引。
</Tab>
</Tab>
<Tab value="响应例子" >
<Tab value="响应例子" >
```json
{
......@@ -982,9 +952,9 @@ curl --location --request POST 'http://localhost:3000/api/core/dataset/data/push
}
```
</Tab>
</Tab>
<Tab value="QA Prompt 模板" >
<Tab value="QA Prompt 模板" >
[theme] 里的内容可以换成数据的主题。默认为：它们可能包含多个主题内容
......@@ -1004,14 +974,14 @@ A2:
我的文本："""{{text}}"""
```
</Tab>
</Tab>
</Tabs>
### 获取集合的数据列表
<Tabs items={['请求示例','参数说明','响应示例']}>
<Tab value="请求示例" >
<Tab value="请求示例" >
```bash
curl --location --request POST 'http://localhost:3000/api/core/dataset/data/v2/list' \
......@@ -1025,20 +995,18 @@ curl --location --request POST 'http://localhost:3000/api/core/dataset/data/v2/l
}'
```
</Tab>
</Tab>
<Tab value="参数说明" >
<Tab value="参数说明" >
<div>
- offset: 偏移量（选填）
- pageSize: 每页数量，最大30（选填）
- collectionId: 集合的ID（必填）
- pageSize: 每页数量，最大 30（选填）
- collectionId: 集合的 ID（必填）
- searchText: 模糊搜索词（选填）
</div>
</Tab>
</Tab>
<Tab value="响应示例" >
<Tab value="响应示例" >
```json
{
......@@ -1069,30 +1037,28 @@ curl --location --request POST 'http://localhost:3000/api/core/dataset/data/v2/l
}
```
</Tab>
</Tab>
</Tabs>
### 获取单条数据详情
<Tabs items={['请求示例','参数说明','响应示例']}>
<Tab value="请求示例" >
<Tab value="请求示例" >
```bash
curl --location --request GET 'http://localhost:3000/api/core/dataset/data/detail?id=65abd4b29d1448617cba61db' \
--header 'Authorization: Bearer {{authorization}}' \
```
</Tab>
</Tab>
<Tab value="参数说明" >
<Tab value="参数说明" >
<div>
- id: 数据的id
</div>
- id: 数据的 ID
</Tab>
</Tab>
<Tab value="响应示例" >
<Tab value="响应示例" >
```json
{
......@@ -1122,13 +1088,13 @@ curl --location --request GET 'http://localhost:3000/api/core/dataset/data/detai
}
```
</Tab>
</Tab>
</Tabs>
### 修改单条数据
<Tabs items={['请求示例','参数说明','响应示例']}>
<Tab value="请求示例" >
<Tab value="请求示例" >
```bash
curl --location --request PUT 'http://localhost:3000/api/core/dataset/data/update' \
......@@ -1157,20 +1123,18 @@ curl --location --request PUT 'http://localhost:3000/api/core/dataset/data/updat
}'
```
</Tab>
</Tab>
<Tab value="参数说明" >
<Tab value="参数说明" >
<div>
- dataId: 数据的id
- dataId: 数据的 ID
- q: 主要数据（选填）
- a: 辅助数据（选填）
- indexes: 自定义索引（选填），类型参考`为集合批量添加添加数据`。如果创建时候有自定义索引，
</div>
- indexes: 自定义索引（选填），类型参考 `为集合批量添加添加数据`。如果创建时候有自定义索引，
</Tab>
</Tab>
<Tab value="响应示例" >
<Tab value="响应示例" >
```json
{
......@@ -1181,30 +1145,28 @@ curl --location --request PUT 'http://localhost:3000/api/core/dataset/data/updat
}
```
</Tab>
</Tab>
</Tabs>
### 删除单条数据
<Tabs items={['请求示例','参数说明','响应示例']}>
<Tab value="请求示例" >
<Tab value="请求示例" >
```bash
curl --location --request DELETE 'http://localhost:3000/api/core/dataset/data/delete?id=65abd4b39d1448617cba624d' \
--header 'Authorization: Bearer {{authorization}}' \
```
</Tab>
</Tab>
<Tab value="参数说明" >
<Tab value="参数说明" >
<div>
- id: 数据的id
</div>
- id: 数据的 ID
</Tab>
</Tab>
<Tab value="响应示例" >
<Tab value="响应示例" >
```json
{
......@@ -1215,13 +1177,13 @@ curl --location --request DELETE 'http://localhost:3000/api/core/dataset/data/de
}
```
</Tab>
</Tab>
</Tabs>
## 搜索测试
<Tabs items={['请求示例','参数说明','响应示例']}>
<Tab value="请求示例" >
<Tab value="请求示例" >
```bash
curl --location --request POST 'http://localhost:3000/api/core/dataset/searchTest' \
......@@ -1241,12 +1203,11 @@ curl --location --request POST 'http://localhost:3000/api/core/dataset/searchTes
}'
```
</Tab>
</Tab>
<Tab value="参数说明" >
<Tab value="参数说明" >
<div>
- datasetId - 知识库ID
- datasetId - 知识库 ID
- text - 需要测试的文本
- limit - 最大 tokens 数量
- similarity - 最低相关度（0~1，可选）
......@@ -1255,13 +1216,12 @@ curl --location --request POST 'http://localhost:3000/api/core/dataset/searchTes
- datasetSearchUsingExtensionQuery - 使用问题优化
- datasetSearchExtensionModel - 问题优化模型
- datasetSearchExtensionBg - 问题优化背景描述
</div>
</Tab>
</Tab>
<Tab value="响应示例" >
<Tab value="响应示例" >
返回 top k 结果， limit 为最大 Tokens 数量，最多 20000 tokens。
返回 top k 结果，limit 为最大 Tokens 数量，最多 20000 tokens。
```json
{
......@@ -1283,5 +1243,5 @@ curl --location --request POST 'http://localhost:3000/api/core/dataset/searchTes
}
```
</Tab>
</Tab>
</Tabs>
document/content/openapi/intro.en.mdx
......@@ -3,15 +3,22 @@ title: OpenAPI Introduction
description: FastGPT OpenAPI Introduction
---
## Automated API Documentation
## Latest OpenAPI Documentation
The automated API documentation covers all endpoints in the current version, regardless of whether they can be called via API Key.
All future endpoints will be auto-generated, with documentation continuously improved.
These are the FastGPT APIs published for external use. If you are integrating with FastGPT externally, use the endpoints in this documentation and authenticate with an API key.
- [China Mainland API Documentation](https://cloud.fastgpt.cn/openapi)
- [International API Documentation](https://cloud.fastgpt.io/openapi)
## Developer API Documentation
The developer API documentation covers all endpoints in the current version, regardless of whether they can be called via API key.
All future endpoints will be auto-generated, with documentation continuously improved.
- [China Mainland API Documentation](https://cloud.fastgpt.cn/devapidoc)
- [International API Documentation](https://cloud.fastgpt.io/devapidoc)
## Usage Guide
FastGPT OpenAPI lets you authenticate with an API Key to access FastGPT services and resources -- such as calling app chat endpoints, uploading knowledge base data, search testing, and more. For compatibility and security reasons, not all endpoints support API Key access.
......@@ -28,11 +35,10 @@ FastGPT has **2 types** of API Keys: a global key (cannot directly call app chat
We recommend using `app-specific keys` only for app or chat-related endpoints, and `global keys` for everything else.
| Global Key | App-Specific Key |
| --------------------- | --------------------- |
| Global Key | App-Specific Key |
| --------------------------------------- | --------------------------------------- |
| ![](../../public/imgs/fastgpt-api2.jpg) | ![](../../public/imgs/fastgpt-api1.jpg) |
## Basic Configuration
In OpenAPI, all endpoints authenticate via Header.Authorization.
......
document/content/openapi/intro.mdx
......@@ -3,18 +3,25 @@ title: OpenAPI 介绍
description: FastGPT OpenAPI 介绍
---
## 自动化 API 文档
## 最新 OpenAPI 文档
自动化 API 文档为当前版本系统的所有接口，不区分是否可通过 API Key 调用。
后续所有接口都将做自动化生成，会逐步完善文档。
这部分接口是 FastGPT 对外提供 API 能力的文档，如果你是外部使用 FastGPT 需使用这个文档里的接口，并通过 apikey 鉴权。
- [中国大陆版 API 文档](https://cloud.fastgpt.cn/openapi)
- [国际版 API 文档](https://cloud.fastgpt.io/openapi)
## 开发者 API 文档
开发者 API 文档为当前版本系统的所有接口，不区分是否可通过 API Key 调用。
后续所有接口都将做自动化生成，会逐步完善文档。
- [中国大陆版 API 文档](https://cloud.fastgpt.cn/devapidoc)
- [国际版 API 文档](https://cloud.fastgpt.io/devapidoc)
## 使用说明
FasGPT OpenAPI 接口允许你使用 Api Key 进行鉴权，从而操作 FastGPT 上的相关服务和资源，例如：调用应用对话接口、上传知识库数据、搜索测试等等。出于兼容性和安全考虑，并不是所有的接口都允许通过 Api Key 访问。
FastGPT OpenAPI 接口允许你使用 API Key 进行鉴权，从而操作 FastGPT 上的相关服务和资源，例如：调用应用对话接口、上传知识库数据、搜索测试等等。出于兼容性和安全考虑，并不是所有的接口都允许通过 API Key 访问。
## 如何查看 BaseURL
......@@ -22,17 +29,16 @@ FasGPT OpenAPI 接口允许你使用 Api Key 进行鉴权，从而操作 FastGPT
![](../../public/imgs/fastgpt-api-baseurl.png)
## 如何获取 Api Key
## 如何获取 API Key
FastGPT 的 API Key **有 2 类**，一类是全局通用的 key (无法直接调用应用对话)；一类是携带了 AppId 也就是有应用标记的 key (可直接调用应用对话)。
我们建议，仅操作应用或者对话的相关接口使用 `应用特定key`，其他接口使用 `通用key`。
| 通用key | 应用特定 key |
| --------------------- | --------------------- |
| 通用 key | 应用特定 key |
| --------------------------------------- | --------------------------------------- |
| ![](../../public/imgs/fastgpt-api2.jpg) | ![](../../public/imgs/fastgpt-api1.jpg) |
## 基本配置
OpenAPI 中，所有的接口都通过 Header.Authorization 进行鉴权。
......@@ -65,7 +71,7 @@ curl --location --request POST 'http://localhost:3000/api/v1/chat/completions' \
## 自定义用户 ID
`v4.8.13`后支持传入自定义的用户 ID, 并且存入历史记录中。
`v4.8.13` 后支持传入自定义的用户 ID, 并且存入历史记录中。
```sh
curl --location --request POST 'http://localhost:3000/api/v1/chat/completions' \
......
document/data/doc-last-modified.json
......@@ -145,16 +145,16 @@
"content/guide/workspace/team/invitation_link.mdx": "2026-05-07T15:06:40+08:00",
"content/guide/workspace/team/team_roles_permissions.en.mdx": "2026-05-07T15:06:40+08:00",
"content/guide/workspace/team/team_roles_permissions.mdx": "2026-05-07T15:06:40+08:00",
"content/openapi/app.en.mdx": "2026-04-26T21:08:47+08:00",
"content/openapi/app.mdx": "2026-04-26T21:08:47+08:00",
"content/openapi/chat.en.mdx": "2026-04-26T21:08:47+08:00",
"content/openapi/chat.mdx": "2026-04-26T21:08:47+08:00",
"content/openapi/dataset.en.mdx": "2026-05-07T15:06:40+08:00",
"content/openapi/dataset.mdx": "2026-05-07T15:06:40+08:00",
"content/openapi/app.en.mdx": "2026-05-29T19:08:31+08:00",
"content/openapi/app.mdx": "2026-05-29T19:08:31+08:00",
"content/openapi/chat.en.mdx": "2026-05-29T19:08:31+08:00",
"content/openapi/chat.mdx": "2026-05-29T19:08:31+08:00",
"content/openapi/dataset.en.mdx": "2026-05-29T19:08:31+08:00",
"content/openapi/dataset.mdx": "2026-05-29T19:08:31+08:00",
"content/openapi/index.en.mdx": "2026-04-26T21:08:47+08:00",
"content/openapi/index.mdx": "2026-04-26T21:08:47+08:00",
"content/openapi/intro.en.mdx": "2026-04-26T21:08:47+08:00",
"content/openapi/intro.mdx": "2026-04-26T21:08:47+08:00",
"content/openapi/intro.en.mdx": "2026-05-29T19:08:31+08:00",
"content/openapi/intro.mdx": "2026-05-29T19:08:31+08:00",
"content/openapi/share.en.mdx": "2026-04-26T21:08:47+08:00",
"content/openapi/share.mdx": "2026-04-26T21:08:47+08:00",
"content/self-host/config/env.en.mdx": "2026-05-27T12:17:46+08:00",
......@@ -280,8 +280,8 @@
"content/self-host/upgrading/4-15/4150.mdx": "2026-05-20T17:52:26+08:00",
"content/self-host/upgrading/4-15/41502.en.mdx": "2026-05-25T11:21:30+08:00",
"content/self-host/upgrading/4-15/41502.mdx": "2026-05-25T11:21:30+08:00",
"content/self-host/upgrading/4-15/41503.en.mdx": "2026-05-28T13:54:38+08:00",
"content/self-host/upgrading/4-15/41503.mdx": "2026-05-28T16:06:08+08:00",
"content/self-host/upgrading/4-15/41503.en.mdx": "2026-05-28T16:21:09+08:00",
"content/self-host/upgrading/4-15/41503.mdx": "2026-05-28T16:21:09+08:00",
"content/self-host/upgrading/outdated/40.en.mdx": "2026-04-26T21:08:47+08:00",
"content/self-host/upgrading/outdated/40.mdx": "2026-04-26T21:08:47+08:00",
"content/self-host/upgrading/outdated/41.en.mdx": "2026-04-26T21:08:47+08:00",
......
packages/global/openapi/apikey/index.ts 0 → 100644
import { createDocument } from 'zod-openapi';
import { openAPIPaths } from '../path';
import type { OpenAPIPath } from '../type';
import { ApiKeyTagMap, ApiKeyTagNameMap, apiKeyTagGroups } from './tag';
type DefinedOpenAPIPath = NonNullable<OpenAPIPath>;
/**
* API key 文档只展示显式打了 ApiKeyTagMap 标签的 operation。
*
* 主文档继续保留原有业务标签；这里在生成 API key 专用文档时过滤并重写 tags，
* 避免没有开放的同模块接口被带入 /openapi。
*/
const pickApiKeyPathsByTags = (paths: DefinedOpenAPIPath) => {
const apiKeyTags = new Set<string>(Object.values(ApiKeyTagMap));
const pickedPaths: DefinedOpenAPIPath = {};
for (const [path, pathItem] of Object.entries(paths)) {
const pickedPathItem: NonNullable<DefinedOpenAPIPath[string]> = {};
for (const [method, operation] of Object.entries(pathItem ?? {})) {
const tags = (operation as { tags?: string[] } | undefined)?.tags ?? [];
const pickedTags = tags.filter((tag) => apiKeyTags.has(tag));
if (pickedTags.length > 0) {
pickedPathItem[method as keyof typeof pickedPathItem] = {
...(operation as object),
tags: [...new Set(pickedTags.map((tag) => ApiKeyTagNameMap[tag]))]
} as never;
}
}
if (Object.keys(pickedPathItem).length > 0) {
pickedPaths[path] = pickedPathItem;
}
}
return pickedPaths;
};
const apiKeyOpenAPIPaths = pickApiKeyPathsByTags(openAPIPaths);
export const apiDocOpenAPIDocument = createDocument({
openapi: '3.1.0',
info: {
title: 'FastGPT OpenAPI',
version: '0.1.0',
description: 'FastGPT 开放 API 文档，仅包含支持 API key 鉴权的接口。'
},
paths: apiKeyOpenAPIPaths,
servers: [{ url: '/api' }],
components: {
securitySchemes: {
ApiKeyAuth: {
type: 'http',
scheme: 'bearer',
bearerFormat: 'API Key',
description: '在 Authorization 请求头中传入 Bearer <apiKey>。'
}
}
},
security: [{ ApiKeyAuth: [] }],
'x-tagGroups': apiKeyTagGroups
});
packages/global/openapi/apikey/tag.ts 0 → 100644
export const ApiKeyTagMap = {
appLog: 'apiKey:appLog',
chatHistory: 'apiKey:chatHistory',
chatSession: 'apiKey:chatSession',
chat: 'apiKey:chat',
dataset: 'apiKey:dataset',
datasetCollection: 'apiKey:datasetCollection',
datasetCollectionCreate: 'apiKey:datasetCollectionCreate',
datasetData: 'apiKey:datasetData',
datasetDataIndex: 'apiKey:datasetDataIndex',
datasetOther: 'apiKey:datasetOther'
};
export const ApiKeyTagNameMap: Record<string, string> = {
[ApiKeyTagMap.appLog]: '应用日志',
[ApiKeyTagMap.chatHistory]: '历史记录管理',
[ApiKeyTagMap.chatSession]: '会话管理',
[ApiKeyTagMap.chat]: '对话管理',
[ApiKeyTagMap.dataset]: '知识库管理',
[ApiKeyTagMap.datasetCollection]: '集合管理',
[ApiKeyTagMap.datasetCollectionCreate]: '集合创建',
[ApiKeyTagMap.datasetData]: '数据管理',
[ApiKeyTagMap.datasetDataIndex]: '索引管理',
[ApiKeyTagMap.datasetOther]: '其他'
};
export const apiKeyTagGroups = [
{
name: '应用管理',
tags: [ApiKeyTagNameMap[ApiKeyTagMap.appLog]]
},
{
name: '应用对话',
tags: [
ApiKeyTagNameMap[ApiKeyTagMap.chatHistory],
ApiKeyTagNameMap[ApiKeyTagMap.chatSession],
ApiKeyTagNameMap[ApiKeyTagMap.chat]
]
},
{
name: '知识库',
tags: [
ApiKeyTagNameMap[ApiKeyTagMap.dataset],
ApiKeyTagNameMap[ApiKeyTagMap.datasetCollection],
ApiKeyTagNameMap[ApiKeyTagMap.datasetCollectionCreate],
ApiKeyTagNameMap[ApiKeyTagMap.datasetData],
ApiKeyTagNameMap[ApiKeyTagMap.datasetDataIndex],
ApiKeyTagNameMap[ApiKeyTagMap.datasetOther]
]
}
];
packages/global/openapi/core/app/log/api.ts
......@@ -191,7 +191,7 @@ export const GetChartDataBodySchema = z.object({
}),
offset: z.number().meta({
example: 1,
description: '时区偏移量'
description: '用户留存偏移量，单位随 userTimespan 变化'
}),
userTimespan: z.nativeEnum(AppLogTimespanEnum).meta({
example: AppLogTimespanEnum.day,
......
packages/global/openapi/core/app/log/index.ts
import type { OpenAPIPath } from '../../../type';
import { TagsMap } from '../../../tag';
import { ApiKeyTagMap } from '../../../apikey/tag';
import z from 'zod';
import {
GetAppChatLogsBodySchema,
......@@ -113,7 +114,7 @@ export const AppLogPath: OpenAPIPath = {
get: {
summary: '获取应用总体数据统计',
description: '获取应用的总体数据统计，包括总用户数、总对话数、总积分消耗',
tags: [TagsMap.appLog],
tags: [TagsMap.appLog, ApiKeyTagMap.appLog],
requestParams: {
query: GetTotalDataQuerySchema
},
......@@ -133,7 +134,7 @@ export const AppLogPath: OpenAPIPath = {
post: {
summary: '获取应用图表数据',
description: '获取应用的图表统计数据，包括用户数据、对话数据、应用数据的时序统计',
tags: [TagsMap.appLog],
tags: [TagsMap.appLog, ApiKeyTagMap.appLog],
requestBody: {
content: {
'application/json': {
......
packages/global/openapi/core/chat/completion/index.ts
import type { OpenAPIPath } from '../../../type';
import { TagsMap } from '../../../tag';
import { ApiKeyTagMap } from '../../../apikey/tag';
import { ChatTestPropsSchema, CompletionsPropsSchema, CompletionsResponseSchema } from './api';
/* =============== Request examples =============== */
......@@ -280,7 +281,7 @@ data: [DONE]`;
export const ChatCompletionPath: OpenAPIPath = {
'/v1/chat/completions': {
post: {
tags: [TagsMap.chatController],
tags: [TagsMap.chatController, ApiKeyTagMap.chat],
summary: '请求对话 Agent 和工作流',
description: `v1 对话接口兼容 GPT 的接口。如果你的项目使用的是标准的 GPT 官方接口，可以直接通过修改 BaseUrl 和 Authorization 来访问 FastGPT 应用。
......
packages/global/openapi/core/chat/controler/index.ts
import type { OpenAPIPath } from '../../../type';
import { TagsMap } from '../../../tag';
import { ApiKeyTagMap } from '../../../apikey/tag';
import {
StopV2ChatSchema,
StopV2ChatResponseSchema,
......@@ -10,9 +11,9 @@ import {
export const ChatControllerPath: OpenAPIPath = {
'/core/chat/init': {
get: {
summary: '初始化聊天',
description: '初始化聊天',
tags: [TagsMap.chatController],
summary: '获取会话框基本信息',
description: '',
tags: [TagsMap.chatController, ApiKeyTagMap.chatSession],
requestParams: {
query: InitChatQuerySchema
},
......
packages/global/openapi/core/chat/feedback/index.ts
import type { OpenAPIPath } from '../../../type';
import { TagsMap } from '../../../tag';
import { ApiKeyTagMap } from '../../../apikey/tag';
import {
UpdateFeedbackReadStatusBodySchema,
UpdateFeedbackReadStatusResponseSchema,
......@@ -18,7 +19,7 @@ export const ChatFeedbackPath: OpenAPIPath = {
post: {
summary: '添加/更新用户反馈',
description: '用户对消息添加或更新好评/差评反馈',
tags: [TagsMap.chatFeedback],
tags: [TagsMap.chatFeedback, ApiKeyTagMap.chat],
requestBody: {
content: {
'application/json': {
......
packages/global/openapi/core/chat/history/index.ts
import type { OpenAPIPath } from '../../../type';
import { TagsMap } from '../../../tag';
import { ApiKeyTagMap } from '../../../apikey/tag';
import {
GetHistoriesBodySchema,
GetHistoriesResponseSchema,
......@@ -15,9 +16,9 @@ import {
export const ChatHistoryPath: OpenAPIPath = {
'/core/chat/history/getHistories': {
post: {
summary: '获取对话历史列表',
description: '分页获取指定应用的对话历史记录',
tags: [TagsMap.chatHistory],
summary: '获取历史记录列表',
description: '分页获取指定应用的历史记录',
tags: [TagsMap.chatHistory, ApiKeyTagMap.chatHistory],
requestBody: {
content: {
'application/json': {
......@@ -27,7 +28,7 @@ export const ChatHistoryPath: OpenAPIPath = {
},
responses: {
200: {
description: '成功获取对话历史列表',
description: '成功获取历史记录列表',
content: {
'application/json': {
schema: GetHistoriesResponseSchema
......@@ -39,7 +40,7 @@ export const ChatHistoryPath: OpenAPIPath = {
},
'/core/chat/history/getHistoryStatus': {
post: {
summary: '批量获取对话状态（生成中/已读）',
summary: '批量获取历史记录状态（生成中/已读）',
description:
'按 chatId 列表返回 chatGenerateStatus、hasBeenRead、updateTime，用于侧栏轻量轮询同步',
tags: [TagsMap.chatHistory],
......@@ -64,7 +65,7 @@ export const ChatHistoryPath: OpenAPIPath = {
},
'/core/chat/history/markRead': {
post: {
summary: '标记对话已读',
summary: '标记历史记录已读',
description: '用户在本页看完回复后调用，同步 Mongo hasBeenRead',
tags: [TagsMap.chatHistory],
requestBody: {
......@@ -83,9 +84,9 @@ export const ChatHistoryPath: OpenAPIPath = {
},
'/core/chat/history/updateHistory': {
put: {
summary: '修改对话历史',
description: '修改对话历史的标题、自定义标题或置顶状态',
tags: [TagsMap.chatHistory],
summary: '修改历史记录',
description: '修改历史记录的标题、自定义标题或置顶状态',
tags: [TagsMap.chatHistory, ApiKeyTagMap.chatHistory],
requestBody: {
content: {
'application/json': {
......@@ -95,49 +96,45 @@ export const ChatHistoryPath: OpenAPIPath = {
},
responses: {
200: {
description: '成功修改对话历史'
description: '成功修改历史记录'
}
}
}
},
'/core/chat/history/delHistory': {
delete: {
summary: '删除单个对话历史',
description: '软删除指定的单个对话记录',
tags: [TagsMap.chatHistory],
requestBody: {
content: {
'application/json': {
schema: DelChatHistorySchema
}
}
summary: '删除单个历史记录',
description: '软删除指定的单个历史记录',
tags: [TagsMap.chatHistory, ApiKeyTagMap.chatHistory],
requestParams: {
query: DelChatHistorySchema
},
responses: {
200: {
description: '成功删除对话'
description: '成功删除历史记录'
}
}
}
},
'/core/chat/history/clearHistories': {
delete: {
summary: '清空应用对话历史',
description: '清空指定应用的所有对话记录(软删除)',
tags: [TagsMap.chatHistory],
summary: '清空应用历史记录',
description: '清空指定应用的所有历史记录(软删除)',
tags: [TagsMap.chatHistory, ApiKeyTagMap.chatHistory],
requestParams: {
query: ClearChatHistoriesSchema
},
responses: {
200: {
description: '成功清空对话历史'
description: '成功清空历史记录'
}
}
}
},
'/core/chat/history/batchDelete': {
post: {
summary: '批量删除对话历史',
description: '批量删除指定应用的多个对话记录(真实删除)，需应用日志权限。',
summary: '批量删除历史记录',
description: '批量删除指定应用的多个历史记录(真实删除)，需应用日志权限。',
tags: [TagsMap.chatHistory],
requestBody: {
content: {
......@@ -148,7 +145,7 @@ export const ChatHistoryPath: OpenAPIPath = {
},
responses: {
200: {
description: '成功删除对话'
description: '成功删除历史记录'
}
}
}
......
packages/global/openapi/core/dataset/collection/createPath.ts
import { TagsMap } from '../../../tag';
import { ApiKeyTagMap } from '../../../apikey/tag';
import type { OpenAPIPath } from '../../../type';
import {
CreateApiCollectionBodySchema,
......@@ -22,7 +23,7 @@ export const DatasetCollectionCreatePath: OpenAPIPath = {
post: {
summary: '创建空集合/目录',
description: '创建空数据集合或者目录',
tags: [TagsMap.datasetCollectionCrteate],
tags: [TagsMap.datasetCollectionCrteate, ApiKeyTagMap.datasetCollectionCreate],
requestBody: {
content: {
'application/json': {
......@@ -92,7 +93,7 @@ export const DatasetCollectionCreatePath: OpenAPIPath = {
summary: '上传本地文件创建集合',
description:
'通过 multipart/form-data 上传文件，自动存储至 S3 后创建集合并触发训练。`file` 字段为二进制文件，`data` 字段为 JSON 序列化的集合参数对象',
tags: [TagsMap.datasetCollectionCrteate],
tags: [TagsMap.datasetCollectionCrteate, ApiKeyTagMap.datasetCollectionCreate],
requestBody: {
content: {
'multipart/form-data': {
......@@ -118,7 +119,7 @@ export const DatasetCollectionCreatePath: OpenAPIPath = {
post: {
summary: '通过链接创建集合',
description: '抓取指定 URL 内容创建集合并触发训练',
tags: [TagsMap.datasetCollectionCrteate],
tags: [TagsMap.datasetCollectionCrteate, ApiKeyTagMap.datasetCollectionCreate],
requestBody: {
content: {
'application/json': {
......@@ -141,7 +142,7 @@ export const DatasetCollectionCreatePath: OpenAPIPath = {
post: {
summary: '通过文本创建集合',
description: '将文本内容存储为文件后创建集合并触发训练',
tags: [TagsMap.datasetCollectionCrteate],
tags: [TagsMap.datasetCollectionCrteate, ApiKeyTagMap.datasetCollectionCreate],
requestBody: {
content: {
'application/json': {
......@@ -165,7 +166,7 @@ export const DatasetCollectionCreatePath: OpenAPIPath = {
summary: '通过 API 数据集创建集合（V1）',
description: '根据 apiFileId 从第三方 API 数据源拉取单个文件并创建集合',
deprecated: true,
tags: [TagsMap.datasetCollectionCrteate],
tags: [TagsMap.datasetCollectionCrteate, ApiKeyTagMap.datasetCollectionCreate],
requestBody: {
content: {
'application/json': {
......
packages/global/openapi/core/dataset/collection/index.ts
import type { OpenAPIPath } from '../../../type';
import { TagsMap } from '../../../tag';
import { ApiKeyTagMap } from '../../../apikey/tag';
import {
DeleteCollectionBodySchema,
DeleteCollectionQuerySchema,
......@@ -22,7 +23,7 @@ export const DatasetCollectionPath: OpenAPIPath = {
delete: {
summary: '删除集合',
description: '删除一个或多个集合及其子集合，支持通过 query.id 或 body.collectionIds 指定',
tags: [TagsMap.datasetCollection],
tags: [TagsMap.datasetCollection, ApiKeyTagMap.datasetCollection],
requestParams: {
query: DeleteCollectionQuerySchema
},
......@@ -44,7 +45,7 @@ export const DatasetCollectionPath: OpenAPIPath = {
get: {
summary: '获取集合详情',
description: '获取集合详细信息，包括索引数量、错误数量、文件信息等',
tags: [TagsMap.datasetCollection],
tags: [TagsMap.datasetCollection, ApiKeyTagMap.datasetCollection],
requestParams: {
query: GetCollectionDetailQuerySchema
},
......@@ -59,7 +60,7 @@ export const DatasetCollectionPath: OpenAPIPath = {
post: {
summary: '获取集合列表（分页）',
description: '获取数据集集合列表，支持分页、搜索、标签过滤',
tags: [TagsMap.datasetCollection],
tags: [TagsMap.datasetCollection, ApiKeyTagMap.datasetCollection],
requestBody: {
content: {
'application/json': {
......@@ -97,7 +98,7 @@ export const DatasetCollectionPath: OpenAPIPath = {
post: {
summary: '更新数据集集合信息',
description: '更新数据集集合信息，支持通过集合ID或数据集ID+外部文件ID定位集合',
tags: [TagsMap.datasetCollection],
tags: [TagsMap.datasetCollection, ApiKeyTagMap.datasetCollection],
requestBody: {
content: {
'application/json': {
......
packages/global/openapi/core/dataset/data/index.ts
import type { OpenAPIPath } from '../../../type';
import { TagsMap } from '../../../tag';
import { ApiKeyTagMap } from '../../../apikey/tag';
import {
GetDatasetDataDetailQuerySchema,
UpdateDatasetDataBodySchema,
......@@ -25,7 +26,7 @@ export const DatasetDataPath: OpenAPIPath = {
post: {
summary: '获取数据列表',
description: '分页查询集合内的数据列表，支持关键词搜索，包含图片预览 URL',
tags: [TagsMap.datasetData],
tags: [TagsMap.datasetData, ApiKeyTagMap.datasetData],
requestBody: {
content: {
'application/json': {
......@@ -49,7 +50,7 @@ export const DatasetDataPath: OpenAPIPath = {
get: {
summary: '获取数据详情',
description: '获取单条数据集数据的详细信息，包括向量索引',
tags: [TagsMap.datasetData],
tags: [TagsMap.datasetData, ApiKeyTagMap.datasetData],
requestParams: {
query: GetDatasetDataDetailQuerySchema
},
......@@ -70,7 +71,7 @@ export const DatasetDataPath: OpenAPIPath = {
put: {
summary: '更新数据',
description: '更新数据集数据的 q、a 和向量索引，触发重新向量化',
tags: [TagsMap.datasetData],
tags: [TagsMap.datasetData, ApiKeyTagMap.datasetData],
requestBody: {
content: {
'application/json': {
......@@ -170,7 +171,7 @@ export const DatasetDataPath: OpenAPIPath = {
delete: {
summary: '删除数据',
description: '删除指定数据集数据，需要写权限',
tags: [TagsMap.datasetData],
tags: [TagsMap.datasetData, ApiKeyTagMap.datasetData],
requestParams: {
query: DeleteDatasetDataQuerySchema
},
......@@ -248,7 +249,7 @@ export const DatasetDataPath: OpenAPIPath = {
post: {
summary: '推送数据到训练队列',
description: '批量推送数据到训练队列，最多 200 条',
tags: [TagsMap.datasetData],
tags: [TagsMap.datasetData, ApiKeyTagMap.datasetData],
requestBody: {
content: {
'application/json': {
......
packages/global/openapi/core/dataset/index.ts
import type { OpenAPIPath } from '../../type';
import { TagsMap } from '../../tag';
import { ApiKeyTagMap } from '../../apikey/tag';
import { DatasetDataPath } from './data';
import { DatasetCollectionPath } from './collection';
import { ApiDatasetPath } from './apiDataset';
......@@ -25,7 +26,7 @@ export const DatasetPath: OpenAPIPath = {
post: {
summary: '创建知识库',
description: '创建新的知识库,支持多种类型(普通知识库、文件夹、网站知识库等)',
tags: [TagsMap.datasetCommon],
tags: [TagsMap.datasetCommon, ApiKeyTagMap.dataset],
requestBody: {
content: {
'application/json': {
......@@ -82,7 +83,7 @@ export const DatasetPath: OpenAPIPath = {
post: {
summary: '获取知识库列表',
description: '获取当前用户有权限访问的知识库列表,支持按类型和关键词筛选',
tags: [TagsMap.datasetCommon],
tags: [TagsMap.datasetCommon, ApiKeyTagMap.dataset],
requestBody: {
content: {
'application/json': {
......@@ -116,7 +117,7 @@ export const DatasetPath: OpenAPIPath = {
get: {
summary: '获取知识库详情',
description: '获取知识库详细信息,包括模型配置、权限和同步状态',
tags: [TagsMap.datasetCommon],
tags: [TagsMap.datasetCommon, ApiKeyTagMap.dataset],
requestParams: {
query: GetDatasetDetailQuerySchema
},
......@@ -131,7 +132,7 @@ export const DatasetPath: OpenAPIPath = {
delete: {
summary: '删除知识库',
description: '删除知识库及其所有子知识库,需要所有者权限',
tags: [TagsMap.datasetCommon],
tags: [TagsMap.datasetCommon, ApiKeyTagMap.dataset],
requestParams: {
query: DeleteDatasetQuerySchema
},
......@@ -185,7 +186,7 @@ export const DatasetPath: OpenAPIPath = {
summary: '搜索测试',
description:
'对知识库执行搜索测试，支持多种搜索模式、重排序、问题扩展和临时图片 key 检索。图片检索需先调用 /core/dataset/file/presignSearchTestImage 获取预签名上传 URL 和 temp/${teamId}/... key',
tags: [TagsMap.datasetCommon],
tags: [TagsMap.datasetCommon, ApiKeyTagMap.datasetOther],
requestBody: {
content: {
'application/json': {
......
packages/global/openapi/index.ts
import { createDocument } from 'zod-openapi';
import { ChatPath } from './core/chat';
import { TagsMap } from './tag';
import { PluginPath } from './core/plugin';
import { AppPath } from './core/app';
import { SupportPath } from './support';
import { DatasetPath } from './core/dataset';
import { AIPath } from './core/ai';
import { SkillPath } from './core/ai/skill';
import { openAPIPaths, openAPITagGroups } from './path';
import { ApiKeyTagMap } from './apikey/tag';
const openAPITagSet = new Set<string>(Object.values(ApiKeyTagMap));
const openAPIDocumentPaths = Object.fromEntries(
Object.entries(openAPIPaths).map(([path, pathItem]) => [
path,
Object.fromEntries(
Object.entries(pathItem ?? {}).map(([method, operation]) => {
const tags = (operation as { tags?: string[] } | undefined)?.tags;
return [
method,
tags
? {
...(operation as object),
// ApiKeyTagMap 只作为 /openapi 的筛选标记，不展示在全量开发者文档里。
tags: tags.filter((tag) => !openAPITagSet.has(tag))
}
: operation
];
})
)
])
) as typeof openAPIPaths;
export const openAPIDocument = createDocument({
openapi: '3.1.0',
......@@ -15,79 +33,7 @@ export const openAPIDocument = createDocument({
version: '0.1.0',
description: 'FastGPT API 文档'
},
paths: {
...AppPath,
...ChatPath,
...DatasetPath,
...PluginPath,
...SupportPath,
...AIPath,
...SkillPath
},
paths: openAPIDocumentPaths,
servers: [{ url: '/api' }],
'x-tagGroups': [
{
name: '我的应用/工具管理',
tags: [TagsMap.appCommon, TagsMap.mcpTools, TagsMap.httpTools, TagsMap.appPer]
},
{
name: 'Agent 应用',
tags: [TagsMap.appLog, TagsMap.publishChannel, TagsMap.mcpServer]
},
{
name: 'AI 相关',
tags: [TagsMap.aiSkill, TagsMap.sandbox, TagsMap.aiCommon]
},
{
name: '对话模块配置',
tags: [TagsMap.chatSetting, TagsMap.chatPage, TagsMap.chatInputGuide]
},
{
name: '对话模块使用',
tags: [
TagsMap.chatHistory,
TagsMap.chatFeedback,
TagsMap.chatFile,
TagsMap.chatRecord,
TagsMap.chatController
]
},
{
name: '知识库',
tags: [
TagsMap.datasetCommon,
TagsMap.datasetCollection,
TagsMap.datasetCollectionCrteate,
TagsMap.datasetData,
TagsMap.datasetFile,
TagsMap.datasetTraining,
TagsMap.datasetApiDataset
]
},
{
name: '插件系统',
tags: [TagsMap.pluginToolTag, TagsMap.pluginTeam]
},
{
name: '用户体系',
tags: [
TagsMap.userInform,
TagsMap.walletBill,
TagsMap.walletDiscountCoupon,
TagsMap.userLogin
]
},
{
name: '通用-辅助功能',
tags: [TagsMap.customDomain, TagsMap.apiKey]
},
{
name: '管理员-插件管理',
tags: [TagsMap.pluginAdmin, TagsMap.pluginMarketplace, TagsMap.pluginToolAdmin]
},
{
name: '系统接口',
tags: [TagsMap.helperBot]
}
]
'x-tagGroups': openAPITagGroups
});
packages/global/openapi/path.ts 0 → 100644
import { AIPath } from './core/ai';
import { SkillPath } from './core/ai/skill';
import { AppPath } from './core/app';
import { ChatPath } from './core/chat';
import { DatasetPath } from './core/dataset';
import { PluginPath } from './core/plugin';
import { SupportPath } from './support';
import { TagsMap } from './tag';
import type { OpenAPIPath } from './type';
export const openAPIPaths: NonNullable<OpenAPIPath> = {
...AppPath,
...ChatPath,
...DatasetPath,
...PluginPath,
...SupportPath,
...AIPath,
...SkillPath
};
export const openAPITagGroups = [
{
name: '我的应用/工具管理',
tags: [TagsMap.appCommon, TagsMap.mcpTools, TagsMap.httpTools, TagsMap.appPer]
},
{
name: 'Agent 应用',
tags: [TagsMap.appLog, TagsMap.publishChannel, TagsMap.mcpServer]
},
{
name: 'AI 相关',
tags: [TagsMap.aiSkill, TagsMap.sandbox, TagsMap.aiCommon]
},
{
name: '对话模块配置',
tags: [TagsMap.chatSetting, TagsMap.chatPage, TagsMap.chatInputGuide]
},
{
name: '对话模块使用',
tags: [
TagsMap.chatHistory,
TagsMap.chatFeedback,
TagsMap.chatFile,
TagsMap.chatRecord,
TagsMap.chatController
]
},
{
name: '知识库',
tags: [
TagsMap.datasetCommon,
TagsMap.datasetCollection,
TagsMap.datasetCollectionCrteate,
TagsMap.datasetData,
TagsMap.datasetFile,
TagsMap.datasetTraining,
TagsMap.datasetApiDataset
]
},
{
name: '插件系统',
tags: [TagsMap.pluginToolTag, TagsMap.pluginTeam]
},
{
name: '用户体系',
tags: [TagsMap.userInform, TagsMap.walletBill, TagsMap.walletDiscountCoupon, TagsMap.userLogin]
},
{
name: '通用-辅助功能',
tags: [TagsMap.customDomain, TagsMap.apiKey]
},
{
name: '管理员-插件管理',
tags: [TagsMap.pluginAdmin, TagsMap.pluginMarketplace, TagsMap.pluginToolAdmin]
},
{
name: '系统接口',
tags: [TagsMap.helperBot]
}
];
packages/global/openapi/reference.ts 0 → 100644
const scalarApiReferenceCss = `
.sidebar-heading-link-method .sidebar-heading-type {
min-width: 42px;
height: 20px;
justify-content: center;
padding: 4px 8px;
border: 0;
border-radius: 999px;
font-size: 10px;
line-height: 1;
}
.sidebar-heading-type--get {
color: #1D6FE8;
background-color: #E8F1FF;
}
.sidebar-heading-type--post {
color: #0F8B57;
background-color: #E6F7EE;
}
.sidebar-heading-type--put,
.sidebar-heading-type--patch {
color: #B86B00;
background-color: #FFF1D8;
}
.sidebar-heading-type--delete {
color: #C93D3D;
background-color: #FDEAEA;
}
.sidebar-heading-type--options {
color: #7A55D9;
background-color: #F1ECFF;
}
.sidebar-heading-type--head,
.sidebar-heading-type--trace {
color: #5B6678;
background-color: #EEF1F5;
}
.dark-mode .sidebar-heading-type--get {
color: #8BBEFF;
background-color: rgba(58, 122, 210, 0.2);
}
.dark-mode .sidebar-heading-type--post {
color: #72DBA2;
background-color: rgba(28, 142, 86, 0.22);
}
.dark-mode .sidebar-heading-type--put,
.dark-mode .sidebar-heading-type--patch {
color: #F0B96A;
background-color: rgba(190, 115, 16, 0.22);
}
.dark-mode .sidebar-heading-type--delete {
color: #F48A8A;
background-color: rgba(190, 62, 62, 0.22);
}
.dark-mode .sidebar-heading-type--options {
color: #B7A3FF;
background-color: rgba(116, 86, 214, 0.24);
}
.dark-mode .sidebar-heading-type--head,
.dark-mode .sidebar-heading-type--trace {
color: #B5BFCE;
background-color: rgba(98, 111, 130, 0.24);
}
`;
export const getScalarOpenApiReferenceConfig = (url: string) =>
({
customCss: scalarApiReferenceCss,
hideDarkModeToggle: false,
hideClientButton: true,
showToolbar: 'never',
theme: 'default',
url
}) as const;
pro @ f500e41b
Subproject commit 85f61b2ddcc7b13b56a282c0c233284c50f2f759
Subproject commit f500e41b5c6dd29ab937b82267dd15749cd17201
projects/app/src/pages/_app.tsx
......@@ -28,8 +28,9 @@ type AppPropsWithLayout = AppProps & {
};
const routesWithCustomHead = ['/chat', '/chat/share', '/app/detail', '/dataset/detail'];
const openAPIReferenceRoutes = ['/openapi', '/devapidoc'];
// 哪些路由不需要 Layout
const routesWithoutLayout = ['/openapi'];
const routesWithoutLayout = openAPIReferenceRoutes;
function App({ Component, pageProps }: AppPropsWithLayout) {
const { feConfigs, scripts, title } = useInitApp();
......@@ -59,7 +60,7 @@ function App({ Component, pageProps }: AppPropsWithLayout) {
const headDesc = appClientEnv.systemDescription || t('common:system_intro', { title });
const headIcon = getWebReqUrl(feConfigs?.favicon || appClientEnv.systemFavicon);
if (router.pathname === '/openapi') {
if (openAPIReferenceRoutes.includes(router.pathname)) {
return (
<>
{showHead && <NextHead title={title} desc={headDesc} icon={headIcon} />}
......@@ -72,7 +73,9 @@ function App({ Component, pageProps }: AppPropsWithLayout) {
<>
{showHead && <NextHead title={title} desc={headDesc} icon={headIcon} />}
{scripts?.map((item, i) => <Script key={i} strategy="lazyOnload" {...item}></Script>)}
{scripts?.map((item, i) => (
<Script key={i} strategy="lazyOnload" {...item}></Script>
))}
<QueryClientContext>
<SystemStoreContextProvider device={pageProps.deviceSize}>
......
projects/app/src/pages/api/core/chat/history/clearHistories.ts
......@@ -12,12 +12,7 @@ export async function handler(req: ApiRequestProps, res: NextApiResponse) {
req.query
);
const {
teamId: chatTeamId,
tmbId,
uid,
authType
} = await authChatCrud({
const { tmbId, uid, authType } = await authChatCrud({
req,
authToken: true,
authApiKey: true,
......
projects/app/src/pages/api/core/chat/history/delHistory.ts
......@@ -11,10 +11,10 @@ export async function handler(req: ApiRequestProps, res: NextApiResponse) {
const { appId, chatId } = parseApiInput({ req, querySchema: DelChatHistorySchema }).query;
await authChatCrud({
...req.query,
req,
authToken: true,
authApiKey: true,
...req.query
authApiKey: true
});
await MongoChat.updateOne(
......
projects/app/src/pages/api/core/chat/history/markRead.ts
......@@ -11,10 +11,10 @@ export async function handler(req: ApiRequestProps, _res: ApiResponseType): Prom
const body = parseApiInput({ req, bodySchema: MarkChatReadBodySchema }).body;
await authChatCrud({
...body,
req,
authToken: true,
authApiKey: true,
...body,
per: WritePermissionVal
});
......
projects/app/src/pages/api/core/chat/history/updateHistory.ts
......@@ -14,10 +14,10 @@ export async function handler(req: ApiRequestProps, res: NextApiResponse) {
bodySchema: UpdateHistoryBodySchema
}).body;
await authChatCrud({
...req.body,
req,
authToken: true,
authApiKey: true,
...req.body,
per: WritePermissionVal
});
......
projects/app/src/pages/api/devapidoc.json.ts 0 → 100644
import type { NextApiRequest, NextApiResponse } from 'next';
import { openAPIDocument } from '@fastgpt/global/openapi';
export default function handler(req: NextApiRequest, res: NextApiResponse) {
res.status(200).json(openAPIDocument);
}
projects/app/src/pages/api/openapi.json.ts
import type { NextApiRequest, NextApiResponse } from 'next';
import { openAPIDocument } from '@fastgpt/global/openapi';
import { apiDocOpenAPIDocument } from '@fastgpt/global/openapi/apikey';
export default function handler(req: NextApiRequest, res: NextApiResponse) {
res.status(200).json(openAPIDocument);
res.status(200).json(apiDocOpenAPIDocument);
}
projects/app/src/pages/devapidoc.tsx 0 → 100644
import { Box } from '@chakra-ui/react';
import dynamic from 'next/dynamic';
import { getScalarOpenApiReferenceConfig } from '@fastgpt/global/openapi/reference';
// 动态加载 @scalar/api-reference-react，避免其 CSS side-effect 在 Node 端
// (next build 的 collecting page data 阶段) 被解析导致 ERR_UNKNOWN_FILE_EXTENSION。
const ApiReferenceReact = dynamic(
() => Promise.all([import('@scalar/api-reference-react')]).then(([mod]) => mod.ApiReferenceReact),
{ ssr: false }
);
function ApiDocPage() {
return (
<Box w="100vw" h="100vh" overflow="auto">
<ApiReferenceReact configuration={getScalarOpenApiReferenceConfig('/api/devapidoc.json')} />
</Box>
);
}
// 禁用静态生成
export async function getServerSideProps() {
return {
props: {}
};
}
export default ApiDocPage;
projects/app/src/pages/openapi.tsx
import { Box } from '@chakra-ui/react';
import dynamic from 'next/dynamic';
import { getScalarOpenApiReferenceConfig } from '@fastgpt/global/openapi/reference';
// 动态加载 @scalar/api-reference-react，避免其 CSS side-effect 在 Node 端
// (next build 的 collecting page data 阶段) 被解析导致 ERR_UNKNOWN_FILE_EXTENSION。
......@@ -11,14 +12,7 @@ const ApiReferenceReact = dynamic(
function OpenAPIPage() {
return (
<Box w="100vw" h="100vh" overflow="auto">
<ApiReferenceReact
configuration={{
hideDarkModeToggle: true,
hideClientButton: true,
theme: 'default',
url: '/api/openapi.json'
}}
/>
<ApiReferenceReact configuration={getScalarOpenApiReferenceConfig('/api/openapi.json')} />
</Box>
);
}
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or sign in to comment