ai-g3sb-backman2.0/tech_architecture.md

# Text2SQL 算法技术方案

## 算法架构概述

Text2SQL 是一个将自然语言转换为 SQL 查询语句的智能算法系统，采用多智能体协作架构，结合向量检索和大语言模型技术，实现高效准确的 SQL 生成。

## 智能体组成

Text2SQL 系统由以下三个核心智能体组成：

| 智能体名称         | 主要职责   | 核心功能                     |
| ------------- | ------ | ------------------------ |
| Schema Linker | 表选择    | 向量检索粗筛、LLM 精筛、外键扩展       |
| SQL Generator | SQL 生成 | Few-shot 示例增强、LLM 生成 SQL |
| Validator     | SQL 验证 | 程序验证、库执行探针（0/1/-1）、LLM 语义验证、结果评估 |

这些智能体协同工作，形成完整的自然语言到 SQL 的转换流程。

## 核心算法流程

```mermaid
flowchart TD
    subgraph 输入层
        A[自然语言问题]
    end
    
    subgraph 核心处理层
        A --> B[意图分类
Dialog Classifier]
        B -->|非查询意图| C[返回对话回复]
        
        subgraph "智能体 1: Schema Linker"
            D[表选择]
            D1[向量检索粗筛
SchemaIndexer]
            D2[LLM 精筛
DeepSeek]
            D3[外键扩展
关联表处理]
            D --> D1
            D1 --> D2
            D2 --> D3
        end
        
        B -->|查询意图| D
        
        subgraph "智能体 2: SQL Generator"
            E[SQL 生成]
            E1[Few-shot 示例增强]
            E2[LLM 生成 SQL
DeepSeek]
            E --> E1
            E1 --> E2
        end
        
        D3 --> E
        
        subgraph "智能体 3: Validator"
            F[SQL 验证]
            F1[程序验证
语法检查]
            F1b[数据库试执行
行列探针 0/1/-1]
            F2[LLM 语义验证
未探针时]
            F3[结果评估]
            F --> F1
            F1 --> F1b
            F1b --> F2
            F2 --> F3
        end
        
        E2 --> F
        F3 -->|验证通过| H[返回有效 SQL]
        F3 -->|验证失败| I[重试逻辑
最多 max_retry 次]
        I -->|重试| E
    end
    
    subgraph 数据层
        J[Schema 管理
SchemaManager]
        K[向量数据库
Chroma]
        L[Few-shot 示例库
JSONL]
        M[DeepSeek API
大语言模型]
        N[业务数据库
database_url]
        J --> D
        K --> D1
        L --> E1
        M --> D2
        M --> E2
        M --> F2
        N --> F1b
    end
```

## 详细算法流程说明

### 1. 意图分类

- **Dialog Classifier**：对用户输入的自然语言进行意图分类
- **分类结果**：非查询意图直接返回对话回复，查询意图进入 SQL 生成流程

### 2. Schema Linker 算法

- **向量检索粗筛**：使用 `SchemaIndexer` 对用户问题进行向量检索，获取相关表的候选列表
  - 利用预训练的嵌入模型将表名和描述转换为向量
  - 使用 Chroma DB 进行相似度搜索
  - 返回 top-k 个最相关的表

* **LLM 精筛**：调用 DeepSeek 模型对候选表进行精筛，选择最相关的表
  - 构造包含表名和描述的提示
  - 让 LLM 基于用户问题选择最相关的表
* **外键扩展**：自动添加与选中表相关的关联表，确保查询完整性
  - 分析表之间的外键关系
  - 自动添加被引用和引用当前表的关联表

### 3. SQL Generator 算法

- **Few-shot 示例增强**：根据用户问题从示例库中选择相似的示例，增强 SQL 生成质量
  - 计算用户问题与示例库中问题的相似度
  - 选择 top-k 个最相似的高质量示例
  - 将示例注入到提示中，指导 SQL 生成
- **LLM 生成 SQL**：调用 DeepSeek 模型，根据选中的表结构和示例生成 SQL 语句
  - 构造包含表结构、用户问题和示例的提示
  - 指导 LLM 生成符合特定 SQL 方言的语句
  - 清理和规范化生成的 SQL

### 4. Validator 算法

- **程序验证**：检查 SQL 语法是否正确，表和列是否存在于 Schema 中，是否包含危险操作
  - 使用 sqlglot 进行语法检查
  - 验证表和列是否存在于 Schema 中
  - 检查是否包含危险操作（如 DROP、DELETE 等）
- **数据库试执行（探针）**：在程序验证全部通过后，于已配置的业务库上对 SQL 做只读试执行，结果用单一状态码表示，**不把具体行列数据交给 Validator LLM**：
  - **1**：执行成功，且**有返回行或有返回列**（列名或数据行至少其一非空）→ **跳过** Validator 的语义审核 LLM，**直接将 SQL 交付用户**
  - **0**：执行成功，但**既无列也无行** → 仍交付 SQL，**跳过** Validator 语义审核 LLM，另调 LLM 生成简短中文说明（可能原因 + 请用户补充条件），随响应一并返回
  - **-1**：执行失败 → 视为本次 SQL 不可用，**不交付**，进入重试；**不调用** Validator 语义审核 LLM
  - 未配置 `database_url` 时跳过探针（可选告警），此时走 **LLM 语义验证** 作为兜底
