supersql-open

README

<p align="center">
	<img alt="logo" src="https://tiger-bucket.oss-cn-shanghai.aliyuncs.com/super-sql/logo.png" width="200" height="60">
</p>
<h1 align="center" style="margin: 30px 0 30px; font-weight: bold;">SuperSQL 1.0.0-M1</h1>
<h4 align="center">中国人自己的生成式SQL Java框架！轻量，易用，易扩展!</h4>

<p align="center">
  <a href="https://gitee.com/guocjsh/supersql-open/blob/master/README.en.md"><img src="https://img.shields.io/badge/English_README-blue" alt="English README"></a>
  <a href="https://gitee.com/guocjsh/supersql-open/blob/master/README.md"><img src="https://img.shields.io/badge/简体中文_README-blue" alt="English README"></a>
  <a href="https://www.apache.org/licenses/LICENSE-2.0.txt"><img src="https://img.shields.io/github/license/guocjsh/SuperSQL?color=%231890FF" alt="License: Apache-2.0"></a>
  <a href="https://github.com/guocjsh/SuperSQL"><img src="https://img.shields.io/github/stars/guocjsh/SuperSQL?style=flat-square" alt="Stars"></a>
  <a href="https://gitee.com/guocjsh/SuperSQL"><img src="https://gitee.com/guocjsh/supersql-open/badge/star.svg?theme=gvp" alt="Gitee Stars"></a>
  <a href="https://gitcode.com/GuoChengJie/SuperSQL"><img src="https://gitcode.com/GuoChengJie/SuperSQL/star/badge.svg" alt="GitCode Stars"></a>
</p>

---

### SuperSQL 介绍
SuperSQL 是一个基于国内外先进生成式大模型实现Nl2sql的Java框架，专注于将数据库表结构通过检索增强生成（RAG, Retrieval-Augmented Generation）技术进行训练，从而实现从自然语言文本到SQL查询的智能转换（Text to SQL）。该框架旨在简化复杂的数据库查询过程，使开发者和用户能够通过简单的自然语言描述获取所需数据。

主要特性包括：

- **生成式SQL**：利用强大的生成式大模型，自动将自然语言问题转化为精确的SQL查询语句。
- **RAG训练**：通过检索增强生成技术对数据库表结构进行深度学习训练，提高SQL生成的准确性和效率。
- **类型安全与灵活易用**：结合Java的泛型机制确保编译期类型检查，同时提供简洁直观的API设计，易于集成到现有项目中。
- **多数据库支持**：兼容多种主流数据库系统，满足不同应用场景的需求。
- **性能优化**：经过精心设计与调优，在保证高效执行的同时保持良好的可读性。

SuperSQL 适用于希望在Java应用程序中快速、安全地进行复杂数据库操作，并且希望通过自然语言处理技术为传统企业应用快速的实现AI赋能。



### SuperSQL 工作原理

SuperSQL 的工作原理基于 RAG 技术，通过检索增强生成技术对数据库表结构进行深度学习训练，从而实现从自然语言文本到SQL查询的智能转换。

![super-sql-ai](https://tiger-bucket.oss-cn-shanghai.aliyuncs.com/super-sql/how-to-work.png)


### SuperSQL 快速开始

#### 导入SuperSQL的maven依赖

```xml
<dependency>
    <groupId>com.aispace.supersql</groupId>
    <artifactId>super-sql-spring-boot-starter</artifactId>
    <version>1.0.0-M1</version>
</dependency>

```

### 配置SuperSQL的配置文件

配置init-train配置项，默认为false，表示不进行训练，如果为true，则自动根据数据库连接配置进行全表训练。
```yaml
super-sql:
  init-train: false
```


### 大语言模型配置

#### Azure OpenAI
```xml
 <!--spring ai azure openai 模型-->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-azure-openai</artifactId>
</dependency>
```
azure的配置文件配置如下：
```yaml
  ai:
    azure:
      openai:
        api-key: xxxxxxxxxxxxxx
        chat:
          options:
            deployment-name: gpt-4o-latest
        endpoint: https://your-resource-name.openai.azure.com/
        embedding:
          options:
            deployment-name: embedding-ada-002
```

请求调用Text To SQL
```java
//使用azure的Chat模型
private final AzureOpenAiChatModel azureChatModel;

private final SpringSqlEngine sqlEngine;

private final SpringVectorStore store;

@GetMapping("getSuperSql")
public Object getSuperSql(@RequestParam String question) {
    String sql = sqlEngine.setChatModel(azureChatModel)
            .setOptions(RagOptions.builder() //设置Rag参数
                    .topN(5) //返回的topN条数据
                    .rerank(false) //是否进行rerank重排序
                    .limitScore(0.4) //返回的分数阈值
                    .build())
            .generateSql(question);
    Object object = sqlEngine.executeSql(sql);
    return object;
}
```
#### 开启ReRanker重排序配置
```
spring:
  ai:
    #  重排序配置，可以上gitee Ai有免费体验 或者使用Xinference本地部署
    reranker:
      enabled: true
      model: Qwen3-Reranker-8B
      baseUrl: https://ai.gitee.com/v1/rerank #http://localhost:9997/v1/rerank
      api-key: xxxxxxxxxx

```

#### Ollama
添加ollam的spring ai依赖
```xml
<!--spring ai ollama-->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-ollama</artifactId>
</dependency>
```
ollama的配置文件配置如下：

#### deepseek

```yaml
spring:
  ai:
    ollama:
      base-url: http://localhost:11434
      chat:
        options:
          model: deepseek-r1:32b
          temperature: 0.7
      embedding:
        options:
          model: mxbai-embed-large
      init:
        pull-model-strategy: never
        embedding:
          additional-models:
            - mxbai-embed-large

```
embedding模型配置

```yaml
spring:
  ai:
    ollama:
      embedding:
        options:
          model: mxbai-embed-large
      init:
        pull-model-strategy: never
        embedding:
          additional-models:
            - mxbai-embed-large
```
参考修改Embedding模型[Ollama Embedding Models](https://ollama.com/search?c=embedding)

请求调用Text To SQL
```java
//使用azure的Chat模型
private final OllamaChatModel chatModel;

private final SpringSqlEngine sqlEngine;

private final SpringVectorStore store;

@GetMapping("getSuperSql")
public Object getSuperSql(@RequestParam String question) {
    String sql = sqlEngine.setChatModel(chatModel).generateSql(question);
    Object object = sqlEngine.executeSql(sql);
    return object;
}
```

### 向量数据库配置

#### Chroma
```xml
<!--spring ai chroma 的向量数据库-->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-vector-store-chroma</artifactId>
</dependency>
```
启动本地chroma
```shell
docker run -it --rm --name chroma -p 8000:8000 ghcr.io/chroma-core/chroma:1.0.0
```

#### 其他支持的向量数据库

参考[Spring AI Vector Databases](https://docs.spring.io/spring-ai/reference/1.0/api/vectordbs.html)


### 请求结果返回示例
![请求示例](https://tiger-bucket.oss-cn-shanghai.aliyuncs.com/super-sql/post-example.jpg)

### 训练指定内容

#### 强化训练数据库的DDL语句
```java
 @GetMapping("trainDdl")
    public String trainDDl() {
        String ddl = """
                 CREATE TABLE `dtp_hospital` (
                 	`id` BIGINT NOT NULL COMMENT '主键',
                 	`province` VARCHAR ( 20 ) CHARACTER SET utf8 COLLATE utf8_unicode_ci NULL DEFAULT NULL COMMENT '省份',
                 	`city` VARCHAR ( 20 ) CHARACT