375 lines
16 KiB
Markdown
375 lines
16 KiB
Markdown
# 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[自然语言问题]
|
||
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`，跳过探针
|
||
|
||
- **LLM 语义验证**：`validate_sql`（仅探针为 None 时调用）
|
||
- 构造包含 SQL、表结构和用户问题的提示
|
||
- 让 LLM 评估 SQL 是否正确回答了用户问题
|
||
- 收集错误和警告信息
|
||
- 如果程序校验已通过 Schema 一致性，则过滤掉 LLM 常误报的 `unknown_table` 和 `unknown_column` 错误
|
||
|
||
- **重试逻辑**：
|
||
- 最多重试 `max_retry` 次（默认 2）
|
||
- 每次重试：
|
||
- 合并上次失败 SQL 中引用的表（`extract_tables_from_sql`）
|
||
- 外键再扩展
|
||
- 重新生成紧凑 Schema
|
||
- 将上次校验错误反馈给 LLM
|
||
|
||
### 5. 数据层支持
|
||
|
||
- **Schema 管理**：`SchemaManager` 管理数据库表结构和元数据
|
||
- 从 JSON/G3SB 文件加载表结构
|
||
- 提供表和列的查询接口
|
||
- 分析表之间的外键关系
|
||
- 生成紧凑的 Schema 描述字符串
|
||
- **向量数据库**：`SchemaIndexer` + Chroma DB 存储和检索表向量
|
||
- 支持增量更新和查询
|
||
- 可配置向量数据库路径
|
||
- **Few-shot 示例库**：`FewShotSelector` 管理高质量示例
|
||
- 支持 Chroma 向量库或 JSONL 文件两种存储方式
|
||
- 基于语义相似度检索示例
|
||
- 支持评分、标签、难度过滤
|
||
- **DeepSeek API**：统一接口提供大语言模型能力
|
||
- `deepseek.chat` 通用对话
|
||
- `select_tables` 表选择
|
||
- `validate_sql` SQL 验证
|
||
- `normalize_nl_question` 问句归一
|
||
- 支持不同的模型参数配置
|
||
|
||
## 技术栈
|
||
|
||
| 类别 | 技术/库 | 用途 |
|
||
| ------ | ------------ | ----------- |
|
||
| 编程语言 | Python | 算法实现 |
|
||
| LLM | DeepSeek API | 提供大语言模型能力 |
|
||
| 向量检索 | Chroma DB | 存储和检索表的向量表示 |
|
||
| SQL 处理 | sqlglot | SQL 语法解析和验证 |
|
||
| 环境管理 | dotenv | 管理环境变量 |
|
||
|
||
## 算法特点
|
||
|
||
1. **模块化编排架构**：Text2SQLOrchestrator 统一编排表选择、SQL 生成、SQL 验证三大模块，各模块协同工作形成完整处理流程
|
||
2. **问句归一化**：支持中英文问句归一为标准中文（默认开启），保证同一语义的查询生成一致的 SQL
|
||
3. **向量检索增强**：Schema Linker 使用 Chroma 向量数据库快速筛选相关表，提高表选择效率，可配置启用/禁用
|
||
4. **经纪商维度表优先**：针对证券/期货业务场景，涉及对手方/经纪商的问题自动优先纳入经纪商维度表
|
||
5. **Few-shot 学习**：SQL Generator 利用示例库增强 SQL 生成质量，支持 Chroma 向量库或 JSONL 存储方式，可配置启用/禁用
|
||
6. **多层验证机制**：程序校验（语法 + Schema 一致性 + 危险操作 + T-SQL 字面量规则）+ 库上探针 + LLM 语义验证
|
||
7. **智能探针分流**：探针返回 1（有数据）直接交付、0（无数据）附带说明引导用户补充条件、-1（失败）自动重试，None 时走 LLM 语义验证兜底
|
||
8. **自动关联表扩展**：通过外键关系双向扩展相关表，确保 JOIN 完整性
|
||
9. **对话上下文支持**：支持多轮对话的上下文合并，处理指代消解和续问
|
||
10. **可配置性**：支持多种配置参数，如最大重试次数、向量检索开关、Few-shot 配置、问句归一开关等，适应不同场景需求
|
||
|
||
## Few-shot 学习详细说明
|
||
|
||
### 概念介绍
|
||
|
||
Few-shot 学习是一种机器学习方法，指通过少量示例来指导模型学习和执行任务。与传统的监督学习需要大量标注数据不同，Few-shot 学习仅需提供少量（通常为个位数）的示例，就能让模型理解任务的模式和要求。
|
||
|
||
### 在 Text2SQL 系统中的应用
|
||
|
||
在 Text2SQL 系统中，Few-shot 学习应用于 SQL 生成阶段，通过 `FewShotSelector` 组件实现，具体流程如下：
|
||
|
||
1. **示例库构建**：系统维护一个存储高质量自然语言到 SQL 示例的库，支持两种存储方式：
|
||
- **Chroma 向量库**：`FEWSHOT_USE_CHROMA=true` 时使用，提供高效的相似度检索
|
||
- **JSONL 文件**：传统方式，从 `all_samples.jsonl` 加载示例
|
||
- 每条示例包含：问题（中文/英文）、SQL 语句、评分、标签、难度等级等元数据
|
||
|
||
2. **相似度匹配**：当用户提出自然语言问题时，使用嵌入模型将问题转换为向量，计算向量相似度
|
||
|
||
3. **示例选择**：基于相似度排序，支持多维度过滤：
|
||
- `top_k`：选择最相关的 top-k 个示例（默认 3）
|
||
- `min_rating`：最低评分过滤（默认 7）
|
||
- `required_tags`：必须包含的标签
|
||
- `max_difficulty`：最大难度过滤
|
||
|
||
4. **提示增强**：将选中的示例注入到给大语言模型的提示中，格式为：
|
||
```
|
||
参考以下相似示例的SQL编写风格：
|
||
|
||
示例 1：
|
||
问题：xxx
|
||
SQL：
|
||
xxx
|
||
|
||
【当前Schema】
|
||
xxx
|
||
```
|
||
|
||
5. **生成指导**：模型参考示例的结构和风格，结合用户问题和表结构，生成符合要求的 SQL 语句
|
||
|
||
### 技术实现
|
||
|
||
- **示例存储**：支持 Chroma 向量库持久化或 JSONL 文件加载两种方式
|
||
- **向量索引**：
|
||
- Chroma 模式：使用 Chroma DB 存储和检索向量
|
||
- JSONL 模式：内存 numpy 数组 + 可选 .npy 缓存
|
||
- **相似度计算**：利用预训练的嵌入模型将问题转换为向量，使用余弦相似度计算
|
||
- **示例选择**：根据相似度得分和元数据过滤选择最相关的示例
|
||
- **提示构造**：将选中的示例与用户问题、表结构一起构造提示，确保模型能理解任务要求
|
||
|
||
### 优势
|
||
|
||
1. **减少数据需求**：不需要大量的标注数据，仅需少量高质量示例
|
||
2. **提高生成质量**：通过示例指导，模型能生成更符合特定场景的 SQL 语句
|
||
3. **学习最佳实践**：示例库可以包含领域专家编写的高质量 SQL，使模型学习到最佳实践
|
||
4. **适应不同场景**：通过扩展示例库，可以适应不同领域和复杂度的 SQL 生成需求
|
||
5. **灵活性**：支持 Chroma 和 JSONL 两种存储方式，可根据场景选择
|
||
6. **高质量保障**：通过评分、标签、难度等元数据过滤，确保选用高质量示例
|
||
|
||
### 应用效果
|
||
|
||
通过 Few-shot 学习，Text2SQL 系统能够：
|
||
|
||
- 处理更复杂的查询场景
|
||
- 生成更符合用户意图的 SQL 语句
|
||
- 减少生成错误
|
||
- 提高系统的泛化能力
|
||
- 通过示例学习特定业务场景的 SQL 编写风格
|
||
|
||
## 性能优化
|
||
|
||
1. **向量索引预构建**：`build_vector_index` 方法提前构建向量索引，加速首次查询
|
||
2. **懒加载机制**：向量索引在首次使用时才加载，避免启动开销
|
||
3. **Few-shot 缓存**：向量缓存到 `.npy` 文件，换模型自动重建
|
||
4. **贪心解码**：SQL 生成使用 `temperature=0.0` 贪心解码，提高一致性和速度
|
||
5. **库探针优化**：仅取 1 行数据（`max_rows=1`）判断探针状态，最小化数据库负载
|
||
6. **SQL 执行优化**：
|
||
- 聚合查询优先直接执行而非 COUNT 包裹
|
||
- 自动去掉派生表内无意义的 ORDER BY
|
||
- 支持多种 SQL 方言的语法处理
|
||
|
||
## 扩展性
|
||
|
||
1. **支持多种数据库**：通过 sqlglot 支持不同的 SQL 方言（T-SQL、MySQL、PostgreSQL 等）
|
||
2. **可插拔的 LLM**：统一通过 `DeepSeekClient` 接口调用，支持替换不同的大语言模型
|
||
3. **可配置的嵌入模型**：通过环境变量支持 OpenAI、ModelScope、DashScope 等多种嵌入 API
|
||
4. **自定义示例库**：可根据特定领域扩展示例库，支持 Chroma 或 JSONL 格式
|
||
5. **Schema 灵活加载**：支持从 JSON 文件或 G3SB 格式加载 Schema
|
||
6. **意图分类可扩展**：支持 rules 和 hybrid 两种模式，可扩展更多分类策略
|
||
|
||
## 总结
|
||
|
||
Text2SQL 算法通过模块化编排架构、向量检索、问句归一化和 Few-shot 学习技术，实现了从自然语言到 SQL 的高效准确转换。系统采用多层验证机制（程序校验 + 库上探针 + LLM 语义验证），配合智能探针分流策略，确保生成的 SQL 既正确又符合用户意图。算法流程清晰，逻辑完善，具有良好的可扩展性和可配置性，能够满足证券/期货等金融业务场景下的 SQL 生成需求。
|