- **LLM 语义验证**：在未命中上述探针结果（即未配置库、未执行探针）时调用 DeepSeek，验证 SQL 语义是否符合用户意图
  - 构造包含 SQL、表结构和用户问题的提示
  - 让 LLM 评估 SQL 是否正确回答了用户问题
  - 收集错误和警告信息
- **结果评估**：验证通过则返回有效 SQL，失败则进入重试逻辑
  - 最多重试 max\_retry 次
  - 每次重试使用相同的表结构，但重新生成 SQL

### 5. 数据层支持

- **Schema 管理**：管理数据库表结构和元数据
  - 从 JSON 文件加载表结构
  - 提供表和列的查询接口
  - 分析表之间的外键关系
- **向量数据库**：存储表和列的向量表示，用于快速检索
  - 使用 Chroma DB 存储向量
  - 支持增量更新和查询
- **Few-shot 示例库**：存储高质量的自然语言到 SQL 的示例
  - 从 JSONL 文件加载示例
  - 支持基于相似度的示例检索
- **DeepSeek API**：提供大语言模型能力，用于表选择、SQL 生成和验证
  - 调用 DeepSeek 聊天模型
  - 支持不同的模型参数配置

## 技术栈

| 类别     | 技术/库         | 用途          |
| ------ | ------------ | ----------- |
| 编程语言   | Python       | 算法实现        |
| LLM    | DeepSeek API | 提供大语言模型能力   |
| 向量检索   | Chroma DB    | 存储和检索表的向量表示 |
| SQL 处理 | sqlglot      | SQL 语法解析和验证 |
| 环境管理   | dotenv       | 管理环境变量      |

## 算法特点

1. **多智能体协作**：Schema Linker、SQL Generator、Validator 三个智能体协同工作，各负责专门任务，形成完整的处理流程
2. **向量检索增强**：Schema Linker 使用向量数据库快速筛选相关表，提高表选择效率
3. **Few-shot 学习**：SQL Generator 利用示例库增强 SQL 生成质量，学习最佳实践
4. **多层验证**：程序校验 + 库上探针；探针为 1/0/-1 时不再走 Validator 语义 LLM（1 直接交付、0 附带无数据说明、-1 重试），未配置库时仍以 LLM 语义验证兜底
5. **自动关联表扩展**：Schema Linker 通过外键关系自动扩展相关表，提高查询完整性
6. **可配置性**：支持多种配置参数，如温度、最大重试次数、向量检索开关等，适应不同场景需求

## Few-shot 学习详细说明

### 概念介绍

Few-shot 学习是一种机器学习方法，指通过少量示例来指导模型学习和执行任务。与传统的监督学习需要大量标注数据不同，Few-shot 学习仅需提供少量（通常为个位数）的示例，就能让模型理解任务的模式和要求。

### 在 Text2SQL 系统中的应用

在 Text2SQL 系统中，Few-shot 学习主要应用于 SQL Generator 智能体，具体流程如下：

1. **示例库构建**：系统维护一个存储高质量自然语言到 SQL 示例的库，从 JSONL 文件加载。这些示例包含各种类型的 SQL 查询场景，如简单查询、复杂连接、聚合操作等。
2. **相似度匹配**：当用户提出自然语言问题时，系统会计算该问题与示例库中问题的语义相似度。
3. **示例选择**：基于相似度排序，选择最相关的 top-k 个高质量示例。
4. **提示增强**：将这些示例注入到给大语言模型的提示中，指导模型生成更准确的 SQL 语句。
5. **生成指导**：模型参考示例的结构和风格，结合用户问题和表结构，生成符合要求的 SQL 语句。

### 技术实现

- **示例存储**：使用 JSONL 格式存储示例，每条示例包含自然语言问题和对应的 SQL 语句。
- **相似度计算**：利用预训练的嵌入模型将问题转换为向量，计算向量相似度。
- **示例选择**：根据相似度得分选择最相关的示例。
- **提示构造**：将选中的示例与用户问题、表结构一起构造提示，确保模型能理解任务要求。

### 优势

1. **减少数据需求**：不需要大量的标注数据，仅需少量高质量示例。
2. **提高生成质量**：通过示例指导，模型能生成更符合特定场景的 SQL 语句。
3. **学习最佳实践**：示例库可以包含领域专家编写的高质量 SQL，使模型学习到最佳实践。
4. **适应不同场景**：通过扩展示例库，可以适应不同领域和复杂度的 SQL 生成需求。
5. **灵活性**：可以根据具体应用场景调整示例库，提高系统的适应性。

### 应用效果

通过 Few-shot 学习，Text2SQL 系统能够：

- 处理更复杂的查询场景
- 生成更符合用户意图的 SQL 语句
- 减少生成错误
- 提高系统的泛化能力

## 性能优化

1. **向量索引预构建**：提前构建向量索引，加速首次查询
2. **缓存机制**：缓存常见查询的结果，提高响应速度
3. **并行处理**：对多个查询进行并行处理，提高系统吞吐量
4. **模型调优**：调整 LLM 参数，平衡生成质量和速度

## 扩展性

1. **支持多种数据库**：通过配置支持不同的 SQL 方言
2. **可插拔的 LLM**：支持替换不同的大语言模型
3. **自定义示例库**：可根据特定领域扩展示例库

## 总结

Text2SQL 算法通过多智能体协作、向量检索和大语言模型技术，实现了从自然语言到 SQL 的高效准确转换。算法流程清晰，逻辑完善，具有良好的可扩展性和可配置性，能够满足不同场景下的 SQL 生成需求。