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 的转换流程。

核心算法流程

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 生成需求。