element.chen/ai-g3sb-backman2.0
1
0
Fork 0
Code Pull Requests Activity
Files
a55fd18915197da01e745ead8fc04c9133bf1b0e
ai-g3sb-backman2.0/IMPACT_ANALYSIS.md
T

19 KiB
Raw Blame History

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

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 时与旧版「仅内存」行为一致。 |

View Git Blame Copy Permalink