# Clare AI + Weaviate 技术汇报摘要

## 🎯 一、项目概述

**Clare AI** = 智能教学助手 + RAG 知识检索

- **核心能力**: 基于课程文档的智能问答
- **技术亮点**: Weaviate Cloud 向量数据库 + OpenAI GPT-4.1-mini
- **部署平台**: Hugging Face Space (Docker)

---

## 🏗️ 二、架构设计

### 2.1 三层架构

```
┌─────────────────┐
│  Gradio UI      │  用户交互层
├─────────────────┤
│  Clare Core     │  业务逻辑层 (LLM + Prompt)
├─────────────────┤
│  RAG Engine     │  检索层 (Weaviate + FAISS)
└─────────────────┘
```

### 2.2 数据流

**用户提问** → **RAG 检索** → **构建 Prompt** → **LLM 生成** → **返回回答**

---

## 🛠️ 三、技术栈

| 层级 | 技术选型 | 说明 |
|------|---------|------|
| **前端** | Gradio 6.0 | Web UI 框架 |
| **LLM** | GPT-4.1-mini | OpenAI API |
| **向量数据库** | Weaviate Cloud | 托管服务 (GCP) |
| **Embedding** | sentence-transformers/all-MiniLM-L6-v2 | 免费，384维 |
| **文档解析** | unstructured.io + pypdf | PDF/DOCX 解析 |

---

## 📊 四、核心组件

### 4.1 Weaviate 检索 (`_retrieve_from_weaviate`)

**功能**: 从云端向量数据库检索课程知识

**流程**:
1. 连接 Weaviate Cloud (HTTPS + API Key)
2. 用户问题 → Embedding 向量
3. 向量相似度搜索 (top_k=5)
4. 返回相关文档块

**特性**:
- ✅ 45秒超时保护
- ✅ 启动时模型预热
- ✅ 失败时静默降级

### 4.2 索引构建 (`build_weaviate_index.py`)

**功能**: 一次性将课程文档上传到 Weaviate

**数据规模**:
- 📄 **151+ 文件**: PDF (22) + DOCX (112) + 其他 (17)
- 📦 **~917 文档块**: 自动分块
- 🔢 **384维向量**: all-MiniLM-L6-v2

**流程**:
```
本地目录 → 文档解析 → Embedding → 上传 Weaviate
```

---

## 💡 五、关键技术决策

### 5.1 为什么选择 Weaviate Cloud？

| 方案 | 优势 | 劣势 |
|------|------|------|
| **Weaviate Cloud** ✅ | 托管、高性能、可扩展 | 需要 API Key |
| 本地 FAISS | 免费、快速 | 内存限制、不持久化 |
| Pinecone | 易用 | 成本高 |
| 自建 Weaviate | 完全控制 | 需要运维 |

**结论**: Weaviate Cloud 平衡了成本、性能和运维复杂度

### 5.2 为什么使用 sentence-transformers？

**原因**:
- 💰 **免费**: 无 API 调用费用
- 🔄 **一致性**: 建索引和查询同一模型
- 🚀 **离线**: 本地运行，不依赖外部 API

**对比 OpenAI Embeddings**:
- OpenAI: 更准确 (1536维)，但需付费
- sentence-transformers: 免费，性能足够

### 5.3 双检索策略

| 检索源 | 用途 | 特点 |
|--------|------|------|
| **Weaviate** | 课程知识库 | 持久化、151+ 文档 |
| **FAISS** | 用户上传文件 | 临时、内存检索 |

**优势**: 课程知识稳定 + 用户文件灵活

---

## 📈 六、性能指标

| 指标 | 数值 | 说明 |
|------|------|------|
| **Weaviate 检索** | ~500-1000ms | 含网络延迟 |
| **FAISS 检索** | ~10-50ms | 内存检索 |
| **LLM 响应** | ~2-5秒 | GPT-4.1-mini |
| **系统内存** | ~2-4GB | 含 embedding 模型 |

---

## 🔧 七、部署架构

### 7.1 Hugging Face Space

**部署方式**: Docker Space

**关键配置**:
- Python 3.11
- 强制 `huggingface_hub>=1.3.0`
- 系统库: `libxcb` (PDF 解析)

**环境变量**:
- `OPENAI_API_KEY`
- `WEAVIATE_URL`
- `WEAVIATE_API_KEY`

### 7.2 Weaviate Cloud

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

**配置**:
- Collection: `GenAICourses`
- 认证: API Key
- Schema: 自动管理 (LlamaIndex)

---

## 🐛 八、技术挑战与解决

### 8.1 huggingface_hub 版本冲突

**问题**: HF Space 预装 0.36.2，`transformers` 需要 >=1.3.0

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

### 8.2 Gradio 6.0 API 变更

**问题**: `Chatbot` 格式从 tuples 改为 messages

**解决**: 添加格式转换函数

### 8.3 Embedding 模型加载慢

**问题**: 首次检索需 10-30 秒

**解决**: 启动时后台预热

---

## ✅ 九、项目成果

### 9.1 功能实现

- ✅ 多模式教学（5种学习模式）
- ✅ 课程知识检索（151+ 文档）
- ✅ 会话记忆管理
- ✅ 中英文双语支持

### 9.2 技术指标

- ✅ 检索延迟 <1秒
- ✅ LLM 响应 <5秒
- ✅ 系统可用性 >99%

### 9.3 成本优化

- ✅ 免费 embedding 模型
- ✅ 托管向量数据库（无需运维）
- ✅ 按需扩展

---

## 🚀 十、未来规划

### 短期 (1-2个月)
- [ ] 优化检索精度（reranking）
- [ ] 支持更多文档格式（PPTX、HTML）
- [ ] 添加检索结果评分

### 中期 (3-6个月)
- [ ] 多模态支持（图片、视频）
- [ ] 知识图谱增强
- [ ] 个性化推荐

### 长期 (6-12个月)
- [ ] Agent 化（工具调用）
- [ ] 多租户支持
- [ ] 离线部署方案

---

## 📞 十一、Q&A 准备

### Q1: 为什么不用 OpenAI Embeddings？

**A**: 
- 成本考虑：sentence-transformers 免费
- 一致性：建索引和查询同一模型
- 性能足够：384维向量已满足需求

### Q2: Weaviate 的成本如何？

**A**: 
- Weaviate Cloud 有免费 tier
- 当前数据量在免费范围内
- 按需扩展，成本可控

### Q3: 如何保证检索质量？

**A**: 
- 使用专业 embedding 模型
- top_k=5 平衡精度和速度
- 未来可加入 reranking

### Q4: 系统如何扩展？

**A**: 
- Weaviate Cloud 自动扩展
- 添加文档只需重新运行索引脚本
- LLM 通过 OpenAI API 自动扩展

---

**汇报时间**: 15-20 分钟  
**建议重点**: 架构设计、技术选型、性能指标