RAG 知识库系统
从设计到实现全解析

POST /api/knowledge/bases/:kbId/documents/upload
    │
    ▼ ① 写入 kb_documents（status=pending）立即返回
    ▼ ② 异步 processDocument() 开始后台处理
    │
    ├─ status → 'indexing'
    ├─ chunker.parseFile(buffer, filename)     → 纯文本
    ├─ UPDATE parsed_content                   → 供预览，限 500KB
    ├─ chunker.chunkText(text)                → chunks[]  600字/块，80字重叠
    ├─ embedding.embedTexts(chunks)            → vectors[][]  调用硅基流动 API
    │
    └─ SQLite 事务 {
         INSERT kb_chunks × N    （含 embedding JSON）
         INSERT kb_chunks_fts × N （FTS5 同步）
         UPDATE kb_documents status='ready'
         UPDATE knowledge_bases chunk_count+=N
       }
    │
    ▼ 前端轮询 GET …/documents → status='ready'

用户发送消息（已选知识库 kb_ids）
    │ POST /api/chat/completions  { message, kb_ids: [1,2] }
    ▼
ChatController
    │
    ├─ KnowledgeService.retrieve(message, kb_ids, 5)
    │      ├─ EmbeddingService.embedQuery(message) → queryVec
    │      ├─ 向量检索：余弦相似度 Top-10
    │      ├─ FTS5 检索：BM25 Top-10
    │      └─ RRF 融合 → Top-5 chunks
    │
    ├─ 注入 RAG System Prompt（"## 参考资料\n【1】..."）
    │
    ├─ SSE: event: rag_sources （推送来源文件名，前端立即显示标签）
    │
    ├─ AiService.streamChat() → SSE: event: chunk × N
    │
    └─ onDone: addMessage(content, { rag_sources: JSON })
               → messages.rag_sources 持久化

CREATE TABLE IF NOT EXISTS kb_chunks (
  id          INTEGER PRIMARY KEY AUTOINCREMENT,
  kb_id       INTEGER NOT NULL,
  doc_id      INTEGER NOT NULL,
  chunk_index INTEGER NOT NULL,   -- 块在文档内的顺序（0-based）
  content     TEXT    NOT NULL,   -- 块文本（600字以内）
  embedding   TEXT,              -- JSON 数组 "[0.12, -0.34, ...]"（1024维）
  token_count INTEGER DEFAULT 0,  -- 近似字数
  FOREIGN KEY (kb_id)  REFERENCES knowledge_bases(id) ON DELETE CASCADE,
  FOREIGN KEY (doc_id) REFERENCES kb_documents(id)    ON DELETE CASCADE
);

-- FTS5 全文检索虚表（与 kb_chunks 同步写入）
CREATE VIRTUAL TABLE IF NOT EXISTS kb_chunks_fts USING fts5(
  content,
  chunk_id   UNINDEXED,
  kb_id      UNINDEXED,
  tokenize='unicode61 remove_diacritics 1'  -- 支持中文
);

server/src/modules/knowledge/
├── knowledge.module.ts      # 模块注册，导入 ChatModule 依赖
├── knowledge.controller.ts  # REST 路由（全部在 /api/knowledge 下）
├── knowledge.service.ts     # 业务逻辑：CRUD、索引、检索、预览
├── chunker.service.ts       # 文本解析 + 分块算法
└── embedding.service.ts     # 调用硅基流动 Embedding API

@Module({
  imports: [DatabaseModule, ConfigModule, HttpModule],
  controllers: [KnowledgeController],
  providers: [KnowledgeService, ChunkerService, EmbeddingService],
  exports: [KnowledgeService],  // 导出供 ChatModule 调用 retrieve()
})
export class KnowledgeModule {}

chunkText(text: string): string[] {
  const paragraphs = text
    .replace(/\r\n/g, '\n').replace(/\r/g, '\n')
    .split('\n\n')
    .map(p => p.trim())
    .filter(p => p.length >= this.MIN_CHUNK_LENGTH);  // 过滤 <20 字碎片

  const chunks: string[] = [];
  let current = '';

  for (const para of paragraphs) {
    if (para.length > this.CHUNK_SIZE) {
      // 超长段落：强制固定窗口切割
      if (current) { chunks.push(current); current = ''; }
      let i = 0;
      while (i < para.length) {
        const slice = para.slice(i, i + this.CHUNK_SIZE).trim();
        if (slice.length >= this.MIN_CHUNK_LENGTH) chunks.push(slice);
        i += this.CHUNK_SIZE - this.OVERLAP;
      }
    } else {
      const candidate = current ? `${current}\n\n${para}` : para;
      if (candidate.length <= this.CHUNK_SIZE) {
        current = candidate;  // 继续追加
      } else {
        if (current) chunks.push(current);
        // 新块以上一块末尾 80 字开头（滑动窗口重叠）
        const overlap = current.slice(-this.OVERLAP);
        current = overlap ? `${overlap}\n\n${para}` : para;
      }
    }
  }
  if (current.trim().length >= this.MIN_CHUNK_LENGTH) chunks.push(current.trim());
  return chunks;
}

// 批量 Embedding（32条/批，避免超出 API 限制）
async embedTexts(texts: string[]): Promise<number[][]> {
  const BATCH = 32;
  const results: number[][] = [];
  for (let i = 0; i < texts.length; i += BATCH) {
    const batch = texts.slice(i, i + BATCH);
    const res = await axios.post(
      'https://api.siliconflow.cn/v1/embeddings',
      { model: 'BAAI/bge-m3', input: batch, encoding_format: 'float' },
      { headers: { Authorization: `Bearer ${this.apiKey}` } },
    );
    results.push(...res.data.data.map((d: any) => d.embedding));
  }
  return results;
}

// 纯 Node.js 余弦相似度，无第三方库
function cosineSimilarity(a: number[], b: number[]): number {
  let dot = 0, normA = 0, normB = 0;
  for (let i = 0; i < a.length; i++) {
    dot   += a[i] * b[i];
    normA += a[i] * a[i];
    normB += b[i] * b[i];
  }
  return dot / (Math.sqrt(normA) * Math.sqrt(normB));
}
// 性能：1万个 1024维向量 ≈ 20-50ms（纯CPU Node.js）

function rrfMerge(vectorList: any[], ftsList: any[], topK: number): any[] {
  const K = 60;
  const scoreMap = new Map<number, { item: any; score: number }>();

  // 向量检索排名贡献
  vectorList.forEach((item, rank) => {
    const s = 1 / (K + rank + 1);
    const cur = scoreMap.get(item.id);
    scoreMap.set(item.id, cur ? { item, score: cur.score + s } : { item, score: s });
  });

  // FTS5 排名贡献（同一文档分数叠加）
  ftsList.forEach((item, rank) => {
    const s = 1 / (K + rank + 1);
    const cur = scoreMap.get(item.id);
    scoreMap.set(item.id, cur ? { item, score: cur.score + s } : { item, score: s });
  });

  return [...scoreMap.values()]
    .sort((a, b) => b.score - a.score)
    .slice(0, topK)
    .map(({ item, score }) => ({ ...item, score }));
}

@Post('completions')
async chatCompletions(@Body() body, @Req() req, @Res() res) {
  const { message, kb_ids } = body;

  // ① RAG 检索（仅当用户选择了知识库时才触发）
  let ragSources: Array<{ filename: string }> = [];
  if (Array.isArray(kb_ids) && kb_ids.length > 0 && message) {
    const chunks = await this.knowledgeService.retrieve(message, kb_ids, 5);
    if (chunks.length > 0) {
      // ② 去重来源文件名
      ragSources = [...new Map(
        chunks.filter(c => c.filename).map(c => [c.filename, { filename: c.filename }])
      ).values()];

      // ③ 注入 RAG System Prompt（AI 输出前插入参考资料）
      const ragContext = chunks.map((c, i) => `【${i+1}】${c.content}`).join('\n\n');
      historyMessages.unshift({
        role: 'system',
        content: `## 参考资料\n请基于以下资料回答用户问题。\n\n${ragContext}`,
      });
    }
  }

  // ④ 设置 SSE 响应头
  res.setHeader('Content-Type', 'text/event-stream');
  res.flushHeaders();

  // ⑤ AI 输出前推送来源事件（前端气泡底部立即显示标签）
  if (ragSources.length > 0) writeEvent('rag_sources', { sources: ragSources });

  // ⑥ 调用 AI 流式输出，onDone 时持久化 rag_sources
  await this.aiService.streamChat({ ...,
    onDone: (fullText) => {
      this.chatService.addMessage(conversationId, 'assistant', fullText, {
        rag_sources: ragSources.length > 0 ? JSON.stringify(ragSources) : undefined,
      });
    },
  });
}

