# solon-ai-nl2sql

**Repository Path**: ai-space-org/solon-ai-nl2sql

## Basic Information

- **Project Name**: solon-ai-nl2sql
- **Description**: 基于 Solon 框架的 NL2SQL（自然语言转SQL）智能框架，Solon版本的SuperSQL。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: https://supersql.ai-space.com.cn/
- **GVP Project**: No

## Statistics

- **Stars**: 4
- **Forks**: 0
- **Created**: 2026-04-18
- **Last Updated**: 2026-06-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">
  <img src="https://tiger-bucket.oss-cn-shanghai.aliyuncs.com/super-sql/logo.png" alt="Solon AI NL2SQL" width="200">

  <h1>Solon AI NL2SQL</h1>

  <p><strong>基于 Solon 框架的智能 SQL 生成引擎 | 自然语言转 SQL</strong></p>

  <p>
    <a href="#-项目介绍">项目介绍</a>
    ·
    <a href="#-核心特性">核心特性</a>
    ·
    <a href="#-快速开始">快速开始</a>
    ·
    <a href="#-架构设计">架构设计</a>
    ·
    <a href="#-API文档">API 文档</a>
  </p>

  <p>
    <img src="https://img.shields.io/badge/Solon-3.10.3-blue" alt="Solon">
    <img src="https://img.shields.io/badge/Java-21-orange" alt="Java">
    <img src="https://img.shields.io/badge/License-Apache%202.0-green" alt="License">
    <img src="https://img.shields.io/badge/build-passing-brightgreen" alt="Build">
    <img src="https://img.shields.io/badge/maven-v1.0.0-blue" alt="Maven">
  </p>

  <p>
    <a href="https://gitee.com/guocjsh/super-sql" target="_blank"><img src="https://img.shields.io/badge/Gitee-SuperSQL-red" alt="Gitee"></a>
    <a href="https://github.com/guocjsh/SuperSQL" target="_blank"><img src="https://img.shields.io/badge/GitHub-SuperSQL-blue" alt="GitHub"></a>
    <a href="https://gitcode.com/GuoChengJie/SuperSQL" target="_blank"><img src="https://img.shields.io/badge/GitCode-SuperSQL-orange" alt="GitCode"></a>
  </p>
</div>

---

## 📖 项目介绍

**Solon AI NL2SQL** 是一个基于 Solon 框架的智能 SQL 生成框架，采用先进的 AI 技术和 RAG（检索增强生成）技术，实现从自然语言到 SQL 的智能转换。

该项目是对 **SuperSQL** 项目的 Solon 框架重写版本，保留了 SuperSQL 的核心设计理念和优秀架构，同时充分利用 Solon 框架的轻量高效特性。

### 🌟 项目来源

