Add user_id for third-party system to record sessions. (#4206)

### What problem does this PR solve?


### Type of change

- [x] New Feature (non-breaking change which adds functionality)
- [x] Documentation Update

---------

Co-authored-by: writinwaters <93570324+writinwaters@users.noreply.github.com>

api/apps/sdk/session.py

@@ -47,7 +47,8 @@ def create(tenant_id, chat_id):
         "id": get_uuid(),
         "dialog_id": req["dialog_id"],
         "name": req.get("name", "New session"),
-        "message": [{"role": "assistant", "content": dia[0].prompt_config.get("prologue")}]
+        "message": [{"role": "assistant", "content": dia[0].prompt_config.get("prologue")}],
+        "user_id": req.get("user_id", "")
     }
     if not conv.get("name"):
         return get_error_data_result(message="`name` can not be empty.")
@@ -197,11 +198,12 @@ def list_session(tenant_id, chat_id):
     page_number = int(request.args.get("page", 1))
     items_per_page = int(request.args.get("page_size", 30))
     orderby = request.args.get("orderby", "create_time")
+    user_id = request.args.get("user_id")
     if request.args.get("desc") == "False" or request.args.get("desc") == "false":
         desc = False
     else:
         desc = True
-    convs = ConversationService.get_list(chat_id, page_number, items_per_page, orderby, desc, id, name)
+    convs = ConversationService.get_list(chat_id, page_number, items_per_page, orderby, desc, id, name, user_id)
     if not convs:
         return get_result(data=[])
     for conv in convs:

api/db/db_models.py

@@ -31,7 +31,6 @@ from peewee import (
 )
 from playhouse.pool import PooledMySQLDatabase, PooledPostgresqlDatabase
 
-
 from api.db import SerializedType, ParserType
 from api import settings
 from api import utils
@@ -926,6 +925,7 @@ class Conversation(DataBaseModel):
     name = CharField(max_length=255, null=True, help_text="converastion name", index=True)
     message = JSONField(null=True)
     reference = JSONField(null=True, default=[])
+    user_id = CharField(max_length=255, null=True, help_text="user_id", index=True)
 
     class Meta:
         db_table = "conversation"
@@ -1070,13 +1070,13 @@ def migrate_db():
             pass
         try:
             migrate(
-                migrator.add_column("tenant_llm","max_tokens",IntegerField(default=8192,index=True))
+                migrator.add_column("tenant_llm", "max_tokens", IntegerField(default=8192, index=True))
             )
         except Exception:
             pass
         try:
             migrate(
-                migrator.add_column("api_4_conversation","dsl",JSONField(null=True, default={}))
+                migrator.add_column("api_4_conversation", "dsl", JSONField(null=True, default={}))
             )
         except Exception:
             pass
@@ -1105,3 +1105,10 @@ def migrate_db():
             )
         except Exception:
             pass
+        try:
+            migrate(
+                migrator.add_column("conversation", "user_id",
+                                    CharField(max_length=255, null=True, help_text="user_id", index=True))
+            )
+        except Exception:
+            pass

api/db/services/api_service.py

@@ -41,11 +41,14 @@ class API4ConversationService(CommonService):
 
     @classmethod
     @DB.connection_context()
-    def get_list(cls,dialog_id, tenant_id,
+    def get_list(cls, dialog_id, tenant_id,
-                 page_number, items_per_page, orderby, desc, id):
+                 page_number, items_per_page,
-        sessions = cls.model.select().where(cls.model.dialog_id ==dialog_id)
+                 orderby, desc, id, user_id=None):
+        sessions = cls.model.select().where(cls.model.dialog_id == dialog_id)
         if id:
             sessions = sessions.where(cls.model.id == id)
+        if user_id:
+            sessions = sessions.where(cls.model.user_id == user_id)
         if desc:
             sessions = sessions.order_by(cls.model.getter_by(orderby).desc())
         else:

api/db/services/conversation_service.py

@@ -28,12 +28,14 @@ class ConversationService(CommonService):
 
     @classmethod
     @DB.connection_context()
-    def get_list(cls,dialog_id,page_number, items_per_page, orderby, desc, id , name):
+    def get_list(cls, dialog_id, page_number, items_per_page, orderby, desc, id, name, user_id=None):
-        sessions = cls.model.select().where(cls.model.dialog_id ==dialog_id)
+        sessions = cls.model.select().where(cls.model.dialog_id == dialog_id)
         if id:
             sessions = sessions.where(cls.model.id == id)
         if name:
             sessions = sessions.where(cls.model.name == name)
+        if user_id:
+            sessions = sessions.where(cls.model.user_id == user_id)
         if desc:
             sessions = sessions.order_by(cls.model.getter_by(orderby).desc())
         else:
@@ -52,6 +54,7 @@ def structure_answer(conv, ans, message_id, session_id):
 
     def get_value(d, k1, k2):
         return d.get(k1, d.get(k2))
