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 项）
增补：英文问句先译中文再走 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. 配置变更
