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.
This commit is contained in:
陈辅元
@@ -206,3 +206,165 @@
|
||||
|-------------|------|
|
||||
| `USE_LOCAL_EMBEDDING`、`EMBEDDING_MODEL_PATH` | 代码不再读取；`.env` 中可删去以免误解。 |
|
||||
| CLI `--embedding-model` | 已删除。 |
|
||||
|
||||
---
|
||||
|
||||
# Impact Analysis Report — main.spec：向量持久化目录不落包（追加）
|
||||
|
||||
## 1. 改动概览
|
||||
|
||||
- **背景与目标**：在 PyInstaller 配置中明确约定「业务侧 Chroma/向量持久化目录」不加入 `datas`，避免误将 `data/embeddings` 等打入 onefile；实际打包行为与此前一致（`datas` 中本未包含上述目录）。
|
||||
- **涉及模块**：`main.spec`。
|
||||
- **改动类型**：配置说明 / 文档化。
|
||||
|
||||
## 2. 方法级改动
|
||||
|
||||
| 位置 | 变更 |
|
||||
|------|------|
|
||||
| `main.spec` 顶部注释与 `datas` | 写明 `VECTOR_DB_PATH`、`FEWSHOT_CHROMA_PATH` 对应目录外置；区分 chromadb **wheel 依赖**与**用户向量库文件**；`EXE` 处注释澄清 `a.datas` 含义。 |
|
||||
|
||||
## 3. 调用方与影响范围
|
||||
|
||||
- **调用方**：仅 `pyinstaller main.spec` 打包流程；运行时仍依赖环境变量或旁路目录提供向量库（与代码逻辑无变更）。
|
||||
- **破坏性变更**：否。
|
||||
|
||||
## 4. 风险与回滚
|
||||
|
||||
- **风险级别**：低。
|
||||
- **回滚**：还原 `main.spec` 对应注释块。
|
||||
|
||||
**回滚方式是否简单**：是。
|
||||
|
||||
## 5. 验证与测试
|
||||
|
||||
- 打包前确认 `datas` 无 `data/embeddings` 等元组；打包后 exe 旁按需放置向量目录并配置 `.env`。
|
||||
|
||||
---
|
||||
|
||||
# Impact Analysis Report — 前端默认 NL API 地址（追加）
|
||||
|
||||
## 1. 改动概览
|
||||
|
||||
- **目标**：前端开发与 UAT 打包默认后端 origin 改为 `http://0.0.0.0:8041`；同 host 解析时默认端口改为 `8041`。
|
||||
- **涉及模块**：`ai-g3sb-backman-web/vite.config.ts`（`VITE_DEV_API_TARGET` 默认值）、`ai-g3sb-backman-web/src/api/packagedOrigin.ts`、`ai-g3sb-backman-web/src/api/config.ts`；`src/locales/{zh,tw,en}.ts` 中管理端 API 占位示例同步。
|
||||
- **改动类型**：配置默认值变更。
|
||||
|
||||
## 2. 调用方与破坏性变更
|
||||
|
||||
- **调用方**：Vite 开发代理 `/g3sb`；非 test 构建注入的 `window.__BACKMAN_API_ORIGIN__` 与 `apiBase()` 默认打包 origin。
|
||||
- **破坏性变更**：否（仍可通过环境变量 `VITE_DEV_API_TARGET`、`VITE_PACKAGED_API_ORIGIN`、`VITE_PACKAGED_API_PORT` 覆盖）。
|
||||
|
||||
## 3. 风险与回滚
|
||||
|
||||
- **风险级别**：低。说明：浏览器直连 `0.0.0.0` 在部分环境下可能不如 `127.0.0.1` 可靠；若遇连接问题可改用 `VITE_*` 覆盖为实际可访问地址。
|
||||
- **回滚**：还原上述三处默认值或设置环境变量覆盖。
|
||||
|
||||
**回滚方式是否简单**：是。
|
||||
|
||||
## 4. 配置变更
|
||||
|
||||
| 项 | 说明 |
|
||||
|----|------|
|
||||
| `VITE_DEV_API_TARGET`（可选） | 未设置时默认 `http://0.0.0.0:8041`。 |
|
||||
| `PACKAGED_API_ORIGIN` / `VITE_PACKAGED_API_ORIGIN` | 代码内默认改为 `http://0.0.0.0:8041`。 |
|
||||
| `VITE_PACKAGED_API_PORT`（可选） | `same-host`/`auto` 时未设置则默认 `8041`。 |
|
||||
|
||||
---
|
||||
|
||||
# Impact Analysis Report — SchemaIndexer 持久化 Chroma（追加）
|
||||
|
||||
## 1. 改动概览
|
||||
|
||||
- **背景与目标**：原先 `SchemaIndexer` 固定使用 `EphemeralClient`，进程内集合恒为空，每次请求粗筛都会全量计算约 2500+ 张表的 embedding；用户已在 `data/embeddings/chroma` 等目录落盘向量库，应直接复用。
|
||||
- **涉及模块**：`backend/schema/indexer.py`、`backend/agents/orchestrator.py`（日志与 `force_rebuild`）、`backend/utils/fewshot_chroma_store.py`（注释）、`main.spec`（打包说明注释）。
|
||||
- **改动类型**：缺陷修复 / 行为优化（性能与成本）。
|
||||
|
||||
## 2. 方法级改动
|
||||
|
||||
| 位置 | 变更 |
|
||||
|------|------|
|
||||
| `SchemaIndexer.__init__` | 默认 `chromadb.PersistentClient(path=persist_dir)`，创建目录；`SCHEMA_INDEXER_EPHEMERAL=true` 或 `use_ephemeral=True` 时仍为 `EphemeralClient`。默认 `persist_dir` 与 `VECTOR_DB_PATH` 对齐为 `./data/embeddings/chroma`。 |
|
||||
| `SchemaIndexer.get_statistics` | `chroma_mode` 区分 `persistent` / `memory`。 |
|
||||
| `Text2SQLOrchestrator._coarse_filter` | 每次粗筛前调用 `SchemaIndexer.ensure_index_for_schema`：索引条数与当前 Schema 表数一致则跳过向量化；空库则构建；不一致则 `force_rebuild` 重建。 |
|
||||
| `SchemaIndexer.ensure_index_for_schema`（新） | 对比 `collection.count()` 与 `len(schema_manager.get_tables())`，避免无意义重复向量化，并在 Schema 增删表后自动重载索引。 |
|
||||
|
||||
## 3. 调用方与影响范围
|
||||
|
||||
- **调用方**：`Text2SQLOrchestrator._get_vector_index()` 传入的 `persist_dir` 仍为 `vector_db_path` / 环境变量 `VECTOR_DB_PATH`；向量粗筛路径经 `ensure_index_for_schema`。
|
||||
- **破坏性变更**：否。若依赖「每次进程冷启动强制空向量库」的测试，需设置 `SCHEMA_INDEXER_EPHEMERAL=true`。
|
||||
|
||||
## 4. 风险与回滚
|
||||
|
||||
- **风险级别**：低。说明：Embedding 模型或维度变更时，旧持久化向量与当前 encoder 不一致可能导致检索质量下降，需删除目录或调用带 `force_rebuild` 的构建逻辑重建。
|
||||
- **回滚**：还原 `indexer.py` 相关提交或设置 `SCHEMA_INDEXER_EPHEMERAL=true`。
|
||||
|
||||
**回滚方式是否简单**：是。
|
||||
|
||||
## 5. 配置变更
|
||||
|
||||
| 项 | 说明 |
|
||||
|----|------|
|
||||
| `VECTOR_DB_PATH` | 既有；默认 `./data/embeddings/chroma`，现为 Schema Chroma 真实持久化根路径。 |
|
||||
| `SCHEMA_INDEXER_EPHEMERAL`（可选） | 设为 `true`/`1`/`yes` 时使用内存 Chroma（与旧行为一致）。 |
|
||||
|
||||
---
|
||||
|
||||
# Impact Analysis Report — 中英文问句归一以提升 SQL 一致性（追加）
|
||||
|
||||
## 1. 改动概览
|
||||
|
||||
- **背景与目标**：同一业务语义分别用中文、英文提问时，原先仅对「纯英文」问句做英译中，中文问句原样进入检索/生成，导致与英文路径的表述不一致，向量粗筛与 SQL 可能分叉。
|
||||
- **涉及模块**：`backend/config/prompts.py`（归一提示词 + SQL_GENERATOR 约束）、`backend/llm/deepseek_client.py`、`backend/agents/orchestrator.py`、`backend/main.py`（CLI 帮助文案）。
|
||||
- **改动类型**：行为优化；默认仍受 `TRANSLATE_EN_TO_ZH` / `--no-translate-en` 控制。
|
||||
|
||||
## 2. 方法级改动
|
||||
|
||||
| 位置 | 变更 |
|
||||
|------|------|
|
||||
| `DeepSeekClient.normalize_nl_question_for_text2sql` | 新增：`temperature=0` 下将中/英问句归一为一句中文。 |
|
||||
| `DeepSeekClient.translate_nl_question_to_zh` | 改为委托上述方法（兼容旧名）。 |
|
||||
| `Text2SQLOrchestrator.generate` | 当 `translate_english_to_zh` 为 True 时，对**所有**非空问句调用归一（不再仅限 `looks_like_english_only`）。 |
|
||||
| `SQL_GENERATOR_SYSTEM` | 新增硬性约束第 6 条：中英文同义时 SQL 逻辑须一致。 |
|
||||
|
||||
## 3. 调用方与破坏性变更
|
||||
|
||||
- **调用方**：所有经 `generate()` 的 Text2SQL 请求（含 `api_server` 默认 `TRANSLATE_EN_TO_ZH` 开启时）。
|
||||
- **破坏性变更**：否。关闭归一：`TRANSLATE_EN_TO_ZH=false` 或 `--no-translate-en` / `Args.no_translate_en`，行为与改动前「中文不归一、英文仍可不译」一致。
|
||||
|
||||
## 4. 风险与回滚
|
||||
|
||||
- **风险级别**：低～中。每次成功归一增加一次 LLM 调用（延迟与 token）；归一失败时回退原文（与旧失败策略一致）。
|
||||
- **回滚**：关闭环境变量或还原相关文件。
|
||||
|
||||
**回滚方式是否简单**：是。
|
||||
|
||||
## 5. 配置变更
|
||||
|
||||
| 项 | 说明 |
|
||||
|----|------|
|
||||
| `TRANSLATE_EN_TO_ZH` | 语义扩展为「是否做问句归一中文」；`false` 关闭额外 LLM 归一步骤。 |
|
||||
|
||||
---
|
||||
|
||||
# Impact Analysis Report — Few-shot Chroma 默认读盘（追加）
|
||||
|
||||
## 1. 改动概览
|
||||
|
||||
- **问题**：`FEWSHOT_USE_CHROMA=true` 时 `FewShotChromaStore` 仍默认 `EphemeralClient`，进程内 `count` 恒为 0，每次启动从 JSONL 重算 embedding，忽略已灌库的 `data/embeddings/chroma_fewshot`。
|
||||
- **模块**：`backend/utils/fewshot_chroma_store.py`。
|
||||
- **类型**：缺陷修复。
|
||||
|
||||
## 2. 行为变更
|
||||
|
||||
| 项 | 说明 |
|
||||
|----|------|
|
||||
| 默认 | `persist_to_disk=None` 时默认使用 `PersistentClient`（`FEWSHOT_CHROMA_PATH` 或 `./data/embeddings/chroma_fewshot`）。 |
|
||||
| 退出 | `FEWSHOT_CHROMA_EPHEMERAL=true` 或构造参数 `persist_to_disk=False` 时仍为内存 Chroma。 |
|
||||
|
||||
## 3. 破坏性变更
|
||||
|
||||
- **否**。灌库脚本显式 `persist_to_disk=True` 不变。
|
||||
|
||||
## 4. 配置
|
||||
|
||||
| `FEWSHOT_CHROMA_EPHEMERAL` | 可选；`true` 时与旧版「仅内存」行为一致。 |
|
||||
|
||||
Reference in New Issue
Block a user