# Text-to-sql

**Repository Path**: mahaining/text-to-sql

## Basic Information

- **Project Name**: Text-to-sql
- **Description**: Text-to-sql
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-26
- **Last Updated**: 2026-02-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 语义增强型企业级 Text-to-SQL 技术方案

## 1. 背景与挑战
在企业级环境中，Text-to-SQL 的核心挑战在于：
- **Schema 规模巨大**：成百上千张表，超出 LLM 上下文限制。
- **业务逻辑复杂**：如“活跃用户”、“成交额 (GMV)”等指标存在特定计算口径，LLM 难以凭空推断。
- **容错要求高**：模型生成的 SQL 必须 100% 可执行且结果准确。
- **语义不一致**：自然语言的模糊性导致同一问题可能映射出不同逻辑的 SQL。

## 2. 核心架构设计
本方案采用 **"Semantic Layer + RAG + Agentic Workflow"** 的复合架构，底层实现已重构为模块化驱动。

### 2.1 底层逻辑组件
- **BaseLLM (抽象层)**：标准化大模型接入协议，支持 OpenAI, Gemini, DeepSeek 等无缝切换。
- **Semantic Engine (业务知识库)**：解析 YAML 定义，为模型提供表结构（Schema）和业务指标（Metrics）的增强上下文。
- **Enterprise Agent (控制中枢)**：管理“生成-执行-分析-修复”的完整生命周期。

### 2.2 整体流程图 (Mermaid)
```mermaid
graph TD
    A[用户自然语言问题] --> B[Semantic Engine: 提取指标 & Schema]
    B --> C[LLM: 结合上下文生成 SQL]
    C --> D[Sandbox: SQL 预执行验证]
    D -- 报错: Column Not Found 等 --> E[Self-Healing: 自动分析错误并修复]
    E --> C
    D -- 执行成功 --> F[Result: 返回结构化数据]
```

## 3. 关键组件说明

### 3.1 语义层建模 (Semantic Layer)
通过 [semantic_model.yaml](./core/semantic_model.yaml) 显式定义业务逻辑，解决 LLM 无法理解私有业务口径的问题。
- **真实案例**：针对 `RepairRecord` 表，定义了 `总维修金额` 指标：
  ```yaml
  metrics:
    - name: "总维修金额"
      formula: "SUM(CAST(repair_cost AS REAL))"
      condition: "repair_cost IS NOT NULL"
  ```

### 3.2 动态 Schema 路由 (RAG-Enhanced)
- **按需召回**：根据问题语义，仅提取相关的表结构和语义定义片段，减少 LLM 的干扰。

### 3.3 Agentic 自愈循环 (Self-Healing)
- **闭环验证**：在沙箱中预执行 SQL。
- **错误修复**：捕获报错信息并回传给 LLM 进行修正，通常可解决大部分初次生成错误。

### 3.4 多轮对话记忆 (Memory Management)
- **状态持久化**：利用 LangGraph 的 `MemorySaver` 实现基于 `thread_id` 的会话隔离与记忆。
- **上下文回溯**：在生成 SQL 时，自动提取历史对话上下文，支持“这个故障发生的频率高吗？”等指代性追问。

## 4. 上下文召回与记忆机制

### 4.1 记忆功能 (Memory)
解决“对话怎么接”的问题，确保 Agent 具备跨轮次的上下文理解能力。
- **短期记忆 (Session-based)**：
    - **实现方式**：在 `AgentState` 中维护 `history` 消息列表，记录 User 和 Assistant 的交互。
    - **本项目实践**：使用 LangGraph 的 Checkpointer 机制，通过 `thread_id` 自动恢复会话状态，支持多轮追问。
- **长期记忆 (Persistent Memory)**：
    - **未来演进**：可将 `MemorySaver` (内存) 替换为 `SqliteSaver` 或 Redis，实现跨进程的会话持久化。

### 4.2 召回机制 (Retrieval)
解决“知识从哪来”的问题，通过 RAG 技术为 LLM 提供最相关的背景知识。
- **向量检索 (Vector Search)**：
    - **语义匹配**：将用户问题向量化，从 Qdrant 向量库中检索最相关的表结构 (Schema) 和业务指标 (Metrics)。
- **按需注入**：
    - **动态 Context**：仅将检索到的相关片段注入 Prompt，避免全量 Schema 导致的 Token 浪费和 LLM 干扰。

