docs/VECTOR_DB_LOGIC_AND_MULTI_COURSE.md

# ClareVoice 向量数据库逻辑 · 多课程支持 · 优化计划

本文档**只描述 ClareVoice（HF Space）**的向量库设计与扩展思路。

---

## 一、当前向量数据库是怎么做的

**ClareVoice 使用 Weaviate Cloud 作为课程知识库**，同时会话级 RAG 用内存 + FAISS。双路检索结果在对话时拼接。

### 1.1 Weaviate + 内存双路检索

| 数据源 | 存储位置 | 用途 | 检索入口 |
|--------|----------|------|----------|
| **Weaviate Cloud** | 持久化向量库（GCP） | GENAI 课程文档（151+ 文档，由 `build_weaviate_index.py` 一次性写入） | `_retrieve_from_weaviate(question)` |
| **内存 + FAISS** | 进程内 `SESSIONS[user_id]["rag_chunks"]` | Module 10 预读 + 用户上传文件 | `retrieve_relevant_chunks()` |

**Weaviate 流程简述：**

1. **建索引（一次性）**  
   - 脚本：`hf_space/GenAICoursesDB_space/build_weaviate_index.py`  
   - 读取 `GENAI COURSES` 目录（.md / .pdf / .txt / .py / .ipynb / .docx），用 LlamaIndex `SimpleDirectoryReader` 加载 → `VectorStoreIndex.from_documents()` + `WeaviateVectorStore`，写入 Weaviate Cloud 的 **collection `GenAICourses`**。  
   - Embedding：默认 `sentence-transformers/all-MiniLM-L6-v2`（与 ClareVoice 运行时一致）；可选 `EMBEDDING_PROVIDER=openai` 用 `text-embedding-3-small`。

2. **运行时检索**（`hf_space/ClareVoice/app.py`）  
   - 配置：`WEAVIATE_URL`、`WEAVIATE_API_KEY`、`WEAVIATE_COLLECTION`（默认 `GenAICourses`），`USE_WEAVIATE_DIRECT=True` 时启用。  
   - `_get_weaviate_embed_model()`：懒加载并缓存 **HuggingFaceEmbedding(all-MiniLM-L6-v2)**（与建索引时一致）。  
   - `_retrieve_from_weaviate(question, top_k=5)`：连接 Weaviate Cloud → `WeaviateVectorStore` + `VectorStoreIndex.from_vector_store(vs)` → `as_retriever(similarity_top_k=top_k).retrieve(question)` → 将 node 内容用 `---` 拼接成字符串返回。  
   - 启动时 `_warmup_weaviate_embed()` 在后台线程预热 embedding 模型，减少首次检索超时。  
   - 未配置 Weaviate 时回退到调用 **GenAICoursesDB Space** 的 `/retrieve` 接口。

3. **对话时的组合**  
   - 先按会话用 `retrieve_relevant_chunks(sess["rag_chunks"])` 得到「Module 10 + 上传」的 context。  
   - 若配置了 Weaviate，再调 `_retrieve_from_weaviate(message)`，把返回的课程检索文本**拼在**上面 context 后面，一起交给 LLM。

---

### 1.2 数据从哪来、存在哪

| 来源 | 何时写入 | 存在哪 |
|------|----------|--------|
| Module 10 预读 | 进程启动时 | 全局 cache → 每会话 `rag_chunks` |
| 用户上传文件 | Gradio 上传回调 | 追加到 `sess["rag_chunks"]` |
| GENAI 课程文档 | 本地运行 `build_weaviate_index.py` | **Weaviate Cloud** collection `GenAICourses` |

### 1.3 Chunk 长什么样（内存/FAISS 侧）

会话级 `rag_chunks` 里每个元素是一个 dict，例如：

```python
{
  "text": "一段正文...",
  "source_file": "module10_responsible_ai.pdf",  # 或上传的文件名
  "section": "pdf_unstructured#1",               # 段落/页码标识
  "doc_type": "Literature Review / Paper",       # Syllabus / Lecture Slides / ...
  "embedding": [0.1, -0.02, ...]                  # 维度由 rag_engine 所用 embedding 模型决定
}
```

- **Embedding**：ClareVoice 的 `rag_engine` 里用 `clare_core.get_embedding()`（或同配置的 embedding）为每个 chunk 生成向量。
- **解析**：PDF 优先 `unstructured.io`，失败则 pypdf；DOCX/PPTX 用 python-docx/pptx；按空行分段落再按约 1400 字符打包成 chunk。

**Weaviate 侧**：由 LlamaIndex 写入的 document/node，带向量与元数据；检索时取 `node.get_content()` 拼成字符串，无单独 chunk dict 结构要求。

### 1.4 检索流程（retrieve_relevant_chunks，仅内存/FAISS）

1. **入参**  
   - `query`：用户问题  
   - `chunks`：当前会话的 `sess["rag_chunks"]`  
   - 可选：`allowed_source_files`、`allowed_doc_types`（例如只查「刚上传的那份文件」）

2. **先做范围过滤**  
   - 若有 `allowed_source_files` / `allowed_doc_types`，只保留符合的 chunks，再参与后续步骤。

