OPENAI_EMBEDDING_SETUP.md

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 文件：

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. 设置环境变量：

   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. 运行索引构建脚本：

   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 以提高安全性