{!isUser && !isStreaming && message.rag_sources?.length > 0 && (
  <div className="flex items-center flex-wrap gap-1.5 mt-2">
    <span className="text-[11px] text-purple-500 font-medium">
      <BookOpen size={11} /> 知识库来源：
    </span>
    {message.rag_sources.map((src, i) => (
      <span key={i}
        className="inline-flex items-center gap-1 px-2 py-0.5 rounded-full
                   bg-purple-50 border border-purple-200 text-[11px] text-purple-700"
      >
        <FileText size={10} />
        <span className="truncate max-w-[180px]">{src.filename}</span>
      </span>
    ))}
  </div>
)}

getDocumentPreview(docId: number, kbId: number) {
  const doc = this.db.get(
    'SELECT id, filename, file_type, parsed_content FROM kb_documents WHERE id=? AND kb_id=?',
    [docId, kbId],
  );
  if (!doc) return null;

  // 老文档 parsed_content 为 NULL → 从 kb_chunks 拼接重建
  if (!doc.parsed_content) {
    const chunks = this.db.all(
      'SELECT content FROM kb_chunks WHERE doc_id=? ORDER BY chunk_index ASC',
      [docId],
    );
    if (chunks.length > 0) {
      let assembled = chunks[0].content;
      for (let i = 1; i < chunks.length; i++) {
        const curr = chunks[i].content;
        const suffix = assembled.slice(-80);
        // 检测相邻块重叠，去重拼接
        if (curr.startsWith(suffix) && suffix.trim().length > 0) {
          assembled += '\n\n' + curr.slice(suffix.length);
        } else {
          assembled += '\n\n' + curr;
        }
      }
      doc.parsed_content = assembled;
    }
  }
  return doc;
}

KnowledgePage
├── 左侧面板：知识库列表
│   ├── 知识库卡片（名称/文档数/分块数）
│   ├── 公共/私有图标（Globe/Lock）
│   └── 删除按钮 → 自定义确认弹窗
│
├── 右侧面板：文档列表
│   ├── 文档卡片（文件名/大小/状态徽章/分块数）
│   ├── 状态轮询（pending → indexing → ready）
│   ├── 分块详情 → 右侧抽屉（chunk_index/字数/内容）
│   ├── 预览按钮 → 全屏预览 Modal（md渲染/txt等宽）
│   └── 删除按钮 → 自定义确认弹窗
│
├── 新建知识库弹窗（名称/描述/公共权限开关）
└── 文件上传（支持 txt/md/docx，拖拽或点击）

// Message 类型新增 rag_sources 字段
export interface Message {
  id: string;
  role: 'user' | 'assistant';
  content: string;
  rag_sources?: Array<{ filename: string }>;  // ← 新增
}

// SSE rag_sources 事件触发的 Action
setMessageSources: (convId, msgId, sources) =>
  set(s => ({
    messages: {
      ...s.messages,
      [convId]: s.messages[convId].map(m =>
        m.id === msgId ? { ...m, rag_sources: sources } : m
      ),
    },
  })),

{
  "message": "如何申请退款？",
  "kb_ids": [1, 2],          // 要检索的知识库 ID 列表（为空则不触发 RAG）
  "conversation_id": "...",
  // ...其他原有参数不变
}