Refactor api_server.py to import environment setup and schema loading from bootstrap.py, enhancing modularity. Introduce a new function in Text2SQLOrchestrator to prioritize VCUserAccessibleFunction in table selection, improving SQL generation accuracy. Update validation logic to enforce restrictions on CJK characters in SQL string literals, ensuring compliance with business rules. Enhance prompts to clarify SQL generation constraints regarding date conditions and CJK usage.
This commit is contained in:
陈辅元
@@ -1,3 +1,79 @@
|
||||
# Impact Analysis Report — CJK 字面量校验（CASE 展示标签）
|
||||
|
||||
## 1. 改动概览
|
||||
|
||||
- **背景与目标**：修复「CASE … THEN/ELSE 中使用中文状态标签」被 `check_no_cjk_in_sql_string_literals` 全文扫描误判为非法，导致合法查询反复重试仍失败的问题。规则本意是禁止在 **WHERE/HAVING/ON/CASE 条件** 中用中文与代码列比对。
|
||||
- **涉及模块**：`backend/utils/validators.py`（CJK 校验改为基于 sqlglot AST + 解析失败时回退全文扫描）、`backend/agents/orchestrator.py`（传入 `dialect`、T-SQL 硬性说明与注释对齐）、`backend/config/prompts.py`（2b 条款与校验语义一致）。
|
||||
- **改动类型**：缺陷修复（验证逻辑与提示词澄清）。
|
||||
|
||||
## 2. 方法级改动
|
||||
|
||||
| 位置 | 变更 |
|
||||
|------|------|
|
||||
| `check_no_cjk_in_sql_string_literals` | 解析成功时仅当 CJK 出现在 `Where`/`Having`/`Join.on` 或 `Case` 分支的 **WHEN 条件**（`If.this`）中报错；`Case` 的 **THEN/ELSE** 与纯 `SELECT` 展示字面量允许。支持 `Literal` 与 `National`（`N'…'`）。解析失败时回退旧版全文扫描（偏严）。 |
|
||||
| `orchestrator._validate_sql` | 调用 `check_no_cjk_in_sql_string_literals(sql, dialect=dialect)`。 |
|
||||
|
||||
## 3. 调用方与影响范围
|
||||
|
||||
- **调用方**：`_validate_sql` 内唯一调用点。
|
||||
- **破坏性变更**：否。行为变更：此前会失败的「仅 CASE/SELECT 含中文标签」现为通过；`WHERE col = N'中文'` 等仍失败。
|
||||
|
||||
## 4. 风险与回滚
|
||||
|
||||
- **风险级别**：低。解析异常时仍走严格全文扫描。
|
||||
- **回滚**：还原 `validators.py` / 相关 prompt 与 orchestrator 片段。
|
||||
|
||||
**回滚方式是否简单**：是。
|
||||
|
||||
## 5. 验证与测试
|
||||
|
||||
- 已执行：脚本用例 — `CASE … THEN '\u8d85\u989d'` 通过；`WHERE x = N'\u8d85\u989d'` 失败。
|
||||
|
||||
## 6. 配置变更
|
||||
|
||||
- 无。
|
||||
|
||||
---
|
||||
|
||||
# Impact Analysis Report — Prompt：无时间表述则不擅自加日期条件
|
||||
|
||||
## 1. 改动概览
|
||||
|
||||
- **背景与目标**：强化 Text2SQL 提示词，避免用户未提任何时间时模型在 `WHERE` 中私自添加日期过滤；Few-shot 黄金适配时若当前问题比范例少时间条件，应去掉多余日期条件。
|
||||
- **涉及模块**：`backend/config/prompts.py`（`SQL_GENERATOR_*`、`GOLDEN_SQL_ADAPT_*`）、`backend/agents/orchestrator.py`（T-SQL 用户侧硬性要求追加一句）。
|
||||
- **改动类型**：配置/提示词优化（行为变更：模型被约束为少加臆测日期条件；**非** API 签名变更）。
|
||||
|
||||
## 2. 方法级改动
|
||||
|
||||
| 位置 | 变更 |
|
||||
|------|------|
|
||||
| `SQL_GENERATOR_SYSTEM` | 新增硬性条款 **1b**（无时间表述则不加日期条件）；收紧第 **2** 条中「未给日期」与日期列的说明；推断指南增加**前提**行；黄金范例括号内补充「完全未提时间勿照抄日期」。 |
|
||||
| `SQL_GENERATOR_USER` | 末尾一句指向 **1b**。 |
|
||||
| `GOLDEN_SQL_ADAPT_SYSTEM` | 第 **2** 条补充：当前问题无时间要求时去掉标准答案中无关日期过滤。 |
|
||||
| `orchestrator` `_generate_sql` / `_generate_sql_golden_adapt` | T-SQL 硬性要求字符串追加与 **1b** 一致的一句提醒。 |
|
||||
|
||||
## 3. 调用方与影响范围
|
||||
|
||||
- **调用方**：所有经 `Text2SQLOrchestrator` 走 SQL 生成的路径（含黄金适配分支）。
|
||||
- **破坏性变更**：否（仅 prompt 与 user 附加说明文本变化）。
|
||||
|
||||
## 4. 风险与回滚
|
||||
|
||||
- **风险级别**：低。可能使「未说时间」类问题返回更宽结果集（符合预期）；若业务依赖模型以前「默认加近期」的隐式行为，需改为在用户问题或后端注入默认时间窗。
|
||||
- **回滚**：还原上述文件相关 diff。
|
||||
|
||||
**回滚方式是否简单**：是。
|
||||
|
||||
## 5. 验证与测试
|
||||
|
||||
- 建议手工：问题不含任何时间词 → 生成 SQL 应无新增日期列条件（除非 Schema/问题语义强制）；含「今天」→ 仍可用 `GETDATE()`。
|
||||
|
||||
## 6. 配置变更
|
||||
|
||||
- 无。
|
||||
|
||||
---
|
||||
|
||||
# Impact Analysis Report — 会话上文注入 Text2SQL
|
||||
|
||||
## 1. 改动概览
|
||||
@@ -672,3 +748,109 @@
|
||||
## 6. 验证与测试
|
||||
|
||||
- 已执行：`python -m py_compile api_server.py`。
|
||||
|
||||
---
|
||||
|
||||
# Impact Analysis Report — API 回包增加 data.sql / data.explanation 便捷字段
|
||||
|
||||
## 1. 改动概览
|
||||
|
||||
- **背景与目标**：前端需要在响应 `data` 内直接读取 `{"sql":"..."}`（SQL 可含 `--` 注释且无 ``` 围栏），并单独读取自然语言解释字段。
|
||||
- **涉及模块**：`api_server.py`（`NLChatSuccessData`、`_nl_dict_from_generation`）。
|
||||
- **改动类型**：向后兼容的字段补充（不移除/不改名原有字段）。
|
||||
|
||||
## 2. 方法级改动
|
||||
|
||||
| 位置 | 变更 |
|
||||
|------|------|
|
||||
| `NLChatSuccessData` | 新增可选字段 `sql`、`explanation`（便捷读取）。 |
|
||||
| `_nl_dict_from_generation` | 在原有 `intent/branch_result` 之外补充 `payload["sql"]` 与 `payload["explanation"]`；`explanation` 优先取 `sql_delivery_message`，否则回退到 `sql_explain`。 |
|
||||
|
||||
## 3. 调用方与影响范围
|
||||
|
||||
- **调用方**：`/g3sb/api/nl/chat` 与 `/g3sb/api/nl/chat/stream` 的结束包 `data`。
|
||||
- **破坏性变更**：否（仅新增字段；原 `branch_result.sql` 等保持不变）。
|
||||
|
||||
## 4. 风险与回滚
|
||||
|
||||
- **风险级别**：低（新增字段）。
|
||||
- **回滚**：回退本改动提交即可。
|
||||
|
||||
**回滚方式是否简单**：是。
|
||||
|
||||
## 5. 验证与测试
|
||||
|
||||
- 已执行：`python -m py_compile api_server.py`。
|
||||
|
||||
---
|
||||
|
||||
# Impact Analysis Report — SSE 流式 SQL 说明与可选 `<data>{"sql":...}</data>` 片段（可开关）
|
||||
|
||||
## 1. 改动概览
|
||||
|
||||
- **背景与目标**：流式 `/g3sb/api/nl/chat/stream` 需要给客户端展示 SQL（LLM 原生 delta）并在必要时提供结构化 SQL。由于当前前端会直接拼接展示 delta 且保留 `<data>`，因此结构化 `<data>` 片段默认不补发，避免同一次流里出现两段可见 SQL；如有需要可通过环境变量开关启用。
|
||||
- **涉及模块**：`api_server.py`（`_chat_stream_events`）。
|
||||
- **改动类型**：向后兼容增强（流式末尾追加内容；并过滤 LLM 可能自行输出的 `<data>...</data>`，避免前端出现重复 SQL/重复结构化片段）。
|
||||
|
||||
## 2. 方法级改动分析
|
||||
|
||||
| 位置 | 变更 |
|
||||
|------|------|
|
||||
| `_chat_stream_events` | 透传 LLM 的 `sql_gen` delta 用于展示；过滤 LLM 自吐的 `<data>...</data>` 段。流结束时结构化 `<data>{"sql":...}</data>` **默认不补发**，仅在 `SSE_APPEND_SQL_DATA_TAG=true` 时启用补发，避免前端拼接展示时出现重复 SQL。 |
|
||||
|
||||
## 3. 调用方与影响范围分析
|
||||
|
||||
- **调用方**：前端 SSE 消费逻辑（`stage="sql_gen"`、`stream_kind="content"`）。
|
||||
- **影响**：
|
||||
- **展示**：若前端直接展示原始流文本，将额外看到「SQL 说明」与 `<data>...</data>`；但通常前端会对 `<data>...</data>` 做隐藏/抽取，不影响页面展示。
|
||||
- **解析**：前端可在流末尾稳定抽取 SQL（而不依赖临时拼接或额外请求非流式接口）。
|
||||
- **破坏性变更**：否（仅追加；不更改原有字段与 SSE 事件结构）。
|
||||
|
||||
## 4. 风险与回滚
|
||||
|
||||
- **风险级别**：低（开关打开时，若前端未过滤 `<data>`，可能展示出标签；默认关闭避免此问题）。
|
||||
- **回滚**：默认即不补发；如需恢复补发仅需设置 `SSE_APPEND_SQL_DATA_TAG=true`，或回退代码提交。
|
||||
|
||||
**回滚方式是否简单**：是。
|
||||
|
||||
## 5. 验证与测试
|
||||
|
||||
- 已验证：`python -m py_compile api_server.py`；默认不再补发 `<data>{"sql":...}</data>`，且不会透传 LLM 自行生成的 `<data>...</data>` 段；需要结构化输出时可设置 `SSE_APPEND_SQL_DATA_TAG=true` 验证补发行为。
|
||||
|
||||
---
|
||||
|
||||
# Impact Analysis Report — api_server 精简未使用请求/查询参数
|
||||
|
||||
## 1. 改动概览
|
||||
|
||||
- **背景与目标**：删除 `api_server.py` 中未被业务逻辑使用的请求字段与路由形参，减少噪音；stub 接口不再声明从不读取的请求体模型。
|
||||
- **涉及模块**：`api_server.py`。
|
||||
- **改动类型**：重构（对外行为基本不变）。
|
||||
|
||||
## 2. 方法级改动
|
||||
|
||||
| 位置 | 变更 |
|
||||
|------|------|
|
||||
| `NLChatRequest` | 移除字段 `taskId`（仓库内无读取）。 |
|
||||
| `SqlExecuteBody` | 删除模型；`POST /g3sb/api/nl/sql/execute` 无请求体形参（仍返回 501）。 |
|
||||
| `POST /g3sb/api/nl/operation-logs` | 移除未使用的 `Body` 形参（仍返回 200）。 |
|
||||
| `GET /g3sb/api/nl/operation-logs` | 仅保留 `limit`、`offset`；其余查询参数从签名中移除。 |
|
||||
| `GET /g3sb/api/nl/knowledge-docs/uploads` | 移除未使用的 `doc_type`，保留 `limit`、`offset`。 |
|
||||
| `lifespan`、全局异常处理 | 未使用的 `app`/`_req` 形参改为 `_app` / `_`（语义不变）。 |
|
||||
|
||||
## 3. 调用方与影响范围
|
||||
|
||||
- **调用方**：`ai-g3sb-backman-web` 的 `nlClient.ts` 仍可对上述 GET 附带更多 query、对 POST 仍发送 JSON；FastAPI 对未声明的 query 通常忽略，不声明的 body 仍会被接收但不解析。
|
||||
- **OpenAPI**：`/sql/execute` 与 `POST /operation-logs` 的文档中可能不再展示请求体 schema（与当前「不读 body」实现一致）。
|
||||
- **破坏性变更**：否（若客户端依赖 OpenAPI 生成且严格要求 `taskId` 出现在 schema，仅文档层面变化；运行时多传 `taskId` 仍被 Pydantic 忽略）。
|
||||
|
||||
## 4. 风险与回滚
|
||||
|
||||
- **风险级别**：低。
|
||||
- **回滚**：回退本改动对应提交即可。
|
||||
|
||||
**回滚方式是否简单**：是。
|
||||
|
||||
## 5. 验证与测试
|
||||
|
||||
- 已执行：`python -m py_compile api_server.py`。
|
||||
|
||||
Reference in New Issue
Block a user