PRESENTATION_SUMMARY.md

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 分钟
建议重点: 架构设计、技术选型、性能指标