+
     chunk_list = [{
         "id": get_value(chunk, "chunk_id", "id"),
         "content": get_value(chunk, "content", "content_with_weight"),
@@ -88,10 +91,11 @@ def completion(tenant_id, chat_id, question, name="New session", session_id=None
     if not session_id:
         session_id = get_uuid()
         conv = {
-            "id":session_id ,
+            "id": session_id,
             "dialog_id": chat_id,
             "name": name,
-            "message": [{"role": "assistant", "content": dia[0].prompt_config.get("prologue")}]
+            "message": [{"role": "assistant", "content": dia[0].prompt_config.get("prologue")}],
+            "user_id": kwargs.get("user_id", "")
         }
         ConversationService.save(**conv)
         yield "data:" + json.dumps({"code": 0, "message": "",
@@ -226,4 +230,3 @@ def iframe_completion(dialog_id, question, session_id=None, stream=True, **kwarg
             API4ConversationService.append_message(conv.id, conv.to_dict())
             break
         yield answer
-

docs/references/http_api_reference.md

@@ -1721,6 +1721,7 @@ Creates a session with a chat assistant.
   - `'Authorization: Bearer <YOUR_API_KEY>'`
 - Body:
   - `"name"`: `string`
+  - `"user_id"`: `string`(optional)
 
 ##### Request example
 
@@ -1741,6 +1742,8 @@ curl --request POST \
   The ID of the associated chat assistant.
 - `"name"`: (*Body parameter*), `string`  
   The name of the chat session to create.
+- `"user_id"`: (*Body parameter*), `string`  
+  Optional user-defined ID.
 
 #### Response
 
@@ -1793,6 +1796,7 @@ Updates a session of a specified chat assistant.
   - `'Authorization: Bearer <YOUR_API_KEY>'`
 - Body:
   - `"name`: `string`
+  - `"user_id`: `string`(optional)
 
 ##### Request example
 
@@ -1815,6 +1819,8 @@ curl --request PUT \
   The ID of the session to update.
 - `"name"`: (*Body Parameter*), `string`  
   The revised name of the session.
+- `"user_id"`: (*Body parameter*), `string`  
+  Optional user-defined ID.
 
 #### Response
 
@@ -1846,7 +1852,7 @@ Lists sessions associated with a specified chat assistant.
 #### Request
 
 - Method: GET
-- URL: `/api/v1/chats/{chat_id}/sessions?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&name={session_name}&id={session_id}`
+- URL: `/api/v1/chats/{chat_id}/sessions?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&name={session_name}&id={session_id}&user_id={user_id}`
 - Headers:
   - `'Authorization: Bearer <YOUR_API_KEY>'`
 
@@ -1876,6 +1882,8 @@ curl --request GET \
   The name of the chat session to retrieve.
 - `id`: (*Filter parameter*), `string`  
   The ID of the chat session to retrieve.
+- `user_id`: (*Filter parameter*), `string`  
+  The optional user-defined ID passed in when creating session.
 
 #### Response
 
@@ -2000,7 +2008,8 @@ Asks a specified chat assistant a question to start an AI-powered conversation.
 - Body:
   - `"question"`: `string`
   - `"stream"`: `boolean`
-  - `"session_id"`: `string`
+  - `"session_id"`: `string`(optional)
+  - `"user_id`: `string`(optional)
 
 ##### Request example
 
@@ -2038,6 +2047,8 @@ curl --request POST \
   - `false`: Disable streaming.
 - `"session_id"`: (*Body Parameter*)  
   The ID of session. If it is not provided, a new session will be generated.
+- `"user_id"`: (*Body parameter*), `string`  
+  The optional user-defined ID. Valid *only* when no `session_id` is provided.
 
 #### Response
 
@@ -2162,6 +2173,8 @@ Creates a session with an agent.
 - Body:
   - the required parameters:`str`
   - the optional parameters:`str`
+    - `"user_id"`: `string`  
+      The optional user-defined ID.
 
 ##### Request example
 If `begin` component in the agent doesn't have required parameters:
@@ -2337,6 +2350,7 @@ Asks a specified agent a question to start an AI-powered conversation.
   - `"question"`: `string`
   - `"stream"`: `boolean`
   - `"session_id"`: `string`
+  - `"user_id"`: `string`(optional)
   - other parameters: `string`
 ##### Request example
 If the `begin` component doesn't have parameters, the following code will create a session.
@@ -2388,6 +2402,8 @@ curl --request POST \
   - `false`: Disable streaming.
 - `"session_id"`: (*Body Parameter*)  
   The ID of the session. If it is not provided, a new session will be generated.
+- `"user_id"`: (*Body parameter*), `string`  
+  The optional user-defined ID. Valid *only* when no `session_id` is provided.
 - Other parameters: (*Body Parameter*)  
   The parameters in the begin component.
 #### Response
@@ -2538,7 +2554,7 @@ Failure:
 
 ### List agent sessions
 
-**GET** `/api/v1/agents/{agent_id}/sessions?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&id={session_id}`
+**GET** `/api/v1/agents/{agent_id}/sessions?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&id={session_id}&user_id={user_id}`
 
 Lists sessions associated with a specified agent.
 
@@ -2553,7 +2569,7 @@ Lists sessions associated with a specified agent.
 
 ```bash
 curl --request GET \
-     --url http://{address}/api/v1/agents/{agent_id}/sessions?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&id={session_id} \
+     --url http://{address}/api/v1/agents/{agent_id}/sessions?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&id={session_id}&user_id={user_id} \
      --header 'Authorization: Bearer <YOUR_API_KEY>'
 ```
 
@@ -2573,6 +2589,8 @@ curl --request GET \
   Indicates whether the retrieved sessions should be sorted in descending order. Defaults to `true`.
 - `id`: (*Filter parameter*), `string`  
   The ID of the agent session to retrieve.
+- `user_id`: (*Filter parameter*), `string`  
+  The optional user-defined ID passed in when creating session.
   
 #### Response