ai-g3sb-backman2.0/IMPACT_ANALYSIS.md

# 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` | 已删除。 |