22 KiB
22 KiB
03 资料上传与处理 — 跨项目完整能力分析
项目角色分类：主链路参与者（iOS、主 API、COS、Python RAG Worker、Qdrant——资料上传后必须经过这些项目才能完成处理）、运维可观测（Admin）。 Rust Document Runtime 不参与上传与处理链路。Heavy Runtime 不参与此链路。 注意：Python RAG Worker 和 Qdrant 在本能力中是主链路参与者；在"知识库与知识点管理"和"AI 对话与知识库问答"能力中角色不同（分别为上游支撑和不参与对话上下文加载）。
1. 能力目标
用户将外部学习资料（PDF、Word、Markdown、图片等）上传至知识库，系统自动完成文本解析、分块、向量索引和知识点候选提取，使资料成为可阅读、可检索、可被 AI 引用的结构化知识。
2. C 端入口
| 入口页面 | 触发方式 | 进入场景 |
|---|---|---|
| 知识库详情页 | 操作菜单 → "上传" | 向已有知识库导入资料 |
| 知识库详情页 | 操作菜单 → "添加" → 文件模式 | 以文件形式添加知识点 |
| 添加知识点页·文件模式 | 点击"选择文件"或"图片"按钮 | 选择文件/照片作为知识点 |
| 导入资料页 | 点击"文件导入"/"相册导入"/"链接导入" | 三种导入方式 |
用户可执行的操作：
- 从系统文件选择器选择文件（PDF、纯文本、图片等）
- 从相册选择照片（自动压缩大于 2MB 的图片）
- 输入 URL 进行链接导入
- 查看上传进度
- 查看导入任务的 AI 处理状态（处理中/就绪/失败）
- 审核 AI 提取的知识点候选（接受/拒绝/批量接受）
3. 用户主流程
用户选择资料
→ iOS 校验文件类型和大小（图片 >2MB 自动压缩）
→ iOS 调用 API 获取 COS 预签名上传 URL
→ iOS 将文件直接 PUT 到 COS
→ iOS 调用 API 确认上传完成（API 验证 COS 中文件存在）
→ API 创建资料记录（KnowledgeSource）
→ API 创建导入任务（DocumentImport，状态 QUEUED）
→ Python RAG Worker 轮询获取导入任务
→ Worker 下载文件 → 解析文本 → 清洗 → 分块 → 向量嵌入 → 索引到 Qdrant → 生成知识点候选
→ Worker 更新 KnowledgeSource 的 parseStatus/indexStatus/learningStatus
→ 用户可在资料详情页查看 AI 处理状态
→ 用户可在导入候选审核页审核 AI 提取的知识点候选
→ 用户接受候选 → API 创建 KnowledgeItem
→ 资料进入可阅读、可被 AI 检索的状态
4. 处理阶段与状态
资料上传后经历多个异步处理阶段，每个阶段有独立的状态追踪：
4.1 原文件上传状态
- 谁创建： iOS 调用 API 确认上传后，API 创建 UploadedFile 记录。
- 谁更新： 上传完成后状态不再变化。文件删除时 API 从 COS 和数据库移除。
- 用户在哪里看到： iOS 上传过程中显示进度指示器；上传完成后在资料详情页看到文件名、格式、大小。
- Admin 在哪里看到： Admin 文件管理页查看所有上传文件列表，可按类型筛选。
- 失败后如何处理： COS 上传失败时 iOS 显示错误提示，用户可重试。
4.2 文本解析状态（parseStatus）
- 谁创建： API 创建 KnowledgeSource 时默认为
pending。 - 谁更新： Python RAG Worker 在处理过程中更新（pending → processing → complete/failed）。同时更新 textLength、parsedObjectKey、errorCode、errorMessage。
- 用户在哪里看到： iOS 资料详情页的 AI 处理状态横幅（处理中为琥珀色、就绪为绿色、失败为红色）。
- Admin 在哪里看到： Admin 来源文件页的 parseStatus 列；导入监控页的步骤日志。
- 失败后如何处理： Admin 可触发重新解析（POST /knowledge-bases/:kbId/sources/:id/parse）；导入任务自动重试最多 3 次。
4.3 向量索引状态（indexStatus）
- 谁创建： API 创建 KnowledgeSource 时默认为
pending。 - 谁更新： Python RAG Worker 在嵌入和索引阶段更新（pending → processing → complete/failed）。
- 用户在哪里看到： iOS 不单独展示索引状态（合并在 AI 处理状态中）。
- Admin 在哪里看到： Admin 来源文件页的 indexStatus 列。
- 失败后如何处理： 同解析失败，Admin 可触发重新解析，系统自动重试。
4.4 学习内容提取状态（learningStatus）
- 谁创建： API 创建 KnowledgeSource 时默认为
pending。 - 谁更新： Python RAG Worker 在知识点候选生成完成后更新为
complete。 - 用户在哪里看到： 不直接展示；用户通过导入候选审核页间接感知（有候选 = 已完成提取）。
- Admin 在哪里看到： Admin 来源文件详情中查看。
- 失败后如何处理： 候选生成是非致命步骤——即使失败，解析和索引仍可成功。
4.5 候选审核状态
- 谁创建： Python RAG Worker 生成候选后，API 创建 ImportCandidate 记录（状态 PENDING）。
- 谁更新： iOS 用户操作：接受 → ACCEPTED；拒绝 → REJECTED；编辑 → EDITED。内容安全拦截 → BLOCKED。
- 用户在哪里看到： iOS 导入候选审核页（候选列表含置信度分数、标题、摘要）。
- Admin 在哪里看到： Admin 知识运营页的候选巡检 Tab。
- 失败后如何处理： 被内容安全拦截的候选标记为 BLOCKED，Admin 可查看但不可恢复。
5. 项目职责
iOS — 主链路参与者
- 提供文件选择器、相册选择器、链接输入弹窗
- 校验文件类型和大小（图片 >2MB 自动 JPEG 压缩）
- 调用 API 获取 COS 预签名上传 URL
- 直接 PUT 文件到 COS
- 调用 API 确认上传
- 展示上传进度和 AI 处理状态
- 提供导入候选审核界面（接受/拒绝/批量接受）
主 API — 主链路参与者
- 提供 COS 预签名上传 URL（POST /files/upload-url）
- 验证文件类型和大小：iOS 端进行初步校验（文件选择器限制可选类型、图片压缩）；API 端进行最终校验（允许 PDF/TXT/Markdown/CSV/XLSX/DOCX/PNG/JPEG/WebP，最大 20MB）
- 文件名内容安全检查
- 确认上传完成（POST /files/complete），验证 COS 中文件存在后创建记录
- 创建 KnowledgeSource 记录并自动创建 DocumentImport 任务
- 管理导入任务状态（Redis 实时状态 + 数据库持久化）
- 提供导入状态查询（GET /imports/:id/status）
- 提供候选审核 API（accept/reject/batch-accept）
- 文件下载 URL 生成（COS 预签名链接）
- 速率限制（文件上传端点）
COS（腾讯云对象存储）— 主链路参与者
- 存储用户上传的原始文件
- 提供预签名 PUT URL（iOS 直接上传，不经 API 中转）
- 提供预签名 GET URL（iOS 下载，Python RAG Worker 下载）
- 对象键格式：
{userId}/{YYYYMM}/{sanitizedFilename}
Python RAG Worker — 主链路参与者
- 轮询 API 获取待处理导入任务（每 5 秒）
- 定期发送心跳保持任务活跃（每 30 秒）
- 完整处理管线：下载文件 → 解析文本 → 清洗（当前仅做 >10 字符长度验证，无实质性文本清洗） → 分块 → 向量嵌入 → 索引到 Qdrant → 生成知识点候选
- 解析器支持：PDF（PyMuPDF 提取文本层 → 若每页平均 <50 字符则回退到 SiliconFlow Qwen3-VL OCR）、DOCX（python-docx）、TXT/MD（直接读取）、CSV/XLSX（pandas 转 Markdown 表格）、图片（SiliconFlow 多模态 OCR）
- 分块策略：递归字符分割，中文句子边界保护，Markdown 标题感知，512 token 块 + 64 token 重叠
- 嵌入模型：BAAI/bge-m3（1024 维），通过 SiliconFlow API
- 候选生成：DeepSeek 分析全文提取知识点（标题、摘要、内容、标签、回忆问题、难度、置信度）
- 更新 KnowledgeSource 的 parseStatus/indexStatus/learningStatus
Qdrant（向量数据库）— 主链路参与者
- 存储文档块的向量索引（集合
zhixi_chunks，1024 维，余弦距离） - 每个向量点携带 payload：userId、knowledgeBaseId、sourceId、chunkId、pageNumber、sectionTitle
- 支持按 sourceId 软删除（mark_deleted）
- 为资料范围 AI 问答和语义检索提供向量搜索能力
Admin — 运维与可观测
- 文件管理页（查看所有上传文件，删除）
- 来源文件页（查看所有 KnowledgeSource，按解析/索引状态筛选）
- 导入监控页（查看所有导入任务，步骤级日志，重试失败任务）
- 候选巡检 Tab（查看所有候选及其审核状态）
- 分块管理 Tab（按 sourceId 查看分块详情）
- RAG 调试 Tab（向量搜索调试）
Rust Document Runtime — 不参与
文件上传和异步处理链路不涉及 Rust Document Runtime。Rust 仅在用户打开已上传资料进行阅读时参与文件解析。
Heavy Runtime — 不参与
Heavy Runtime 不参与文件上传、解析、分块、索引和候选生成流程。
6. 项目间调用关系
6.1 iOS → API
| 调用目的 | 业务结果 |
|---|---|
| 请求上传授权 | 返回 COS 预签名 PUT URL + objectKey |
| 确认上传完成 | API 验证 COS 文件存在，创建 UploadedFile 记录 |
| 创建知识源 | 创建 KnowledgeSource + DocumentImport 任务（QUEUED） |
| 查询导入状态 | 返回 Redis 实时状态（进度百分比 + 文字描述） |
| 获取下载 URL | 返回 COS 预签名下载链接 |
6.2 iOS → COS（直接）
| 调用目的 | 业务结果 |
|---|---|
| 上传文件 | 文件直接 PUT 到 COS，不经 API 中转 |
6.3 Python RAG Worker → API
| 调用目的 | 业务结果 |
|---|---|
| 轮询待处理任务 | 获取 QUEUED 状态的导入任务 |
| 锁定任务 | 原子转换 QUEUED → CLAIMED |
| 心跳上报 | 保持任务活跃，防止超时回收 |
| 更新任务状态 | 更新 Redis 进度/消息 |
| 更新 KnowledgeSource | 更新 parseStatus/indexStatus/learningStatus |
| 保存分块 | 批量写入 KnowledgeChunk 记录 |
| 保存候选 | 批量写入 ImportCandidate 记录 |
6.4 Python RAG Worker → COS
| 调用目的 | 业务结果 |
|---|---|
| 下载文件 | 通过预签名 URL 下载原始文件用于处理 |
6.5 Python RAG Worker → Qdrant
| 调用目的 | 业务结果 |
|---|---|
| 写入向量 | 将文档块的嵌入向量写入 zhixi_chunks 集合 |
| 软删除 | 标记指定 sourceId 的向量为 deleted |
6.6 Python RAG Worker → 模型服务
| 调用目的 | 业务结果 |
|---|---|
| 文本嵌入 | 调用 SiliconFlow BAAI/bge-m3 生成 1024 维向量 |
| 图片 OCR | 调用 SiliconFlow Qwen3-VL 多模态模型提取图片文字 |
| 候选生成 | 调用 DeepSeek 分析全文提取知识点候选 |
6.7 Admin → API（运维可观测）
| 调用目的 | 业务结果 |
|---|---|
| 查看/删除文件 | 文件管理 |
| 查看来源文件 | 列表 + 按状态筛选 |
| 查看导入任务 | 列表 + 步骤日志 |
| 重试导入 | 重置失败任务为 QUEUED |
| 查看候选 | 候选巡检 |
| 查看分块 | 按 sourceId 查看分块详情 |
7. 核心业务数据
7.1 上传文件（UploadedFile）
- 谁创建： API 在确认上传时创建。
- 谁更新： 不更新（创建后不可变）。
- 谁查询： iOS 在上传后获取文件信息；Admin 在文件管理页查询。
- 用途： 记录已上传到 COS 的文件，作为 KnowledgeSource 的 fileId 引用来源。
7.2 知识源（KnowledgeSource）
- 谁创建： API 在添加来源时创建（关联 fileId）。
- 谁更新： Python RAG Worker 更新 parseStatus/indexStatus/learningStatus。
- 谁查询： iOS 在知识库详情页来源 Tab；Admin 在来源文件页。
- 用途： 知识库中每个导入资料的记录，追踪处理状态。
7.3 导入任务（DocumentImport）
- 谁创建： API 在创建 KnowledgeSource 时自动创建（状态 QUEUED）。
- 谁更新： Python RAG Worker 更新状态、进度、步骤日志；Admin 可重置为 QUEUED（重试）。
- 谁查询： iOS 查询导入状态；Admin 在导入监控页。
- 用途： 追踪单个文档的完整处理生命周期，从排队到完成或失败。
7.4 知识分块（KnowledgeChunk）
- 谁创建： Python RAG Worker 在分块和索引阶段批量创建。
- 谁更新： 创建后不可修改（软删除通过 Qdrant 实现）。
- 谁查询： Admin 在分块管理 Tab 按 sourceId 查看；系统内部通过 Qdrant 向量搜索使用。
- 用途： 文档的语义分块，每个块有向量嵌入，用于资料范围 AI 问答的语义检索。
7.5 导入候选（ImportCandidate）
- 谁创建： Python RAG Worker 在候选生成阶段批量创建（状态 PENDING）。
- 谁更新： iOS 用户操作（accept → ACCEPTED，reject → REJECTED，edit → EDITED）。内容安全拦截 → BLOCKED。
- 谁查询： iOS 在候选审核页按 sourceId 查询；Admin 在候选巡检 Tab 查看。
- 用途： AI 从文档中提取的知识点候选，等待用户审核确认。
7.6 知识点（KnowledgeItem，由候选接受生成）
- 谁创建： API 在用户接受候选时创建（itemType: ai_generated）。
- 谁更新： 用户在编辑知识点页修改。
- 谁查询： iOS 在知识点详情页和知识库详情页。
- 用途： 用户确认后的正式知识点，进入知识库内容体系。
7.7 向量索引（Qdrant Collection）
- 谁创建： Python RAG Worker 在索引阶段写入。
- 谁更新： 软删除通过 mark_deleted(sourceId) 实现。
- 谁查询： API 在资料范围 AI 问答时通过向量搜索检索相关块；Admin 通过向量管理页查看统计。
- 用途： 为资料范围 AI 问答提供语义级检索能力。
8. 查询入口
用户查询
- 上传进度： iOS 添加知识点页/导入资料页的上传进度指示器。
- AI 处理状态： iOS 资料详情页的 AI 处理状态横幅（处理中/就绪/失败）。
- 导入候选： iOS 导入候选审核页（列表含置信度、标题、摘要）。
- 来源文件列表： iOS 知识库详情页来源 Tab（含处理状态标签）。
Admin 查询
- 文件列表： Admin 文件管理页（按类型查看、删除）。
- 来源文件列表： Admin 来源文件页（按解析/索引状态筛选）。
- 导入任务列表： Admin 导入监控页（状态、进度、步骤日志、重试）。
- 候选巡检： Admin 知识运营页候选巡检 Tab。
- 分块管理： Admin 知识运营页分块管理 Tab（按 sourceId 查看）。
- RAG 调试： Admin 知识运营页 RAG 调试 Tab（向量搜索测试）。
系统内部查询
- RAG Worker 轮询任务： Python RAG Worker 定期轮询 QUEUED 导入任务。
- 向量搜索： API 在资料范围 AI 问答时查询 Qdrant 获取相关块。
- Redis 状态查询： API 提供导入任务实时状态（24 小时 TTL）。
9. 修改入口
用户操作
- 上传新文件： iOS 导入资料页/添加知识点页。
- 接受候选： iOS 候选审核页接受单个候选。
- 拒绝候选： iOS 候选审核页拒绝单个候选。
- 批量接受： iOS 候选审核页"全部接受"按钮。
- 编辑候选： iOS 可编辑候选内容后再接受。
Admin 操作
- 删除文件： Admin 文件管理页删除上传文件（同时从 COS 删除）。
- 重试导入： Admin 导入监控页重试失败任务（重置为 QUEUED，最多 3 次系统自动重试，Admin 手动重置不占重试次数）。
- 触发重新解析： Admin 可触发知识源的重新解析。
系统自动修改
- 导入任务自动重试： Python RAG Worker 失败时系统自动重试（最多 3 次，超时后标记 FAILED_FINAL）。
- 过期任务回收： 心跳超过 5 分钟的 CLAIMED 任务被重置为 QUEUED。
- 内容安全检查： 文件名、KB 标题、候选内容接受时自动进行敏感词检查。
- Redis 状态过期： 导入任务 Redis 状态在 24 小时后自动清除。
- 分布式锁过期： 重复上传防护锁在 5 分钟后自动释放。
配置修改
- 允许的文件类型： API 端配置（PDF/TXT/Markdown/CSV/XLSX/DOCX/PNG/JPEG/WebP）。
- 最大文件大小： API 端硬编码 20MB。
- COS 预签名 URL 有效期： 上传 1 小时，下载 24 小时（知识点详情页 7 天）。
- 分块参数： Python RAG Worker 配置（512 token 块大小，64 token 重叠）。
- 嵌入模型： Python RAG Worker 配置（BAAI/bge-m3）。
- 候选生成模型： Python RAG Worker 配置（deepseek-chat，temperature 0.3）。
10. 异常与恢复
10.1 文件类型不支持
- 场景： 用户选择不支持的文件类型。
- iOS 处理： 文件选择器限制可选类型（PDF/纯文本/图片）；API 在请求上传 URL 时二次校验，返回错误。
- 用户感知： iOS 提示"不支持的文件格式"。
10.2 文件过大
- 场景： 文件超过 20MB 限制。
- iOS 处理： 图片 >2MB 自动 JPEG 压缩；非图片文件 >20MB 时 API 拒绝。
- 用户感知： API 返回文件过大错误。
10.3 COS 上传失败
- 场景： 网络问题或 COS 服务异常导致 PUT 失败。
- iOS 处理： 显示上传错误提示，用户可重试。上传使用预签名 URL，不经过 API 中转。
- API 处理： 确认上传时如果 COS 中文件不存在（headObject 失败），返回确认失败。
10.4 上传成功但 API 创建记录失败
- 场景： COS 上传成功，但确认 API 调用失败（网络中断、服务错误）。
- 结果： 文件在 COS 中存在但数据库无记录（孤儿文件）。
- 恢复： 用户重新上传（生成新的 objectKey）；Admin 可手动清理孤儿文件（file-cleanup 队列定期执行）。
10.5 导入任务失败
- 场景： Python RAG Worker 处理过程中出错（下载失败、解析失败、API 调用失败）。
- 系统处理： 自动重试最多 3 次，每次重置为 QUEUED。3 次失败后标记 FAILED_FINAL。
- 用户感知： iOS 资料详情页 AI 处理状态显示红色"失败"横幅。
- Admin 恢复： Admin 在导入监控页查看步骤日志，手动重试（不占系统重试次数）。
10.6 RAG 解析失败
- 场景： PDF 损坏、DOCX 格式异常、OCR 无法识别。
- Worker 处理： 解析阶段失败 → 任务标记 FAILED，更新 parseStatus 为 failed，记录 errorCode 和 errorMessage。
- 影响范围： 解析失败的文件无法进行后续分块、嵌入和索引。
- 恢复： Admin 触发重新解析；用户可尝试重新上传。
10.7 向量索引失败
- 场景： Qdrant 不可用、嵌入 API 调用失败。
- Worker 处理： 索引阶段失败 → 任务标记 FAILED。parseStatus 可能已 complete，但 indexStatus 为 failed。
- 影响范围： 资料可阅读但不可用于语义检索。
- 恢复： Admin 重试导入任务；系统自动重试。
10.8 重复上传
- 场景： 用户短时间内上传相同文件多次。
- API 处理： 使用 Redis 分布式锁（
lock:document-import:{fileName}:{timestamp}，5 分钟 TTL）防止并发重复导入。 - 边界： 锁只防止并发重复；用户间隔 5 分钟后仍可上传相同文件创建新的 KnowledgeSource。
10.9 用户删除处理中资料
- 场景： 用户在导入任务处理过程中删除知识源。
- API 处理： KnowledgeSource 使用软删除（设置 deletedAt）。Python RAG Worker 在处理前应检查源是否已被删除（具体行为待确认）。
- 影响： 已生成的 KnowledgeChunk 和 ImportCandidate 可能成为孤儿数据。
10.10 候选审核失败
- 场景： 接受候选时内容安全检查失败。
- API 处理： 候选标记为 BLOCKED，返回原因。用户无法强制接受。
- Admin 查看： Admin 可在候选巡检中看到 BLOCKED 状态的候选。
11. 当前完成状态
| 组件 | 状态 | 说明 |
|---|---|---|
| iOS 文件选择与上传 | 已完成 | 文件选择器 + 相册选择器 + 链接导入 |
| iOS 图片压缩 | 已完成 | >2MB 自动 JPEG 压缩 |
| iOS 上传进度展示 | 已完成 | 进度指示器 |
| iOS 候选审核界面 | 已完成 | 接受/拒绝/批量接受 |
| iOS AI 处理状态展示 | 已完成 | 资料详情页三色横幅（处理中/就绪/失败） |
| API COS 预签名 URL 上传流程 | 已完成 | 请求 URL → 直接 PUT → 确认 |
| API 文件类型与大小校验 | 已完成 | 8 种类型，最大 20MB |
| API 内容安全检查（文件名） | 已完成 | 敏感词匹配 |
| API 速率限制 | 已完成 | 文件上传端点 |
| API KnowledgeSource 创建与管理 | 已完成 | 含自动 DocumentImport 任务创建 |
| API 导入状态查询 | 已完成 | Redis 实时状态（进度+消息） |
| API 候选审核 API | 已完成 | accept/reject/batch-accept |
| Python RAG Worker 轮询与锁定 | 已完成 | 每 5 秒轮询，心跳每 30 秒 |
| Python RAG Worker 文本解析 | 已完成 | PDF/DOCX/TXT/MD/CSV/XLSX/图片 OCR |
| Python RAG Worker 分块与嵌入 | 已完成 | 递归分割 + BAAI/bge-m3 |
| Python RAG Worker 向量索引 | 已完成 | Qdrant zhixi_chunks 集合 |
| Python RAG Worker 候选生成 | 已完成 | DeepSeek 提取知识点 |
| Python RAG Worker 状态更新 | 已完成 | parseStatus/indexStatus/learningStatus |
| 导入任务自动重试 | 已完成 | 最多 3 次，过期任务自动回收 |
| Admin 文件管理 | 已完成 | 查看/删除 |
| Admin 来源文件查看 | 已完成 | 列表 + 按状态筛选 |
| Admin 导入监控 | 已完成 | 步骤日志 + 重试 |
| Admin 候选巡检 | 已完成 | 列表查看 |
| Admin 分块管理 | 已完成 | 按 sourceId 查看 |
| Admin RAG 调试 | 部分完成 | 基础向量搜索测试工具，展示原始 JSON 响应；非生产级检索调试界面 |
| 孤儿文件自动清理 | 暂未确认 | file-cleanup 队列存在但清理策略待确认 |
| 处理中删除源的行为 | 暂未确认 | Worker 是否检查软删除标志待确认 |