# java_nl2sql

**Repository Path**: ppcirgo/java_nl2sql

## Basic Information

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

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-06-15
- **Last Updated**: 2026-07-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# java_nl2sql

智能问数应用 MVP - 基于自然语言的数据查询系统

## 项目简介

java_nl2sql 是一个智能自然语言查询系统，能够将用户的自然语言问题转换为 SQL 查询，并从数据库中获取结果。该系统采用双漏斗架构（指标漏斗 + 维度漏斗），结合 RAG（检索增强生成）技术和 LLM（大语言模型）实现智能数据查询。

## 技术栈

- **后端框架**: Spring Boot
- **LLM 框架**: LangChain4j
- **搜索引擎**: Apache Lucene
- **向量模型**: ONNX Runtime (all-MiniLM-L6-v2)
- **前端框架**: Bootstrap 5 + WebSocket (STOMP)
- **数据库查询**: MetricFlow API

## 系统架构

### 核心模块

1. **Agent 模块** - 负责处理用户查询的完整流水线
   - `IntentClassifierTool` - 意图分类
   - `MetricReasoningTool` - 指标推理
   - `TimeRangeExtractorTool` - 时间范围提取
   - `DimensionLookupTool` - 维度查找
   - `MetricFlowTool` - 查询执行

2. **RAG 检索模块** - 基于 Lucene 的混合搜索
   - `HybridSearcher` - BM25 + 向量检索融合
   - `Bm25Retriever` - 文本检索
   - `VectorRetriever` - 向量检索
   - `RrfFusion` - RRF 排名融合

3. **外部集成**
   - `MetricFlowClient` - 数据查询 API 客户端
   - `LlmClient` - LLM API 客户端
   - `EmbeddingClient` - 向量嵌入服务

## 功能特性

- 自然语言转 SQL 查询
- 支持指标（Metrics）和维度（Dimensions）检索
- 混合搜索（BM25 + 向量检索）
- 意图识别与置信度评估
- 查询结果自动图表展示
- WebSocket 实时流式输出
- 批量测试模式（Dry-Run）
- 提示词在线管理
- 链路追踪与日志

## 快速开始

### 环境要求

- JDK 17+
- Maven 3.8+
- 网络访问 LLM API（默认配置支持多种 LLM 提供商）

### 配置说明

在 `src/main/resources/application.yml` 中配置：

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

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

rag:
  indexDir: data/lucene-index
  bm25TopK: 10
  vectorTopK: 10

metricflow:
  base-url: http://your-metricflow-api
```

### 构建运行

```bash
# 构建项目
mvn clean package -DskipTests

# 运行应用
java -jar target/*.jar
```

访问 `http://localhost:8080` 打开前端界面。

## 接口文档

### REST API

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

### WebSocket

- 端点: `/ws`
- 消息类型: STOMP over WebSocket
- 主题: `/topic/query/{sessionId}`

## 项目结构

```
src/main/java/com/intelligent/query/
├── agent/              # Agent 核心模块
│   ├── QueryAgent.java
│   ├── LlmClient.java
│   └── tools/         # Agent 工具集
├── config/            # 配置类
├── constant/         # 常量定义
├── controller/       # REST 控制器
├── external/         # 外部 API 客户端
├── log/              # 日志与追踪
├── prompt/           # 提示词管理
├── rag/              # RAG 检索模块
│   ├── index/        # 索引构建
│   ├── search/       # 搜索功能
│   └── schema/       # 数据模型
├── util/             # 工具类
└── websocket/        # WebSocket 处理
```

## 配置说明

### 提示词模板

系统使用 Jinja2 模板引擎，提示词文件位于：
- `src/main/resources/prompts/`
- `data/prompts/`

### 索引数据

- 指标配置: `data/index-config/metrics.json`
- 维度配置: `data/index-config/dimensions.json`

## 许可证

MIT License