Refactor API for document and session (#2819)

### What problem does this PR solve? Refactor API for document and session. ### Type of change - [x] Refactoring --------- Co-authored-by: liuhua <10215101452@stu.ecun.edu.cn>
2025-12-08 20:42:30 +08:00 · 2024-10-12 19:35:19 +08:00
parent 7d80fc474c
commit 6eed115723
9 changed files with 821 additions and 745 deletions
--- a/api/http_api.md
+++ b/api/http_api.md
@ -1441,60 +1441,196 @@ Create a chat session
 ### Request

 - Method: POST
- URL: `/api/v1/chat/{chat_id}/session`
+- URL: `http://{address}/api/v1/chat/{chat_id}/session`
 - Headers:
  - `content-Type: application/json`
-  - 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'
+  - 'Authorization: Bearer {YOUR_ACCESS_TOKEN}' 
+- Body:
+  - name: `string`

 #### Request example
+```bash
 curl --request POST \
  --url http://{address}/api/v1/chat/{chat_id}/session \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {YOUR_ACCESS_TOKEN}' \
-  --data-binary '{
+  --data '{
    "name": "new session"
  }'
+```
+#### Request parameters
+- `"id"`: (*Body parameter*)  
+    The ID of the created session used to identify different sessions.  
+    - `None`  
+    - `id` cannot be provided when creating.
+
+- `"name"`: (*Body parameter*)  
+    The name of the created session.  
+    - `"New session"`
+
+- `"messages"`: (*Body parameter*)  
+    The messages of the created session.  
+    - `[{"role": "assistant", "content": "Hi! I am your assistant, can I help you?"}]`  
+    - `messages` cannot be provided when creating.
+
+- `"chat_id"`: (*Path parameter*)  
+    The ID of the associated chat.  
+    - `""`  
+    - `chat_id` cannot be changed.
+
+### Response
+Success
+```json
+{
+    "code": 0,
+    "data": {
+        "chat_id": "2ca4b22e878011ef88fe0242ac120005",
+        "create_date": "Fri, 11 Oct 2024 08:46:14 GMT",
+        "create_time": 1728636374571,
+        "id": "4606b4ec87ad11efbc4f0242ac120006",
+        "messages": [
+            {
+                "content": "Hi! I am your assistant，can I help you?",
+                "role": "assistant"
+            }
+        ],
+        "name": "new session",
+        "update_date": "Fri, 11 Oct 2024 08:46:14 GMT",
+        "update_time": 1728636374571
+    }
+}
+```
+Error
+```json
+{
+    "code": 102,
+    "message": "Name can not be empty."
+}
+```

 ## List the sessions of a chat

-**GET** `/api/v1/chat/{chat_id}/session`
+**GET** `/api/v1/chat/{chat_id}/session?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&name={dataset_name}&id={dataset_id}`

-List all the session of a chat
+List all sessions under the chat based on the filtering criteria.

 ### Request

 - Method: GET
- URL: `/api/v1/chat/{chat_id}/session`
+- URL: `http://{address}/api/v1/chat/{chat_id}/session?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&name={dataset_name}&id={dataset_id}`
 - Headers:
-  - `content-Type: application/json`
  - 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

 #### Request example
+```bash
 curl --request GET \
-  --url http://{address}/api/v1/chat/554e96746aaa11efb06b0242ac120005/session \
-  --header 'Content-Type: application/json' \
+  --url http://{address}/api/v1/chat/{chat_id}/session?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&name={dataset_name}&id={dataset_id} \
  --header 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'
+```

-## Delete a chat session
+#### Request Parameters
+- `"page"`: (*Path parameter*)  
+    The current page number to retrieve from the paginated data. This parameter determines which set of records will be fetched.  
+    - `1`

-**DELETE** `/api/v1/chat/{chat_id}/session/{session_id}`
+- `"page_size"`: (*Path parameter*)  
+    The number of records to retrieve per page. This controls how many records will be included in each page.  
+    - `1024`

-Delete a chat session
+- `"orderby"`: (*Path parameter*)  
+    The field by which the records should be sorted. This specifies the attribute or column used to order the results.  
+    - `"create_time"`
+
+- `"desc"`: (*Path parameter*)  
+    A boolean flag indicating whether the sorting should be in descending order.  
+    - `True`
+
+- `"id"`: (*Path parameter*)  
+    The ID of the session to be retrieved.  
+    - `None`
+
+- `"name"`: (*Path parameter*)  
+    The name of the session to be retrieved.  
+    - `None`
+### Response
+Success
+```json
+{
+    "code": 0,
+    "data": [
+        {
+            "chat": "2ca4b22e878011ef88fe0242ac120005",
+            "create_date": "Fri, 11 Oct 2024 08:46:43 GMT",
+            "create_time": 1728636403974,
+            "id": "578d541e87ad11ef96b90242ac120006",
+            "messages": [
+                {
+                    "content": "Hi! I am your assistant，can I help you?",
+                    "role": "assistant"
+                }
+            ],
+            "name": "new session",
+            "update_date": "Fri, 11 Oct 2024 08:46:43 GMT",
+            "update_time": 1728636403974
+        }
+    ]
+}
+```
+Error
+```json
+{
+    "code": 102,
+    "message": "The session doesn't exist"
+}
+```
+
+
+## Delete chat sessions
+
+**DELETE** `/api/v1/chat/{chat_id}/session`
+
+Delete chat sessions

 ### Request

 - Method: DELETE
- URL: `/api/v1/chat/{chat_id}/session/{session_id}`
+- URL: `http://{address}/api/v1/chat/{chat_id}/session`
 - Headers:
  - `content-Type: application/json`
  - 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'
+- Body:
+  - `ids`: List[string]

 #### Request example
+```bash
+# Either id or name must be provided, but not both.
 curl --request DELETE \
-  --url http://{address}/api/v1/chat/554e96746aaa11efb06b0242ac120005/session/791aed9670ea11efbb7e0242ac120007 \
-  --header 'Content-Type: application/json' \
-  --header 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'
+--url http://{address}/api/v1/chat/{chat_id}/session \
+--header 'Content-Type: application/json' \
+--header 'Authorization: Bear {YOUR_ACCESS_TOKEN}' \
+  --data '{
+  "ids": ["test_1", "test_2"]
+  }'
+```

+#### Request Parameters
+- `ids`: (*Body Parameter*)  
+    IDs of the sessions to be deleted.
+    - `None`
+### Response
+Success
+```json
+{
+    "code": 0
+}
+```
+Error
+```json
+{
+    "code": 102,
+    "message": "The chat doesn't own the session"
+}
+```
 ## Update a chat session

 **PUT** `/api/v1/chat/{chat_id}/session/{session_id}`
@ -1504,20 +1640,45 @@ Update a chat session
 ### Request

 - Method: PUT
- URL: `/api/v1/chat/{chat_id}/session/{session_id}`
+- URL: `http://{address}/api/v1/chat/{chat_id}/session/{session_id}`
 - Headers:
  - `content-Type: application/json`
  - 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'
+- Body:
+  - `name`: string

 #### Request example
+```bash
 curl --request PUT \
-  --url http://{address}/api/v1/chat/554e96746aaa11efb06b0242ac120005/session/791aed9670ea11efbb7e0242ac120007 \
+  --url http://{address}/api/v1/chat/{chat_id}/session/{session_id} \
  --header 'Content-Type: application/json' \
-  --header 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'
-  --data-binary '{
+  --header 'Authorization: Bearer {YOUR_ACCESS_TOKEN}' \
+  --data '{
    "name": "Updated session"
  }'

+```
+
+#### Request Parameter
+- `name`:(*Body Parameter)  
+    The name of the created session.
+    - `None`
+
+### Response
+Success
+```json
+{
+    "code": 0
+}
+```
+Error
+```json
+{
+    "code": 102,
+    "message": "Name can not be empty."
+}
+```
+
 ## Chat with a chat session

 **POST** `/api/v1/chat/{chat_id}/session/{session_id}/completion`
@ -1527,17 +1688,139 @@ Chat with a chat session
 ### Request

 - Method: POST
- URL: `/api/v1/chat/{chat_id}/session/{session_id}/completion`
+- URL: `http://{address} /api/v1/chat/{chat_id}/session/{session_id}/completion`
 - Headers:
  - `content-Type: application/json`
  - 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'
+- Body:
+  - `question`: string
+  - `stream`: bool
+

 #### Request example
+```bash
 curl --request POST \
-  --url http://{address}/api/v1/chat/554e96746aaa11efb06b0242ac120005/session/791aed9670ea11efbb7e0242ac120007/completion \
+  --url http://{address} /api/v1/chat/{chat_id}/session/{session_id}/completion \
  --header 'Content-Type: application/json' \
-  --header 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'
+  --header 'Authorization: Bearer {YOUR_ACCESS_TOKEN}' \
  --data-binary '{
-    "question":  "Hello!",
-    "stream": true,
+    "question":  "你好!",
+    "stream": true
  }'
+```
+#### Request Parameters
+- `question`:(*Body Parameter*)  
+    The question you want to ask.
+    - question is required.
+    `None`
+- `stream`: (*Body Parameter*)  
+    The approach of streaming text generation.
+    `False`
+### Response
+Success
+```json
+data: {
+    "code": 0,
+    "data": {
+        "answer": "您好！有什么具体的问题或者需要的帮助",
+        "reference": {},
+        "audio_binary": null,
+        "id": "31153052-7bac-4741-a513-ed07d853f29e"
+    }
+}
+
+data: {
+    "code": 0,
+    "data": {
+        "answer": "您好！有什么具体的问题或者需要的帮助可以告诉我吗？我在这里是为了帮助",
+        "reference": {},
+        "audio_binary": null,
+        "id": "31153052-7bac-4741-a513-ed07d853f29e"
+    }
+}
+
+data: {
+    "code": 0,
+    "data": {
+        "answer": "您好！有什么具体的问题或者需要的帮助可以告诉我吗？我在这里是为了帮助您的。如果您有任何疑问或是需要获取",
+        "reference": {},
+        "audio_binary": null,
+        "id": "31153052-7bac-4741-a513-ed07d853f29e"
+    }
+}
+
+data: {
+    "code": 0,
+    "data": {
+        "answer": "您好！有什么具体的问题或者需要的帮助可以告诉我吗？我在这里是为了帮助您的。如果您有任何疑问或是需要获取某些信息，请随时提出。",
+        "reference": {},
+        "audio_binary": null,
+        "id": "31153052-7bac-4741-a513-ed07d853f29e"
+    }
+}
+
+data: {
+    "code": 0,
+    "data": {
+        "answer": "您好！有什么具体的问题或者需要的帮助可以告诉我吗 ##0$$？我在这里是为了帮助您的。如果您有任何疑问或是需要获取某些信息，请随时提出。",
+        "reference": {
+            "total": 19,
+            "chunks": [
+                {
+                    "chunk_id": "9d87f9d70a0d8a7565694a81fd4c5d5f",
+                    "content_ltks": "当所有知识库内容都与问题无关时 ,你的回答必须包括“知识库中未找到您要的答案!”这句话。回答需要考虑聊天历史。\r\n以下是知识库:\r\n{knowledg}\r\n以上是知识库\r\n\"\"\"\r\n 1\r\n 2\r\n 3\r\n 4\r\n 5\r\n 6\r\n总结\r\n通过上面的介绍,可以对开源的 ragflow有了一个大致的了解,与前面的有道qanyth整体流程还是比较类似的。 ",
+                    "content_with_weight": "当所有知识库内容都与问题无关时，你的回答必须包括“知识库中未找到您要的答案！”这句话。回答需要考虑聊天历史。\r\n    以下是知识库：\r\n    {knowledge}\r\n    以上是知识库\r\n\"\"\"\r\n1\r\n2\r\n3\r\n4\r\n5\r\n6\r\n总结\r\n通过上面的介绍，可以对开源的 RagFlow 有了一个大致的了解，与前面的 有道 QAnything 整体流程还是比较类似的。",
+                    "doc_id": "5c5999ec7be811ef9cab0242ac120005",
+                    "docnm_kwd": "1.txt",
+                    "kb_id": "c7ee74067a2c11efb21c0242ac120006",
+                    "important_kwd": [],
+                    "img_id": "",
+                    "similarity": 0.38337178633282265,
+                    "vector_similarity": 0.3321336754679629,
+                    "term_similarity": 0.4053309767034769,
+                    "positions": [
+                        ""
+                    ]
+                },
+                {
+                    "chunk_id": "895d34de762e674b43e8613c6fb54c6d",
+                    "content_ltks": "\r\n\r\n实际内容可能会超过大模型的输入token数量,因此在调用大模型前会调用api/db/servic/dialog_service.py文件中 messag_fit_in ()根据大模型可用的 token数量进行过滤。这部分与有道的 qanyth的实现大同小异,就不额外展开了。\r\n\r\n将检索的内容,历史聊天记录以及问题构造为 prompt ,即可作为大模型的输入了 ,默认的英文prompt如下所示:\r\n\r\n\"\"\"\r\nyou are an intellig assistant. pleas summar the content of the knowledg base to answer the question. pleas list thedata in the knowledg base and answer in detail. when all knowledg base content is irrelev to the question , your answer must includ the sentenc\"the answer you are lookfor isnot found in the knowledg base!\" answer needto consid chat history.\r\n here is the knowledg base:\r\n{ knowledg}\r\nthe abov is the knowledg base.\r\n\"\"\"\r\n1\r\n 2\r\n 3\r\n 4\r\n 5\r\n 6\r\n对应的中文prompt如下所示:\r\n\r\n\"\"\"\r\n你是一个智能助手,请总结知识库的内容来回答问题,请列举知识库中的数据详细回答。 ",
+                    "content_with_weight": "\r\n\r\n实际内容可能会超过大模型的输入 token 数量，因此在调用大模型前会调用 api/db/services/dialog_service.py 文件中 message_fit_in() 根据大模型可用的 token 数量进行过滤。这部分与有道的 QAnything 的实现大同小异，就不额外展开了。\r\n\r\n将检索的内容，历史聊天记录以及问题构造为 prompt，即可作为大模型的输入了，默认的英文 prompt 如下所示：\r\n\r\n\"\"\"\r\nYou are an intelligent assistant. Please summarize the content of the knowledge base to answer the question. Please list the data in the knowledge base and answer in detail. When all knowledge base content is irrelevant to the question, your answer must include the sentence \"The answer you are looking for is not found in the knowledge base!\" Answers need to consider chat history.\r\n      Here is the knowledge base:\r\n      {knowledge}\r\n      The above is the knowledge base.\r\n\"\"\"\r\n1\r\n2\r\n3\r\n4\r\n5\r\n6\r\n对应的中文 prompt 如下所示：\r\n\r\n\"\"\"\r\n你是一个智能助手，请总结知识库的内容来回答问题，请列举知识库中的数据详细回答。",
+                    "doc_id": "5c5999ec7be811ef9cab0242ac120005",
+                    "docnm_kwd": "1.txt",
+                    "kb_id": "c7ee74067a2c11efb21c0242ac120006",
+                    "important_kwd": [],
+                    "img_id": "",
+                    "similarity": 0.2788204323926715,
+                    "vector_similarity": 0.35489427679953667,
+                    "term_similarity": 0.2462173562183008,
+                    "positions": [
+                        ""
+                    ]
+                }
+            ],
+            "doc_aggs": [
+                {
+                    "doc_name": "1.txt",
+                    "doc_id": "5c5999ec7be811ef9cab0242ac120005",
+                    "count": 2
+                }
+            ]
+        },
+        "prompt": "你是一个智能助手，请总结知识库的内容来回答问题，请列举知识库中的数据详细回答。当所有知识库内容都与问题无关时，你的回答必须包括“知识库中未找到您要的答案！”这句话。回答需要考虑聊天历史。\n            以下是知识库：\n            当所有知识库内容都与问题无关时，你的回答必须包括“知识库中未找到您要的答案！”这句话。回答需要考虑聊天历史。\r\n    以下是知识库：\r\n    {knowledge}\r\n    以上是知识库\r\n\"\"\"\r\n1\r\n2\r\n3\r\n4\r\n5\r\n6\r\n总结\r\n通过上面的介绍，可以对开源的 RagFlow 有了一个大致的了解，与前面的 有道 QAnything 整体流程还是比较类似的。\n\n------\n\n\r\n\r\n实际内容可能会超过大模型的输入 token 数量，因此在调用大模型前会调用 api/db/services/dialog_service.py 文件中 message_fit_in() 根据大模型可用的 token 数量进行过滤。这部分与有道的 QAnything 的实现大同小异，就不额外展开了。\r\n\r\n将检索的内容，历史聊天记录以及问题构造为 prompt，即可作为大模型的输入了，默认的英文 prompt 如下所示：\r\n\r\n\"\"\"\r\nYou are an intelligent assistant. Please summarize the content of the knowledge base to answer the question. Please list the data in the knowledge base and answer in detail. When all knowledge base content is irrelevant to the question, your answer must include the sentence \"The answer you are looking for is not found in the knowledge base!\" Answers need to consider chat history.\r\n      Here is the knowledge base:\r\n      {knowledge}\r\n      The above is the knowledge base.\r\n\"\"\"\r\n1\r\n2\r\n3\r\n4\r\n5\r\n6\r\n对应的中文 prompt 如下所示：\r\n\r\n\"\"\"\r\n你是一个智能助手，请总结知识库的内容来回答问题，请列举知识库中的数据详细回答。\n            以上是知识库。\n\n### Query:\n你好，请问有什么问题需要我帮忙解答吗？\n\n### Elapsed\n  - Retrieval: 9131.1 ms\n  - LLM: 12802.6 ms",
+        "id": "31153052-7bac-4741-a513-ed07d853f29e"
+    }
+}
+
+data:{
+    "code": 0,
+    "data": true
+}
+```
+Error
+```json
+{
+    "code": 102,
+    "message": "Please input your question."
+}
+```