## 5. 记忆管理深度解析：存储 vs 压缩

为了直观理解 L4 级的记忆管理，我们可以将其比作“工作笔记”的处理流程：

### 5.1 存储流程 (Persistence) —— 解决“笔记存哪”
存储流程关心的不是笔记的内容，而是载体的物理位置。
- **内存存储 (MemorySaver)**：类似将笔记记在**脑子里**。程序关闭或崩溃，记忆即消失。
- **持久化存储 (SqliteSaver)**：类似将笔记记在**实体笔记本 (.db 文件)** 上。即使下班回家（程序关闭），第二天翻开笔记本依然能接续昨天的进度。
- **核心价值**：实现跨时间、跨会话的记忆连续性。

### 5.2 压缩流程 (Summary) —— 解决“笔记太厚”
压缩流程关心的是内容密度，防止“翻不动笔记”（超出 LLM 上下文限制）。
- **无压缩模式**：对话 100 轮，每次都要重读 100 轮的笔记。会导致响应变慢、Token 成本激增、甚至超出模型处理上限。
- **摘要压缩模式**：当笔记写满 10 页时，自动在第 11 页写下“前情提要”，并封存前 10 页。
- **核心价值**：节省 Token 成本，提升 LLM 处理复杂长任务的专注度与效率。

### 5.3 协同工作链路
1. **[存]** 每轮对话实时写入持久化数据库。
2. **[判]** 系统检测对话长度是否触发阈值。
3. **[压]** 触发 LLM 摘要节点，将陈旧对话提炼为关键背景。
4. **[更]** 在数据库中用摘要替换冗长历史，仅保留“摘要 + 最近 N 轮对话”。

## 6. 安全与性能治理
- **权限隔离**：使用 Read-Only 账号执行生成的 SQL。
- **查询拦截**：对 `DELETE`, `DROP` 等敏感操作进行硬过滤。
- **超时控制**：设置 `Statement Timeout` 防止慢查询。

## 6. 服务化与 Docker 集成 (Future Roadmap)
为了配合 Web 端的集成，方案支持全栈容器化部署：
- **API 层**：基于 FastAPI 封装 Agent 逻辑，提供标准 REST API。
- **容器化**：提供 `Dockerfile`，将语义层定义、Agent 代码及依赖库打包。
- **沙箱隔离**：在 Docker 内部运行独立的数据库执行环境，确保主库安全。
- **前端集成**：后端 API 可直接对接 Vue/React 构建的 Chat 界面。

## 7. 演进建议
1. **L1 级**：基础 Prompt 方案。
2. **L2 级**：引入 **语义建模 (YAML)** + RAG，解决指标口径不一的问题。
3. **L3 级 (已实现)**：引入 **LangGraph** 构建具备**自愈能力**的自动化 Agent。
    - **自愈循环 (Self-Healing)**：使用 LangGraph 状态机捕获错误并自动修复。
    - **多步推理**：通过 Graph 节点流实现复杂的逻辑拆解。
    - **模块化扩展**：方便后续增加“反思”、“审核”等高级节点。
4. **L4 级 (规划中)**：**长效记忆与混合上下文管理**。
    - **方案 A：摘要压缩 (Summary Compression)**：
        - **触发机制**：当对话轮次超过阈值（如 10 轮）或 Token 占用过高时自动触发。
        - **核心逻辑**：调用 LLM 对早期对话进行“语义提炼”，仅保留核心业务意图和关键实体，释放上下文空间。
        - **混合模式**：采用“最近 3 轮全量对话 + 远期滚动摘要”的模式，兼顾即时细节与长程背景。
    - **方案 B：持久化存储 (Persistent Storage)**：
        - **实现路径**：将 `MemorySaver` (内存型) 升级为 `SqliteSaver` (文件型) 或 `PostgresSaver`。
        - **核心价值**：解决“程序重启即失忆”问题。通过 `thread_id` 在数据库中检索历史状态，实现跨会话、跨周期的对话续接。
    - **语义缓存 (Semantic Cache)**：对相似问题的 SQL 结果进行缓存，提升响应速度并降低 LLM 成本。

---
*注：本方案配套代码实现参考 [core/enterprise_sql_agent.py](./core/enterprise_sql_agent.py) 和 [core/semantic_model.yaml](./core/semantic_model.yaml)*