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 — 新增 OpenAI LLM Client（对话/JSON 输出）
1. 改动概览
- 背景与目标：补齐
backend/llm/openai_client.py，提供 OpenAI（或 OpenAI 兼容网关）调用封装，支持同步/异步 chat 与 chat_with_json，便于与既有 prompt/JSON 输出链路复用。
- 涉及模块：
backend/llm/openai_client.py、.env（仅补充注释示例，不影响现有运行配置）。
- 改动类型：功能新增。
2. 方法级改动分析
| 位置 |
变更 |
OpenAIClient.chat |
新增：基于 openai SDK 的 Chat Completions 调用封装，支持覆盖 temperature/max_tokens/top_p 等参数。 |
OpenAIClient.chat_with_json |
新增：抽取/解析 JSON（兼容 markdown code fence）；解析失败时返回 {"_json_decode_failed": true, "raw_content": ...}。 |
create_openai_client |
新增：从环境变量读取 OPENAI_API_KEY、可选 OPENAI_BASE_URL、OPENAI_MODEL/OPENAI_CHAT_MODEL。 |
3. 调用方与影响范围分析
- 调用方：当前仓库运行链路仍默认使用
DeepSeekClient；本次新增仅提供可选能力，未修改既有编排器/接口路由。
- 破坏性变更：否。
4. 风险与回滚
- 风险级别：低（新增模块，不改变既有默认路径）。
- 回滚：删除新增文件与对应文档/注释即可。
回滚方式是否简单：是。
5. 验证与测试
- 已执行：
python -m py_compile backend/llm/openai_client.py。
6. 配置变更
.env：补充 OPENAI_MODEL/OPENAI_CHAT_MODEL 注释示例（不修改现有真实配置）。
Impact Analysis Report — DeepSeek/OpenAI 双模型切换（LLM_SERVICE_CODE）
1. 改动概览
- 背景与目标：支持在 DeepSeek 与 OpenAI（或兼容网关）之间切换 LLM 调用来源，便于在不同环境/配额下切换推理服务。
- 涉及模块：
backend/llm/router.py（新）、backend/agents/orchestrator.py、backend/main.py、api_server.py、.env（新增开关）。
- 改动类型：功能增强（可配置路由）。
2. 方法级改动分析
| 位置 |
变更 |
backend/llm/router.py |
新增：resolve_llm_service_code + create_llm_client，按 LLM_SERVICE_CODE 或 Key 存在性创建 LLM Client。 |
Text2SQLOrchestrator.__init__ |
新增可选 llm_client 参数；若传入则作为 self.deepseek 使用（保留属性名避免大范围改动）。 |
backend/main.py |
setup_environment 增加 LLM_SERVICE_CODE 校验；create_orchestrator 通过 router 创建 LLM Client。 |
api_server.py |
错误提示文案更新；编排器初始化保持通过 create_orchestrator 完成。 |
3. 调用方与影响范围分析
- 调用方：CLI（
backend/main.py）与 API（api_server.py）初始化编排器路径。
- 行为变化：
LLM_SERVICE_CODE=openai：使用 OPENAI_* 做 LLM 调用（意图分类 / 归一 / 选表 / 生成 / 说明等）。LLM_SERVICE_CODE=deepseek 或未设置但存在 DEEPSEEK_API_KEY：仍默认 DeepSeek（与历史一致）。
- 破坏性变更：否（对外 API 入参/出参不变；仅初始化与内部客户端来源可切换）。
4. 风险与回滚
- 风险级别：中（不同模型对 JSON 严格性/输出格式偏好不同，可能影响
chat_with_json 的解析成功率与稳定性；失败时仍会返回 _json_decode_failed 供上游处理）。
- 回滚：将
LLM_SERVICE_CODE 切回 deepseek 或回退相关文件改动。
回滚方式是否简单：是。
5. 验证与测试
- 已执行：
python -m py_compile 覆盖 backend/llm/router.py、backend/agents/orchestrator.py、backend/main.py、api_server.py。
6. 配置变更
| 配置项 |
含义 |
取值 |
LLM_SERVICE_CODE |
选择 LLM 路由 |
openai / deepseek（留空自动按 Key 选择，优先 deepseek） |
Impact Analysis Report — 适配前端参数（lang_code / model）
1. 改动概览
- 背景与目标：前端请求会携带
lang_code（zh/tc/en）与 model（模型名覆盖）；后端需接收并在对话分支/LLM 调用侧生效。
- 涉及模块：
api_server.py。
- 改动类型：兼容性增强。
2. 方法级改动分析
| 位置 |
变更 |
NLChatRequest |
新增 model 字段；保留 lang_code（规范化为 zh/tc/en/auto）。 |
nl_chat / _chat_stream_events |
对话分支：空输入/默认引导文案按 lang_code 返回（中/繁/英）。 |
_maybe_override_orch_llm（新） |
若请求带 service_code/model，临时覆盖 orchestrator.deepseek 为按请求创建的 LLM client；使用锁避免并发串改。 |
_run_generate |
增加 request 参数，用于按请求覆盖 LLM client 后再生成。 |
3. 调用方与影响范围分析
- 调用方：
/g3sb/api/nl/chat、/g3sb/api/nl/chat/stream。
- 破坏性变更：否（仅新增可选请求字段与内部适配；未提供时行为保持不变）。
4. 风险与回滚
- 风险级别：中（带
model/service_code 的请求会串行化执行 LLM 调用，避免并发污染；在高并发时可能降低吞吐）。
- 回滚：回退
api_server.py 的按请求覆盖逻辑即可。
回滚方式是否简单：是。
5. 验证与测试
- 已执行：
python -m py_compile api_server.py。
Impact Analysis Report — 方案A：新话题禁用 dialog_context（防上下文污染）
1. 改动概览
- 背景与目标：同一会话内出现多个不同话题时，历史摘要（含上轮 SQL）注入 Text2SQL 易造成上下文污染，导致选表/条件串话。本次引入“续问判定”规则：仅在疑似续问时注入少量上文；新话题默认不注入上文。
- 涉及模块：
api_server.py、backend/utils/dialog_context.py。
- 改动类型：缺陷修复 / 行为优化（仅影响带
session_id 且存在历史消息的请求）。
2. 方法级改动分析
| 位置 |
变更 |
backend/utils/dialog_context.py is_likely_follow_up |
新增：基于用户文本的轻量续问判定（关键字/短句规则），用于决定是否需要注入上文。 |
api_server.py _load_session_text2sql_context |
调整：新增 user_text 入参；根据 is_likely_follow_up(user_text) 选择 max_pairs=2 或 0，并据此构造 dialog_context。 |
api_server.py 两个入口 |
调整：/g3sb/api/nl/chat 与 /g3sb/api/nl/chat/stream 调用 _load_session_text2sql_context(request, text)。 |
3. 调用方与影响范围分析
- 调用方：
/g3sb/api/nl/chat、/g3sb/api/nl/chat/stream（请求带 session_id 且历史不为空时生效）。
- 行为变化：
- 新话题（非续问）：
dialog_context 变为空（不再携带历史摘要），降低串话风险。
- 续问：仅携带最近 2 轮（原默认最多 8 轮），降低旧话题回流概率。
- 破坏性变更：否（对外 API 入参/出参未变；仅内部上下文组装策略变化）。
4. 风险与回滚
- 风险级别：中（可能把少量“隐式续问”误判为新话题，导致指代消解能力下降；但能显著降低跨话题污染）。
- 回滚：回退本次提交（或将
max_pairs 固定恢复为 8 / 去掉续问判定）。
回滚方式是否简单：是。
5. 验证与测试
- 建议手工：
- 同一 session：话题A生成 SQL → 话题B（无续问词）应不再引用 A 的表/条件。
- 同一 session：首轮查询 → 次轮“再/按上面/沿用口径”续问，应仍能沿用上轮 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 时与旧版「仅内存」行为一致。 |
Impact Analysis Report — /g3sb/api/nl/chat/stream 分片 SSE（追加）
1. 改动概览
- 背景与目标：前端
chatStore 按多次 { stage, stream_kind, content } 累加 chatText / sqlGenHtml；原先后端在 chat / sql_gen 阶段各只发一条大包，网络侧无渐进感。
- 涉及模块：
api_server.py。
- 改动类型：行为优化（SSE 事件形态不变，仅增加条数）。
2. 方法级改动
| 位置 |
变更 |
_sse_stream_text_chunks |
新增：按字符窗口（默认 64，可用 SSE_STREAM_CHUNK_CHARS 覆盖）拆成多段 SSE；段间 asyncio.sleep(0) 让出事件循环。 |
_chat_stream_events |
chat / sql_gen 正文改为 async for 分片 yield。 |
3. 破坏性变更
- 否（结束包
code/msg/data 仍与原先一致）。
4. 配置变更
| 项 |
说明 |
SSE_STREAM_CHUNK_CHARS |
可选；每段 SSE 的 content 最大字符数，默认 64。 |
Impact Analysis Report — API 日志落盘与可观测性（追加）
1. 改动概览
- 背景与目标：终端日志偏少，难以排查 Text2SQL 全链路问题；需将更细粒度的日志写入仓库
logs/，且每次进程启动只保留一个 .log 文件。
- 涉及模块：
api_server.py、backend/utils/repo_logging.py（新）、backend/agents/orchestrator.py、backend/schema/indexer.py、backend/utils/dialog_classifier.py。
- 改动类型：可观测性增强（行为对业务结果无影响）。
2. 方法级改动
| 位置 |
变更 |
configure_text2sql_api_logging |
新建：清空 logs/*.log，创建 logs/text2sql_api.log（覆盖写）；root 双 Handler（控制台简短格式 + 文件含 filename/lineno/funcName）；关闭 Chroma/posthog 遥测 logger；httpx/httpcore 降为 WARNING。 |
api_server 导入段 |
在 from main import … 之前调用上述配置；移除 basicConfig；uvicorn.run(..., log_config=None) 避免覆盖 root（勿用 False，否则会走 fileConfig 崩溃），并清空 uvicorn 自带 handler 改为 propagate。 |
_run_generate / nl_chat / _chat_stream_events |
增加请求维度、对话上文长度、流式结束时的 valid/attempts/tables/SQL 摘要等 INFO 日志。 |
Text2SQLOrchestrator |
向量粗筛输出表名+分数列表；选表输出 reasoning 预览；few-shot 注入 qid 与问题预览；生成 SQL 全文（超长截断至约 12k 字符）；_validate_sql 返回前汇总 valid/errors/warnings/探针。 |
SchemaIndexer.search |
检索结果由 DEBUG 改为 INFO，输出命中数与 top 表+分。 |
classify_dialog 规则/hybrid 快路径 |
DEBUG 改为 INFO，附用户输入预览；LLM 分支补充 reply 预览。 |
3. 调用方与影响范围
- 调用方：仅通过
python api_server.py（或等价导入 api_server）启动 API 时生效；backend/main.py CLI 仍使用自身 basicConfig，不落盘到本 logs/text2sql_api.log（未改 CLI）。
- 破坏性变更：否。
4. 风险与回滚
- 风险级别：低。日志文件可能含用户查询片段与 SQL，需注意磁盘与隐私（内网演示场景可接受）。
- 回滚：删除
repo_logging 调用与相关增强日志，恢复 basicConfig 与默认 uvicorn.run 即可。
回滚方式是否简单：是。
5. 验证与测试
- 建议：
python -m py_compile api_server.py backend/utils/repo_logging.py；启动 python api_server.py 后确认生成 logs/text2sql_api.log 且重启后仅保留该文件。
6. 配置变更
- 无新增环境变量；日志路径固定为仓库根下
logs/text2sql_api.log。
Impact Analysis Report — Chroma Few-shot 黄金 SQL 条件适配（追加）
1. 改动概览
- 背景与目标：
data/embeddings/chroma_fewshot 中存储的问答-SQL 视为已校验正确答案；当向量检索与当前问题足够相似时，不再仅作「风格示例」，而是以该 SQL 为骨架，仅让 LLM 调整 WHERE/HAVING 等与用户问题相关的特殊条件。
- 涉及模块：
backend/config/prompts.py（GOLDEN_SQL_ADAPT_*）、backend/utils/fewshot_selector.py（select_best_with_score、is_chroma_backend）、backend/agents/orchestrator.py（_generate_sql_golden_adapt、_generate_sql 分支）、api_server.py（响应中可选 fewshot_golden）。
- 改动类型：生成策略增强（默认开启，可用环境变量关闭或调阈值）。
2. 方法级改动
| 位置 |
变更 |
FewShotSelector |
新增 _passes_filters、select_best_with_score；is_chroma_backend 属性。 |
Text2SQLOrchestrator._generate_sql |
在 Chroma 且满足阈值时调用 _generate_sql_golden_adapt 并设置 _last_fewshot_golden；否则沿用原 few-shot 注入 + 全量生成。 |
_generate_sql_golden_adapt |
使用 GOLDEN_SQL_ADAPT_SYSTEM/USER，强调保留 JOIN/SELECT 结构、仅改条件。 |
generate |
metadata 增加 fewshot_golden_reuse、fewshot_golden_qid、fewshot_golden_score；失败路径亦回传（若曾走黄金分支）。 |
_nl_dict_from_generation |
若存在黄金复用，增加 fewshot_golden 字段供前端展示/调试。 |
3. 破坏性变更
- 否。未命中阈值时行为与原先「多示例风格参考」一致。
4. 配置变更
| 环境变量 |
含义 |
默认 |
FEWSHOT_GOLDEN_REUSE |
是否启用黄金 SQL 条件适配 |
true |
FEWSHOT_GOLDEN_ONLY_CHROMA |
是否仅在 Chroma 后端启用（与 chroma_fewshot 策略一致） |
true |
FEWSHOT_GOLDEN_MIN_SCORE |
最低相似度（1-距离，约等于余弦相似度） |
0.88 |
FEWSHOT_GOLDEN_SQL_PROMPT_MAX |
写入提示词的标准答案 SQL 最大字符数 |
16000 |
5. 风险与回滚
- 风险：阈值过低可能把不太相似的问题强行套在同一 SQL 上；过高则很少触发黄金分支。
- 回滚：设
FEWSHOT_GOLDEN_REUSE=false 或回退相关提交。
回滚方式是否简单：是。
Impact Analysis Report — 流式 SSE sql_gen 分片与节流
1. 改动概览
- 背景与目标：前端约定每条 SSE 为
data: {"stage":"sql_gen","stream_kind":"content","content":"..."}；服务端需按 LLM 原生流式 delta 透传（默认不二次切分），并支持可选分片间隔。
- 涉及模块：
api_server.py（/g3sb/api/nl/chat/stream、_iter_sql_gen_content_pieces、_sse_stream_text_chunks）。
- 改动类型：行为调整（默认分片粒度为
delta：不做二次切分；如确需更细粒度可配置 char）。
2. 方法级改动
| 位置 |
变更 |
NLChatRequest |
新增可选 sql_stream_granularity（sqlStreamGranularity）；明确 streaming_throttle 为相邻 content 间隔毫秒。 |
_iter_sql_gen_content_pieces |
支持传入 mode；未设置时 SSE_SQL_GEN_SPLIT 默认 delta（不切分）。 |
_chat_stream_events |
sql_gen 循环按粒度拆分后对每条 data 可选 asyncio.sleep(throttle)；寒暄分支 _sse_stream_text_chunks 支持相同节流。 |
3. 调用方与影响范围
- 调用方：仅 SSE 流式客户端；非流式
/g3sb/api/nl/chat 不变。
- 破坏性变更：否。未传新字段时：粒度由
SSE_SQL_GEN_SPLIT 决定（默认 delta，事件条数与 LLM 原生一致）；若需更细粒度可设 SSE_SQL_GEN_SPLIT=char 或请求体 sqlStreamGranularity: "char"。
4. 配置变更
| 环境变量 |
含义 |
默认 |
SSE_SQL_GEN_SPLIT |
delta：与 LLM 增量一致；char：逐 Unicode 标量多条 SSE |
delta（未设置 env 时由代码默认） |
5. 风险与回滚
- 风险级别：低。
char 模式下 SSE 条数增加，带宽与前端拼接次数上升。
- 回滚：设
SSE_SQL_GEN_SPLIT=delta 或请求传 sqlStreamGranularity: "delta"（回到默认：不切分）。
回滚方式是否简单：是。
6. 验证与测试
- 已执行：
python -m py_compile api_server.py。
