3.8-RAG-Agent RAG 系统的接口文档

查看源文件

一、用户管理模块

01、用户注册接口

• URL: /api/v1/users/register

• Method: POST

• Request Body:

{"username": "string",   // 用户名，唯一"password": "string"    // 密码（明文传输，后端加密存储）}

• Response:

{
  "code": 200,// 成功
  "message": "User registered successfully"
}
 
{
  "code": 400, // 失败
  "message": "Username already exists"
}

02、用户登录接口

• URL: /api/v1/users/login

• Method: POST

• Request Body:

{
  "username": "string",
  "password": "string"
}

• Response:

{
  "code": 200,// 成功
  "message": "Login successful",
  "data": {
    "token": "JWT_TOKEN_STRING"
  }
}
 
{
  "code": 401, // 失败
  "message": "Invalid username or password"
}

03、获取用户信息接口

• URL: /api/v1/users/me

• Method: GET

• Headers:

  • Authorization: Bearer JWT_TOKEN_STRING

• Response:

{
  "code": 200,// 成功
  "message": "Success",
  "data": {
    "id": 1,
    "username": "example_user",
    "role": "USER",
    "orgTags": ["dept1", "team2"],
    "primaryOrg": "dept1"
  }
}
 
{
  "code": 401, // 失败
  "message": "Unauthorized"
}

04、组织标签管理接口

①、创建组织标签（管理员）

• URL: /api/v1/admin/org-tags

• Method: POST

• Headers:

  • Authorization: Bearer JWT_TOKEN_STRING

• Request Body:

{
  "tagId": "string",     // 标签ID，唯一
  "name": "string",      // 标签名称
  "description": "string", // 标签描述
  "parentTag": "string"  // 父标签ID（可选）
}

• Response:

{
  "code": 200,
  "message": "Organization tag created successfully"
}

②、为用户分配组织标签

• URL: /api/v1/admin/users/{userId}/org-tags

• Method: PUT

• Headers:

  • Authorization: Bearer JWT_TOKEN_STRING

• Request Body:

{"orgTags": ["tag1", "tag2"]}

• Response:

{"code": 200,"message": "Organization tags assigned successfully"}复制代码

③、设置用户组织

• URL: /api/v1/users/primary-org

• Method: PUT

• Headers:

  • Authorization: Bearer JWT_TOKEN_STRING

• Request Body:

{"primaryOrg": "tag1"}复制代码

• Response:

  • 成功：

{"code": 200,"message": "Primary organization set successfully"}

④、获取用户组织标签详情

• URL: /api/v1/users/org-tags

• Method: GET

• Headers:

• Authorization: Bearer JWT_TOKEN_STRING

• Response:

{
  "code": 200,
  "message": "Get user organization tags successful",
  "data": {
    "orgTags": ["PRIVATE_example_user", "dept1", "team2"],
    "primaryOrg": "PRIVATE_example_user",
    "orgTagDetails": [
      {
        "tagId": "PRIVATE_example_user",
        "name": "example_user的私人空间",
        "description": "用户的私人组织标签，仅用户本人可访问"
      },
      {
        "tagId": "dept1",
        "name": "部门1",
        "description": "部门1的组织标签"
      },
      {
        "tagId": "team2",
        "name": "团队2",
        "description": "团队2的组织标签"
      }
    ]
  }
}

二、文件上传与处理模块

01、分片上传接口

URL: /api/v1/upload/chunk

Method: POST

Headers:

X-File-MD5: d41d8cd98f00b204e9800998ecf8427e

X-Chunk-Index: 3

Authorization: Bearer

Body: multipart/form-data (分片二进制数据)

Response:

{
  "code": 200,// 成功
  "message": "Chunk uploaded successfully",
  "data": {
    "uploaded": [0, 1, 2, 3],
    "progress": 75.0
  }
}
 
{
  "code": 400,//失败
  "message": "Invalid chunk data"
}

02、查询上传状态接口

• URL: /api/v1/upload/status

• Method: GET

• Query Parameters:

  • file_md5: d41d8cd98f00b204e9800998ecf8427e

• Headers:

  • Authorization: Bearer

• Response:

{
  "code": 200,// 成功
  "message": "Success",
  "data": {
    "uploaded": [0, 1, 2],
    "progress": 60.0,
    "total_chunks": 5
  }
}
 
{
  "code": 404,//失败
  "message": "Upload record not found"
}

03、文件合并接口

• URL: /api/v1/upload/merge

• Method: POST

• Headers:

  • Authorization: Bearer

• Request Body:

{
  "file_md5": "d41d8cd98f00b204e9800998ecf8427e",
  "file_name": "paismart.pdf"
}

• Response:

{
  "code": 200, // 成功
  "message": "File merged successfully",
  "data": {
    "object_url": "https://minio.example.com/reports/paismart.pdf",
    "file_size": 15728640
  }
}
 
{
  "code": 400, // 失败
  "message": "Not all chunks have been uploaded"
}

04、文件删除接口

• URL: /api/v1/documents/{file_md5}

• Method: DELETE

• Path Parameters:

  • file_md5 : 要删除的文件唯一标识（MD5值）

• Headers:

  • Authorization : Bearer {token} （用于身份验证）

• Response:

{
  "status": "success",
  "message": "文档删除成功"
}
 
{
  "status": "error",
  "message": "文档不存在"
}
 
{
  "status": "error",
  "message": "没有权限删除此文档"
}
 
{
  "status": "error",
  "message": "删除文档失败: 详细错误信息"
}

三、知识库检索模块

01、混合搜索接口

• URL: /api/search/hybrid

• Method: POST

• Request Body:

{
  "query": "沉默王二是条狗？",
  "topK": 10
}

• Response:

[
  {
    "file_md5": "abc123...",
    "chunk_id": 1,
    "text_content": "哦不，沉默王二帅的像个人。",
    "score": 0.92,
    "file_name": "itwanger.pdf"
  },
  // ...更多结果
]

02、文档删除接口

• URL: /api/documents/{file_md5}

• Method: DELETE

• Path Parameters:

  • file_md5 : 要删除的文件唯一标识（MD5值）

• Headers:

  • Authorization : Bearer {token} （用于身份验证）

• Response:

{
  "status": "success",
  "message": "文档删除成功"
}
 
{
  "status": "error",
  "message": "文档不存在"
}
 
{
  "status": "error",
  "message": "没有权限删除此文档"
}
 
{
  "status": "error",
  "message": "删除文档失败: 详细错误信息"
}

四、聊天助手模块

01、WebSocket 接口

• URL: /ws/chat

• 协议: WebSocket

• 功能: 用户通过WebSocket发送消息，服务端逐段返回回答内容

• 客户端发送消息格式:

{
  "message": "RAG-Agent是什么？",
  "conversationId": "abcdef123456"  // 可选，不提供则使用当前会话
}

• 服务端返回格式:

{"chunk": "RAG-Agent是"}{"chunk": "一个 RAG"}{"chunk": " 的私有知识库。"}

02、创建聊天接口

• URL: /api/conversation/create

• Method: POST

• Request Body:

{
  "userId": "12345"
}

• Response:

{"conversationId": "abcdef123456" //为用户生成一个新的conversationId，并将其与用户关联}

03、获取聊天历史

• URL: /api/conversation/history

• Method: GET

• Query Parameters: userId : 用户ID

• Response:

{ // 根据用户的userId获取其当前会话的对话历史
  "messages": [
    {"role": "user", "content": "RAG-Agent是什么？"},
    {"role": "assistant", "content": "RAG-Agent是一个 RAG 的私有知识库。"}
  ]
}