3. **向量检索（默认开启）**  
   - 用当前配置的 embedding 模型对 query 生成向量；  
   - 用当前过滤后的 chunks 临时建一个 **VectorStore**（FAISS IndexFlatL2 或列表余弦）；  
   - 取 top `k*2` 个候选（默认 k=4），再按 `vector_similarity_threshold`（默认 0.7）过滤。

4. **Rerank**  
   - 对候选做 **token 重叠**（query 与 chunk 的 token 交集）；  
   - 综合分 = `0.7 * 向量相似度 + 0.3 * 归一化 token 重叠`，再取 top k。

5. **无结果或分数过低**  
   - 回退到**纯 token 重叠**检索（按词匹配，无向量）。

6. **拼上下文**  
   - 对最终 top chunks 做 token 截断（单 chunk 500、总 context 2000），拼成一段 `context_text` 返回给 LLM，同时返回 `used_chunks` 供前端展示引用。

### 1.5 可选：GenAICoursesDB 回退

- 若**未配置 Weaviate**，ClareVoice 用 `GENAI_COURSES_SPACE` 调用 GenAICoursesDB Space 的 `/retrieve` 接口，作为课程知识库的「远程 RAG」回退。

### 1.6 小结（当前逻辑）

- **Weaviate Cloud**：存 GENAI 课程知识库（`build_weaviate_index.py` 建索引，`_retrieve_from_weaviate` 检索）。
- **内存 + FAISS**：会话级 `rag_chunks`（Module 10 预读 + 用户上传），`retrieve_relevant_chunks()` 检索。
- **对话时**：先取 FAISS 的 context，再调 `_retrieve_from_weaviate` 把课程检索结果拼在后面，一起交给 LLM。
- **多课程**：当前 Weaviate 单 collection（GenAICourses）；支持多门课时可在 Weaviate 内按 `course_id` 或分 collection 扩展（见下文）。

---

## 二、要支持多门课程，需要怎么做

目标：**多门课程并存、按课程（或 workspace）隔离检索**，且不破坏现有单会话、单课程使用方式。  
**ClareVoice 已有 Weaviate**，多课程可在此基础上扩展（多 collection 或单 collection + course_id 过滤）。

### 2.1 数据模型上区分「课程」

- 为 chunk / 文档增加**课程维度**，例如：
  - `course_id`：对应 `course_directory` 里的一门课；
  - 或 `workspace_id`：对应某个 workspace（若一个 workspace 绑定一门课）。
- 会话侧增加「当前使用的课程/workspace」：
  - 例如 `sess["course_id"]` 或 `sess["workspace_id"]`，由前端「选课/选 workspace」或默认规则设定。

这样：  
- **建索引时**：每个 chunk 带上 `course_id`（或 `workspace_id`）；  
- **检索时**：只在该会话当前 `course_id`（或当前 workspace 绑定的课程）对应的数据里搜。

### 2.2 两种实现路径

**路径 A：内存 + 按课程分桶（仅会话级）**

- 会话结构扩展为例如：`sess["rag_chunks_by_course"] = { "course_ai_001": [...], "course_ml_002": [...] }`。
- 或保持 `sess["rag_chunks"]` 为「当前课程」的列表，在**切换课程**时从「课程级缓存」里加载对应列表。
- **课程级 chunk 从哪来**：
  - **方案 A1**：仍以「上传」为主——用户选一门课再上传，上传时带 `course_id`，写入 `rag_chunks_by_course[course_id]`。
  - **方案 A2**：预置「课程资料」——每门课有预解析好的 chunk 列表，登录/选课后加载到会话或课程缓存。
- **检索**：只对当前课程的 chunk 列表做现有 `retrieve_relevant_chunks()`，逻辑不变。

**路径 B：Weaviate 扩展（推荐）**

- ClareVoice 已用 **Weaviate Cloud** 存 GENAI 课程（单 collection `GenAICourses`）。多课程可：
  - **方案 B1**：多 collection——每门课一个 collection，如 `GenAICourses`、`Course_ML_101`；`_retrieve_from_weaviate` 根据 `sess["course_id"]` 或配置选择 `index_name`。
  - **方案 B2**：单 collection + 元数据过滤——在 Weaviate 的 class 上增加属性 `course_id`（或 `courseId`），建索引时写入；检索时用 Weaviate 的 **filter**（如 `where course_id == "course_ai_001"`）再做向量检索。
- **写入**：  
  - 预置课程：沿用或扩展 `build_weaviate_index.py`，按课程目录/配置写入，带 `course_id`；  
  - 用户上传：解析 → embedding → 写入 Weaviate，并带上当前 `course_id`（需在 ClareVoice 中接 Weaviate 写接口）。
- **检索**：  
  - query embedding + **filter (course_id = 当前课程)**；  
  - 再在应用层做 token rerank / 截断，拼 context。
- **会话**：存 `user_id`、`course_id`；多门课共享同一 Weaviate 集群，靠 collection 或 filter 隔离。

### 2.3 与 Gradio 前端配合

