leaudit-platform-backend/docs/RAG/RAG知识库文档管理接口与行为变更说明.md

RAG 知识库文档管理接口与行为变更说明

最后整理：2026-05-11 对应后端提交：8206ed7 对应控制器：fastapi_modules/fastapi_leaudit/controllers/ragChatController.py 对应服务：fastapi_modules/fastapi_leaudit/services/impl/ragDatasetServiceImpl.py 统一前缀：/api/v3/rag

1. 目标

本文档说明本次 RAG 知识库“文档管理”相关后端改动，重点覆盖：

• 知识库文档批量删除
• 删除结果明细返回
• 处理中 / 索引中文档删除限制
• 文档上传改为异步处理
• 文档重处理改为异步处理
• 前端轮询所依赖的状态流转
• 向量化调用的分批与错误处理

不在本文范围内：

• 聊天接口
• 应用管理接口
• 知识库基础 CRUD
• 子分段 / 分段编辑细节

2. 相关权限

本次涉及的接口主要使用以下权限：

接口	权限
GET /api/v3/rag/datasets/{DatasetId}/documents/{DocumentId}/indexing-status	rag:dataset:read
POST /api/v3/rag/datasets/{DatasetId}/documents	rag:dataset:update
POST /api/v3/rag/datasets/{DatasetId}/documents/{DocumentId}/update-by-file	rag:dataset:update
DELETE /api/v3/rag/datasets/{DatasetId}/documents/{DocumentId}	rag:dataset:delete
POST /api/v3/rag/datasets/{DatasetId}/documents/batch-delete	rag:dataset:delete

补充：

• 后端控制器层会先检查权限键。
• 服务层还会继续校验角色范围。
• 当前允许执行文档上传 / 删除的角色范围仍为：
  • provincial_admin
  • super_admin
  • admin

3. 本次行为变化总览

3.1 批量删除

新增接口：

• POST /api/v3/rag/datasets/{DatasetId}/documents/batch-delete

行为：

• 支持单请求删除多个文档
• 返回删除成功数量、跳过数量、已删除 ID、跳过原因明细

3.2 删除限制

删除接口不再允许删除“处理中”的文档。

当前视为处理中、不可删除的状态：

• waiting
• parsing
• cleaning
• splitting
• indexing

当前允许删除的状态：

• completed
• error
• paused

3.3 上传与重处理改为异步

此前：

• 上传接口会等完整解析、切分、向量化完成后才返回

现在：

• 上传接口创建文档记录后立即返回
• 后台使用异步任务继续完成后续处理
• 前端通过 indexing-status 接口轮询状态

3.4 向量化调用分批

此前：

• 一次性将全部 chunk 发给 embedding 接口

现在：

• 按 RAG_CONFIG["EMBED_BATCH_SIZE"] 分批提交
• 默认值由配置控制，未配置时使用 10

目的：

• 降低 DashScope / embedding 服务因单次输入过大返回 400 Bad Request 的概率

4. 接口说明

4.1 上传知识库文档

POST /api/v3/rag/datasets/{DatasetId}/documents

请求：

• multipart/form-data
• file: 文件内容
• data: 可选，JSON 字符串，表示处理配置

当前支持格式：

• .pdf
• .docx
• .txt
• .md
• .json

成功响应示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "document": {
      "id": "12",
      "name": "示例文档.pdf",
      "indexing_status": "indexing",
      "word_count": 0,
      "hit_count": 0,
      "enabled": true
    },
    "batch": "12"
  }
}

说明：

• 返回时不代表向量化已经完成。
• batch 当前等同于 documentId，前端可直接拿去轮询状态。

4.2 重处理知识库文档

POST /api/v3/rag/datasets/{DatasetId}/documents/{DocumentId}/update-by-file

行为与上传接口一致：

• 先把文档状态置为 indexing
• 清理旧向量
• 立即返回
• 后台异步重建 chunk 与向量

成功响应示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "document": {
      "id": "12",
      "name": "示例文档.pdf",
      "indexing_status": "indexing",
      "word_count": 0,
      "hit_count": 0,
      "enabled": true
    },
    "batch": "12"
  }
}

