Spaces:
Sleeping
Sleeping
| # 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 | |