- **母项目**: [SuperSQL](https://github.com/guocjsh/SuperSQL) - 由 GuoChengJie 开发
- **Gitee**: [https://gitee.com/guocjsh/super-sql](https://gitee.com/guocjsh/super-sql)
- **GitHub**: [https://github.com/guocjsh/SuperSQL](https://github.com/guocjsh/SuperSQL)
- **GitCode**: [https://gitcode.com/GuoChengJie/SuperSQL](https://gitcode.com/GuoChengJie/SuperSQL)

### 📌 核心特性

- ✅ **自然语言转 SQL** - 支持中文自然语言到 SQL 的智能转换
- ✅ **RAG 技术增强** - 通过检索增强生成提高 SQL 准确性
- ✅ **向量数据库集成** - 支持 Chroma 向量数据库存储和检索
- ✅ **多模型支持** - 支持 OpenAI、Azure OpenAI、Kimi 等多种 AI 模型
- ✅ **多数据库支持** - 支持 MySQL、PostgreSQL、Oracle、SQL Server 等主流数据库
- ✅ **SQL 自修复** - 内置 SQL 验证和自修复机制
- ✅ **重排序机制** - 支持 Rerank 提高检索质量
- ✅ **类型安全** - 利用 Java 泛型机制确保编译期类型检查
- ✅ **易于扩展** - 采用策略模式、工厂模式等设计模式，易于功能扩展
- ✅ **Solon 框架集成** - 完美集成 Solon 生态，轻量高效

---

## 🚀 快速开始

### 环境要求

- JDK 21+
- Maven 3.8+
- Solon 3.10.3+
- ChromaDB 1.0.0+

### 安装依赖

在 `pom.xml` 中添加依赖：

```xml
<dependency>
    <groupId>uno.aispace</groupId>
    <artifactId>solon-ai-nl2sql-plugin</artifactId>
    <version>1.0.0</version>
</dependency>
```

### 配置文件

在 `app.yml` 中配置：

```yaml
# Solon AI 配置
solon:
  ai:
    # Chat 模型配置
    chat:
      nl2sql:
        api-key: your-api-key
        api-url: https://ark.cn-beijing.volces.com/api/v3/chat/completions
        model: kimi-k2-5-260127
        provider: openai
    
    # Embedding 模型配置
    embed:
      azure:
        api-key: your-azure-api-key
        api-url: https://your-azure-endpoint/openai/deployments/your-deployment/embeddings?api-version=2023-05-15
        model: your-deployment-name
        provider: openai
    
    # 向量数据库配置
    repo:
      chroma:
        url: http://localhost:8000
```

### 代码示例

```java
@Inject
private SqlEngine sqlEngine;

public void demo() {
    // 1. 生成 SQL
    String sql = sqlEngine.generateSql("查询所有年龄大于18岁的用户");
    System.out.println(sql);
    // 输出: SELECT * FROM users WHERE age > 18
    
    // 2. 注入 DDL（推荐）
    TrainingRequest ddlRequest = TrainingRequest.builder()
        .policy(TrainingPolicy.DDL)
        .ddl("CREATE TABLE users (id INT, name VARCHAR(50), age INT)")
        .tableName("users")
        .build();
    sqlEngine.train(ddlRequest);
    
    // 3. 训练 SQL 示例
    TrainingRequest sqlRequest = TrainingRequest.ofSql(
        "查询所有男性用户",
        "SELECT * FROM users WHERE gender = 'male'"
    );
    sqlEngine.train(sqlRequest);
}
```

### 启动项目运行

```bash
# 编译项目
mvn clean install

# 启动示例
cd solon-ai-nl2sql-console
mvn solon:run
```

或者使用提供的脚本：

```bash
# Windows
start.bat

# 使用官方 API 启动
start-with-official-api.bat
```

---

## 💡 使用示例

### 1. 基础 SQL 生成

```java
// 简单查询
String sql = sqlEngine.generateSql("查询所有用户");

// 指定数据库类型
String sql = sqlEngine.generateSql("查询所有订单", DatabaseType.POSTGRESQL);
```

### 2. 高级配置

```java
// 使用 RAG 配置
RagOptions options = RagOptions.builder()
    .topN(5)
    .limitScore(0.7)
    .rerank(true)
    .validateSql(true)
    .temperature(0.3)
    .build();

String sql = sqlEngine.withOptions(options)
    .withDatabaseType(DatabaseType.MYSQL)
    .generateSql("统计每个部门的员工数量");
```

### 3. 训练模型

```java
// DDL 训练（推荐：注入表结构，提高准确性）
TrainingRequest ddlRequest = TrainingRequest.builder()
    .policy(TrainingPolicy.DDL)
    .ddl("CREATE TABLE users (id INT, name VARCHAR(50), age INT)")
    .tableName("users")
    .build();

// SQL 训练
TrainingRequest sqlRequest = TrainingRequest.ofSql(
    "查询所有成年用户",
    "SELECT * FROM users WHERE age >= 18"
);

// 批量训练
sqlEngine.trainBatch(Arrays.asList(ddlRequest, sqlRequest));
```

### 4. DDL 注入（重要）

**推荐在项目启动时注入所有核心表的 DDL**，让 AI 知道准确的表名和字段信息：

```java
// 通过 REST API 注入 DDL
POST /api/sql/train/ddl
{
  "ddl": "CREATE TABLE `dtp_hospital` (...)",
  "tableName": "dtp_hospital",
  "databaseName": "default"
}
```

**效果对比：

- ❌ **没有注入 DDL**：AI 猜测表名 → `SELECT * FROM hospitals WHERE ...`（错误）
- ✅ **注入 DDL 后**：AI 知道准确表名 → `SELECT * FROM dtp_hospital WHERE ...`（正确）

### 5. REST API 使用

项目提供了完整的 REST API 接口：

```bash
# 生成 SQL
POST /api/sql/generate?question=查询北京的医院数量&dbType=MYSQL

# 高级 SQL 生成
POST /api/sql/generate/advanced
{
  "question": "统计每个省份的医院数量",
  "dbType": "MYSQL",
  "topN": 5,
  "limitScore": 0.7,
  "rerank": false,
  "validateSql": true,
  "temperature": 0.3
}

# 训练 DDL
POST /api/sql/train/ddl
{
  "ddl": "CREATE TABLE ...",
  "tableName": "dtp_hospital",
  "databaseName": "default"
}

# 批量训练
POST /api/sql/train/batch
[{...}, {...}]

# 验证 SQL
GET /api/sql/validate?sql=SELECT * FROM dtp_hospital
```

---

## 🏗️ 架构设计

### 模块结构

```
solon-ai-nl2sql
├── solon-ai-nl2sql-core        # 核心模块
│   ├── engine                  # 引擎接口和抽象实现
│   ├── enums                   # 枚举类型
│   ├── model                   # 数据模型
│   ├── prompt                  # 提示词模板
│   ├── vector                 # 向量存储接口
│   ├── validator              # SQL 验证器
│   ├── healer                # SQL 自修复器
│   ├── rerank                # 重排序器
│   ├── training               # 训练管理器
│   └── util                  # 工具类
├── solon-ai-nl2sql-plugin      # Solon 插件模块
│   ├── config                  # 自动配置
│   ├── engine                  # Solon AI 引擎实现
│   └── vector                  # 向量存储实现
└── solon-ai-nl2sql-console     # 控制台示例
    ├── controller              # REST 接口
    └── example                # 示例代码
```

### 设计模式

本项目采用了多种优秀的设计模式：

#### 1. 策略模式（Strategy Pattern）
用于支持不同的数据库类型和 AI 模型。

```java
public interface SqlEngine {
    String generateSql(String question, DatabaseType dbType);
}
```

#### 2. 建造者模式（Builder Pattern）
用于构建复杂的配置对象。

```java
RagOptions options = RagOptions.builder()
    .topN(5)
    .limitScore(0.7)
    .build();
```

#### 3. 模板方法模式（Template Method Pattern）
用于定义 SQL 生成的核心流程。

```java
public abstract class AbstractSqlEngine implements SqlEngine {
    @Override
    public String generateSql(String question, DatabaseType dbType, RagOptions options) {
        // 1. 参数校验
        validateParameters(question, options);
        // 2. RAG 检索
        List<String> docs = retrieveRelevantDocuments(question, options);
        // 3. 构建提示词
        String prompt = buildPrompt(question, dbType, docs, options);
        // 4. 调用 AI 模型
        String response = callAiModel(prompt, options);
        // 5. 提取 SQL
        return extractSql(response);
    }
}
```

#### 4. 工厂模式（Factory Pattern）
用于创建不同类型的引擎和客户端。

#### 5. 适配器模式（Adapter Pattern）
用于适配不同的 AI 模型和向量数据库。

### 技术架构图

```
┌─────────────────────────────────────────────────────────┐
│                     客户端 (Client)
├─────────────────────────────────────────────────────────┤
│                                                        │
│  ┌────────────────────────────────────────────────────┐  │
│  │         SqlEngine (SQL 引擎)                    │  │
│  │  ┌──────────────────────────────────────┐  │  │
│  │  │  AbstractSqlEngine (模板方法)       │  │  │
│  │  └──────────────────────────────────────┘  │  │
│  │         ↓                                   │  │
│  │  ┌──────────────────────────────────────┐  │  │
│  │  │  SolonSqlEngine (Solon实现)      │  │  │
│  │  └──────────────────────────────────────┘  │  │
│  └────────────────────────────────────────────────────┘  │
│                                                        │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────┐  │
│  │  VectorStore │◄─┤  Reranker  │◄─┤Healer│  │
│  └──────────────┘  └──────────────┘  └──────────┘  │
│                                                        │
│  ┌──────────────────────────────────────────────┐  │
│  │    Solon AI (ChatModel + EmbeddingModel) │  │
│  └──────────────────────────────────────────────┘  │
│                                                        │
│  ┌──────────────────────────────────────────────┐  │
│  │       Chroma Repository (向量数据库)          │  │
│  └──────────────────────────────────────────────┘  │
│                                                        │
└─────────────────────────────────────────────────────────┘
```

---

## 🎨 技术栈

| 技术 | 版本 | 说明 |
|------|------|------|
| Solon | 3.10.3 | 轻量级 Java 框架 |
| Solon AI | 3.10.3 | Solon AI 生态 |
| Java | 21 | 编程语言 |
| Hutool | 5.8.35 | Java 工具类库 |
| FastJSON2 | 2.0.51 | JSON 处理 |
| Lombok | 1.18.32 | 代码简化 |
| MyBatis Plus | 3.5.8 | ORM 框架 |
| MySQL | 8.0.33 | 数据库 |
| H2 | 2.2.224 | 内存数据库 |
| ChromaDB | 1.0.0+ | 向量数据库 |

---

## 📝 API 文档

### SqlEngine API

```java
public interface SqlEngine {
    // 基础 SQL 生成
    String generateSql(String question);
    String generateSql(String question, DatabaseType dbType);
    
    // 链式调用
    SqlEngine withOptions(RagOptions options);
    SqlEngine withDatabaseType(DatabaseType dbType);
    
    // 训练
    void train(TrainingRequest request);
    void trainBatch(List<TrainingRequest> requests);
    
    // 验证
    boolean validateSql(String sql);
}
```

### TrainingRequest API

```java
// DDL 训练
TrainingRequest.ofDdl(String ddl);

// SQL 训练
TrainingRequest.ofSql(String question, String sql);

// 文档训练
TrainingRequest.ofDocument(String document);

// 完整构建
TrainingRequest.builder()
    .policy(TrainingPolicy policy)
    .ddl(String ddl)
    .sql(String sql)
    .question(String question)
    .document(String document)
    .tableName(String tableName)
    .databaseName(String databaseName)
    .metadata(Map<String, Object> metadata)
    .build();
```

### RagOptions API

```java
RagOptions.builder()
    .topN(int topN)                    // 返回数量
    .limitScore(double limitScore)      // 最低相似度阈值
    .rerank(boolean rerank)            // 是否重排序
    .validateSql(boolean validateSql)    // 是否验证 SQL
    .temperature(double temperature)       // 温度参数
    .build();
```

---

## 🤝 贡献指南

我们非常欢迎社区贡献！

### 贡献方式

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 提交 Pull Request

### 代码规范

- 遵循 Java 编码规范
- 添加必要的注释和文档
- 编写单元测试
- 保持代码简洁清晰

### 开发流程

```bash
# 1. 克隆项目
git clone https://gitee.com/ai-space-org/solon-ai-nl2sql.git

# 2. 编译项目
mvn clean install

# 3. 运行测试
mvn test

# 4. 启动示例
cd solon-ai-nl2sql-console
mvn solon:run
```

---

## 📄 许可证

本项目采用 Apache 2.0 许可证。详见 [LICENSE](LICENSE) 文件。

---

## 👨‍💻 作者

**GuoChengJie**

- Email: chengjie.x.guo@gsk.com
- Organization: AI Space
- GitHub: [@GuoChengJie](https://github.com/guocjsh)
- Gitee: [@guocjsh](https://gitee.com/guocjsh)

---

## 🙏 致谢

感谢以下项目的启发：

- [SuperSQL](https://github.com/guocjsh/SuperSQL) - 原始项目
- [Solon](https://solon.noear.org/) - 优秀的 Java 框架
- [Spring AI](https://spring.io/projects/spring-ai) - AI 集成参考

---

## 📚 相关文档

- [快速开始指南](quick-start-guide.md)
- [Azure OpenAI 配置指南](AZURE_OPENAI_CONFIG.md)
- [官方 API 迁移指南](OFFICIAL_API_MIGRATION.md)
- [配置完成报告](CONFIGURATION_COMPLETE.md)
- [测试报告](TEST_REPORT.md)

---

<div align="center">
  <p><strong>让 AI 点亮生活 | AI Space © 2026</strong></p>
  <p>
    <sub>如果这个项目对您有帮助，请给我们一个 ⭐️ Star 支持一下！</sub>
  </p>
  <p>
    <a href="README.en.md">English Version</a>
  </p>
</div>