element.chen/ai-g3sb-backman2.0
1
0
Fork 0
Code Pull Requests Activity
Files
a55fd18915197da01e745ead8fc04c9133bf1b0e
ai-g3sb-backman2.0/IMPACT_ANALYSIS.md
T

371 lines
19 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Impact Analysis Report — 会话上文注入 Text2SQL
## 1. 改动概览
- **背景与目标**：在带 `session_id` 的 NL 对话中，将前几轮已落库的对话摘要注入选表、向量粗筛、SQL 生成与「无数据」说明，支持续问与指代消解。
- **涉及模块**：`api_server.py`、`backend/utils/dialog_context.py`（新）、`backend/utils/dialog_classifier.py`、`backend/agents/orchestrator.py`。
- **改动类型**：功能新增（向后兼容：无 `session_id` 或空历史时行为与原先一致）。
## 2. 方法级改动
| 位置 | 变更 |
|------|------|
| `LiteNlStore` | 无变更；仍由 `_append_session_if_needed` 在应答后写入。 |
| `_load_session_text2sql_context`（api_server） | 新增：读 `get_messages`，构造上文块，并判断上一轮是否为数据查询。 |
| `classify_dialog` | 新增可选关键字参数 `last_turn_was_data_query`；为 True 时在非寒暄/非元问题下将输入倾向判为 TEXT2SQL。 |
| `messages_to_text2sql_context` 等 | 新工具：消息列表 → 可读摘要；解析 assistant JSON。 |
| `Text2SQLOrchestrator.generate` | 新增可选 `dialog_context`；粗筛/选表/续问 broker 优先/生成/无数据反馈使用该上文。 |
| `_generate_sql` / `_validate_sql` | 接收 `dialog_context`，Few-shot 检索问题与生成 user 提示含上文。 |
## 3. 调用方与影响范围
- **调用方**：`/g3sb/api/nl/chat`、`/g3sb/api/nl/chat/stream`（仅当请求带有效 `session_id` 且会话内已有历史消息时生效）。
- **CLI `backend/main.py` `single_query`**：现传入 `llm_client`；当 `DIALOG_INTENT_CLASSIFIER=rules` 时与旧规则行为一致。
- **破坏性变更**：否（新增可选参数与默认 `False` 的关键字参数）。
## 4. 风险与回滚
- **风险级别**：中（依赖会话中 assistant 内容为合法 JSON；解析失败时上文退化为截断原文或空段）。
- **额外成本**：带历史的请求 prompt 更长，token 与耗时可能上升。
- **回滚**：回退本提交即可；无配置开关。
**回滚方式是否简单**：是。
## 5. 验证与测试
- 已执行：`python -m py_compile` 对改动文件语法检查。
- 建议手工：创建 session → 首轮数据查询 → 次轮「按上个月再查一遍」类续问，确认走 TEXT2SQL 且 SQL 与上文一致。
## 6. 配置变更
- 无。
---
# Impact Analysis Report — 库探针追问与交付分支（追加）
## 1. 改动概览
- **目标**：对齐库探针语义：`0` 无行时返回 SQL + 问题分析 + 固定追问引导重生成；`1` 有行时由 LLM 生成简短交付说明并返回 SQL；`-1` 失败时明确文案并走既有重试。
- **涉及模块**：`backend/agents/orchestrator.py`、`backend/llm/deepseek_client.py`、`backend/config/prompts.py`、`api_server.py`（`DataQueryResult` 字段）、`backend/utils/dialog_context.py`（摘要）。
## 2. 破坏性变更
- **否**（API 新增可选字段；未配置 `database_url` 时行为与原先一致）。
## 3. 风险
- **低～中**：探针为 `1` 时增加一次 LLM 调用（延迟与 token）；失败时降级为仅返回 SQL。
## 4. 验证
- `python -m py_compile` 覆盖改动文件。
---
# Impact Analysis Report — Few-shot 写入 Chroma（追加）
## 1. 改动概览
- **目标**：将 `all_samples.jsonl` 写入 Chroma 持久化向量库；`FEWSHOT_USE_CHROMA=true` 时 `FewShotSelector` 从 Chroma 检索，否则仍用内存 + `.npy` 缓存。
- **新增**：`backend/utils/fewshot_chroma_store.py`、`scripts/build_fewshot_chroma_index.py`；`.env` 增加注释说明；`FewShotSelector` 扩展参数与分支逻辑。
## 2. 破坏性变更
- **否**（默认 `FEWSHOT_USE_CHROMA` 未开启时行为不变）。
## 3. 风险
- **中**：Chroma metadata 对单字段长度有限制，超长 SQL/说明在入库时截断；换 Embedding 模型后应 `--force` 重建索引。
## 4. 验证
- `python -m py_compile` 已通过相关文件。
**追加（Chroma 优先、JSONL 可选）**：`FEWSHOT_USE_CHROMA=true` 且未设置 `FEWSHOT_DATA_PATH` 时，编排器默认不再读 JSONL；`FewShotSelector` 支持无文件 + Chroma 检索；`get_stats` / `get_tagged_examples` 在无内存样本时从 Chroma 全量导出统计。
**追加（Embedding 默认远程）**：移除对 `data/models/Qwen3-Embedding-0.6B` 的默认依赖；`USE_LOCAL_EMBEDDING` 默认视为 `false`；`get_embedder` / `setup_environment` / `EMBEDDING_MODEL_PATH` 与文档对齐为「远程 OpenAI 兼容等优先，本地仅显式开启」。
---
# Impact Analysis Report — Workbuddy Markdown → JSONL（追加）
## 1. 改动概览
- **目标**：将 `data/常问问题对应SQL_50个问题知识库_Workbuddy生成.md` 转为与 `data/experiences/all_samples.jsonl` 同结构的 JSONL，并保证每条含 `question_en`（英文题干）。
- **新增**：`scripts/md_workbuddy_to_jsonl.py`；产出 `data/experiences/workbuddy_50_questions.jsonl`（50 行）。
- **改动类型**：数据与脚本（可重复生成）。
## 2. 方法级说明
- 解析 Markdown 中 `## Qn` 节：`### 问题`（中英分行）、全部 `` ```sql `` 块（去重拼接）、`### SQL执行结果` / 内联结果、`### SQL理由`、`### SQL准确度评分`。
- 与 `all_samples.jsonl` 按 `qid` 合并 `schema_info`、`tags`、`difficulty`；正文覆盖 `question_zh`、`question_en`、`sql`、`explanation`、`rating`、`result_note`。
- 写出 JSONL 时字段顺序固定为：`question_zh` 后紧跟 **`question_en`**（便于在极长单行里肉眼看到英文题干）。
- **Q50**：Markdown 仅有中文问题；脚本补充 `question_en`：`List all client trade records for today.`
## 3. 调用方与破坏性变更
- **调用方**：无运行时自动引用；需手工执行 `python scripts/md_workbuddy_to_jsonl.py` 或下游自行读 JSONL。
- **破坏性变更**：否。
## 4. 风险与回滚
- **风险**：低（生成物可被版本管理；`schema_info` 与含多段 SQL 的题目可能不完全一致，仍以 `all_samples` 为基线）。
- **回滚**：删除脚本与 JSONL，或从 Git 回退。
**回滚方式是否简单**：是。
## 5. 验证
- 已执行：`python scripts/md_workbuddy_to_jsonl.py`；校验 50 行且 `question_en` 均非空。
## 6. 配置变更
- 无。
---
# Impact Analysis Report — 对话意图 hybrid + LLM（追加）
## 1. 改动概览
- **背景与目标**：纯规则在「上一轮为数据查询」时把「结果不对」等反馈误判为 TEXT2SQL；改为默认 **hybrid**：明显查数词/寒暄/元问题仍走规则，其余由 **LLM 输出 JSON** 判定 `text2sql` / `conversation`。
- **涉及模块**：`backend/utils/dialog_classifier.py`、`backend/config/prompts.py`（`DIALOG_INTENT_CLASSIFIER_*`）、`api_server.py`、`backend/main.py`。
- **改动类型**：功能调整（默认多一次小 LLM 调用；可配置关闭）。
## 2. 方法级改动
| 位置 | 变更 |
|------|------|
| `classify_dialog` | 新增可选参数 `dialog_context`、`llm_client`；引入 `_classify_dialog_rules`、`_classify_dialog_llm`；读环境变量 `DIALOG_INTENT_CLASSIFIER`。 |
| `api_server` 流式/非流式 NL | 在分类前 `get_orchestrator()`，用 `asyncio.to_thread(classify_dialog, ..., llm_client=orch.deepseek)` 避免阻塞事件循环。 |
| `single_query` | `classify_dialog(question, llm_client=orchestrator.deepseek)` 与 API 对齐。 |
## 3. 调用方与影响范围
- **调用方**：`/g3sb/api/nl/chat`、`/g3sb/api/nl/chat/stream`、`single_query`。
- **破坏性变更**：否；`DIALOG_INTENT_CLASSIFIER=rules` 时与原先规则路径一致（无 LLM 意图调用）。
## 4. 风险与回滚
- **风险级别**：中（每轮非「快速命中」类输入增加一次短 LLM 调用：延迟与费用；JSON 异常时回退规则）。
- **回滚**：设 `DIALOG_INTENT_CLASSIFIER=rules` 或回退代码提交。
**回滚方式是否简单**：是。
## 5. 验证与测试
- 建议手工：`hybrid` 下首轮查数 → 次轮「这个结果不正确呀」应判为 conversation 并返回引导文案，不跑选表/SQL 链路。
## 6. 配置变更
| 配置项 | 含义 | 默认 |
|--------|------|------|
| `DIALOG_INTENT_CLASSIFIER` | `hybrid`：规则快速路径 + LLM；`rules`：仅规则 | `hybrid`（未设置时按 hybrid 处理） |
---
# Impact Analysis — 移除本地 Embedding（仅远程 API）
## 1. 改动概览
- **背景与目标**：不再维护本地 HuggingFace / PyTorch 推理路径；Embedding 统一为 OpenAI 兼容远程 `/v1/embeddings`。
- **涉及模块**：`backend/utils/embedding.py`、`backend/main.py`、`backend/agents/orchestrator.py`、`backend/utils/fewshot_selector.py`、`backend/config/settings.py`、`api_server.py`、`scripts/build_fewshot_chroma_index.py`、`pyproject.toml`、`requirements.txt`、`main.spec`、`README.md`、`.env` 注释。
- **改动类型**：功能删减 / 依赖精简。
## 2. 方法级改动
| 位置 | 变更 |
|------|------|
| `Qwen3Embedding`（原） | **删除**；本地 `transformers`+`torch` 编码路径移除。 |
| `get_embedder` | 仅构造 `OpenAICompatibleRemoteEmbedding`；前两个位置参数废弃保留以兼容旧调用。 |
| `clear_embedder` | 仅 `gc.collect()`，不再触碰 CUDA。 |
| `Text2SQLOrchestrator.__init__` | 移除 `embedding_model_path`；`FewShotSelector` 不再传模型路径。 |
| `FewShotSelector.__init__` | 移除 `embedding_model_path`。 |
| `setup_environment` | 删除 `USE_LOCAL_EMBEDDING` / `EMBEDDING_MODEL_PATH` 分支。 |
## 3. 调用方与影响范围
- **调用方**：所有原 `get_embedder(path)` 仍可运行（路径被忽略）；`Text2SQLOrchestrator(..., embedding_model_path=...)` 需改为不传该参数（已改仓库内引用）。
- **破坏性变更**：**是**——不再支持 `USE_LOCAL_EMBEDDING=true` 与本地模型目录；`pyproject.toml` / `requirements.txt` 不再声明 `torch`/`transformers`/`sentencepiece`/`accelerate`/`safetensors`（若 `camel-ai[all]` 等仍带入部分传递依赖，以实际 lock 为准）。
## 4. 风险与回滚
- **风险级别**：中（仅使用本地 Embedding 的部署将失效；需改为远程 Key 与模型名）。
- **回滚**：回退提交并恢复依赖与 `embedding.py` 历史版本。
**回滚方式是否简单**：是（单提交回退）。
## 5. 验证与测试
- 建议：`python -m py_compile` 对改动 `.py`；在已配置 `OPENAI_*` 或 `MODELSCOPE_*` 的环境下跑一次 Schema 向量构建或 Few-shot 检索。
## 6. 配置变更
| 移除/失效项 | 说明 |
|-------------|------|
| `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` 时与旧版「仅内存」行为一致。 |
View Git Blame Copy Permalink