1560 lines
34 KiB
Markdown
1560 lines
34 KiB
Markdown
|
||
可以，现在应该把它整理成一个**分板块执行的落地方案**。你后面就不要再一直在脑子里绕了，按这个顺序推进。
|
||
|
||
# 知习知识库落地执行方案（完整版）
|
||
|
||
---
|
||
|
||
## 一、服务器部署板块
|
||
|
||
### 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
|
||
系统盘：30G
|
||
数据盘：70G
|
||
公网：1Mbps
|
||
地域：北京
|
||
```
|
||
|
||
### 2. 数据盘挂载
|
||
|
||
挂载到：
|
||
|
||
```text
|
||
/data
|
||
```
|
||
|
||
目录规划：
|
||
|
||
```text
|
||
/data/docker ← Docker data-root
|
||
/data/qdrant ← Qdrant storage（向量数据）
|
||
/data/tmp/imports ← 临时下载、解析工作区
|
||
/data/logs ← Worker 日志
|
||
/data/worker-cache ← llama-index 缓存
|
||
/data/backups ← Qdrant 快照 + MySQL dump
|
||
```
|
||
|
||
系统盘只放：Ubuntu 系统 + 基础配置 + 少量代码。不要让 Docker、Qdrant、临时解析文件堆到 30G 系统盘里。
|
||
|
||
---
|
||
|
||
## 三、服务器需要安装的东西
|
||
|
||
### 1. 基础环境
|
||
|
||
```text
|
||
Docker
|
||
Docker Compose
|
||
Git
|
||
Node.js
|
||
pnpm
|
||
Python 3.11+
|
||
pip / poetry
|
||
nginx（可选，后续对外暴露 API 时配）
|
||
supervisor / systemd
|
||
logrotate
|
||
```
|
||
|
||
### 2. 知识库服务组件
|
||
|
||
```text
|
||
Qdrant（Docker）
|
||
RAG Worker（Python）
|
||
NestJS API（Node，部署在 4核4G 主服务器）
|
||
COS SDK
|
||
AI Gateway（Node，主服务器）
|
||
OCR Provider SDK
|
||
Embedding Provider SDK
|
||
```
|
||
|
||
### 3. Python Worker 主要依赖
|
||
|
||
```text
|
||
llama-index
|
||
qdrant-client
|
||
pymupdf / pdfplumber
|
||
python-docx
|
||
markdown
|
||
pandas / openpyxl
|
||
pydantic
|
||
requests / httpx
|
||
tencentcloud-sdk-python
|
||
Pillow（HEIC → JPG 转换）
|
||
```
|
||
|
||
### 4. Node 后端主要依赖
|
||
|
||
```text
|
||
NestJS
|
||
Prisma
|
||
MySQL client
|
||
Redis / BullMQ（任务队列）
|
||
COS SDK
|
||
AI Provider SDK
|
||
JWT / Auth
|
||
class-validator
|
||
zod / JSON Schema 校验
|
||
```
|
||
|
||
> **语言分工：** 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. 服务器之间通信
|
||
|
||
```text
|
||
4核4G 主服务器
|
||
→ 内网调用（HTTP）
|
||
8核32G 知识库服务器
|
||
```
|
||
|
||
不要让知识库内部接口直接暴露公网。
|
||
|
||
### 3. COS 访问方式
|
||
|
||
COS 不作为本地硬盘长期挂载。正确方式：
|
||
|
||
```text
|
||
Worker 通过 COS SDK 拉取文件
|
||
→ 临时下载到 /data/tmp/imports/{jobId}
|
||
→ 解析处理
|
||
→ 写入 Qdrant / MySQL
|
||
→ 删除临时文件
|
||
```
|
||
|
||
COS 负责原始文件存储，服务器负责临时处理和索引。
|
||
|
||
---
|
||
|
||
## 五、COS 存储结构
|
||
|
||
核心原则：
|
||
|
||
```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 天
|
||
每天凌晨定时任务清理超期文件
|
||
```
|
||
|
||
---
|
||
|
||
## 六、知识库支持的上传格式及处理策略
|
||
|
||
### 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
|
||
```
|
||
|
||
---
|
||
|
||
## 七、核心数据模型
|
||
|
||
### 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 切片策略（已拍板）
|
||
|
||
### 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（已拍板）
|
||
|
||
### 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：✅
|
||
取最近 3 轮对话拼入 prompt：✅ 少量做
|
||
根据历史重写检索 query：❌ 后面再做
|
||
通用 AI 问答（非知识库内容）：❌ 第一阶段不支持
|
||
```
|
||
|
||
检索 query 仍使用用户当前原问题，但 prompt 上下文附带最近 3 轮历史。
|
||
|
||
当检索不到相关内容时返回：
|
||
|
||
```text
|
||
当前知识库中没有找到足够相关的资料。
|
||
你可以上传更多资料，或换一种问法。
|
||
```
|
||
|
||
知习第一阶段只做**基于当前知识库内容的 RAG 问答**，不做纯通用 AI 对话。避免产品定位偏离、增加无意义 token 成本和用户把它当 ChatGPT 用。
|
||
|
||
---
|
||
|
||
## 十二、AI 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 起步）
|
||
|
||
```text
|
||
RAG Worker 进程数：1
|
||
```
|
||
|
||
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 解析失败页）
|
||
→ 后台告警
|
||
```
|
||
|
||
---
|
||
|
||
## 十五、删除与清理策略（已拍板）
|
||
|
||
### 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()
|
||
→ 级联软删该 KB 下所有 sources / chunks / candidates / items / review cards / learning records
|
||
→ Qdrant 标记 deleted = true
|
||
→ COS 异步清理
|
||
```
|
||
|
||
用户删除的是整个学习空间，所以级联删除。
|
||
|
||
### 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 一起快速物理删除
|
||
```
|
||
|
||
---
|
||
|
||
## 十六、备份与灾备策略（已拍板）
|
||
|
||
### 1. MySQL 备份
|
||
|
||
```text
|
||
优先级最高：MySQL > Qdrant > COS
|
||
```
|
||
|
||
理由：Qdrant 可重建，COS 有原文件，但 MySQL 丢了业务关系、用户数据、学习记录会非常麻烦。
|
||
|
||
```text
|
||
每日凌晨备份 → /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. 备份任务记录表
|
||
|
||
```text
|
||
backup_jobs
|
||
- id
|
||
- type ← QDRANT / MYSQL
|
||
- status ← RUNNING / COMPLETED / FAILED
|
||
- localPath
|
||
- cosObjectKey
|
||
- fileSizeBytes
|
||
- startedAt
|
||
- completedAt
|
||
- errorMessage
|
||
- createdAt
|
||
```
|
||
|
||
### 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
|
||
会员额度使用情况
|
||
反馈记录
|
||
后台操作审计
|
||
```
|
||
|
||
核心目标是**成本可视化和异常发现**。
|
||
|
||
---
|
||
|
||
## 十九、额度系统
|
||
|
||
### 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 增长 / 高成本用户行为
|
||
```
|
||
|
||
---
|
||
|
||
## 二十、核心接口设计
|
||
|
||
### 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. 索引流程
|
||
|
||
```text
|
||
iOS 上传文件到 COS
|
||
→ 后端创建 File（含 sha256 重复检测）
|
||
→ 后端创建 KnowledgeSource
|
||
→ 创建 DocumentImport（status = QUEUED）
|
||
→ Worker claim 任务（QUEUED → CLAIMED）
|
||
→ Worker 从 COS 拉文件到 /data/tmp/imports/{jobId}
|
||
→ 本地解析 / OCR / 多模态
|
||
→ 写入 parsed.md 到 COS
|
||
→ 清洗文本
|
||
→ chunking（512 tokens + 64 overlap）
|
||
→ embedding（bge-m3，batch 50~100）
|
||
→ Qdrant upsert
|
||
→ 保存 KnowledgeChunk 到 MySQL
|
||
→ source.indexStatus = INDEXED
|
||
→ import.status = COMPLETED
|
||
```
|
||
|
||
### 2. 学习流程
|
||
|
||
```text
|
||
用户打开文件
|
||
→ DeepSeek 生成 ImportCandidate（上限 30 条）
|
||
→ 用户确认 / 编辑 / 拒绝
|
||
→ 生成 KnowledgeItem
|
||
→ 用户主动回忆
|
||
→ DeepSeek 诊断（thinking 模式）
|
||
→ 生成 FocusItem（待巩固项）
|
||
→ 生成 ReviewCard（复习卡）
|
||
→ 记录 LearningActivity
|
||
```
|
||
|
||
---
|
||
|
||
## 二十二、iOS 需要的页面
|
||
|
||
### 知识库相关
|
||
|
||
```text
|
||
知识库列表页
|
||
知识库详情页
|
||
创建知识库页
|
||
上传资料页
|
||
资料列表页
|
||
资料详情页
|
||
导入进度页（含步骤+进度条）
|
||
解析失败页（含错误原因+重试按钮）
|
||
候选知识点确认页（批量接受/拒绝/编辑）
|
||
知识点详情页
|
||
知识库对话页
|
||
```
|
||
|
||
### 学习相关
|
||
|
||
```text
|
||
单文件学习首页
|
||
主动回忆输入页
|
||
AI 分析结果页
|
||
待巩固项页
|
||
复习卡页
|
||
学习记录页
|
||
```
|
||
|
||
### 额度相关
|
||
|
||
```text
|
||
额度展示页
|
||
会员升级页
|
||
OCR / 多模态额度提示
|
||
文件过大提示
|
||
解析额度不足提示
|
||
重复文件提示
|
||
```
|
||
|
||
---
|
||
|
||
## 二十三、执行顺序
|
||
|
||
### 第一阶段：服务器基础
|
||
|
||
```text
|
||
1. 购买服务器
|
||
2. 挂载 /data 数据盘
|
||
3. 配置安全组
|
||
4. 安装 Docker / Docker Compose
|
||
5. 配置 Docker data-root → /data/docker
|
||
6. 部署 Qdrant（含 payload 索引创建）
|
||
7. 配置 COS SDK
|
||
8. 配置 MySQL 每日备份脚本 + COS 同步
|
||
9. 配置 Qdrant 每日快照脚本 + COS 同步
|
||
```
|
||
|
||
### 第二阶段：基础数据模型
|
||
|
||
```text
|
||
1. File（含 sha256）
|
||
2. KnowledgeBase
|
||
3. KnowledgeSource（含 version/reserved 字段）
|
||
4. DocumentImport（含 retryCount/heartbeat 机制）
|
||
5. KnowledgeChunk
|
||
6. ImportCandidate（含 sourceChunkIds/difficulty）
|
||
7. KnowledgeItem
|
||
```
|
||
|
||
### 第三阶段：文件导入闭环
|
||
|
||
```text
|
||
1. iOS 申请上传 URL
|
||
2. iOS 直传 COS + sha256 计算
|
||
3. 后端重复文件检测
|
||
4. 创建 source + import 任务
|
||
5. Worker claim + heartbeat
|
||
6. 本地解析（PDF/DOCX/TXT/MD）
|
||
7. OCR / 多模态（按需）
|
||
8. 写入 parsed.md 到 COS
|
||
9. 更新任务状态
|
||
```
|
||
|
||
### 第四阶段：RAG 索引
|
||
|
||
```text
|
||
1. chunking（512 tokens + 64 overlap）
|
||
2. embedding（bge-m3, batch 50~100）
|
||
3. Qdrant upsert
|
||
4. 保存 KnowledgeChunk 到 MySQL
|
||
5. source.indexStatus = INDEXED
|
||
```
|
||
|
||
### 第五阶段：AI 学习化
|
||
|
||
```text
|
||
1. DeepSeek 生成 ImportCandidate
|
||
2. iOS 展示候选知识点（含置信度、标签、回忆题）
|
||
3. 用户确认 / 编辑
|
||
4. 生成 KnowledgeItem
|
||
```
|
||
|
||
### 第六阶段：单文件学习
|
||
|
||
```text
|
||
1. 主动回忆
|
||
2. AI 诊断（thinking 模式）
|
||
3. 待巩固项 → FocusItem
|
||
4. 复习卡 → ReviewCard
|
||
5. 学习记录
|
||
```
|
||
|
||
### 第七阶段：知识库增强
|
||
|
||
```text
|
||
1. 知识库对话（单轮 RAG + 最近 3 轮上下文）
|
||
2. 引用来源（citations）
|
||
3. rerank 精排
|
||
4. 推荐学习内容
|
||
5. 后台成本监控
|
||
6. 额度检查全链路接入
|
||
```
|
||
|
||
---
|
||
|
||
## 二十四、最终落地原则
|
||
|
||
```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 |
|
||
| 2 | Overlap | 64 tokens（~12%） |
|
||
| 3 | 切片策略 | 递归字符分割 + 中文分句保护 |
|
||
| 4 | Embedding 模型 | BAAI/bge-m3，硅基流动 |
|
||
| 5 | Vector 维度 | 1024 |
|
||
| 6 | Qdrant distance | Cosine |
|
||
| 7 | Qdrant 部署 | 单节点 Docker，1 shard，replication_factor=1 |
|
||
| 8 | Qdrant 集群时机 | 100 万 points 或资源瓶颈后评估 |
|
||
| 9 | Rerank 模型 | BAAI/bge-reranker-v2-m3 |
|
||
| 10 | RAG 召回 | Top-50 ANN → rerank → Top-5~8 |
|
||
| 11 | 知识库对话 | 仅限 KB 内检索，不支持通用 AI 问答 |
|
||
| 12 | 多轮对话 | 保存 session + 最近 3 轮上下文拼入 prompt，不做 query rewrite |
|
||
| 13 | 候选知识点数量 | 每 2000 字 1~2 条，上限 30，最少 3 |
|
||
| 14 | 自动接受 | 第一阶段不做，全部 PENDING 等确认 |
|
||
| 15 | OCR | 百度 OCR（简单文字），Qwen3-VL（复杂排版） |
|
||
| 16 | 多模态兜底 | 硅基流动 Qwen3-VL-32B-Thinking |
|
||
| 17 | 删除 source → KnowledgeItem | 默认保留，记录 sourceDeleted 快照 |
|
||
| 18 | 删除 KB → 全对象 | 级联删除 |
|
||
| 19 | Qdrant 快照 | 本地 + 同步 COS |
|
||
| 20 | Qdrant 本地快照保留 | 7 天 |
|
||
| 21 | Qdrant COS 快照保留 | 30 天 |
|
||
| 22 | MySQL 备份 | 每日凌晨 + 同步 COS |
|
||
| 23 | COS 文件清理 | soft delete 后 7 天 |
|
||
| 24 | MySQL 物理删除 | 默认 30 天，环境变量可配 |
|
||
| 25 | AI 成本日志保留 | 180 天 |
|
||
| 26 | 审计日志保留 | 365 天 |
|
||
| 27 | Pro 定价 | 28 元/月预设，配置化，跑 1 个月成本后调整 |
|
||
| 28 | Worker 进程数 | 单 Worker 起步 |
|
||
| 29 | Worker 扩展 | CPU/内存/队列压力上来后 2~3 个 |
|
||
| 30 | 文档版本管理 | 第一阶段不做，预留 version 字段 |
|
||
| 31 | 重复文件 | sha256 检测 + 提示用户，不做自动去重 |
|
||
| 32 | 语言分工 | Node/NestJS=API+AI Gateway；Python=RAG Worker |
|
||
|
||
---
|
||
|
||
你接下来就按这个顺序推进：**先部署服务器环境，再建数据模型，再做上传和导入任务，再接 Qdrant，最后接学习闭环和知识库对话。**
|