# java_nl2sql

**Repository Path**: ppcirgo/java_nl2sql

## Basic Information

- **Project Name**: java_nl2sql
- **Description**: 基于指标语义层构建的NL2SQL系统。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: liuz_260615
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-15
- **Last Updated**: 2026-06-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Intelligent Query - 智能问数应用

基于大语言模型的自然语言转SQL查询系统

## 项目简介

Intelligent Query 是一个智能问数应用MVP（最小可行产品），旨在通过自然语言处理技术，将用户的自然语言问题转换为SQL查询，从数据仓库中获取所需的数据指标。该系统采用双漏斗架构（指标漏斗 + 维度漏斗），结合RAG（检索增强生成）技术和Agent框架，实现智能化的指标理解、维度识别和时间范围提取。

## 核心功能

- **自然语言转SQL**：将用户的自然语言问题转换为精确的SQL查询
- **意图识别**：自动判断问题是数据查询还是元查询
- **指标推理**：从问题中识别和推理出需要的指标
- **时间提取**：智能解析问题中的时间范围
- **维度查找**：识别问题中涉及的维度并构建过滤条件
- **RAG检索**：基于Lucene的混合搜索（BM25 + 向量检索）
- **多轮澄清**：当问题不明确时，通过交互式界面请求用户确认
- **实时流式输出**：通过WebSocket实现实时推理过程推送
- **批量测试**：支持Dry-Run模式批量测试问题集

## 技术栈

- **后端框架**：Spring Boot
- **LLM框架**：LangChain4j
- **搜索引擎**：Apache Lucene
- **向量模型**：ONNX Embedding (all-MiniLM-L6-v2)
- **前端框架**：Bootstrap 5 + 原生JavaScript
- **消息通信**：WebSocket (STOMP)
- **模板引擎**：Jinjava

## 快速开始

### 环境要求

- JDK 17+
- Maven 3.8+

### 配置说明

在 `src/main/resources/application.yml` 中配置以下关键参数：

```yaml
llm:
  base-url: http://your-llm-server:port
  api-key: your-api-key
  model-name: your-model

embedding:
  provider: local  # 或 openai
  local-model: data/models/all-MiniLM-L6-v2.onnx

rag:
  index-dir: data/lucene-index
  bm25-top-k: 10
  vector-top-k: 10

metricflow:
  base-url: http://your-metricflow-server:port
```

### 启动应用

```bash
mvn spring-boot:run
```

访问 http://localhost:8080 进入Web界面。

## 系统架构

### 双漏斗架构

1. **指标漏斗**：问题 → 意图分类 → 指标推理 → 指标确认
2. **维度漏斗**：维度检索 → 维度验证 → 条件构建

### 处理流程

```
用户问题 → 意图分类 → 指标推理 → 时间提取 → 维度查找 → SQL生成 → 结果查询
```

## API接口

### REST API

| 接口 | 方法 | 说明 |
|------|------|------|
| /api/health | GET | 健康检查 |
| /api/metrics | GET | 获取指标列表 |
| /api/query | POST | 执行查询 |
| /api/dry-run | POST | 触发批量测试 |
| /api/initrag | POST | 初始化RAG索引 |
| /api/rag/search | POST | RAG搜索 |

### WebSocket

- 端点：`/ws`
- 订阅主题：`/topic/query/{sessionId}`
- 发送目的地：`/app/query`

## 目录结构

```
src/main/java/com/intelligent/query/
├── IntelligentQueryApplication.java  # 应用入口
├── agent/                             # Agent模块
│   ├── QueryAgent.java               # 主查询Agent
│   ├── LlmClient.java               # LLM客户端
│   ├── state/QueryState.java        # 状态对象
│   └── tools/                       # 工具类
│       ├── IntentClassifierTool.java
│       ├── MetricReasoningTool.java
│       ├── TimeRangeExtractorTool.java
│       ├── DimensionLookupTool.java
│       └── MetricFlowTool.java
├── rag/                              # RAG模块
│   ├── index/                       # 索引构建
│   ├── search/                    # 混合搜索
│   └── schema/                   # 数据模型
├── config/                          # 配置类
├── controller/                     # 控制器
├── external/                      # 外部API客户端
├── prompt/                       # 提示词管理
├── util/                        # 工具类
└── websocket/                   # WebSocket处理
```

## 开发说明

### 添加新的工具

1. 在 `agent/tools/` 目录下创建新的Tool类
2. 实现工具逻辑并在 `QueryAgent` 中注入
3. 在处理流程中调用工具

### 修改提示词

可通过Web界面 `/api/prompts` 接口或直接修改 `src/main/resources/prompts/` 目录下的Jinja模板文件。

## 许可证

本项目仅供内部使用。