common_agent/rag-store-page-apis.md

知识库页面后端接口清单

本文对应前端页面：RagStoresPage.vue 和 RagDocumentsPage.vue。

1. 页面目标

知识库页面采用：

• 顶部 4 张全局统计卡片
• 左侧知识库名称搜索与列表
• 右侧当前知识库详情
• 当前知识库级别操作：编辑、批量导入文件、重建索引

因此接口拆成 全局概览、知识库列表/详情、文档管理、后续索引动作 四组。

2. 本批已实现并已用于前端联调的接口

2.1 查询全部知识库

• POST /api/rag/store/list

当前返回类型：

• RequestResult<List<RagStoreResponse>>

当前字段：

• id
• storeCode
• storeName
• description
• status
• remark

对应代码：

• src/main/java/com/bruce/rag/controller/RagStoreController.java
• src/main/java/com/bruce/rag/dto/response/RagStoreResponse.java

2.2 按条件查询知识库

• POST /api/rag/store/query

请求体：

{
  "storeCode": "PROD_DOC",
  "storeName": "产品制度",
  "status": "ENABLED"
}

当前支持字段：

• storeCode
• storeName
• status

对应代码：

• src/main/java/com/bruce/rag/dto/request/RagStoreQueryRequest.java

2.3 查询知识库详情

• GET /api/rag/store/detail?id={id}

返回类型：

• RequestResult<RagStoreResponse>

2.4 新增或修改知识库

• POST /api/rag/store/save

请求体：

{
  "id": 1,
  "storeCode": "PROD_DOC",
  "storeName": "产品制度库",
  "description": "产品制度、业务规范、流程材料",
  "status": "启用",
  "remark": "核心制度库"
}

返回类型：

• RequestResult<Boolean>

说明：

• id 为空时新增
• id 不为空时修改

2.5 删除知识库

• POST /api/rag/store/delete?id={id}

返回类型：

• RequestResult<Boolean>

2.6 知识库总览统计

• GET /api/rag/store/overview

返回类型：

• RequestResult<RagStoreOverviewResponse>

字段：

• totalStores
• totalDocuments
• totalChunks（当前为 null，待切片入库后统计）
• retrievableStores

2.7 知识库文档概览

• GET /api/rag/store/documentOverview?storeId={storeId}

返回类型：

• RequestResult<RagStoreDocumentOverviewResponse>

字段：

• storeId
• storeName
• documentCount
• enabledDocumentCount
• parsedDocumentCount
• indexedDocumentCount
• lastUploadTime

3. 当前文档管理接口

3.1 查询全部知识文档

• POST /api/rag/documents/list

3.2 按条件查询知识文档

• POST /api/rag/documents/query

当前可用于按 storeId 查询当前知识库下文档。

对应代码：

• src/main/java/com/bruce/rag/controller/RagDocumentController.java
• src/main/java/com/bruce/rag/dto/request/RagDocumentQueryRequest.java

3.3 查询知识文档详情

• GET /api/rag/documents/detail?id={id}

3.4 新增或修改知识文档

• POST /api/rag/documents/save

3.5 删除知识文档

• POST /api/rag/documents/delete?id={id}

3.6 批量上传文档到知识库

• POST /api/rag/documents/batchUpload

请求类型：

• multipart/form-data

表单字段：

• storeId：知识库 ID
• sourceType：默认为 RAG
• files：文件数组
• documentSummary：可选，批量设置文档摘要
• remark：可选

当前行为：

• 逐个调用附件上传服务，写入 sys_attachment
• 自动创建 rag_document
• 新文档默认 parseStatus=UPLOADED、indexStatus=PENDING、enabled=true

3.7 批量解析知识文档

• POST /api/rag/documents/parse

请求体：

{
  "documentIds": [1, 2]
}

当前行为：

• 根据附件后缀或 content type 选择 Tika 解析器
• 解析结果写入 rag_document_parse_result
• 解析成功后更新 parseStatus=PARSED
• 解析失败后更新 parseStatus=FAILED 和 errorMessage

3.8 批量切片知识文档

• POST /api/rag/documents/chunk

请求体：

{
  "documentIds": [1, 2],
  "chunkStrategy": 1,
  "chunkSize": 800,
  "chunkOverlap": 120,
  "delimiter": "。"
}

当前行为：

• chunkStrategy 使用 RagChunkStrategyEnum 的整型枚举值，例如 1 表示固定长度切片，5 表示按分隔符切片。
• 只处理已经存在解析快照的文档。
• 按策略生成 rag_chunk，写入前会替换该文档已有切片。
• 当前尚未调用 Embedding 模型写入 rag_chunk_embedding。

4. 下一批建议补充的接口

