# semantic_layer

**Repository Path**: ppcirgo/semantic_layer

## Basic Information

- **Project Name**: semantic_layer
- **Description**: 关于语义治理的一些探索。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-20
- **Last Updated**: 2026-05-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



# Semantic Layer - 智能语义层系统

## 项目简介

Semantic Layer 是一个面向告警分析的智能语义层系统，通过自然语言处理技术，将用户的文本查询转换为结构化的数据查询。该系统整合了 RAG（检索增强生成）技术、度量流（MetricFlow）语义层服务和 LLM（大语言模型），为用户提供直观的数据分析体验。

## 系统架构

系统由三个核心微服务组成：

| 服务 | 描述 | 端口 |
|------|------|------|
| chatservice | 对话服务，处理自然语言查询 | 8080 |
| mfservice | MetricFlow 语义层服务 | 8081 |
| ragservice | 向量检索服务 | 8082 |

### 技术栈

- **后端框架**: Spring Boot 3.x + Java 17
- **数据存储**: DuckDB
- **数据建模**: dbt (data build tool)
- **前端框架**: Vue 3 + Vite
- **LLM 集成**: OpenAI Compatible API

## 功能特性

### 1. 自然语言转 SQL (NL2SQL)
- 支持中文自然语言查询
- 自动识别指标、维度、过滤条件
- 时间语义解析（昨天、上周、本月等）

### 2. 语义搜索
- 基于向量相似度的语义匹配
- 支持指标、维度、过滤器检索
- 同义词扩展

### 3. 多轮对话
- 会话上下文管理
- 多轮澄清交互
- 查询历史记忆

### 4. 语义层查询
- MQL (MetricFlow Query Language) 查询
- 多维度分组聚合
- 跨表关联查询

## 快速开始

### 环境要求

- Java 17+
- Python 3.8+ (用于 dbt)
- Maven 3.8+

### 构建和运行

```bash
# 构建所有服务
mvn clean package

# 启动各服务
cd chatservice && mvn spring-boot:run
cd mfservice && mvn spring-boot:run
cd ragservice && mvn spring-boot:run
```

### 配置说明

各服务的配置文件位于 `src/main/resources/application.yml`：

- **chatservice**: LLM 端点、RAG 服务地址、MF 服务地址
- **mfservice**: dbt 项目路径、数据库配置
- **ragservice**: Embedding API 配置、存储路径

## API 接口

### Chat Service

| 接口 | 方法 | 描述 |
|------|------|------|
| `/api/chat` | POST | 处理对话请求 |
| `/api/session` | POST | 创建新会话 |

### MetricFlow Service

| 接口 | 方法 | 描述 |
|------|------|------|
| `/lz_nl2sql/api/v1/metrics` | GET | 获取指标列表 |
| `/lz_nl2sql/api/v1/metrics/{name}` | GET | 获取指标详情 |
| `/lz_nl2sql/api/v1/dimensions` | GET | 获取维度列表 |
| `/lz_nl2sql/api/v1/dimensions/{name}` | GET | 获取维度详情 |
| `/lz_nl2sql/api/v1/query` | POST | 执行查询 |

### RAG Service

| 接口 | 方法 | 描述 |
|------|------|------|
| `/lz_nl2sql/repo/{repoName}/add` | POST | 添加向量记录 |
| `/lz_nl2sql/repo/{repoName}/search` | POST | 语义搜索 |
| `/lz_nl2sql/repos` | GET | 列出所有知识库 |

## 使用示例

### 查询告警数量

```
用户: 最近一周有多少紧急告警？
```

系统会自动：
1. 解析时间范围为「最近一周」
2. 识别指标为「告警数量」
3. 识别过滤条件为「紧急级别」
4. 生成 MQL 查询并执行
5. 返回分析结果

### 查询设备告警分布

```
用户: 按设备类型统计告警数量
```

系统会按设备类型维度分组，返回告警分布数据。

## 数据模型

### 告警表 (AlarmRecord)

- `alarm_id`: 告警 ID
- `alarm_name`: 告警名称
- `level`: 告警级别
- `device_id`: 关联设备 ID
- `event_time`: 事件时间

### 资源设备表 (ResourceDevice)

- `device_id`: 设备 ID
- `device_name`: 设备名称
- `device_type`: 设备类型
- `mac_address`: MAC 地址
- `location`: 位置

## 目录结构

```
semantic_layer/
├── chatservice/       # 对话服务
│   ├── src/main/java/
│   └── data/         # 数据和 dbt 项目
├── mfservice/        # MetricFlow 服务
│   ├── src/main/java/
│   └── data/         # 数据和 dbt 项目
└── ragservice/       # 向量检索服务
    └── src/main/java/
```

## 许可证

MIT License

## 相关文档

- [MetricFlow API 文档](./mfservice/API_README.md)
- [RAG Service API 文档](./ragservice/API_README.md)
- [RAG Service 设计文档](./ragservice/SDD.md)