- **选课/选 workspace**：  
  - 若 UI 有选课或 workspace，在会话中维护 `sess["course_id"]` / `sess["workspace_id"]`，上传与检索时只作用当前课程。
- **上传**：  
  - 上传回调里从当前会话读 `course_id`（若有），写入 chunk 池或 Weaviate 时带课程维度。
- **对话**：  
  - 多课程下从「当前课程对应的 chunk 源」取数（内存分桶或 Weaviate filter），再调 `retrieve_relevant_chunks()` 或 `_retrieve_from_weaviate(..., course_id=...)`。

### 2.4 小结：多课程支持要做的事

| 项目 | 说明 |
|------|------|
| Chunk 增加 course_id（或 workspace_id） | 建索引/写入时必带；检索时按此过滤。 |
| 会话增加当前课程 | `sess["course_id"]` 或 `sess["workspace_id"]`，由选课/选 workspace 设定。 |
| 上传与选课绑定 | 上传时带 course_id，写入对应课程 chunk 池或向量库。 |
| 检索只查当前课程 | 内存方案：只对当前课程的 chunk 列表检索；向量库方案：filter by course_id。 |
| 可选：课程预置资料 | 每门课预解析+embedding，放入课程缓存或持久化向量库。 |

---

## 三、向量数据库的优化计划与想法

在「写清当前逻辑」和「多课程支持」之上，可以按阶段做以下优化。

### 3.1 短期（不引入新服务）

- **按会话/按课程复用 FAISS 索引**  
  - 当前是**每次** `retrieve_relevant_chunks` 都 `VectorStore()` + `build_index(chunks)`，重复建索引。  
  - 改为：对同一份 `chunks`（按会话或按 course_id 的列表）**建一次索引并缓存**，只有 chunks 变化（如新上传）时再重建。这样检索延迟和 CPU 都会明显下降。

- **Chunk 与 embedding 分离缓存**  
  - 对「未改动的文件」缓存其 chunk 列表（或甚至只缓存 embedding），避免重复解析、重复调 OpenAI Embeddings；上传同一文件时可直接复用。

- **检索参数可配置**  
  - `top_k`、`vector_similarity_threshold`、`RAG_CONTEXT_TOKEN_LIMIT` 等放进 config 或 API，便于按课程/场景调优（如考试模式用更大 top_k）。

- **多课程内存分桶**  
  - 实现 2.1 / 2.2 路径 A：`rag_chunks_by_course` + 选课接口，先支持多门课隔离，为后续迁到向量库打基础。

### 3.2 中期（扩展 Weaviate / 持久化向量库）

- **ClareVoice 已接 Weaviate Cloud**；可在此基础上：  
  - Schema 增加 `course_id`（及可选 `workspace_id`、`uploaded_at`）；  
  - 多 collection 或单 collection + filter，实现多课程隔离；  
  - 上传时写入 Weaviate（需在服务端接 Weaviate 写接口），预置课程继续用 `build_weaviate_index.py` 或同类脚本。

- **统一检索接口**  
  - 封装一层「RAG 检索」：内部根据配置选择「内存 FAISS」或「Weaviate」（及可选 GenAICoursesDB 回退）；对上层仍返回 `(context_text, used_chunks)`，便于后续扩展与多课程切换。

- **课程级预建索引**  
  - 每门课预解析 + 批量 embedding → 写入 Weaviate（按 course_id 或分 collection）；用户选课后直接查。

### 3.3 中长期（效果与规模）

- **混合检索（Hybrid）**  
  - 向量检索 + 关键词（BM25/lexical）再融合（如 RRF），减少纯向量「语义漂移」或专有名词漏检。

- **Rerank 模型**  
  - 向量初筛后用小型的 cross-encoder 或 rerank API 精排，再截断进 context，提升引用准确度。

- **分片与规模**  
  - 按 `course_id` 分 collection 或分索引，便于按课程做备份、迁移、删除；单集合过大时再考虑按时间或按文档分片。

- **可观测性**  
  - 记录检索延迟、命中 chunk 数、分数分布；可选 A/B 不同 top_k 或阈值，便于调参。

---

## 四、总结表

| 维度 | ClareVoice 当前 | 多课程（建议） | 优化方向 |
|------|-----------------|----------------|----------|
| 课程知识库 | **Weaviate Cloud**（GenAICourses） | 多 collection 或 course_id 过滤 | 多课程 schema、统一检索接口 |
| 会话 RAG | 内存 rag_chunks + FAISS | 按 course_id 分桶或统一走 Weaviate | 索引复用、课程级预建 |
| 检索 | Weaviate + FAISS 双路，结果拼接 | 先按 course_id 过滤再检索 | Hybrid、rerank、可调参 |
| 数据来源 | Module10 预读 + 上传 + **Weaviate 课程** | + 课程预置资料、多课程上传 | 批量预置、可观测 |

按上述步骤：先把「当前向量库逻辑」和「多课程支持」在设计与实现上对齐，再分阶段做「缓存/索引复用 → 扩展 Weaviate 多课程 → 混合检索与规模化」，即可在支持多门课的同时逐步优化 ClareVoice 向量数据库的表现与可维护性。