0.1.1 暂存

IMPACT_ANALYSIS.md

@@ -0,0 +1,109 @@
+# Impact Analysis Report — NL2SQL 确定性（temperature）
+
+## 1. 改动概览
+
+- **背景与目标**：同一中文问题多次请求时，选表与生成 SQL 因 LLM 采样（默认 `temperature=0.3`）出现不一致。
+- **涉及模块**：`backend/llm/deepseek_client.py`（选表、校验、便捷 `generate_sql`）、`backend/agents/orchestrator.py`（编排器内 SQL 生成）。
+- **改动类型**：缺陷修复 / 行为稳定性增强（非功能扩展）。
+
+## 2. 方法级改动
+
+| 位置 | 原行为 | 新行为 |
+|------|--------|--------|
+| `DeepSeekClient.select_tables` | 使用配置默认 `temperature`（如 0.3） | `setdefault(temperature=0.0, top_p=1.0)` 后调用 `chat_with_json`；调用方仍可通过 `**kwargs` 覆盖 |
+| `DeepSeekClient.validate_sql` | 同上 | 同上 |
+| `DeepSeekClient.generate_sql` | 同上 | 同上 |
+| `Text2SQLOrchestrator._generate_sql` | `chat(messages)` 使用默认温度 | 显式 `temperature=0.0, top_p=1.0` |
+
+与原有逻辑差异：选表、校验、SQL 文本生成在相同 prompt 下更趋确定；若上游 API 在 `temperature=0` 下仍存在极小浮动，属于服务商实现范畴。
+
+## 3. 调用方与影响范围
+
+- **调用方**：`orchestrator._llm_select_tables` → `deepseek.select_tables`；`orchestrator._generate_sql` → `deepseek.chat`；校验链路 → `validate_sql`；脚本或其它代码若直接调用 `generate_sql`/`select_tables`/`validate_sql` 并传入自定义 `temperature`，**仍以调用方 kwargs 为准**（`setdefault` 不覆盖已传值）。
+- **输入输出**：接口签名未变；返回 JSON/SQL 文本的**内容分布**更集中，极端情况下可能从「多种可接受 SQL」收敛到其中一种。
+- **破坏性变更**：否（未改公开方法签名；仅默认采样参数与编排器单次 `chat` 参数）。
+
+## 4. 风险与回滚
+
+- **风险级别**：低。可能略微降低「多解探索」多样性；对 Text2SQL 通常可接受。
+- **回滚**：恢复上述文件中的 `setdefault` / 显式 `temperature` 改动，或于环境变量/配置层为 DeepSeek 提高默认 `temperature`（若未来抽到配置项）。
+- **回滚方式是否简单**：是（单提交回退即可）。
+
+## 5. 验证与测试
+
+- **建议**：对固定中文问题连续请求 5～10 次，比对日志中 `LLM精筛选中表` 与最终 SQL 是否一致。
+- **说明**：Few-shot / 向量粗筛若存在非确定性实现，仍可能导致差异；本次改动仅消除 **LLM 采样** 主导的不一致。
+
+## 6. 配置变更（temperature 项）
+
+- 无新增环境变量或配置文件项；未改 `.env`。
+
+---
+
+# 增补：英文问句先译中文再走 Text2SQL（2026-04）
+
+## 1. 改动概览
+
+- **目标**：缓解「同一意图中英文提问选表/SQL 不一致」——在无 CJK 的英文问句进入粗筛、选表、few-shot、SQL 生成前，先经 DeepSeek 译为中文。
+- **涉及模块**：`backend/utils/question_locale.py`（新建）、`backend/config/prompts.py`、`backend/llm/deepseek_client.py`、`backend/agents/orchestrator.py`、`backend/main.py`、`api_server.py`。
+
+## 2. 方法级改动
+
+| 符号 | 说明 |
+|------|------|
+| `looks_like_english_only` | 无中日韩/假名/韩文且拉丁字母≥3 时视为「可译英文」 |
+| `DeepSeekClient.translate_nl_question_to_zh` | 一次 `chat(temperature=0)`，返回单行中文问句 |
+| `Text2SQLOrchestrator.generate` | 开头若开启且命中启发式则译问句，后续全流程使用中文；`metadata` 含 `question_original`、`question_zh_normalized` |
+| `_nl_dict_from_generation` | 若有译句，响应增加 `query_normalization: { original, zh }` |
+
+## 3. 调用方与破坏性变更
+
+- **调用方**：所有 `orchestrator.generate()`；API 层无签名变更。
+- **破坏性变更**：否。默认开启；关闭后行为与旧版一致。英文请求多一次 LLM 调用（延迟与费用略增）。
+
+## 4. 配置变更
+
+| 变量 | 含义 | 默认 |
+|------|------|------|
+| `TRANSLATE_EN_TO_ZH` | `false`/`0`/`off` 关闭英译中 | 开启 |
+
+CLI：`python backend/main.py --no-translate-en` 关闭。
+
+## 5. 风险与回滚
+
+- **风险**：翻译偏差导致表意偏移；专有名词若未保留可能被误译。
+- **回滚**：`TRANSLATE_EN_TO_ZH=false` 或 `--no-translate-en`；或回退相关提交。
+- **回滚方式是否简单**：是。
+
+---
+
+# 增补：库探针状态码 0 / 1 / -1 语义对齐（2026-04）
+
+## 1. 改动概览
+
+- **目标**：与业务约定一致——**1** 表示查询返回至少一行数据；**0** 表示执行成功但**行数为 0**（含「有列无行」的 SELECT）；**-1** 表示执行失败并触发重新生成，且重试提示携带数据库错误摘要。
+- **涉及模块**：`backend/db/dbhub_tools.py`、`backend/agents/orchestrator.py`、`backend/llm/deepseek_client.py`（注释）、`backend/main.py`（CLI 展示无行说明）、`backend/db/__init__.py`、`tools/dbhub_tools.py`、`tools/__init__.py`。
+
+## 2. 方法级改动
+
+| 符号 | 说明 |
+|------|------|
+| `probe_sql_execution_status_ex` | 新增；返回 `(status, error_message)`，`-1` 时第二项为异常字符串 |
+| `probe_sql_execution_status` | 仍返回 `int \| None`，内部委托 `_ex`，**语义变更**：由「有列或行即 1」改为「**至少一行数据**为 1」 |
+| `Text2SQLOrchestrator._validate_sql` | `-1` 错误信息附带库端详情；状态 `0` 时在 LLM 反馈外增加固定前缀，引导用户核对 SQL 并补充条件 |
+| `single_query` | 验证通过且存在 `db_empty_feedback` 时打印「探针 0」说明块 |
+
+## 3. 调用方与破坏性变更
+
+- **调用方**：仅编排器直接调用探针；对外 API 仍通过 `GenerationResult.metadata` 的 `db_execution_status` / `db_empty_feedback` 表达结果。
+- **破坏性变更**：是（**语义**）。此前「SELECT 返回 0 行但有列名」会被判为 **1**；现改为 **0**，会走无数据说明分支而非「直接可交付」。
+
+## 4. 风险与回滚
+
+- **风险**：低～中。更多查询会落入「无数据行」分支，多一次 `empty_result_user_feedback` LLM 调用；但更符合「无数据则请用户补充」的产品逻辑。
+- **回滚**：恢复 `probe_sql_execution_status` 内基于「列或行非空」判定 1 的旧实现，并回退编排器与 CLI 改动。
+- **回滚方式是否简单**：是。
+
+## 5. 配置变更
+
+- 无。