方案 A: 预构建索引 Dataset，启动时直接下载免 embedding

- 新增 build_and_upload_index.py 本地构建并上传索引
- 优先从 INDEX_DATASET_ID 下载预构建索引
- 默认 INDEX_DATASET_ID=claudqunwang/genai-courses-index

.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.pyc
+.env
+local_index_build/

README.md

@@ -28,10 +28,35 @@ Space 在启动时从 Dataset 下载课程目录后再构建/加载索引。
 - **可选**：`GENAI_COURSES_DATASET_ID`（默认：`claudqunwang/genai-courses-data`）
 - **可选**：`GENAI_COURSES_DATASET_SUBDIR`（默认：`GENAI COURSES`）
 - **可选**：`HF_EMBEDDING_MODEL`（免费方案时生效，默认：`sentence-transformers/all-MiniLM-L6-v2`）
+- **可选（方案 A）**：`INDEX_DATASET_ID`（预构建索引 Dataset，设置后启动时直接下载，无需 embedding）
 
 ## 使用方式
 
-打开 Space 页面后直接提问即可；首次启动或勾选“强制重建索引”会花更久（因为需要做 Embedding）。使用免费 embedding 时首次会下载模型，可能稍慢。
+打开 Space 页面后直接提问即可。
+
+### 方案 A：预构建索引（启动快，无需每次 embedding）
+
+若配置了预构建索引，Space 启动时**直接下载索引**，几秒内就绪，不再做 embedding。
+
+**步骤：**
+
+1. **创建索引 Dataset**：在 [huggingface.co/datasets](https://huggingface.co/datasets) 点击 **Create new dataset**，名称如 `genai-courses-index`。
+
+2. **本地构建并上传**（需有 `GENAI COURSES` 目录）：
+   ```bash
+   cd hf_space/GenAICoursesDB_space
+   # 设置与 Space 一致（推荐用免费 embedding）
+   export EMBEDDING_PROVIDER=huggingface
+   # 若用默认 Dataset，可设置 INDEX_DATASET_ID=你的用户名/genai-courses-index
+   python build_and_upload_index.py
+   ```
+
+3. **Space 配置**：在 GenAICoursesDB Space → **Settings → Variables** 添加：
+   - `INDEX_DATASET_ID` = `你的用户名/genai-courses-index`
+
+4. **重启 Space**：下次启动将从 Dataset 下载索引，无需重新 embedding。
+
+**未配置预构建时**：首次启动或勾选“强制重建索引”会从课程 Dataset 下载并构建，耗时较长（需做 Embedding）。
 
 ## Clare 方案三：外部调用 retrieve 接口
 

app.py

@@ -1,5 +1,6 @@
 import os
 from pathlib import Path
+from typing import Optional, Tuple
 
 import gradio as gr
 from dotenv import load_dotenv
@@ -20,6 +21,9 @@ load_dotenv()
 DATASET_ID = (os.getenv("GENAI_COURSES_DATASET_ID") or "claudqunwang/genai-courses-data").strip()
 DATASET_SUBDIR = (os.getenv("GENAI_COURSES_DATASET_SUBDIR") or "GENAI COURSES").strip()
 
+# 方案 A：预构建索引 Dataset。若设置，Space 启动时直接下载加载，无需重新 embedding
+INDEX_DATASET_ID = (os.getenv("INDEX_DATASET_ID") or "claudqunwang/genai-courses-index").strip()
+
 # Hugging Face Spaces 没有持久化磁盘时，每次重启可能需要重建索引
 PERSIST_DIR = Path(os.getenv("GENAI_INDEX_DIR") or "/tmp/genai_courses_index").resolve()
 
@@ -133,6 +137,31 @@ def _get_courses_dir() -> Path:
     return courses_dir
 
 
+def _download_and_load_prebuilt_index() -> Tuple[bool, Optional["VectorStoreIndex"]]:
+    """方案 A：从 INDEX_DATASET_ID 下载预构建索引并加载到 PERSIST_DIR。成功返回 True。"""
+    if not INDEX_DATASET_ID:
+        return False, None
+    try:
+        import shutil
+        if PERSIST_DIR.exists():
+            shutil.rmtree(PERSIST_DIR)
+        PERSIST_DIR.mkdir(parents=True, exist_ok=True)
+        from huggingface_hub import snapshot_download
+        snapshot_download(
+            repo_id=INDEX_DATASET_ID,
+            repo_type="dataset",
+            local_dir=str(PERSIST_DIR),
+            local_dir_use_symlinks=False,
+        )
+        storage_context = StorageContext.from_defaults(persist_dir=str(PERSIST_DIR))
+        idx = load_index_from_storage(storage_context)
+        print(f"[index] 已从预构建索引加载: {INDEX_DATASET_ID}")
+        return True, idx
+    except Exception as e:
+        print(f"[index] 预构建索引加载失败: {repr(e)}")
+        return False, None
+
+
 def get_index(force_rebuild: bool = False) -> VectorStoreIndex:
     _ensure_openai_key()
 
@@ -144,6 +173,19 @@ def get_index(force_rebuild: bool = False) -> VectorStoreIndex:
         except Exception as e:
             print(f"[index] load failed, rebuilding: {repr(e)}")
 
+    # 方案 A：优先尝试从预构建索引 Dataset 下载
+    if not force_rebuild and INDEX_DATASET_ID:
+        ok, idx = _download_and_load_prebuilt_index()
+        if ok and idx is not None:
+            return idx
+        if PERSIST_DIR.exists():
+            try:
+                import shutil
+                shutil.rmtree(PERSIST_DIR)
+            except Exception:
+                pass
+        PERSIST_DIR.mkdir(parents=True, exist_ok=True)
+
     courses_dir = _get_courses_dir()
     print(f"[index] building from: {courses_dir}")
 
@@ -234,11 +276,13 @@ def retrieve_chunks(question: str, top_k: int = 5) -> str:
 
 def status_md() -> str:
     emb_line = f"- **Embedding**: `{EMBEDDING_PROVIDER}` (免费)" if EMBEDDING_PROVIDER == "huggingface" else f"- **Embedding**: OpenAI (付费)"
+    idx_src = f"- **索引来源**: 预构建 `{INDEX_DATASET_ID}`" if INDEX_DATASET_ID else "- **索引来源**: 运行时构建"
     if INDEX is not None:
         return (
             "✅ **Index ready**\n\n"
             f"- **Dataset**: `{DATASET_ID}`\n"
             f"- **Subdir**: `{DATASET_SUBDIR}`\n"
+            f"{idx_src}\n"
             f"{emb_line}\n"
             f"- **Index dir**: `{str(PERSIST_DIR)}`\n"
         )
@@ -246,6 +290,7 @@ def status_md() -> str:
         "⚠️ **Index not ready**\n\n"
         f"- **Dataset**: `{DATASET_ID}`\n"
         f"- **Subdir**: `{DATASET_SUBDIR}`\n"
+        f"{idx_src}\n"
         f"{emb_line}\n"
         f"- **Index dir**: `{str(PERSIST_DIR)}`\n\n"
         f"Error: `{INDEX_ERR or 'unknown'}`"

build_and_upload_index.py

@@ -0,0 +1,124 @@
+#!/usr/bin/env python3
+"""
+方案 A：本地构建索引并上传到 HF Dataset，Space 启动时直接下载加载，无需每次 embedding。
+
+用法：
+  1. 确保本地有 GENAI COURSES 目录（或设置从 Dataset 下载）
+  2. 安装依赖：pip install -r requirements.txt
+  3. 设置环境变量（与 Space 一致）：
+     - EMBEDDING_PROVIDER=huggingface  # 推荐，不花 OpenAI 钱
+     - 或 OPENAI_API_KEY=...  # 若用 OpenAI
+  4. 运行：python build_and_upload_index.py
+  5. 首次需创建 Dataset：https://huggingface.co/datasets/new
+     - 名称如 genai-courses-index
+     - 登录：huggingface-cli login 或 HF_TOKEN 环境变量
+
+上传后，在 Space 的 Variables 设置 INDEX_DATASET_ID=你的用户名/genai-courses-index
+"""
+import os
+import sys
+from pathlib import Path
+
+# 项目根目录
+SCRIPT_DIR = Path(__file__).resolve().parent
+PROJECT_ROOT = SCRIPT_DIR.parent.parent
+COURSES_DIR = PROJECT_ROOT / "GENAI COURSES"
+
+# 索引输出目录（本地）
+INDEX_OUTPUT = SCRIPT_DIR / "local_index_build"
+
+# Dataset 存储预构建索引
+INDEX_DATASET_ID = (os.getenv("INDEX_DATASET_ID") or "claudqunwang/genai-courses-index").strip()
+
+
+def build_index():
+    """与 app.py 相同的索引构建逻辑。"""
+    os.chdir(SCRIPT_DIR)
+    sys.path.insert(0, str(SCRIPT_DIR))
+
+    from dotenv import load_dotenv
+    load_dotenv(SCRIPT_DIR / ".env")
+    load_dotenv(PROJECT_ROOT / ".env")
+
+    # 必须在 import app 前设置，因为 app 会执行模块级 Settings
+    emb = os.getenv("EMBEDDING_PROVIDER", "huggingface").strip().lower()
+    if emb == "huggingface":
+        os.environ.setdefault("EMBEDDING_PROVIDER", "huggingface")
+
+    from llama_index.core import (
+        Settings,
+        SimpleDirectoryReader,
+        StorageContext,
+        VectorStoreIndex,
+        load_index_from_storage,
+    )
+
+    # Embedding 配置（与 app 一致）
+    if emb == "huggingface":
+        from llama_index.embeddings.huggingface import HuggingFaceEmbedding
+        hf_model = os.getenv("HF_EMBEDDING_MODEL", "sentence-transformers/all-MiniLM-L6-v2").strip()
+        Settings.embed_model = HuggingFaceEmbedding(model_name=hf_model)
+    else:
+        from llama_index.embeddings.openai import OpenAIEmbedding
+        Settings.embed_model = OpenAIEmbedding(model="text-embedding-3-small")
+
+    if not COURSES_DIR.exists():
+        raise FileNotFoundError(
+            f"课程目录不存在：{COURSES_DIR}\n"
+            "请将 GENAI COURSES 放在项目根目录，或修改脚本中的 COURSES_DIR。"
+        )
+
+    print(f"📂 读取课程目录: {COURSES_DIR}")
+    reader = SimpleDirectoryReader(
+        input_dir=str(COURSES_DIR),
+        recursive=True,
+        required_exts=[".md", ".pdf", ".txt", ".py", ".ipynb", ".docx"],
+    )
+    documents = reader.load_data()
+    print(f"📄 加载 {len(documents)} 个文档块，正在 embedding...")
+
+    index = VectorStoreIndex.from_documents(documents)
+    INDEX_OUTPUT.mkdir(parents=True, exist_ok=True)
+    index.storage_context.persist(persist_dir=str(INDEX_OUTPUT))
+    print(f"✅ 索引已保存到 {INDEX_OUTPUT}")
+    return INDEX_OUTPUT
+
+
+def upload_index(persist_dir: Path):
+    """将索引目录上传到 HF Dataset。"""
+    from huggingface_hub import HfApi
+
+    api = HfApi()
+    files = list(persist_dir.rglob("*"))
+    files = [f for f in files if f.is_file()]
+
+    if not files:
+        raise RuntimeError(f"索引目录为空: {persist_dir}")
+
+    print(f"📤 上传 {len(files)} 个文件到 {INDEX_DATASET_ID}...")
+    for f in files:
+        rel = f.relative_to(persist_dir)
+        path_in_repo = str(rel).replace("\\", "/")
+        api.upload_file(
+            path_or_fileobj=str(f),
+            path_in_repo=path_in_repo,
+            repo_id=INDEX_DATASET_ID,
+            repo_type="dataset",
+        )
+        print(f"  - {path_in_repo}")
+    print(f"✅ 上传完成: https://huggingface.co/datasets/{INDEX_DATASET_ID}")
+
+
+def main():
+    print("=" * 50)
+    print("GenAICoursesDB 索引构建与上传（方案 A）")
+    print("=" * 50)
+    persist_dir = build_index()
+    upload_index(persist_dir)
+    print("\n下一步：在 GenAICoursesDB Space 的 Variables 中添加：")
+    print(f"  INDEX_DATASET_ID={INDEX_DATASET_ID}")
+    print("Space 启动时将从此 Dataset 下载索引，无需重新 embedding。")
+
+
+if __name__ == "__main__":
+    main()