11 KiB
11 KiB
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.pysingle_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 |
已删除。 |