Switch to OpenAI embedding (text-embedding-3-small) for Weaviate retrieval

OPENAI_EMBEDDING_SETUP.md

@@ -0,0 +1,77 @@
+# OpenAI Embedding 配置说明
+
+ClareVoice 现在使用 **OpenAI `text-embedding-3-small`** 进行 Weaviate 向量数据库的 embedding 和检索。
+
+## 1. 在 Hugging Face Space 中配置 API Key
+
+### 步骤：
+1. 访问你的 ClareVoice Space: https://huggingface.co/spaces/claudqunwang/ClareVoice
+2. 点击右上角的 **Settings**（设置）
+3. 在左侧菜单找到 **Secrets**（密钥）
+4. 添加或更新以下 Secret：
+   - **Key**: `OPENAI_API_KEY`
+   - **Value**: `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`
+5. 点击 **Save**（保存）
+
+### 重要提示：
+- 保存后，Space 会自动重启
+- 如果 Space 已经在运行，重启后新的 API key 才会生效
+- 确保 `WEAVIATE_URL` 和 `WEAVIATE_API_KEY` 也已正确配置在 Secrets 中
+
+## 2. 本地开发配置
+
+如果你在本地运行 ClareVoice，在项目根目录创建 `.env` 文件：
+
+```bash
+OPENAI_API_KEY=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
+WEAVIATE_URL=https://your-weaviate-cluster-url
+WEAVIATE_API_KEY=your-weaviate-api-key
+WEAVIATE_COLLECTION=GenAICourses
+```
+
+## 3. 重建 Weaviate 索引（如果需要）
+
+如果你需要重新构建 Weaviate 向量数据库索引以使用 OpenAI embedding：
+
+1. 进入 `hf_space/GenAICoursesDB_space/` 目录
+2. 设置环境变量：
+   ```bash
+   export OPENAI_API_KEY=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
+   export EMBEDDING_PROVIDER=openai
+   export WEAVIATE_URL=your-weaviate-url
+   export WEAVIATE_API_KEY=your-weaviate-key
+   ```
+3. 运行索引构建脚本：
+   ```bash
+   python build_weaviate_index.py
+   ```
+
+## 4. 技术细节
+
+### Embedding 模型
+- **模型**: `text-embedding-3-small`
+- **维度**: 1536
+- **提供商**: OpenAI API
+
+### 代码位置
+- `app.py`: `_get_weaviate_embed_model()` 函数
+- `server.py`: `_get_weaviate_embed_model()` 函数
+- 两者都使用相同的 OpenAI embedding 配置，确保检索时与索引构建时一致
+
+### 优势
+- **一致性**: 检索和索引使用相同的 embedding 模型
+- **质量**: OpenAI embedding 通常比本地 HuggingFace 模型质量更高
+- **性能**: 通过 API 调用，无需本地加载模型
+
+## 5. 验证配置
+
+启动 ClareVoice 后，检查日志输出：
+- 应该看到 `[ClareVoice] Weaviate 直连: 已配置`
+- 如果看到 `OPENAI_API_KEY is required for Weaviate embedding` 错误，说明 API key 未正确配置
+
+## 注意事项
+
+⚠️ **安全提示**: 
+- 不要在代码中硬编码 API key
+- 使用 Hugging Face Secrets 或 `.env` 文件（已加入 `.gitignore`）
+- 定期轮换 API key 以提高安全性

app.py

@@ -115,12 +115,16 @@ def _warmup_weaviate_embed():
 
 
 def _get_weaviate_embed_model():
-    """懒加载并缓存 embedding 模型（与建索引时一致）。"""
+    """懒加载并缓存 embedding 模型（使用 OpenAI text-embedding-3-small，与建索引时一致）。"""
     global _WEAVIATE_EMBED_MODEL
     if _WEAVIATE_EMBED_MODEL is None:
-        from llama_index.embeddings.huggingface import HuggingFaceEmbedding
-        _WEAVIATE_EMBED_MODEL = HuggingFaceEmbedding(
-            model_name="sentence-transformers/all-MiniLM-L6-v2"
+        from llama_index.embeddings.openai import OpenAIEmbedding
+        from config import OPENAI_API_KEY
+        if not OPENAI_API_KEY:
+            raise RuntimeError("OPENAI_API_KEY is required for Weaviate embedding")
+        _WEAVIATE_EMBED_MODEL = OpenAIEmbedding(
+            model="text-embedding-3-small",
+            api_key=OPENAI_API_KEY,
         )
     return _WEAVIATE_EMBED_MODEL
 

server.py

@@ -62,10 +62,17 @@ if not preloaded_topics:
 _WEAVIATE_EMBED_MODEL = None
 
 def _get_weaviate_embed_model():
+    """使用 OpenAI text-embedding-3-small（与建索引时一致）。"""
     global _WEAVIATE_EMBED_MODEL
     if _WEAVIATE_EMBED_MODEL is None:
-        from llama_index.embeddings.huggingface import HuggingFaceEmbedding
-        _WEAVIATE_EMBED_MODEL = HuggingFaceEmbedding(model_name="sentence-transformers/all-MiniLM-L6-v2")
+        from llama_index.embeddings.openai import OpenAIEmbedding
+        from config import OPENAI_API_KEY
+        if not OPENAI_API_KEY:
+            raise RuntimeError("OPENAI_API_KEY is required for Weaviate embedding")
+        _WEAVIATE_EMBED_MODEL = OpenAIEmbedding(
+            model="text-embedding-3-small",
+            api_key=OPENAI_API_KEY,
+        )
     return _WEAVIATE_EMBED_MODEL
 
 def _retrieve_from_weaviate(question: str, top_k: int = 5, timeout_sec: float = 45.0) -> str: