1481 lines
36 KiB
Markdown
1481 lines
36 KiB
Markdown
|
||
可以，现在应该把它整理成一个**分板块执行的落地方案**。你后面就不要再一直在脑子里绕了，按这个顺序推进。
|
||
|
||
# 知习知识库落地执行方案（完整版）
|
||
|
||
> 最后检查：2026-05-20 14:00 | 标记：✅ 已完成 | 🔶 部分完成 | ⏳ 待完成 | ❌ 未开始
|
||
|
||
---
|
||
|
||
## 一、服务器部署板块 ✅ 已完成
|
||
|
||
### 1. 当前服务器分工
|
||
|
||
```text
|
||
4核4G 轻量云：
|
||
主业务服务器
|
||
|
||
8核32G CVM：
|
||
知识库 / RAG / 文档处理 / AI 调度服务器
|
||
|
||
腾讯云 COS：
|
||
原始文件存储
|
||
```
|
||
|
||
### 2. 8核32G 服务器用途
|
||
|
||
这台服务器负责：
|
||
|
||
```text
|
||
Qdrant 向量库
|
||
LlamaIndex / RAG Worker
|
||
文档解析
|
||
PDF / DOCX / TXT / Markdown 处理
|
||
OCR / 多模态任务调度
|
||
chunking 切片
|
||
embedding 调用
|
||
知识库检索
|
||
AI Gateway 部分调度
|
||
DocumentImport 异步任务
|
||
KnowledgeChunk 写入
|
||
ImportCandidate 生成
|
||
```
|
||
|
||
它不负责：
|
||
|
||
```text
|
||
本地大模型推理
|
||
本地多模态大模型
|
||
GPU 任务
|
||
原始文件长期存储
|
||
```
|
||
|
||
---
|
||
|
||
## 二、服务器基础环境 ✅ 已完成
|
||
|
||
### 1. 系统配置
|
||
|
||
```text
|
||
CPU：8核
|
||
内存：32G
|
||
系统：Ubuntu Server 22.04 LTS
|
||
系统盘：40G
|
||
数据盘：70G
|
||
公网：1Mbps
|
||
地域：北京（蜂驰云）
|
||
内网 IP：172.21.0.4 ↔ 4核4G（10.2.0.7），~1.9ms 延迟
|
||
```
|
||
|
||
### 2. 数据盘挂载 ✅ 已完成
|
||
|
||
挂载到：`/data`，9 个子目录已创建
|
||
|
||
---
|
||
|
||
## 三、服务器需要安装的东西 ✅ 全部完成
|
||
|
||
### 1. 基础环境
|
||
|
||
```text
|
||
Docker ✅
|
||
Docker Compose ✅
|
||
Git ✅
|
||
Node.js ✅
|
||
pnpm ✅
|
||
Python 3.11+ ✅ (3.11.15，systemd 用 /usr/bin/python3.11)
|
||
pip / poetry ✅
|
||
nginx ✅
|
||
supervisor / systemd ✅
|
||
logrotate ✅
|
||
```
|
||
|
||
### 2. 知识库服务组件
|
||
|
||
```text
|
||
Qdrant（Docker）✅
|
||
RAG Worker（Python）✅ (systemd zhixi-worker 已启动，polling 正常)
|
||
NestJS API（Node）✅ (8核32G systemd + 4核4G Docker 双部署)
|
||
COS SDK ✅
|
||
AI Gateway ✅
|
||
OCR Provider SDK ✅ (百度 OCR AppID 7767914)
|
||
Embedding Provider SDK ✅ (硅基流动 bge-m3)
|
||
```
|
||
|
||
### 3. Python Worker 主要依赖
|
||
|
||
```text
|
||
llama-index ✅ (httpx + pymupdf 替代：parser/chunker/embedder 自实现，无需 llama-index 重量级框架)
|
||
qdrant-client ✅
|
||
pymupdf ✅
|
||
python-docx ✅
|
||
markdown ✅
|
||
pandas ✅
|
||
openpyxl ✅
|
||
pydantic ✅
|
||
httpx ✅
|
||
tencentcloud-sdk-python ✅ (httpx 直接调 COS API 替代，无需引入整个 SDK)
|
||
Pillow ✅
|
||
python-dotenv ✅
|
||
```
|
||
|
||
### 4. Node 后端主要依赖 ✅ 全部安装
|
||
|
||
```text
|
||
NestJS 11.x ✅ (@nestjs/core, common, config, jwt, passport, swagger, throttler, bullmq)
|
||
Prisma 5.22 ✅ (@prisma/client)
|
||
Redis / BullMQ ✅ (ioredis 5.10 + bullmq 5.76)
|
||
COS SDK ✅ (cos-nodejs-sdk-v5，非 AWS S3 SDK)
|
||
AI Provider ✅ (httpx 调用 DeepSeek/硅基流动)
|
||
JWT / Auth ✅ (bcryptjs + jose + passport-jwt)
|
||
class-validator ✅ 0.15.1
|
||
zod ✅ 4.4.3
|
||
helmet ✅ 8.1
|
||
```
|
||
|
||
> **语言分工：** NestJS（Node）负责 API 层 + AI Gateway + 任务入队。Python 负责 RAG Worker（文档解析、chunking、embedding、Qdrant 写入），因为 llama-index 生态在 Python 侧最成熟。两者通过 Redis/BullMQ（入队） + 内部 HTTP（heartbeat/result）通信。
|
||
|
||
---
|
||
|
||
## 四、安全组和网络 ✅ 已配置
|
||
|
||
### 1. 安全组建议
|
||
|
||
```text
|
||
22：只允许你的 IP
|
||
80 / 443：如果知识库服务需要对外访问再开
|
||
6333 / 6334：Qdrant 不开放公网
|
||
3306：MySQL 不开放公网
|
||
6379：Redis 不开放公网
|
||
```
|
||
|
||
### 2. 服务器之间通信 ✅ 内网直连
|
||
|
||
| 路径 | 方式 | 延迟 |
|
||
|------|------|------|
|
||
| 4核4G (10.2.0.7) → 8核32G (172.21.0.4) | 内网 HTTP | ~1.9ms |
|
||
| 8核32G → 4核4G Gitea (10.2.0.7:3000) | 内网 HTTP | ~1.9ms |
|
||
| 8核32G Runner → Gitea | 内网 | 已切换 |
|
||
| COS (ap-beijing) → 两台服务器 | VPC 内网端点 | 免流量费 |
|
||
|
||
> 所有服务器间通信均走内网。知识库内部接口不暴露公网。
|
||
|
||
### 3. COS 访问方式 ✅ 已实现
|
||
|
||
COS 不作为本地硬盘长期挂载。import_pipeline.py 已实现：
|
||
|
||
```text
|
||
Worker 通过 COS 预签名 URL 拉取文件
|
||
→ 临时下载到 /data/tmp/imports/{jobId}
|
||
→ 解析处理
|
||
→ 写入 Qdrant / MySQL
|
||
→ finally 块 shutil.rmtree 清理临时文件
|
||
```
|
||
|
||
COS 负责原始文件存储，服务器负责临时处理和索引。
|
||
|
||
---
|
||
|
||
## 五、COS 存储结构 ✅ Bucket 已验证，同区内网免流
|
||
|
||
核心原则：
|
||
|
||
```text
|
||
数据库是主关系，COS 是文件仓库
|
||
COS 路径按 userId / knowledgeBaseId / sourceId 分类
|
||
权限、归属、状态永远以数据库为准
|
||
不要直接用用户原文件名当 objectKey（用 fileId/sourceId 避免重名和特殊字符）
|
||
```
|
||
|
||
### 1. Bucket
|
||
|
||
第一阶段一个 bucket 就够：
|
||
|
||
```text
|
||
zhixi-prod
|
||
```
|
||
|
||
### 2. 用户知识库原始文件
|
||
|
||
```text
|
||
users/{userId}/knowledge-bases/{knowledgeBaseId}/sources/{sourceId}/original/{fileId}.{ext}
|
||
```
|
||
|
||
示例：
|
||
|
||
```text
|
||
users/user_001/knowledge-bases/kb_001/sources/src_001/original/file_001.pdf
|
||
users/user_001/knowledge-bases/kb_001/sources/src_002/original/file_002.docx
|
||
```
|
||
|
||
### 3. 解析结果
|
||
|
||
```text
|
||
users/{userId}/knowledge-bases/{knowledgeBaseId}/sources/{sourceId}/parsed/parsed.md
|
||
users/{userId}/knowledge-bases/{knowledgeBaseId}/sources/{sourceId}/parsed/metadata.json
|
||
```
|
||
|
||
`parsed.md` 保留完整解析文本，MySQL 不存全文，通过 `parsedObjectKey` 引用。
|
||
|
||
### 4. OCR / 多模态结果
|
||
|
||
```text
|
||
users/{userId}/knowledge-bases/{knowledgeBaseId}/sources/{sourceId}/processed/ocr/page_001.json
|
||
users/{userId}/knowledge-bases/{knowledgeBaseId}/sources/{sourceId}/processed/vision/page_001.json
|
||
```
|
||
|
||
早期可只保存最终 `parsed.md`，调试 OCR/多模态质量时再保存中间结果。
|
||
|
||
### 5. 用户头像与反馈
|
||
|
||
```text
|
||
users/{userId}/profile/avatar/{fileId}.{ext}
|
||
users/{userId}/feedback/{feedbackId}/screenshots/{fileId}.{ext}
|
||
```
|
||
|
||
### 6. 系统内置知识库
|
||
|
||
```text
|
||
system/knowledge-bases/{systemKnowledgeBaseId}/sources/{sourceId}/original/{fileId}.{ext}
|
||
system/knowledge-bases/{systemKnowledgeBaseId}/sources/{sourceId}/parsed/parsed.md
|
||
system/knowledge-bases/{systemKnowledgeBaseId}/sources/{sourceId}/parsed/metadata.json
|
||
```
|
||
|
||
系统知识库只存一份，用户使用系统知识库时是"引用"，不要给每个用户复制一份。
|
||
|
||
### 7. 备份（同步到 COS）
|
||
|
||
```text
|
||
system/backups/qdrant/{yyyy-mm-dd}/zhixi_chunks.snapshot
|
||
system/backups/mysql/{yyyy-mm-dd}/zhixi.sql.gz
|
||
```
|
||
|
||
### 8. 用户导出
|
||
|
||
```text
|
||
exports/users/{userId}/{exportId}/learning_report.pdf
|
||
exports/users/{userId}/{exportId}/knowledge_base_export.zip
|
||
```
|
||
|
||
### 9. 临时文件（服务器本地为主）
|
||
|
||
默认放服务器 `/data/tmp/imports`，处理完删除。如果必须放 COS：
|
||
|
||
```text
|
||
temp/imports/{importId}/original.{ext}
|
||
temp/imports/{importId}/pages/page_001.png
|
||
temp/imports/{importId}/ocr/page_001.json
|
||
```
|
||
|
||
### 10. 完整 COS 目录树
|
||
|
||
```text
|
||
zhixi-prod/
|
||
users/
|
||
{userId}/
|
||
knowledge-bases/
|
||
{knowledgeBaseId}/
|
||
sources/
|
||
{sourceId}/
|
||
original/
|
||
{fileId}.{ext}
|
||
parsed/
|
||
parsed.md
|
||
metadata.json
|
||
processed/
|
||
ocr/
|
||
page_001.json
|
||
vision/
|
||
page_001.json
|
||
profile/
|
||
avatar/
|
||
{fileId}.{ext}
|
||
feedback/
|
||
{feedbackId}/
|
||
screenshots/
|
||
{fileId}.{ext}
|
||
|
||
system/
|
||
knowledge-bases/
|
||
{systemKnowledgeBaseId}/
|
||
sources/
|
||
{sourceId}/
|
||
original/
|
||
{fileId}.{ext}
|
||
parsed/
|
||
parsed.md
|
||
metadata.json
|
||
backups/
|
||
qdrant/
|
||
{yyyy-mm-dd}/
|
||
zhixi_chunks.snapshot
|
||
mysql/
|
||
{yyyy-mm-dd}/
|
||
zhixi.sql.gz
|
||
|
||
exports/
|
||
users/
|
||
{userId}/
|
||
{exportId}/
|
||
learning_report.pdf
|
||
knowledge_base_export.zip
|
||
|
||
temp/
|
||
imports/
|
||
{importId}/
|
||
original.{ext}
|
||
|
||
public/
|
||
app-assets/
|
||
icons/
|
||
illustrations/
|
||
```
|
||
|
||
### 11. 数据库里需保存的 COS 关联字段
|
||
|
||
`files` 表：`bucket / objectKey / originalFilename / mimeType / sizeBytes / sha256 / purpose / status`
|
||
|
||
`knowledge_sources` 表：`originalObjectKey / parsedObjectKey / metadataObjectKey`
|
||
|
||
### 12. COS 生命周期
|
||
|
||
```text
|
||
软删除后保留 7 天
|
||
每天凌晨定时任务清理超期文件
|
||
```
|
||
|
||
---
|
||
|
||
## 六、知识库支持的上传格式及处理策略 ✅ Parser 代码已完成，百度 OCR 已开通
|
||
|
||
### 1. 第一阶段必须支持
|
||
|
||
```text
|
||
PDF DOCX TXT Markdown / MD
|
||
PNG JPG / JPEG WEBP HEIC
|
||
CSV XLSX
|
||
```
|
||
|
||
### 2. 详细处理策略
|
||
|
||
| 类型 | 处理方式 | 工具 |
|
||
|------|---------|------|
|
||
| TXT / Markdown | 本地解析 | Python 原生 |
|
||
| DOCX | 本地解析 | python-docx |
|
||
| 文本型 PDF | PyMuPDF 提取文本层 | pymupdf |
|
||
| 扫描 PDF（文本层为空） | 百度 OCR / Qwen3-VL 兜底 | 百度 OCR → 硅基流动 |
|
||
| 图片文字 | 百度 OCR | 百度 OCR |
|
||
| 表格截图 | Qwen3-VL 多模态 | 硅基流动 |
|
||
| 图文混排 | Qwen3-VL 多模态 | 硅基流动 |
|
||
| CSV / XLSX | 本地解析为 Markdown table | pandas / openpyxl |
|
||
| PPTX | 预留，仅提取文本 | python-pptx（后续） |
|
||
| HEIC | 先转 JPG 再处理 | Pillow |
|
||
|
||
### 3. 暂时预留
|
||
|
||
```text
|
||
音频 视频 网页抓取 压缩包批量导入
|
||
```
|
||
|
||
### 4. PDF 解析细化
|
||
|
||
```text
|
||
先尝试 PyMuPDF 提取文本层
|
||
如果文本层为空或每页文本 < 50 字符
|
||
→ 判断为扫描件
|
||
→ 走百度 OCR（普通扫描文字）
|
||
→ 复杂排版 / 教材类走 Qwen3-VL
|
||
```
|
||
|
||
---
|
||
|
||
## 七、核心数据模型 ✅ 33 张表全部建好
|
||
|
||
### 1. File
|
||
|
||
```text
|
||
files
|
||
- id
|
||
- userId
|
||
- bucket
|
||
- objectKey
|
||
- originalFilename
|
||
- mimeType
|
||
- sizeBytes
|
||
- sha256 ← 用于重复文件检测
|
||
- purpose
|
||
- status
|
||
- createdAt
|
||
- updatedAt
|
||
- deletedAt
|
||
```
|
||
|
||
重复文件检测逻辑：同一用户、同一知识库内 sha256 重复 → 提示用户"该文件已存在"，允许取消 / 引用已有文件 / 仍然新增。
|
||
|
||
### 2. KnowledgeBase
|
||
|
||
```text
|
||
knowledge_bases
|
||
- id
|
||
- userId
|
||
- title
|
||
- description
|
||
- icon
|
||
- coverColor
|
||
- visibility ← 先预留，第一阶段默认 private
|
||
- status
|
||
- itemCount
|
||
- sourceCount
|
||
- storageUsedBytes
|
||
- lastImportedAt
|
||
- lastStudiedAt
|
||
- createdAt
|
||
- updatedAt
|
||
- deletedAt
|
||
```
|
||
|
||
### 3. KnowledgeSource
|
||
|
||
```text
|
||
knowledge_sources
|
||
- id
|
||
- userId
|
||
- knowledgeBaseId
|
||
- fileId
|
||
- type
|
||
- title
|
||
- originalFilename
|
||
- mimeType
|
||
- sizeBytes
|
||
- textLength
|
||
- parseStatus
|
||
- indexStatus
|
||
- learningStatus
|
||
- parsedObjectKey
|
||
- version ← 预留，默认 1
|
||
- parentSourceId ← 预留（版本链）
|
||
- replacedBySourceId ← 预留（被哪个新版本替代）
|
||
- errorCode
|
||
- errorMessage
|
||
- createdAt
|
||
- updatedAt
|
||
- deletedAt
|
||
```
|
||
|
||
### 4. DocumentImport
|
||
|
||
```text
|
||
document_imports
|
||
- id
|
||
- userId
|
||
- knowledgeBaseId
|
||
- sourceId
|
||
- status
|
||
- step
|
||
- progress ← 0~100
|
||
- workerId
|
||
- retryCount ← 新增
|
||
- maxRetries ← 新增，默认 3
|
||
- heartbeatAt
|
||
- errorCode
|
||
- errorMessage
|
||
- startedAt
|
||
- completedAt
|
||
- createdAt
|
||
- updatedAt
|
||
```
|
||
|
||
状态机：
|
||
|
||
```text
|
||
QUEUED
|
||
CLAIMED
|
||
DOWNLOADING
|
||
PARSING
|
||
OCR_PROCESSING
|
||
VISION_PROCESSING
|
||
CLEANING
|
||
CHUNKING
|
||
EMBEDDING
|
||
INDEXING
|
||
GENERATING_CANDIDATES
|
||
WAITING_CONFIRM
|
||
COMPLETED
|
||
FAILED_RETRYABLE
|
||
FAILED_FINAL
|
||
CANCELED
|
||
```
|
||
|
||
**Heartbeat 机制：** Worker 每 30 秒上报一次。超过 5 分钟无 heartbeat → 状态回退 QUEUED + workerId 清空 + retryCount +1。
|
||
|
||
**Stale Job Recovery（定时任务，每分钟）：**
|
||
|
||
```sql
|
||
UPDATE document_imports
|
||
SET status = 'QUEUED', workerId = NULL
|
||
WHERE status IN ('CLAIMED', 'DOWNLOADING', 'PARSING', 'OCR_PROCESSING',
|
||
'VISION_PROCESSING', 'CLEANING', 'CHUNKING', 'EMBEDDING',
|
||
'INDEXING', 'GENERATING_CANDIDATES')
|
||
AND heartbeatAt < NOW() - INTERVAL 5 MINUTE;
|
||
```
|
||
|
||
### 5. KnowledgeChunk
|
||
|
||
```text
|
||
knowledge_chunks
|
||
- id
|
||
- userId
|
||
- knowledgeBaseId
|
||
- sourceId
|
||
- content
|
||
- chunkIndex
|
||
- pageNumber
|
||
- sectionTitle
|
||
- tokenCount
|
||
- externalVectorId ← Qdrant point ID
|
||
- embeddingModel ← 'bge-m3'
|
||
- embeddingStatus ← PENDING / COMPLETED / FAILED
|
||
- metadataJson ← { overlapWith, chunkType, ... }
|
||
- createdAt
|
||
- updatedAt
|
||
- deletedAt
|
||
```
|
||
|
||
### 6. ImportCandidate
|
||
|
||
```text
|
||
import_candidates
|
||
- id
|
||
- userId
|
||
- knowledgeBaseId
|
||
- sourceId
|
||
- importId
|
||
- title
|
||
- summary
|
||
- content
|
||
- tagsJson
|
||
- recallQuestionsJson
|
||
- sourceTextSnippet
|
||
- sourceChunkIds ← 新增：关联哪些 chunk
|
||
- confidence ← 0.0 ~ 1.0
|
||
- difficulty ← 新增：easy / medium / hard
|
||
- orderIndex
|
||
- status ← PENDING / ACCEPTED / REJECTED / EDITED / IMPORTED
|
||
- createdAt
|
||
- updatedAt
|
||
```
|
||
|
||
生成规则（已拍板）：
|
||
|
||
```text
|
||
每 2000 中文字生成 1~2 个候选
|
||
单个 source 上限 30 个
|
||
最少生成 3 个（即使文档很短）
|
||
第一阶段不自动接受，全部 PENDING 等用户确认
|
||
```
|
||
|
||
### 7. KnowledgeItem
|
||
|
||
```text
|
||
knowledge_items
|
||
- id
|
||
- userId
|
||
- knowledgeBaseId
|
||
- sourceId
|
||
- importId
|
||
- title
|
||
- summary
|
||
- content
|
||
- tagsJson
|
||
- sourceType
|
||
- masteryLevel
|
||
- sourceDeleted ← 新增：原资料是否已删除
|
||
- sourceTitleSnapshot ← 新增：原资料标题快照
|
||
- sourceSnippetSnapshot ← 新增：原引用片段快照
|
||
- createdAt
|
||
- updatedAt
|
||
- deletedAt
|
||
```
|
||
|
||
### 8. MembershipPlan
|
||
|
||
```text
|
||
membership_plans
|
||
- id
|
||
- code ← FREE / PRO_TEST / PRO
|
||
- name
|
||
- priceMonthly ← 单位：分（避免浮点），配置化可随时调
|
||
- priceYearly
|
||
- maxKnowledgeBases
|
||
- maxStorageBytes
|
||
- maxFileSizeBytes
|
||
- monthlyOcrPages
|
||
- monthlyVisionPages
|
||
- monthlyChatCount
|
||
- monthlyAiAnalysisCount
|
||
- monthlyRecallCount
|
||
- monthlyCardGenCount
|
||
- isActive
|
||
- createdAt
|
||
- updatedAt
|
||
```
|
||
|
||
价格不写死在代码里，后端只认 planId + quotaConfig。第一阶段先用 28 元/月作为 Pro 预设，跑 1 个月真实成本后再正式确定价格和额度。
|
||
|
||
### 9. BackupJob
|
||
|
||
```text
|
||
backup_jobs
|
||
- id
|
||
- type ← QDRANT / MYSQL
|
||
- status ← RUNNING / COMPLETED / FAILED
|
||
- localPath
|
||
- cosObjectKey
|
||
- fileSizeBytes
|
||
- startedAt
|
||
- completedAt
|
||
- errorMessage
|
||
- createdAt
|
||
```
|
||
|
||
---
|
||
|
||
## 八、Chunking 切片策略（已拍板）✅ chunker.py 已实现
|
||
|
||
### 1. 默认参数
|
||
|
||
```text
|
||
chunk_size = 512 tokens
|
||
overlap = 64 tokens（~12%）
|
||
策略 = 递归字符分割 + 中文分句保护
|
||
```
|
||
|
||
### 2. 分文档类型规则
|
||
|
||
| 文档类型 | 切片方式 |
|
||
|---------|---------|
|
||
| Markdown | 优先按 `#` / `##` / `###` 标题分层切片 |
|
||
| PDF | 保留 pageNumber，在段落边界切 |
|
||
| DOCX | 按标题 / 段落层级切 |
|
||
| 表格 | **整表保留**，不强行切碎 |
|
||
| 代码块 | **整块保留** |
|
||
| 公式附近 | 公式 + 上下文保留在同一 chunk |
|
||
| 普通文本 | 512 tokens |
|
||
| 复杂解释型段落 | 允许扩展到 768 tokens |
|
||
|
||
### 3. 注入每个 chunk 的元数据
|
||
|
||
```text
|
||
sourceId
|
||
pageNumber
|
||
sectionTitle
|
||
chunkIndex
|
||
chunkType（text / table / code / formula）
|
||
```
|
||
|
||
---
|
||
|
||
## 九、Qdrant 设计（已拍板）✅ 已部署运行
|
||
|
||
### 1. 部署参数
|
||
|
||
```text
|
||
部署模式：单节点 Docker
|
||
Collection：zhixi_chunks
|
||
vector_size：1024
|
||
distance：Cosine
|
||
```
|
||
|
||
### 2. Collection 创建参数
|
||
|
||
```json
|
||
{
|
||
"vectors": {
|
||
"size": 1024,
|
||
"distance": "Cosine"
|
||
},
|
||
"shard_number": 1,
|
||
"replication_factor": 1,
|
||
"hnsw_config": {
|
||
"m": 16,
|
||
"ef_construct": 100
|
||
},
|
||
"optimizers_config": {
|
||
"default_segment_number": 2
|
||
},
|
||
"on_disk_payload": true
|
||
}
|
||
```
|
||
|
||
> **注意：** 单节点不要设 `replication_factor = 2`，没有意义且浪费资源。
|
||
|
||
### 3. Payload
|
||
|
||
```json
|
||
{
|
||
"userId": "user_xxx",
|
||
"knowledgeBaseId": "kb_xxx",
|
||
"sourceId": "src_xxx",
|
||
"chunkId": "chunk_xxx",
|
||
"pageNumber": 3,
|
||
"sectionTitle": "章节标题",
|
||
"deleted": false
|
||
}
|
||
```
|
||
|
||
### 4. Payload 索引（必须建）
|
||
|
||
```text
|
||
userId → keyword index
|
||
knowledgeBaseId → keyword index
|
||
sourceId → keyword index
|
||
chunkId → keyword index
|
||
deleted → bool index
|
||
```
|
||
|
||
### 5. 检索过滤
|
||
|
||
每次检索必须带：
|
||
|
||
```text
|
||
userId = 当前用户
|
||
knowledgeBaseId = 当前知识库
|
||
deleted = false
|
||
```
|
||
|
||
### 6. 备份策略（已拍板：本地 + 同步 COS）
|
||
|
||
```text
|
||
每日凌晨 3 点生成 Qdrant snapshot → /data/backups/qdrant/
|
||
生成后上传到 COS → system/backups/qdrant/{yyyy-mm-dd}/zhixi_chunks.snapshot
|
||
本地保留最近 7 天
|
||
COS 保留最近 30 天
|
||
```
|
||
|
||
恢复依赖链：COS 原始文件 + MySQL 元数据 + Qdrant 快照 → 三者共同保证可恢复。
|
||
|
||
### 7. Qdrant 集群迁移时机
|
||
|
||
```text
|
||
第一阶段：单节点 Qdrant，1 shard，replication_factor = 1
|
||
```
|
||
|
||
迁移触发条件（任一满足即评估）：
|
||
|
||
```text
|
||
collection 超过 100 万 points
|
||
Qdrant 内存长期超过 70%
|
||
检索 p95 延迟超过 1.5 秒
|
||
snapshot / restore 时间过长
|
||
```
|
||
|
||
迁移路径：
|
||
|
||
```text
|
||
阶段 1：单节点 Qdrant（现在）
|
||
阶段 2：当前服务器加数据盘
|
||
阶段 3：Qdrant 独立迁移到新服务器
|
||
阶段 4：Qdrant 集群
|
||
```
|
||
|
||
---
|
||
|
||
## 十、Embedding & Rerank（已拍板）✅ 硅基流动 Key 已配置
|
||
|
||
### 1. Embedding
|
||
|
||
```text
|
||
模型：BAAI/bge-m3
|
||
Provider：硅基流动
|
||
维度：1024
|
||
Batch size：50~100 chunks / 批次
|
||
```
|
||
|
||
注意：不要一个大文档全塞进一次 embedding 调用，分批处理。单批失败只重试该批，不重跑全部。
|
||
|
||
备选降级（如果 bge-m3 成本或速度不理想）：
|
||
|
||
```text
|
||
→ 切到 bge-large-zh-v1.5（同样 1024d）
|
||
```
|
||
|
||
但第一版先统一用 bge-m3，不要同时支持多个 embedding 模型。
|
||
|
||
### 2. Rerank
|
||
|
||
```text
|
||
模型：BAAI/bge-reranker-v2-m3
|
||
Provider：硅基流动
|
||
输入：query + Top-50 候选 chunks
|
||
输出：精排 Top-5~8
|
||
```
|
||
|
||
---
|
||
|
||
## 十一、RAG 检索流程（已拍板）✅ 全链路已验证通过
|
||
|
||
```text
|
||
用户提问
|
||
→ 生成 query embedding（bge-m3）
|
||
→ Qdrant ANN 召回 Top-50（带 userId/kbId/deleted 过滤）
|
||
→ bge-reranker-v2-m3 精排
|
||
→ 取 Top-5（普通问题）~ Top-8（复杂问题）
|
||
→ 拼接 context
|
||
→ DeepSeek 生成回答 + 引用溯源
|
||
```
|
||
|
||
### Context 拼接格式
|
||
|
||
```text
|
||
[来源：{sourceTitle}，章节：{sectionTitle}，第 {pageNumber} 页]
|
||
{chunkContent}
|
||
```
|
||
|
||
### 知识库对话多轮策略
|
||
|
||
第一阶段：
|
||
|
||
```text
|
||
保存 chat session + messages：✅ 客户端管理，API 接收 history 参数
|
||
取最近 3 轮对话拼入 prompt：✅ 最近 10 条历史注入上下文
|
||
根据历史重写检索 query：❌ 后面再做
|
||
通用 AI 问答（非知识库内容）：❌ 第一阶段不支持
|
||
```
|
||
|
||
检索 query 仍使用用户当前原问题，但 prompt 上下文附带最近多轮历史。API 端点 `POST /api/rag/chat` 接受可选 `history` 参数。
|
||
|
||
当检索不到相关内容时返回：
|
||
|
||
```text
|
||
知识库中暂无相关内容，请先导入文档。
|
||
```
|
||
|
||
知习第一阶段只做**基于当前知识库内容的 RAG 问答**，不做纯通用 AI 对话。避免产品定位偏离、增加无意义 token 成本和用户把它当 ChatGPT 用。
|
||
|
||
---
|
||
|
||
## 十二、AI Provider 策略 ✅ 三大 Provider 全部配置完毕
|
||
|
||
### 1. DeepSeek 官方 — 核心文本智能
|
||
|
||
```text
|
||
知识点提取 默认 V4 Flash（非思考）
|
||
摘要 / 标签 默认 V4 Flash
|
||
主动回忆题 默认 V4 Flash
|
||
复习卡生成 默认 V4 Flash
|
||
知识库问答 默认 V4 Flash
|
||
主动回忆诊断 V4 Flash thinking
|
||
待巩固项分析 V4 Flash thinking
|
||
学习报告 V4 Flash thinking
|
||
高价值深度分析 V4 Pro
|
||
```
|
||
|
||
### 2. 硅基流动 — 工具模型
|
||
|
||
```text
|
||
Qwen3-VL 多模态 Qwen/Qwen3-VL-32B-Instruct
|
||
复杂视觉兜底 Qwen/Qwen3-VL-32B-Thinking
|
||
embedding BAAI/bge-m3
|
||
rerank BAAI/bge-reranker-v2-m3
|
||
备用模型池 营销 / 客服 / 润色测试
|
||
```
|
||
|
||
### 3. 百度 OCR
|
||
|
||
```text
|
||
普通扫描文字
|
||
图片文字
|
||
截图文字
|
||
→ 复杂页面不要用 OCR 硬识别，交给 Qwen3-VL
|
||
```
|
||
|
||
---
|
||
|
||
## 十三、AI Gateway ✅ 三层架构已落地
|
||
|
||
所有 AI 调用必须走 AI Gateway。负责：
|
||
|
||
```text
|
||
模型路由
|
||
Prompt 版本管理
|
||
JSON Schema 校验
|
||
失败重试 + 超时控制
|
||
token 统计 + 成本估算
|
||
AIUsageLog
|
||
会员额度扣减
|
||
模型降级
|
||
```
|
||
|
||
业务模块只调用：
|
||
|
||
```text
|
||
AIGateway.run("extract_knowledge_candidates")
|
||
AIGateway.run("analyze_active_recall")
|
||
AIGateway.run("knowledge_chat")
|
||
AIGateway.run("parse_complex_page")
|
||
AIGateway.run("embed_chunks")
|
||
AIGateway.run("rerank_chunks")
|
||
```
|
||
|
||
---
|
||
|
||
## 十四、Worker 部署与并发控制 ✅ 部署完成
|
||
|
||
### 1. 进程数与并发（已拍板：单 Worker 起步）
|
||
|
||
- ✅ 代码：10 个文件全部到位
|
||
- ✅ systemd：zhixi-worker.service enabled active
|
||
- ✅ pip 依赖：28+ packages 全部安装
|
||
```
|
||
|
||
8 核 32G 服务器起步并发：
|
||
|
||
```text
|
||
文档导入并发 1
|
||
embedding batch 50~100 chunks
|
||
OCR 并发 1~2
|
||
多模态并发 1
|
||
候选知识点生成并发 1~2
|
||
```
|
||
|
||
原因：文档解析、embedding、OCR、多模态、Qdrant upsert 都可能吃 CPU/内存/网络。先稳，再提并发。
|
||
|
||
### 2. 扩展条件
|
||
|
||
```text
|
||
CPU 长期低于 50%
|
||
内存长期低于 60%
|
||
任务队列积压明显
|
||
```
|
||
|
||
满足以上 → 扩展到 2~3 Worker 进程。多 Worker 时靠数据库原子更新防止重复处理：
|
||
|
||
```sql
|
||
UPDATE document_imports
|
||
SET status = 'CLAIMED', workerId = ?, heartbeatAt = NOW()
|
||
WHERE id = ?
|
||
AND status = 'QUEUED';
|
||
```
|
||
|
||
### 3. 各环节重试策略
|
||
|
||
| 环节 | 重试次数 | 退避策略 | 失败后行为 |
|
||
|------|---------|---------|-----------|
|
||
| COS 下载 | 3 次 | 指数退避 1s/4s/16s | FAILED_RETRYABLE |
|
||
| OCR API | 2 次 | 固定 2s | 降级到多模态 |
|
||
| 多模态 API | 2 次 | 固定 2s | FAILED_RETRYABLE |
|
||
| Embedding batch | 2 次 | 固定 2s | 只重试该 batch |
|
||
| Qdrant upsert | 2 次 | 固定 2s | 回滚该 batch |
|
||
| Worker 崩溃 | — | heartbeat 超时 5min | 自动回队列 |
|
||
| DeepSeek 调用 | 2 次 | 固定 1s | FAILED_RETRYABLE |
|
||
|
||
### 2. 最大重试
|
||
|
||
```text
|
||
maxRetries = 3
|
||
超过 → FAILED_FINAL
|
||
→ 通知用户（iOS 解析失败页）
|
||
→ 后台告警
|
||
```
|
||
|
||
---
|
||
|
||
## 十五、删除与清理策略（已拍板）✅ Prisma schema 已含 soft delete + 保留天数配置
|
||
|
||
### 1. 删除单个 KnowledgeSource
|
||
|
||
```text
|
||
source.deletedAt = now()
|
||
chunks.deletedAt = now()
|
||
Qdrant points → deleted = true（不物理删除）
|
||
COS 原文件 → 进入待清理队列（7 天后清除）
|
||
KnowledgeItem → 默认保留
|
||
```
|
||
|
||
用户已确认、编辑、学习过的知识点，不应因删除原文件而丢失。KnowledgeItem 记录来源状态：
|
||
|
||
```text
|
||
knowledge_items.sourceDeleted = true
|
||
knowledge_items.sourceTitleSnapshot = 原资料标题
|
||
knowledge_items.sourceSnippetSnapshot = 原始引用片段
|
||
```
|
||
|
||
这样即使原资料被删，知识点页仍能展示"该知识点来自已删除资料"。
|
||
|
||
### 2. 用户删除 source 时给两个选项
|
||
|
||
```text
|
||
默认：仅删除原资料，保留已确认知识点
|
||
高级：同时删除该资料生成的知识点
|
||
```
|
||
|
||
### 3. 删除整个 KnowledgeBase（与人不同）✅ 已实现
|
||
|
||
```text
|
||
knowledgeBase.deletedAt = now()
|
||
→ KnowledgeItems (soft delete)
|
||
→ ImportCandidates (hard delete)
|
||
→ KnowledgeChunks (soft delete)
|
||
→ DocumentImports (status→CANCELLED)
|
||
→ KnowledgeSources (soft delete)
|
||
→ Qdrant vectors (delete by filter)
|
||
→ COS 异步清理（待配）
|
||
```
|
||
|
||
用户删除的是整个学习空间，所以级联删除。`KnowledgeBaseService.remove()` 已实现。
|
||
|
||
### 4. 后台物理清理（每日凌晨）
|
||
|
||
数据保留天数全部配置化（环境变量）：
|
||
|
||
```text
|
||
DATA_RETENTION_DAYS=30 ← 普通业务数据物理删除
|
||
SOURCE_PURGE_DAYS=7 ← COS 原文件物理删除
|
||
QDRANT_PURGE_DAYS=7 ← Qdrant deleted=true 点物理删除
|
||
COS_PURGE_DAYS=7 ← COS 标记删除文件物理删除
|
||
AI_USAGE_LOG_RETENTION_DAYS=180 ← AI 成本日志保留更久
|
||
ADMIN_AUDIT_RETENTION_DAYS=365 ← 审计日志保留更久
|
||
```
|
||
|
||
规则：
|
||
|
||
```text
|
||
普通业务数据 soft delete 后 30 天物理删除
|
||
COS 原文件 soft delete 后 7 天物理删除
|
||
Qdrant deleted=true 后 7 天物理删除
|
||
AI 成本日志保留 180 天
|
||
后台操作审计日志保留 365 天
|
||
用户学习记录 / 支付记录不要跟普通 source 一起快速物理删除
|
||
```
|
||
|
||
---
|
||
|
||
## 十六、备份与灾备策略（已拍板）🔶 本地备份完成，COS 同步待配
|
||
|
||
### 1. MySQL 备份
|
||
|
||
```text
|
||
优先级最高：MySQL > Qdrant > COS
|
||
```
|
||
|
||
```text
|
||
✅ 每日凌晨 3 点 mysqldump → /data/backups/mysql/zhixi_{yyyy-mm-dd}.sql.gz
|
||
⏳ 备份后上传 COS → system/backups/mysql/{yyyy-mm-dd}/zhixi.sql.gz
|
||
✅ 本地保留 7 天
|
||
⏳ COS 保留 30 天
|
||
```
|
||
|
||
### 2. Qdrant 备份
|
||
|
||
```text
|
||
✅ 每日凌晨 3 点生成 snapshot → /data/backups/qdrant/
|
||
⏳ 生成后上传 COS → system/backups/qdrant/{yyyy-mm-dd}/zhixi_chunks.snapshot
|
||
✅ 本地保留 7 天
|
||
⏳ COS 保留 30 天
|
||
```
|
||
|
||
### 3. 备份脚本
|
||
|
||
✅ `/opt/zhixi/backup/backup.sh` 已部署，cron `0 3 * * *`，首次手动执行成功（MySQL 8K + Qdrant 284K）。
|
||
|
||
### 4. 恢复依赖链
|
||
|
||
```text
|
||
COS 原始文件 + MySQL 元数据 + Qdrant 快照 → 三者共同保证可恢复
|
||
```
|
||
|
||
---
|
||
|
||
## 十七、文档版本管理 ✅ 预留字段已建表，第一阶段不做完整版本管理
|
||
|
||
第一阶段不做完整版本管理，但预留字段：
|
||
|
||
```text
|
||
KnowledgeSource.version = 1
|
||
KnowledgeSource.parentSourceId = nullable
|
||
KnowledgeSource.replacedBySourceId = nullable
|
||
```
|
||
|
||
当前行为：用户重新上传同名文件 → 按新 source 独立处理。
|
||
|
||
后续升级：新版本 ready → 旧版本 Qdrant 标记 deleted=true → 旧版本 COS 保留 7 天。
|
||
|
||
---
|
||
|
||
## 十八、后台管理 ⏳ 待开发
|
||
|
||
后台要能看：
|
||
|
||
```text
|
||
用户列表
|
||
知识库列表
|
||
文件列表
|
||
DocumentImport 任务（按状态筛选）
|
||
失败任务（含错误原因）
|
||
OCR 调用记录（按用户、按时间）
|
||
多模态调用记录
|
||
DeepSeek 调用记录
|
||
AI 成本（按 Provider 汇总）
|
||
Qdrant 索引状态（collection 大小、points 数量）
|
||
高成本用户 Top N
|
||
会员额度使用情况
|
||
反馈记录
|
||
后台操作审计
|
||
```
|
||
|
||
核心目标是**成本可视化和异常发现**。
|
||
|
||
---
|
||
|
||
## 十九、额度系统 ⏳ 表已建（membership_plans + quota_usage），检查逻辑待实现
|
||
|
||
### 1. 必须控制的维度
|
||
|
||
```text
|
||
知识库数量
|
||
总存储空间
|
||
单文件大小
|
||
每月上传文件数
|
||
每月普通解析页数
|
||
每月 OCR 页数
|
||
每月多模态页数
|
||
每月知识库对话次数
|
||
每月 AI 分析次数
|
||
每月主动回忆次数
|
||
每月复习卡生成次数
|
||
```
|
||
|
||
### 2. 检查点（每次调用前）
|
||
|
||
```text
|
||
上传前 → 存储 + 数量
|
||
解析前 → 页数
|
||
OCR 前 → OCR 页数
|
||
多模态前 → 多模态页数
|
||
知识点生成前 → AI 分析次数
|
||
知识库对话前 → 对话次数
|
||
AI 诊断前 → AI 分析次数
|
||
复习卡生成前 → 复习卡次数
|
||
```
|
||
|
||
### 3. 推荐初始额度（已拍板：配置化，随时可调）
|
||
|
||
| 维度 | 免费用户 | Pro 用户 |
|
||
|------|---------|---------|
|
||
| 知识库数量 | 3 个 | 30 个 |
|
||
| 总存储 | 100 MB | 5 GB |
|
||
| 单文件大小 | 20 MB | 100 MB |
|
||
| 每月 OCR 页数 | 20 页 | 500 页 |
|
||
| 每月多模态页数 | 5 页 | 100 页 |
|
||
| 每月知识库对话 | 20 次 | 1000 次 |
|
||
| 每月 AI 诊断 | 20 次 | 500 次 |
|
||
|
||
### 4. 定价策略
|
||
|
||
```text
|
||
价格不写死在代码里，后端只认 planId + quotaConfig
|
||
第一阶段按 28 元/月作为 Pro 预设
|
||
跑 1 个月真实成本后正式确定价格和额度
|
||
重点记录：DeepSeek token 成本 / 硅基流动视觉成本 / 百度 OCR 页数 / COS 存储 / Qdrant 增长 / 高成本用户行为
|
||
```
|
||
|
||
---
|
||
|
||
## 二十、核心接口设计 ✅ 内部 RAG API (7 端点) + KnowledgeSource + ImportCandidate 已实现
|
||
|
||
### 1. 文件上传
|
||
|
||
```http
|
||
POST /api/files/upload-url
|
||
```
|
||
|
||
返回：
|
||
|
||
```json
|
||
{
|
||
"fileId": "file_xxx",
|
||
"uploadUrl": "...",
|
||
"objectKey": "...",
|
||
"headers": {},
|
||
"duplicateOf": null
|
||
}
|
||
```
|
||
|
||
如果 sha256 匹配到已有文件，返回 `duplicateOf` 指向已有 fileId，iOS 提示用户。
|
||
|
||
### 2. 知识库 CRUD
|
||
|
||
```http
|
||
POST /api/knowledge-bases
|
||
GET /api/knowledge-bases
|
||
GET /api/knowledge-bases/:id
|
||
PATCH /api/knowledge-bases/:id
|
||
DELETE /api/knowledge-bases/:id
|
||
```
|
||
|
||
### 3. 资料来源
|
||
|
||
```http
|
||
POST /api/knowledge-bases/:id/sources
|
||
GET /api/knowledge-bases/:id/sources
|
||
GET /api/knowledge-sources/:sourceId
|
||
DELETE /api/knowledge-sources/:sourceId
|
||
```
|
||
|
||
创建 source 后自动生成 KnowledgeSource + DocumentImport。
|
||
|
||
### 4. 导入任务
|
||
|
||
```http
|
||
GET /api/document-imports/:id
|
||
GET /api/knowledge-sources/:sourceId/imports/latest
|
||
POST /api/document-imports/:id/retry
|
||
POST /api/document-imports/:id/cancel
|
||
```
|
||
|
||
iOS 用这些接口展示导入进度（排队中 → 解析中 → 索引中 → 生成知识点中 → 等待确认 → 完成 / 失败可重试）。
|
||
|
||
### 5. Worker 内部接口
|
||
|
||
```http
|
||
GET /internal/rag/jobs/next
|
||
POST /internal/rag/jobs/:id/heartbeat
|
||
POST /internal/rag/jobs/:id/result
|
||
POST /internal/rag/jobs/:id/fail
|
||
```
|
||
|
||
### 6. 候选知识点
|
||
|
||
```http
|
||
GET /api/knowledge-sources/:sourceId/import-candidates
|
||
PATCH /api/import-candidates/:id
|
||
POST /api/import-candidates/:id/accept
|
||
POST /api/import-candidates/:id/reject
|
||
POST /api/import-candidates/batch-accept
|
||
```
|
||
|
||
用户确认后生成 KnowledgeItem。
|
||
|
||
### 7. 正式知识点
|
||
|
||
```http
|
||
GET /api/knowledge-bases/:id/items
|
||
GET /api/knowledge-items/:id
|
||
POST /api/knowledge-items ← 手动创建
|
||
PATCH /api/knowledge-items/:id
|
||
DELETE /api/knowledge-items/:id
|
||
```
|
||
|
||
### 8. 知识库对话
|
||
|
||
```http
|
||
POST /api/knowledge-bases/:id/chat
|
||
GET /api/knowledge-bases/:id/chat-sessions
|
||
GET /api/knowledge-chat-sessions/:id/messages
|
||
```
|
||
|
||
返回：
|
||
|
||
```json
|
||
{
|
||
"answer": "...",
|
||
"citations": [
|
||
{
|
||
"sourceId": "src_xxx",
|
||
"chunkId": "chunk_xxx",
|
||
"title": "资料标题",
|
||
"snippet": "引用片段",
|
||
"pageNumber": 3
|
||
}
|
||
],
|
||
"suggestedActions": [
|
||
"CREATE_KNOWLEDGE_ITEM",
|
||
"GENERATE_ACTIVE_RECALL",
|
||
"ADD_TO_FOCUS_ITEM"
|
||
]
|
||
}
|
||
```
|
||
|
||
### 9. 单文件学习
|
||
|
||
```http
|
||
POST /api/knowledge-sources/:sourceId/prepare-learning
|
||
GET /api/knowledge-sources/:sourceId/learning-view
|
||
POST /api/knowledge-items/:id/active-recall
|
||
POST /api/active-recall-answers/:id/analyze
|
||
GET /api/knowledge-items/:id/review-cards
|
||
```
|
||
|
||
流程：
|
||
|
||
```text
|
||
source → ImportCandidate → KnowledgeItem
|
||
→ ActiveRecall → AIAnalysis → FocusItem → ReviewCard
|
||
```
|
||
|
||
---
|
||
|
||
## 二十一、知识库主流程 ✅ 全链路已验证通过
|
||
|
||
### 1. 索引流程 ✅
|
||
|
||
测试验证（raw text 导入）✅：
|
||
```text
|
||
POST /api/imports (raw text)
|
||
→ NestJS DocumentImportWorker 入队 ✅
|
||
→ chunking（512 tokens + 64 overlap）✅ 4 chunks
|
||
→ embedding（bge-m3，batch 50）✅
|
||
→ Qdrant upsert ✅ 4 points
|
||
→ KnowledgeChunk MySQL 写入 ✅
|
||
→ ImportCandidate 生成（DeepSeek）✅ 3 candidates
|
||
→ KB.itemCount 更新 ✅
|
||
→ import.status = COMPLETED ✅
|
||
→ ⬜ COS 文件上传路径（待 iOS 真文件）
|
||
→ ⬜ OCR / 多模态（parser 代码已就，待真文件触发）
|
||
```
|
||
|
||
### 2. 学习流程
|
||
|
||
```text
|
||
用户打开文件
|
||
→ DeepSeek 生成 ImportCandidate（上限 30 条）
|
||
→ 用户确认 / 编辑 / 拒绝
|
||
→ 生成 KnowledgeItem
|
||
→ 用户主动回忆
|
||
→ DeepSeek 诊断（thinking 模式）
|
||
→ 生成 FocusItem（待巩固项）
|
||
→ 生成 ReviewCard（复习卡）
|
||
→ 记录 LearningActivity
|
||
```
|
||
|
||
---
|
||
|
||
## 二十二、iOS 需要的页面 ⏳ 设计完成，待 iOS 实现
|
||
|
||
### 知识库相关
|
||
|
||
```text
|
||
知识库列表页
|
||
知识库详情页
|
||
创建知识库页
|
||
上传资料页
|
||
资料列表页
|
||
资料详情页
|
||
导入进度页（含步骤+进度条）
|
||
解析失败页（含错误原因+重试按钮）
|
||
候选知识点确认页（批量接受/拒绝/编辑）
|
||
知识点详情页
|
||
知识库对话页
|
||
```
|
||
|
||
### 学习相关
|
||
|
||
```text
|
||
单文件学习首页
|
||
主动回忆输入页
|
||
AI 分析结果页
|
||
待巩固项页
|
||
复习卡页
|
||
学习记录页
|
||
```
|
||
|
||
### 额度相关
|
||
|
||
```text
|
||
额度展示页
|
||
会员升级页
|
||
OCR / 多模态额度提示
|
||
文件过大提示
|
||
解析额度不足提示
|
||
重复文件提示
|
||
```
|
||
|
||
---
|
||
|
||
## 二十三、执行顺序（状态更新）
|
||
|
||
### 第一阶段：服务器基础 ✅ 已完成
|
||
### 第二阶段：基础数据模型 ✅ 已完成（35 张表全部建好）
|
||
### 第三阶段：文件导入闭环 ✅ NestJS Worker 完整流水线、Python Worker 轮询就绪
|
||
### 第四阶段：RAG 索引 ✅ RAG chat + 多轮对话接口已验证
|
||
### 第五阶段：AI 学习化 ✅ 全链路补齐
|
||
|
||
NestJS DocumentImportWorker 完整流水线：
|
||
```
|
||
raw text → ChunkingService (512t/64overlap) → VectorService (bge-m3 + Qdrant UUID + MySQL)
|
||
→ ImportCandidate 生成 → KB.itemCount 更新
|
||
```
|
||
验证：4 chunks + 3 candidates + Qdrant 11 points + itemCount=3 ✅
|
||
|
||
### 第六阶段：单文件学习 🔶 模块已建，待端到端对接
|
||
|
||
ActiveRecallController / AiAnalysisController / FocusItemsController / ReviewController / LearningSessionController 已全部实现，Workflow 层（active-recall-analysis / feynman-evaluation / learning-trend / review-card-generation）已到位，AiAnalysisWorker 异步处理已就绪。
|
||
|
||
**缺：** 从 KnowledgeItem → 开始学习 → 主动回忆 → AI 诊断 → 待巩固项 → 复习卡的完整串联流程未跑通过。
|
||
|
||
### 第七阶段：知识库增强 ⏳ 待开发
|
||
|
||
- Chat session 持久化（当前 history 由客户端管理，无服务端 session 存储）
|
||
- 知识库对话 session 列表 API
|
||
- 文件上传 COS 真文件测试（待 iOS 端触发）
|
||
|
||
---
|
||
|
||
## 二十四、最终落地原则
|
||
|
||
```text
|
||
COS 存原始文件 → 检索前临时拉取，不留本地
|
||
Qdrant 存向量索引 → 单节点，1024d Cosine，deleted 标记而非物理删除
|
||
MySQL 存业务状态 → Prisma ORM，软删除 + 后台清理
|
||
DeepSeek 负责核心文本智能 → Flash 日常 + thinking 诊断 + Pro 高价值
|
||
硅基流动负责工具模型 → embedding / rerank / 多模态
|
||
百度 OCR 负责普通扫描文字 → 复杂页面交给 Qwen3-VL
|
||
切片 512 token + 64 overlap → 递归分割 + 中文分句保护
|
||
候选知识点上限 30 条/source → 不自动接受，用户确认
|
||
删除策略软删除 + 7 天冷却 → 后台定时物理清理
|
||
所有成本进入额度系统 → 每次调用前查额度
|
||
```
|
||
|
||
---
|
||
|
||
## 二十五、全部决策汇总（实现状态）
|
||
|
||
| # | 决策项 | 最终决策 | 状态 |
|
||
|---|--------|---------|------|
|
||
| 1 | Chunk size | 512 tokens | ✅ chunker.py 已实现 |
|
||
| 2 | Overlap | 64 tokens（~12%） | ✅ chunker.py 已实现 |
|
||
| 3 | 切片策略 | 递归字符分割 + 中文分句保护 | ✅ chunker.py 已实现 |
|
||
| 4 | Embedding 模型 | BAAI/bge-m3，硅基流动 | ✅ embedder.py + Key 已配置 |
|
||
| 5 | Vector 维度 | 1024 | ✅ Qdrant collection 已创建 |
|
||
| 6 | Qdrant distance | Cosine | ✅ 已配置 |
|
||
| 7 | Qdrant 部署 | 单节点 Docker，1 shard | ✅ 已部署运行 |
|
||
| 8 | Qdrant 集群时机 | 100 万 points 后评估 | ⏳ 远期 |
|
||
| 9 | Rerank 模型 | BAAI/bge-reranker-v2-m3 | ✅ reranker.py + RAG chat 已用 |
|
||
| 10 | RAG 召回 | Top-50 ANN → rerank → Top-5~8 | ✅ RAG chat 服务已实现 |
|
||
| 11 | 知识库对话 | 仅限 KB 内检索 | ✅ POST /api/rag/chat |
|
||
| 12 | 多轮对话 | history 参数，客户端管理状态 | ✅ 支持最近 10 条历史 |
|
||
| 13 | 候选知识点数量 | 上限 30，最少 3 | ✅ candidate_generator.py 已实现 |
|
||
| 14 | 自动接受 | 全部 PENDING 等确认 | ✅ ImportCandidate 模块已实现 |
|
||
| 15 | OCR | 百度 OCR + Qwen3-VL | ✅ 百度 OCR AppID 7767914 |
|
||
| 16 | 多模态兜底 | Qwen3-VL-32B-Thinking | ✅ Key 已配置 |
|
||
| 17 | 删除 source → KI | 默认保留 + sourceDeleted 快照 | ✅ Prisma schema 已含 |
|
||
| 18 | 删除 KB → 全对象 | 级联删除 | ✅ KB Service 已实现 |
|
||
| 19 | Qdrant 快照 | 本地 + 同步 COS | 🔶 本地 cron 已配，COS 同步待配 |
|
||
| 20 | Qdrant 本地快照保留 | 7 天 | ✅ backup.sh |
|
||
| 21 | Qdrant COS 快照保留 | 30 天 | ⏳ COS 同步待配 |
|
||
| 22 | MySQL 备份 | 每日凌晨 + 同步 COS | 🔶 本地完成，COS 同步待配 |
|
||
| 23 | COS 文件清理 | soft delete 后 7 天 | ⏳ COS 生命周期待配 |
|
||
| 24 | MySQL 物理删除 | 默认 30 天 | ⏳ 清理脚本待写 |
|
||
| 25 | AI 成本日志保留 | 180 天 | ✅ AiUsageLog 表已建 |
|
||
| 26 | 审计日志保留 | 365 天 | ✅ AdminAuditLog 表已建 |
|
||
| 27 | Pro 定价 | 28 元/月预设，配置化 | ✅ MembershipPlan 表已建 |
|
||
| 28 | Worker 进程数 | 单 Worker 起步 | ✅ systemd zhixi-worker + NestJS BullMQ |
|
||
| 29 | Worker 扩展 | 压力上来后 2~3 个 | ⏳ 远期 |
|
||
| 30 | 文档版本管理 | 预留 version 字段 | ✅ schema 已预留 |
|
||
| 31 | 重复文件 | sha256 检测 + 提示用户 | ✅ UploadedFile sha256 已实现 |
|
||
| 32 | 语言分工 | Node=API+Gateway, Python=RAG | ✅ 已按此执行 |
|
||
|
||
---
|
||
|
||
你接下来就按这个顺序推进：**先部署服务器环境，再建数据模型，再做上传和导入任务，再接 Qdrant，最后接学习闭环和知识库对话。**
|