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[自然语言问题]
        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 生成需求。