NL2SQL Demo 项目

这是一个NL2SQL（自然语言转SQL）功能模块，包含Python和Java两部分。

项目架构

NL2SQL/
├── nl2sql-python/    # Python NL2SQL服务
└── nl2sql-java/      # Java后端服务

功能特性

Python模块 (nl2sql-python)

• 自然语言转SQL核心算法
• 支持多表多字段智能召回和筛选
• 支持流式输出思考过程
• 支持多种LLM模型 (OpenAI, Claude等)
• 支持MySQL等SQL方言

Java模块 (nl2sql-java)

• RESTful API接口
• 数据库连接和查询执行
• SQL解析和结果处理
• 同步和流式响应支持
• Spring Boot框架

快速开始

1. 环境要求

• Python >= 3.11
• Java >= 17
• Maven >= 3.6
• 数据库连接池(可选)

2. 安装Python依赖

cd nl2sql-python
pip install -e .

3. 配置环境变量

# 在 nl2sql-python 目录下
cp .env_template .env
# 编辑 .env 文件，配置LLM API密钥

4. 启动Python服务

cd nl2sql-python
python -m uvicorn nl2sql_tool.tool.nl2sql:app --host 0.0.0.0 --port 1601

或者使用提供的启动脚本：

cd nl2sql-python
./start.sh

5. 配置Java服务

编辑 nl2sql-java/src/main/resources/application.yml：

nl2sql:
  agent-url: http://localhost:1601  # Python服务地址
  db-config:
    type: mysql
    host: localhost
    port: 3306
    schema: your_database
    username: your_username
    password: your_password

6. 启动Java服务

cd nl2sql-java
mvn spring-boot:run

或者使用提供的启动脚本：

cd nl2sql-java
./start.sh

API接口

Python服务 (端口1601)

• POST /v1/tool/nl2sql - NL2SQL转换接口

Java服务 (端口8080)

• POST /api/nl2sql/query - 同步查询
• POST /api/nl2sql/chat - 流式查询
• GET /api/nl2sql/health - 健康检查

使用示例

1. 直接调用Python服务

from nl2sql_tool.model.protocal import NL2SQLRequest
from nl2sql_tool.tool.nl2sql import NL2SQLAgent

agent = NL2SQLAgent()
request = NL2SQLRequest(
    request_id="test-123",
    query="查询不同国家的销售总额",
    current_date_info="当前时间信息：2025-09-12,星期五",
    table_id_list=["sales"],
    column_info=[...],  # 表结构信息
    dialect="mysql"
)
result = await agent.run(request)

2. 调用Java服务

curl -X POST http://localhost:8080/api/nl2sql/query \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "test-123",
    "query": "查询不同国家的销售总额",
    "modelCodeList": ["sales"],
    "schemaInfo": [...],
    "currentDateInfo": "当前时间信息：2025-09-12,星期五",
    "dbType": "mysql"
  }'

项目结构

Python模块

nl2sql-python/
├── nl2sql_tool/
│   ├── tool/
│   │   ├── nl2sql.py              # 核心NL2SQL逻辑
│   │   └── table_rag/
│   │       ├── table_column_filter.py  # 字段筛选
│   │       └── utils.py           # 工具函数
│   ├── model/
│   │   └── protocal.py            # 数据模型
│   ├── util/
│   │   ├── llm_util.py            # LLM工具
│   │   ├── log_util.py            # 日志工具
│   │   └── prompt_util.py         # 提示词工具
│   └── prompt/
│       ├── nl2sql.yaml            # NL2SQL提示词
│       └── table_rag.yaml         # 表召回提示词
├── .env_template                  # 环境变量模板
├── pyproject.toml                 # 项目配置
└── README.md                      # Python模块说明

Java模块

nl2sql-java/
├── src/main/java/com/nl2sql/
│   ├── Application.java           # 启动类
│   ├── controller/
│   │   └── NL2SQLController.java  # API控制器
│   ├── service/
│   │   └── NL2SQLService.java     # 核心服务
│   ├── config/
│   │   ├── NL2SQLConfig.java      # 主配置
│   │   └── DbConfig.java          # 数据库配置
│   ├── data/
│   │   ├── dto/                   # 数据传输对象
│   │   ├── model/                 # 数据模型
│   │   ├── sql/                   # SQL解析工具
│   │   └── provider/jdbc/         # JDBC数据访问
│   └── util/
│       └── JdbcUtils.java         # JDBC工具
├── src/main/resources/
│   └── application.yml            # 配置文件
├── pom.xml                        # Maven配置
└── README.md                      # Java模块说明

开发说明

Python开发

• 使用 asyncio 进行异步编程
• 支持多种LLM提供商（通过litellm）
• 使用 pydantic 进行数据验证

Java开发

• 使用Spring Boot框架
• 使用Apache Calcite进行SQL解析
• 支持同步和异步响应

注意事项

1. 必须先启动Python服务，再启动Java服务
2. 确保LLM API密钥配置正确
3. 数据库连接信息需要根据实际情况配置
4. 表结构需要与schemaInfo中的定义匹配
5. 支持MySQL方言，其他数据库需要调整配置

许可证

MIT License