16 KiB
16 KiB
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[自然语言问题]
Actx[可选会话上文
dialog_context]
end
subgraph 核心处理层
A --> B[意图分类 classify_dialog]
Actx --> B
B -->|conversation| C[直接返回引导性中文回复]
B -->|text2sql| N0[问句归一 normalize_nl_question
TRANSLATE_EN_TO_ZH=true 默认开启]
N0 --> D0[合并上文用于检索选表
_merge_dialog_for_model]
subgraph "Schema Linker 表选择模块"
D[表选择流程]
D1[向量粗筛 _coarse_filter
SchemaIndexer Chroma 或全表降级]
D2[LLM 精筛 _llm_select_tables
select_tables]
D2b[经纪商维度表优先
_prioritize_broker_tables]
D3[外键双向扩展
_expand_relations]
D4[生成紧凑 Schema 字符串
to_compact_string]
D --> D1
D1 --> D2
D2 --> D2b
D2b --> D3
D3 --> D4
end
D0 --> D
subgraph "SQL Generator SQL生成模块"
E[SQL 生成 _generate_sql]
E1[Few-shot 示例增强 FewShotSelector
Chroma 或 JSONL FEWSHOT_USE_CHROMA]
E2[LLM chat 生成
temperature=0.0 top_p=1.0]
E3[sqlglot 方言归一
normalize_sql_for_dialect]
E --> E1
E1 --> E2
E2 --> E3
end
D4 --> E
subgraph "Validator SQL验证模块 _validate_sql"
F[程序校验]
F1[语法验证 sqlglot]
F1a[表列一致性验证 SchemaManager]
F1b[危险操作检查 check_dangerous_operations]
F1c[T-SQL 字面量规则检查
check_no_cjk_in_sql_string_literals]
F1d[库探针 probe_sql_execution_status_ex
需 database_url 配置]
F2[LLM 语义验证 validate_sql
仅探针为 None 时调用]
F0a[探针 1 交付说明
sql_probe_success_delivery_message]
F0b[探针 0 无数据说明
empty_result_user_feedback]
F --> F1
F1 --> F1a
F1a --> F1b
F1b --> F1c
F1c -->|无程序错误| F1d
F1c -->|有程序错误| I[未通过 max_retry 内重试]
F1d -->|探针 None| F2
F1d -->|探针 1| F0a
F1d -->|探针 0| F0b
F1d -->|探针 -1| I
F2 -->|LLM 报错| I
F2 -->|通过| H[GenerationResult 有效 SQL]
F0a --> H
F0b --> H
end
E3 --> F
I --> R[重试回合]
R --> R1[extract_tables 合并上次SQL引用的表]
R1 --> R2[外键再扩展 _expand_relations]
R2 --> R3[重新生成紧凑 Schema to_compact_string]
R3 -->|下一 attempt| E
end
subgraph 数据层
J[SchemaManager
加载 Schema 元数据]
K[Chroma 持久化
schema 向量索引 SchemaIndexer]
K2[Few-shot 向量库或 JSONL
FewShotSelector]
Emb[嵌入模型
OpenAI 兼容 Embeddings API]
M[DeepSeek LLM
统一接口 deepseek.chat/select_tables
/validate_sql 等方法]
N[业务库 SQLAlchemy
database_url]
J --> D1
J --> F1a
Emb --> D1
Emb --> E1
K --> D1
K2 --> E1
M --> N0
M --> D2
M --> E2
M --> F2
M --> F0a
M --> F0b
M --> B
N --> F1d
end
详细算法流程说明
1. 意图分类
- Dialog Classifier：对用户输入的自然语言进行意图分类
- 分类模式：支持
rules（仅规则）和hybrid（混合）两种模式rules模式：仅使用关键词和短语规则，无 LLM 调用hybrid模式（默认）：明显查数词/寒暄/元问题走规则快速返回；其余交 LLM 判断
- 分类结果：非查询意图（conversation）直接返回对话回复，查询意图（text2sql）进入 SQL 生成流程
- 规则关键词：包含查数词（查、查询、统计、汇总）、业务词（余额、交易、账户、持仓）、寒暄词（元问题、致谢等）
2. Schema Linker 表选择模块
-
问句归一化（可选）：
normalize_nl_question_for_text2sql- 将用户中英文问题归一为标准中文（默认开启，
TRANSLATE_EN_TO_ZH=true） - 使同一语义的中英文表述对齐，保证 SQL 一致性
- 使用 LLM temperature=0 贪心解码
- 将用户中英文问题归一为标准中文（默认开启，
-
对话上文合并：
_merge_dialog_for_model- 拼接上文与当前问句，控制总长度（默认 4000 字符用于检索，6000 字符用于选表）
- 优先保留当前问句完整
-
向量检索粗筛：
_coarse_filter→SchemaIndexer- 使用嵌入模型将表结构转换为向量
- 使用 Chroma DB 进行相似度搜索
- 返回 top-k 个最相关的候选表
- 可配置是否启用向量检索（
use_vector_search）
-
LLM 精筛：
_llm_select_tables→select_tables- 构造包含候选表名和注释的提示
- 调用 DeepSeek 模型选择最相关的表
- 返回相关表列表和选择理由
-
经纪商维度表优先（可选）：
_prioritize_broker_tables- 问题涉及对手方/经纪商时，优先纳入
TSBBrokerContract与MCBroker - 避免仅选中报表视图却无 BrokerID
- 问题涉及对手方/经纪商时，优先纳入
-
外键双向扩展：
_expand_relations- 自动添加被引用的表（外键指向的表）
- 自动添加引用当前表的表（反向外键）
- 确保 JOIN 完整性
-
生成紧凑 Schema 字符串：
to_compact_string- 根据选中的表生成紧凑的 Schema 描述
- 包含表名、注释、字段、类型、主键、外键等信息
3. SQL Generator SQL生成模块
-
Few-shot 示例增强：
FewShotSelector- 支持 Chroma 向量库或 JSONL 两种存储方式
- 根据用户问题计算语义相似度
- 选择 top-k 个最相似的高质量示例（支持评分、标签、难度过滤）
- 将示例注入到提示中，指导 SQL 生成
- 可配置
FEWSHOT_USE_CHROMA=true/false
-
LLM 生成 SQL：
_generate_sql→deepseek.chat- 构造包含 Schema、用户问题、示例（可选）、对话上文的提示
- 使用
temperature=0.0, top_p=1.0贪心解码 - T-SQL 特殊要求：使用方括号
[]、禁止反引号、+拼接字符串、今日用CAST(GETDATE() AS DATE)
-
SQL 方言归一：
normalize_sql_for_dialect- 使用 sqlglot 清理和规范化生成的 SQL
- 提取 markdown 代码块中的 SQL
4. Validator SQL验证模块
-
程序校验（确定性规则，按顺序执行）：
- 语法验证：
validate_sql_syntax（sqlglot） - Schema 一致性验证：
validate_schema_consistency（检查表和列是否存在于 Schema 中） - 危险操作检查：
check_dangerous_operations（DROP、DELETE、UPDATE、INSERT、ALTER、TRUNCATE 等） - T-SQL 字面量规则检查：
check_no_cjk_in_sql_string_literals（禁止在字符串字面量中出现中文）
- 语法验证：
-
数据库试执行（探针）：
probe_sql_execution_status_ex- 仅在程序校验全部通过后执行
- 需要配置
database_url环境变量 - 返回状态码：
- 1：执行成功，且有返回行 → 跳过 LLM 语义验证，直接将 SQL 交付用户，可调用
sql_probe_success_delivery_message生成交付说明 - 0：执行成功，但数据行数为 0 → 跳过 LLM 语义验证，调用
empty_result_user_feedback生成补充说明和追问引导 - -1：执行失败 → 进入重试流程，不交付 SQL
- None：未配置
database_url，跳过探针
- 1：执行成功，且有返回行 → 跳过 LLM 语义验证，直接将 SQL 交付用户，可调用
-
LLM 语义验证：
validate_sql（仅探针为 None 时调用）- 构造包含 SQL、表结构和用户问题的提示
- 让 LLM 评估 SQL 是否正确回答了用户问题
- 收集错误和警告信息
- 如果程序校验已通过 Schema 一致性，则过滤掉 LLM 常误报的
unknown_table和unknown_column错误
-
重试逻辑：
- 最多重试
max_retry次（默认 2） - 每次重试：
- 合并上次失败 SQL 中引用的表（
extract_tables_from_sql） - 外键再扩展
- 重新生成紧凑 Schema
- 将上次校验错误反馈给 LLM
- 合并上次失败 SQL 中引用的表（
- 最多重试
5. 数据层支持
- Schema 管理：
SchemaManager管理数据库表结构和元数据- 从 JSON/G3SB 文件加载表结构
- 提供表和列的查询接口
- 分析表之间的外键关系
- 生成紧凑的 Schema 描述字符串
- 向量数据库：
SchemaIndexer+ Chroma DB 存储和检索表向量- 支持增量更新和查询
- 可配置向量数据库路径
- Few-shot 示例库：
FewShotSelector管理高质量示例- 支持 Chroma 向量库或 JSONL 文件两种存储方式
- 基于语义相似度检索示例
- 支持评分、标签、难度过滤
- DeepSeek API：统一接口提供大语言模型能力
deepseek.chat通用对话select_tables表选择validate_sqlSQL 验证normalize_nl_question问句归一- 支持不同的模型参数配置
技术栈
| 类别 | 技术/库 | 用途 |
|---|---|---|
| 编程语言 | Python | 算法实现 |
| LLM | DeepSeek API | 提供大语言模型能力 |
| 向量检索 | Chroma DB | 存储和检索表的向量表示 |
| SQL 处理 | sqlglot | SQL 语法解析和验证 |
| 环境管理 | dotenv | 管理环境变量 |
算法特点
- 模块化编排架构：Text2SQLOrchestrator 统一编排表选择、SQL 生成、SQL 验证三大模块，各模块协同工作形成完整处理流程
- 问句归一化：支持中英文问句归一为标准中文（默认开启），保证同一语义的查询生成一致的 SQL
- 向量检索增强：Schema Linker 使用 Chroma 向量数据库快速筛选相关表，提高表选择效率，可配置启用/禁用
- 经纪商维度表优先：针对证券/期货业务场景，涉及对手方/经纪商的问题自动优先纳入经纪商维度表
- Few-shot 学习：SQL Generator 利用示例库增强 SQL 生成质量，支持 Chroma 向量库或 JSONL 存储方式，可配置启用/禁用
- 多层验证机制：程序校验（语法 + Schema 一致性 + 危险操作 + T-SQL 字面量规则）+ 库上探针 + LLM 语义验证
- 智能探针分流：探针返回 1（有数据）直接交付、0（无数据）附带说明引导用户补充条件、-1（失败）自动重试，None 时走 LLM 语义验证兜底
- 自动关联表扩展：通过外键关系双向扩展相关表，确保 JOIN 完整性
- 对话上下文支持：支持多轮对话的上下文合并，处理指代消解和续问
- 可配置性：支持多种配置参数，如最大重试次数、向量检索开关、Few-shot 配置、问句归一开关等，适应不同场景需求
Few-shot 学习详细说明
概念介绍
Few-shot 学习是一种机器学习方法，指通过少量示例来指导模型学习和执行任务。与传统的监督学习需要大量标注数据不同，Few-shot 学习仅需提供少量（通常为个位数）的示例，就能让模型理解任务的模式和要求。
在 Text2SQL 系统中的应用
在 Text2SQL 系统中，Few-shot 学习应用于 SQL 生成阶段，通过 FewShotSelector 组件实现，具体流程如下：
-
示例库构建：系统维护一个存储高质量自然语言到 SQL 示例的库，支持两种存储方式：
- Chroma 向量库：
FEWSHOT_USE_CHROMA=true时使用，提供高效的相似度检索 - JSONL 文件：传统方式，从
all_samples.jsonl加载示例 - 每条示例包含：问题（中文/英文）、SQL 语句、评分、标签、难度等级等元数据
- Chroma 向量库：
-
相似度匹配：当用户提出自然语言问题时，使用嵌入模型将问题转换为向量，计算向量相似度
-
示例选择：基于相似度排序，支持多维度过滤：
top_k：选择最相关的 top-k 个示例（默认 3）min_rating：最低评分过滤（默认 7）required_tags：必须包含的标签max_difficulty：最大难度过滤
-
提示增强：将选中的示例注入到给大语言模型的提示中，格式为：
参考以下相似示例的SQL编写风格： 示例 1： 问题：xxx SQL： xxx 【当前Schema】 xxx -
生成指导：模型参考示例的结构和风格，结合用户问题和表结构，生成符合要求的 SQL 语句
技术实现
- 示例存储：支持 Chroma 向量库持久化或 JSONL 文件加载两种方式
- 向量索引：
- Chroma 模式：使用 Chroma DB 存储和检索向量
- JSONL 模式：内存 numpy 数组 + 可选 .npy 缓存
- 相似度计算：利用预训练的嵌入模型将问题转换为向量，使用余弦相似度计算
- 示例选择：根据相似度得分和元数据过滤选择最相关的示例
- 提示构造：将选中的示例与用户问题、表结构一起构造提示，确保模型能理解任务要求
优势
- 减少数据需求：不需要大量的标注数据，仅需少量高质量示例
- 提高生成质量：通过示例指导，模型能生成更符合特定场景的 SQL 语句
- 学习最佳实践：示例库可以包含领域专家编写的高质量 SQL，使模型学习到最佳实践
- 适应不同场景：通过扩展示例库，可以适应不同领域和复杂度的 SQL 生成需求
- 灵活性：支持 Chroma 和 JSONL 两种存储方式，可根据场景选择
- 高质量保障：通过评分、标签、难度等元数据过滤，确保选用高质量示例
应用效果
通过 Few-shot 学习，Text2SQL 系统能够：
- 处理更复杂的查询场景
- 生成更符合用户意图的 SQL 语句
- 减少生成错误
- 提高系统的泛化能力
- 通过示例学习特定业务场景的 SQL 编写风格
性能优化
- 向量索引预构建：
build_vector_index方法提前构建向量索引，加速首次查询 - 懒加载机制：向量索引在首次使用时才加载，避免启动开销
- Few-shot 缓存：向量缓存到
.npy文件，换模型自动重建 - 贪心解码：SQL 生成使用
temperature=0.0贪心解码，提高一致性和速度 - 库探针优化：仅取 1 行数据（
max_rows=1）判断探针状态，最小化数据库负载 - SQL 执行优化：
- 聚合查询优先直接执行而非 COUNT 包裹
- 自动去掉派生表内无意义的 ORDER BY
- 支持多种 SQL 方言的语法处理
扩展性
- 支持多种数据库：通过 sqlglot 支持不同的 SQL 方言（T-SQL、MySQL、PostgreSQL 等）
- 可插拔的 LLM：统一通过
DeepSeekClient接口调用，支持替换不同的大语言模型 - 可配置的嵌入模型：通过环境变量支持 OpenAI、ModelScope、DashScope 等多种嵌入 API
- 自定义示例库：可根据特定领域扩展示例库，支持 Chroma 或 JSONL 格式
- Schema 灵活加载：支持从 JSON 文件或 G3SB 格式加载 Schema
- 意图分类可扩展：支持 rules 和 hybrid 两种模式，可扩展更多分类策略
总结
Text2SQL 算法通过模块化编排架构、向量检索、问句归一化和 Few-shot 学习技术，实现了从自然语言到 SQL 的高效准确转换。系统采用多层验证机制（程序校验 + 库上探针 + LLM 语义验证），配合智能探针分流策略，确保生成的 SQL 既正确又符合用户意图。算法流程清晰，逻辑完善，具有良好的可扩展性和可配置性，能够满足证券/期货等金融业务场景下的 SQL 生成需求。