当前已有接口能支撑知识库、文档、上传、解析和手动切片入口。下一批建议聚焦向量索引、模型配置和任务化。

4.1 知识库列表查询增强版

• POST /api/rag/store/manage/query

用途：

• 左侧知识库列表

相比当前 /query，建议直接返回列表页需要的摘要字段，避免前端再额外聚合文档数据。

请求体建议：

{
  "storeName": "FAQ"
}

返回建议：

{
  "resultcode": "0",
  "message": null,
  "data": [
    {
      "id": 2,
      "storeCode": "FAQ",
      "storeName": "FAQ知识库",
      "description": "常见问题知识沉淀",
      "status": "ENABLED",
      "documentCount": 58,
      "chunkCount": 920,
      "indexStatus": "PROCESSING",
      "retrievable": true,
      "updateTime": "2026-05-21 11:12:00"
    }
  ]
}

建议响应 DTO：

• RagStoreManageListResponse

字段建议：

• id
• storeCode
• storeName
• description
• status
• documentCount
• chunkCount
• indexStatus
• retrievable
• updateTime

4.2 查询单个知识库详情增强版

• GET /api/rag/store/detailPlus?id={id}

用途：

• 右侧详情区

返回建议：

{
  "resultcode": "0",
  "message": null,
  "data": {
    "id": 1,
    "storeCode": "PROD_DOC",
    "storeName": "产品制度库",
    "description": "产品制度、业务规范、流程材料",
    "status": "ENABLED",
    "createTime": "2026-05-03 10:20:00",
    "updateTime": "2026-05-21 16:40:00",
    "documentCount": 126,
    "parseSuccessCount": 120,
    "parseFailedCount": 6,
    "chunkCount": 3800,
    "lastUploadTime": "2026-05-21 15:32:00",
    "lastIndexTime": "2026-05-21 15:48:00",
    "retrievalMode": "HYBRID",
    "embeddingModel": "bge-large-zh",
    "chunkSize": 500,
    "chunkOverlap": 100,
    "topK": 5,
    "retrievable": true
  }
}

建议响应 DTO：

• RagStoreDetailResponse

4.3 发起当前知识库重建索引

• POST /api/rag/store/reindex?storeId={id}

用途：

• 右侧“重建索引”按钮

请求体建议：

{
  "force": true
}

返回建议：

{
  "resultcode": "0",
  "message": null,
  "data": {
    "taskId": 1002,
    "storeId": 1,
    "status": "PROCESSING"
  }
}

4.4 查询当前知识库最近任务

• GET /api/rag/store/tasks?storeId={id}&limit=10

用途：

• 右侧“最近任务”区

返回建议：

{
  "resultcode": "0",
  "message": null,
  "data": [
    {
      "id": 1002,
      "taskType": "REINDEX",
      "summary": "全库索引刷新",
      "status": "PROCESSING",
      "startedAt": "2026-05-21 16:00:00"
    },
    {
      "id": 1001,
      "taskType": "IMPORT",
      "summary": "12 个文件，制度文档增量导入",
      "status": "SUCCESS",
      "startedAt": "2026-05-21 15:20:00"
    }
  ]
}

建议响应 DTO：

• RagStoreTaskResponse

5. 这页前后端最小联调顺序

当前知识库页和知识文档页已经接入基础接口。下一步联调顺序建议：

1. 完成向量入库：

   • POST /api/rag/documents/chunk 生成 rag_chunk
   • 通过模型网关调用 Embedding 并写入 rag_chunk_embedding

2. 完成索引入口：

   • POST /api/rag/documents/index
   • POST /api/rag/store/reindex

3. 再补任务查询：

   • GET /api/rag/store/tasks
   • GET /api/rag/documents/tasks

6. 当前前端实现说明

当前前端已经接入：

• 统计卡片：/api/rag/store/overview
• 左侧列表：/api/rag/store/query
• 右侧详情：/api/rag/store/detail
• 文档概览：/api/rag/store/documentOverview
• 批量上传：/api/rag/documents/batchUpload
• 知识文档列表：/api/rag/documents/query
• 批量解析：/api/rag/documents/parse
• 批量切片：/api/rag/documents/chunk

仍待后端补齐后再联调：

• 重建索引
• 最近任务
• 模型服务商与 Embedding 模型配置
• 检索配置
• 检索测试/召回预览

7. 与 Agent 调试链路的关联

当前 RAG 切片与向量数据已经被 Agent 调试页直接消费：

• Agent 调试接口 POST /api/agents/{agentId}/chat 在 ragEnabled=true 时会读取 rag_chunk_embedding 进行 TopK 召回。
• 若未完成切片向量化，Agent 调试会返回“未召回到可用知识切片”。

关联文档：

• Agent 页面后端接口清单