ARCHITECTURE.md

# Clare AI + Weaviate 技术架构文档

## 📋 目录
1. [系统概述](#系统概述)
2. [架构图](#架构图)
3. [技术栈](#技术栈)
4. [核心组件](#核心组件)
5. [数据流](#数据流)
6. [部署架构](#部署架构)
7. [关键技术决策](#关键技术决策)

---

## 🎯 系统概述

**Clare AI** 是一个基于 RAG (Retrieval-Augmented Generation) 的智能教学助手，通过 **Weaviate Cloud** 向量数据库提供课程知识检索能力。

### 核心功能
- **多模式教学**：概念解释、苏格拉底式辅导、考试准备、作业助手、快速总结
- **知识检索**：从 151+ 个课程文档（PDF、DOCX、代码等）中检索相关内容
- **会话记忆**：跟踪学生弱项、认知状态、学习进度
- **多语言支持**：中英文双语对话

---

## 🏗️ 架构图

```
┌─────────────────────────────────────────────────────────────┐
│                    Hugging Face Space                        │
│  ┌──────────────────────────────────────────────────────┐   │
│  │           ClareVoice (Gradio App)                   │   │
│  │  ┌──────────────────────────────────────────────┐  │   │
│  │  │  Frontend: Gradio UI                          │  │   │
│  │  │  - Chat Interface                              │  │   │
│  │  │  - File Upload                                 │  │   │
│  │  │  - Session Management                          │  │   │
│  │  └──────────────────────────────────────────────┘  │   │
│  │                                                      │   │
│  │  ┌──────────────────────────────────────────────┐  │   │
│  │  │  Core Logic (clare_core.py)                    │  │   │
│  │  │  - LLM: GPT-4.1-mini (OpenAI)                  │  │   │
│  │  │  - Prompt Engineering                          │  │   │
│  │  │  - Session Memory                              │  │   │
│  │  └──────────────────────────────────────────────┘  │   │
│  │                                                      │   │
│  │  ┌──────────────────────────────────────────────┐  │   │
│  │  │  RAG Engine (rag_engine.py)                    │  │   │
│  │  │  - Local FAISS (上传文件)                       │  │   │
│  │  │  - PDF/DOCX Parsing                            │  │   │
│  │  └──────────────────────────────────────────────┘  │   │
│  └──────────────────────────────────────────────────────┘   │
│                          │                                  │
│                          │ HTTPS + API Key                  │
│                          ▼                                  │
└─────────────────────────────────────────────────────────────┘
                          │
                          │
┌─────────────────────────────────────────────────────────────┐
│              Weaviate Cloud (GCP)                          │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  Collection: GenAICourses                             │   │
│  │  - 151+ 文档块 (chunks)                               │   │
│  │  - Vector Embeddings (384-dim)                       │   │
│  │  - Metadata (source_file, section)                   │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                          ▲
                          │
┌─────────────────────────────────────────────────────────────┐
│         Index Builder (本地/CI)                              │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  build_weaviate_index.py                             │   │
│  │  - 读取 GENAI COURSES/ 目录                           │   │
│  │  - Embedding: sentence-transformers/all-MiniLM-L6-v2 │   │
│  │  - 上传到 Weaviate Cloud                             │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
```

---

## 🛠️ 技术栈

### 前端层
- **Gradio 6.0+**: Web UI 框架，支持实时对话、文件上传
- **Python 3.11**: 运行环境

### 后端层
- **OpenAI GPT-4.1-mini**: 主要 LLM，用于生成回答
- **LangChain**: LLM 编排框架
- **LlamaIndex**: 向量检索框架

### 向量数据库
- **Weaviate Cloud**: 托管向量数据库（GCP）
  - Collection: `GenAICourses`
  - Embedding Model: `sentence-transformers/all-MiniLM-L6-v2` (384维)
  - 文档类型: PDF, DOCX, TXT, PY, IPYNB

### Embedding 模型
- **建索引**: `sentence-transformers/all-MiniLM-L6-v2` (免费，本地运行)
- **查询**: 与建索引使用相同模型（保证向量空间一致）

### 文档解析
- **unstructured.io**: PDF 解析（优先）
- **pypdf**: PDF 解析（降级方案）
- **python-docx**: DOCX 解析

---

## 🔧 核心组件

### 1. ClareVoice App (`app.py`)

**职责**: 主应用入口，处理用户交互

**关键功能**:
- Gradio UI 渲染
- 用户会话管理
- 调用 RAG 检索和 LLM 生成
- Weaviate 直连检索

**关键代码**:
```python
# Weaviate 检索（优先）
if USE_WEAVIATE_DIRECT:
    course_chunks = _retrieve_from_weaviate(message)
    
# 本地 FAISS（上传文件）
rag_context_text = retrieve_relevant_chunks(message, rag_chunks)
```

### 2. RAG Engine (`rag_engine.py`)

**职责**: 本地文件向量化和检索

**功能**:
- 解析上传的 PDF/DOCX
- 构建 FAISS 索引（内存）
- 向量相似度检索

### 3. Clare Core (`clare_core.py`)

**职责**: LLM 调用和 Prompt 构建

**功能**:
- 构建多轮对话上下文
- 整合 RAG 检索结果
- 管理会话记忆（弱项、认知状态）
- 生成教学回答

### 4. Weaviate 检索 (`app.py` → `_retrieve_from_weaviate`)

**职责**: 从 Weaviate Cloud 检索课程知识

**流程**:
1. 加载 embedding 模型（缓存）
2. 连接 Weaviate Cloud
3. 将用户问题编码为向量
4. 向量相似度搜索（top_k=5）
5. 返回相关文档块

**关键特性**:
- **超时保护**: 45秒超时，避免阻塞
- **模型预热**: 启动时后台加载，避免首次查询慢
- **错误降级**: 失败时静默返回空，不影响主流程

---

## 📊 数据流

### 用户提问流程

```
1. 用户输入问题
   │
   ▼
2. 检测是否为学术查询 (is_academic_query)
   │
   ├─ 是 → 触发 RAG 检索
   │   │
   │   ├─ Weaviate 检索 (优先)
   │   │   └─ 返回课程文档块
   │   │
   │   └─ 本地 FAISS 检索 (上传文件)
   │       └─ 返回文档块
   │
   └─ 否 → 跳过 RAG
   │
   ▼
3. 构建 Prompt
   ├─ System Prompt (Clare 身份)
   ├─ Session Memory (弱项、认知状态)
   ├─ RAG Context (检索到的文档)
   └─ User Message
   │
   ▼
4. 调用 OpenAI API (GPT-4.1-mini)
   │
   ▼
5. 返回回答 + 更新会话历史
```

### 索引构建流程

```
1. 本地运行 build_weaviate_index.py
   │
   ▼
2. 读取 GENAI COURSES/ 目录
   ├─ 支持格式: .md, .pdf, .txt, .py, .ipynb, .docx
   └─ 递归扫描所有子目录
   │
   ▼
3. 文档分块 (LlamaIndex SimpleDirectoryReader)
   └─ 自动分块，保留元数据
   │
   ▼
4. Embedding 编码
   └─ sentence-transformers/all-MiniLM-L6-v2
   │
   ▼
5. 上传到 Weaviate Cloud
   ├─ Collection: GenAICourses
   ├─ 向量 + 元数据 (source_file, section)
   └─ 验证 object count
```

---

## 🚀 部署架构

### Hugging Face Space (ClareVoice)

**部署方式**: Docker Space

**Dockerfile 关键配置**:
```dockerfile
FROM python:3.11-slim
# 安装系统依赖 (libxcb for unstructured)
RUN apt-get update && apt-get install -y libxcb1 libxcb-xinerama0
# 强制升级 huggingface_hub>=1.3.0
RUN pip install --upgrade "huggingface_hub>=1.3.0,<2.0"
# 安装依赖
RUN pip install -r requirements.txt
```

**环境变量 (Secrets)**:
- `OPENAI_API_KEY`: OpenAI API 密钥
- `WEAVIATE_URL`: Weaviate Cloud REST 地址
- `WEAVIATE_API_KEY`: Weaviate API Key
- `WEAVIATE_COLLECTION`: 集合名（默认 `GenAICourses`）

**启动流程**:
1. 加载环境变量
2. 后台预热 Weaviate embedding 模型
3. 启动 Gradio 服务（端口 7860）

### Weaviate Cloud

**托管**: Google Cloud Platform (GCP)

**配置**:
- Cluster URL: `https://riiqvgc7tuum6cgwhik9ra.c0.us-west3.gcp.weaviate.cloud`
- Authentication: API Key
- Collection Schema: 自动创建（LlamaIndex 管理）

**数据规模**:
- 文档数量: 151+ 文件
- 文档块数: ~917 objects
- 向量维度: 384 (all-MiniLM-L6-v2)

---

## 💡 关键技术决策

### 1. 为什么选择 Weaviate Cloud？

**优势**:
- ✅ **托管服务**: 无需自建数据库，降低运维成本
- ✅ **高性能**: 向量检索延迟 <100ms
- ✅ **可扩展**: 支持大规模文档库
- ✅ **API 简单**: RESTful API，易于集成

**对比其他方案**:
- ❌ **本地 FAISS**: 内存限制，无法持久化
- ❌ **Pinecone**: 成本较高
- ❌ **自建 Weaviate**: 需要服务器和运维

### 2. 为什么使用 sentence-transformers 而非 OpenAI Embeddings？

**原因**:
- ✅ **成本**: 免费，无 API 调用费用
- ✅ **一致性**: 建索引和查询使用同一模型，保证向量空间一致
- ✅ **离线能力**: 本地运行，不依赖外部 API

**权衡**:
- ⚠️ **性能**: OpenAI `text-embedding-3-small` (1536维) 可能更准确
- ⚠️ **延迟**: 首次加载模型需要 10-30 秒（已通过预热解决）

### 3. 为什么采用 Docker Space 而非 Gradio SDK？

**原因**:
- ✅ **依赖控制**: 可以强制升级特定包（如 `huggingface_hub`）
- ✅ **系统库**: 可以安装 `libxcb` 等系统依赖
- ✅ **灵活性**: 完全控制构建过程

### 4. 双检索策略（Weaviate + FAISS）

**设计**:
- **Weaviate**: 课程知识库（151+ 文档，持久化）
- **FAISS**: 用户上传文件（临时，内存）

**优势**:
- ✅ 课程知识稳定可用
- ✅ 用户文件灵活处理
- ✅ 降级方案：Weaviate 失败时仍有 FAISS

---

## 📈 性能指标

### 检索性能
- **Weaviate 检索**: ~500-1000ms（含网络延迟）
- **FAISS 检索**: ~10-50ms（内存检索）
- **Embedding 编码**: ~100-300ms（首次需加载模型）

### LLM 响应
- **GPT-4.1-mini**: ~2-5秒（取决于回答长度）

### 系统资源
- **内存**: ~2-4GB（含 embedding 模型）
- **CPU**: 中等负载（embedding 计算）

---

## 🔒 安全与隐私

### API 密钥管理
- ✅ 使用 Hugging Face Secrets（加密存储）
- ✅ 不在代码中硬编码密钥

### 数据隐私
- ✅ 用户会话数据不持久化（仅内存）
- ✅ Weaviate 仅存储课程文档（公开内容）
- ✅ 用户上传文件仅用于当前会话

---

## 🐛 已知问题与解决方案

### 1. huggingface_hub 版本冲突
**问题**: HF Space 预装旧版 (0.36.2)，`transformers` 需要 >=1.3.0

**解决**: 
- Dockerfile 中强制升级
- App 启动时 monkey-patch `is_offline_mode`

### 2. Gradio 6.0 API 变更
**问题**: `Chatbot` 不再支持 `type="tuples"`，改为 `messages` 格式

**解决**: 添加格式转换函数 `_tuples_to_messages` / `_messages_to_tuples`

### 3. Embedding 模型首次加载慢
**问题**: 首次检索需要 10-30 秒加载模型

**解决**: 启动时后台预热（`_warmup_weaviate_embed`）

---

## 📝 总结

Clare AI 采用 **RAG + LLM** 架构，通过 **Weaviate Cloud** 提供稳定的课程知识检索能力。系统设计注重：

1. **可靠性**: 多重降级方案，确保服务可用
2. **性能**: 模型预热、超时保护、缓存机制
3. **可扩展**: 托管服务，易于扩展文档库
4. **成本**: 使用免费 embedding 模型，降低运营成本

---

**文档版本**: v1.0  
**最后更新**: 2026-02-11  
**维护者**: Clare AI Team