Enhance impact analysis and configuration for vector persistence and API integration. Update main.spec to clarify data handling for ChromaDB, ensuring vector directories are excluded from packaging. Modify Text2SQLOrchestrator to unify question normalization for consistent SQL generation across languages. Introduce SchemaIndexer improvements for persistent vector storage and optimize embedding retrieval processes. Update documentation and comments for clarity on configuration changes and behavior adjustments.

backend/schema/indexer.py

@@ -2,11 +2,13 @@
 Schema向量索引构建器 - 基于ChromaDB
 """
 
+import logging
+import os
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
 import chromadb
 from chromadb.config import Settings as ChromaSettings
-from typing import Any, List, Dict, Optional
-import logging
-from pathlib import Path
 
 from schema.manager import SchemaManager
 
@@ -20,31 +22,50 @@ class SchemaIndexer:
     功能：
     1. 为表结构构建向量索引
     2. 基于问题的表检索
-    3. Chroma 使用内存模式（EphemeralClient），进程退出后不保留；``persist_dir`` 仅作配置/统计引用
+    3. 默认使用 Chroma ``PersistentClient``，数据落在 ``persist_dir``（与 ``VECTOR_DB_PATH`` 一致）；
+       仅当环境变量 ``SCHEMA_INDEXER_EPHEMERAL=true`` 或构造参数 ``use_ephemeral=True`` 时使用内存客户端。
     """
 
     def __init__(
         self,
         embedder: Any,
-        persist_dir: str = "./data/embeddings",
+        persist_dir: str = "./data/embeddings/chroma",
         collection_name: str = "schema_tables",
+        *,
+        use_ephemeral: Optional[bool] = None,
     ):
         """
         初始化索引器
 
         Args:
             embedder: Embedding模型实例
-            persist_dir: 历史配置中的向量库路径（仅展示与统计，不落盘）
+            persist_dir: Chroma 持久化目录（默认与编排器 ``vector_db_path`` / ``VECTOR_DB_PATH`` 一致）
             collection_name: 集合名称
+            use_ephemeral: 为 True 时使用内存 Chroma；为 None 时读环境变量 SCHEMA_INDEXER_EPHEMERAL
         """
         self.embedder = embedder
         self.persist_dir = Path(persist_dir)
         self.collection_name = collection_name
 
-        # 内存 Chroma：不落盘，每次进程需重新 build_index
-        self.client = chromadb.EphemeralClient(
-            settings=ChromaSettings(anonymized_telemetry=False),
+        env_ephemeral = os.getenv("SCHEMA_INDEXER_EPHEMERAL", "").lower() in (
+            "1",
+            "true",
+            "yes",
         )
+        self._chroma_ephemeral = bool(use_ephemeral) if use_ephemeral is not None else env_ephemeral
+
+        if self._chroma_ephemeral:
+            self.client = chromadb.EphemeralClient(
+                settings=ChromaSettings(anonymized_telemetry=False),
+            )
+            backend_desc = "Chroma内存"
+        else:
+            self.persist_dir.mkdir(parents=True, exist_ok=True)
+            self.client = chromadb.PersistentClient(
+                path=str(self.persist_dir),
+                settings=ChromaSettings(anonymized_telemetry=False),
+            )
+            backend_desc = f"Chroma磁盘 path={self.persist_dir}"
 
         # 获取或创建集合
         self.collection = self.client.get_or_create_collection(
@@ -53,10 +74,50 @@ class SchemaIndexer:
         )
 
         logger.info(
-            f"[OK] 初始化SchemaIndexer(Chroma内存): collection={self.collection_name}, "
-            f"配置路径引用={self.persist_dir}"
+            f"[OK] 初始化SchemaIndexer({backend_desc}): collection={self.collection_name}, "
+            f"count={self.collection.count()}"
         )
 
+    def ensure_index_for_schema(
+        self,
+        schema_manager: SchemaManager,
+        batch_size: int = 32,
+    ) -> None:
+        """
+        每次使用向量粗筛前调用：若持久化集合中表条数与当前 Schema 一致且非空，则跳过向量化；
+        若为空则全量构建；若条数不一致则强制重建（Schema 变更后重新加载）。
+        """
+        expected = len(schema_manager.get_tables())
+        indexed = self.count()
+
+        if expected == 0:
+            if indexed > 0:
+                logger.warning("当前 Schema 无表但向量索引非空，已清空索引")
+                self.clear()
+            return
+
+        if indexed == expected:
+            logger.info(
+                "Schema 向量索引已就绪（%s 张表），跳过向量化",
+                indexed,
+            )
+            return
+
+        if indexed == 0:
+            logger.info(
+                "向量索引为空，开始构建共 %s 张表（向量化）...",
+                expected,
+            )
+            self.build_index(schema_manager, batch_size=batch_size, force_rebuild=False)
+            return
+
+        logger.info(
+            "向量索引与当前 Schema 不一致（索引 %s 张，Schema %s 张），重新向量化并加载...",
+            indexed,
+            expected,
+        )
+        self.build_index(schema_manager, batch_size=batch_size, force_rebuild=True)
+
     def build_index(
         self,
         schema_manager: SchemaManager,
@@ -250,5 +311,5 @@ class SchemaIndexer:
             "total_columns": total_columns,
             "avg_columns": total_columns / count if count > 0 else 0,
             "persist_dir": str(self.persist_dir),
-            "chroma_mode": "memory",
+            "chroma_mode": "memory" if self._chroma_ephemeral else "persistent",
         }