4.3 查询文档处理状态

GET /api/v3/rag/datasets/{DatasetId}/documents/{DocumentId}/indexing-status

成功响应示例：

{
  "code": 200,
  "msg": "success",
  "data": [
    {
      "id": "12",
      "indexing_status": "splitting",
      "processing_started_at": 1778490000,
      "parsing_completed_at": 1778490003,
      "cleaning_completed_at": 1778490005,
      "splitting_completed_at": null,
      "completed_at": null,
      "paused_at": null,
      "error": null,
      "stopped_at": null,
      "completed_segments": 0,
      "total_segments": 24
    }
  ]
}

状态流转顺序：

• indexing（创建记录后的初始状态）
• parsing
• cleaning
• splitting
• indexing（写入向量阶段）
• completed

失败时：

• 状态会更新为 error
• error 字段会记录截断后的错误信息

4.4 单文档删除

DELETE /api/v3/rag/datasets/{DatasetId}/documents/{DocumentId}

行为：

• 实际内部复用批量删除逻辑
• 如果目标文档处于处理中状态，会直接返回 400

错误示例：

{
  "code": 400,
  "msg": "文档仍在处理中，暂不允许删除",
  "data": null
}

4.5 批量删除文档

POST /api/v3/rag/datasets/{DatasetId}/documents/batch-delete

请求体：

{
  "document_ids": [12, 13, 14]
}

成功响应示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "result": "success",
    "requestedCount": 3,
    "deletedCount": 2,
    "skippedCount": 1,
    "deletedIds": [12, 13],
    "skipped": [
      {
        "id": 14,
        "name": "处理中示例.pdf",
        "reason": "文档仍在处理中，暂不允许删除"
      }
    ]
  }
}

说明：

• 后端会先查询所有目标文档
• 对可删除文档：
  • 删除 Chroma 中对应向量
  • 删除 OSS 对象
  • 逻辑删除 rag_document
• 完成后统一回写：
  • rag_dataset.document_count
  • rag_dataset.total_chunks

5. 后端内部状态处理说明

5.1 异步处理任务

上传 / 重处理现在通过内部异步任务 _run_document_indexing_task(...) 执行后续工作。

任务步骤：

1. 更新状态为 parsing
2. 提取文本
3. 更新状态为 cleaning
4. 构建 chunk
5. 更新状态为 splitting
6. 调 embedding 接口生成向量
7. 更新状态为 indexing
8. 写入 Chroma
9. 更新状态为 completed
10. 同步 rag_dataset 统计字段

异常时：

• 状态写为 error
• indexing_error 写入错误摘要

5.2 向量化分批

方法：

• _embed_texts(texts, model_name)

变化：

• 以前单次请求提交全部文本
• 现在按批次循环提交

错误处理：

• 若 embedding 服务返回 HTTP 错误
• 服务层会转成：

向量化服务调用失败: <上游错误文本>

以便前端直接显示可读错误

6. 前后端联调注意事项

6.1 上传成功不等于处理完成

前端不能再以“上传接口返回 200”判断文档已经可检索。

正确做法：

1. 调上传接口
2. 读取响应中的 batch
3. 轮询 indexing-status
4. 直到状态变为：
   • completed
   • 或 error

6.2 批量删除要接删除明细

前端不应只提示“删除成功”。

建议按以下优先级展示：

• 全部删除成功：提示删除数量
• 部分删除成功：提示成功数 + 跳过数
• 全部跳过：提示未删除，并展示跳过原因

6.3 处理中状态要禁用删除入口

虽然服务端已经拦截，但前端仍应同步禁用：

• 单删按钮
• 批量多选框

避免用户误操作后频繁打到 400

7. 对应提交

本次后端变更对应提交：

• 8206ed7 feat: improve rag dataset document management

如果后续继续扩展：

• 文档状态更多细粒度字段
• chunk 统计维度
• 删除结果补充更多结构化信息

建议继续更新本文，而不是另起一份零散说明。