Add Weaviate index rebuild instructions

Co-authored-by: Cursor <cursoragent@cursor.com>

REBUILD_WEAVIATE_INDEX.md

@@ -0,0 +1,105 @@
+# 重建 Weaviate 索引（使用 OpenAI Embedding）
+
+由于 ClareVoice 已切换到使用 **OpenAI `text-embedding-3-small`** 进行 embedding，如果 Weaviate 向量数据库中的索引是用旧的 HuggingFace embedding 构建的，需要重新构建索引以确保检索一致性。
+
+## 前置条件
+
+1. **本地环境**：Python 3.8+，已安装所需依赖
+2. **Weaviate 配置**：需要 Weaviate Cloud 的 URL 和 API Key
+3. **OpenAI API Key**：已提供（见 `OPENAI_EMBEDDING_SETUP.md`）
+4. **课程文档**：确保项目根目录有 `GENAI COURSES` 文件夹
+
+## 步骤
+
+### 1. 安装依赖
+
+```bash
+cd hf_space/GenAICoursesDB_space
+pip install -r requirements.txt
+```
+
+### 2. 设置环境变量
+
+在项目根目录创建或更新 `.env` 文件：
+
+```bash
+# OpenAI API Key（用于 embedding）
+OPENAI_API_KEY=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
+
+# Weaviate 配置（从 Weaviate Cloud Console 获取）
+WEAVIATE_URL=https://your-cluster.c0.us-west3.gcp.weaviate.cloud
+WEAVIATE_API_KEY=your-weaviate-api-key
+
+# 使用 OpenAI embedding（默认）
+EMBEDDING_PROVIDER=openai
+
+# 可选：清空旧索引后重建（默认：1，即清空）
+WEAVIATE_CLEAR_FIRST=1
+```
+
+### 3. 运行索引构建脚本
+
+```bash
+cd hf_space/GenAICoursesDB_space
+python build_weaviate_index.py
+```
+
+脚本会：
+1. 读取 `GENAI COURSES` 目录下的所有文档（.md, .pdf, .txt, .py, .ipynb, .docx）
+2. 使用 OpenAI `text-embedding-3-small` 生成 embedding
+3. 上传到 Weaviate Cloud（collection: `GenAICourses`）
+4. 显示最终的对象数量以验证
+
+### 4. 验证
+
+脚本完成后会显示：
+```
+✅ 索引已上传，当前 object count = [数量]
+```
+
+如果数量为 0，请检查：
+- `WEAVIATE_URL` 是否与 Weaviate Console 中的 REST 地址一致
+- 是否使用同一 Weaviate 账号
+- 网络连接是否正常
+
+### 5. 在 Hugging Face Space 中配置
+
+确保 ClareVoice Space 的 **Settings → Secrets** 中已配置：
+
+- `OPENAI_API_KEY`：用于检索时的 embedding
+- `WEAVIATE_URL`：Weaviate Cloud REST 地址
+- `WEAVIATE_API_KEY`：Weaviate API Key
+- `WEAVIATE_COLLECTION`：`GenAICourses`（默认）
+
+## 注意事项
+
+⚠️ **重要**：
+- 重建索引会**清空**旧的 `GenAICourses` collection（如果 `WEAVIATE_CLEAR_FIRST=1`）
+- 确保在重建前备份重要数据（如果需要）
+- 重建过程可能需要几分钟到几十分钟，取决于文档数量
+- 索引构建完成后，ClareVoice 的检索将使用新的 OpenAI embedding，与索引构建时一致
+
+## 故障排除
+
+### 错误：`OPENAI_API_KEY is required`
+- 检查 `.env` 文件中的 `OPENAI_API_KEY` 是否正确设置
+- 确保环境变量已加载（脚本会自动加载 `.env`）
+
+### 错误：`Weaviate 连接失败`
+- 检查 `WEAVIATE_URL` 格式是否正确（应以 `https://` 开头）
+- 验证 `WEAVIATE_API_KEY` 是否有效
+- 确认网络连接正常
+
+### 错误：`课程目录不存在`
+- 确保项目根目录有 `GENAI COURSES` 文件夹
+- 检查路径是否正确（脚本从 `hf_space/GenAICoursesDB_space` 运行，会查找 `../../GENAI COURSES`）
+
+### 索引构建成功但 object count = 0
+- 检查 Weaviate Console 中的 collection 名称是否匹配（应为 `GenAICourses`）
+- 确认使用的是同一 Weaviate 集群和账号
+- 等待几秒钟后再次检查（可能有延迟）
+
+## 相关文档
+
+- `OPENAI_EMBEDDING_SETUP.md`：OpenAI embedding 配置说明
+- `build_weaviate_index.py`：索引构建脚本源码