# springcloud-ai-alibaba-ctl-v1

**Repository Path**: ctllin/springcloud-ai-alibaba-ctl-v1

## Basic Information

- **Project Name**: springcloud-ai-alibaba-ctl-v1
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-13
- **Last Updated**: 2026-09-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 门店节能智能问答助手

基于 **Spring Cloud Alibaba AI** 的门店节能管理 AI 对话平台。用户通过自然语言即可完成知识库问答（RAG）、IoT 业务数据查询、统计分析、图表生成、数据导出、设备远程控制与多步工作流执行。

## 核心特性

- **智能意图识别**：LLM 将用户输入分类为 10 类意图，自动路由到对应处理模块，支持多轮上下文澄清（最多 10 轮）
- **知识库 RAG**：文件上传 → 解析分块 → ONNX 本地 Embedding → Milvus 向量检索 → 交叉编码器 Rerank → LLM 生成回答，回答附带引用来源
- **数据查询**：通过 MongoDB Skill + Spring AI `@Tool` 将自然语言翻译为 JSON 查询/聚合管道
- **图表与导出**：根据查询结果生成 ECharts 配置、导出 CSV/XLSX 文件
- **设备控制**：空调/冷柜/调光器/断路器远程指令下发，带安全边界校验与高风险二次确认
- **工作流引擎**：LiteFlow 编排多步节能任务（查询/控制/图表/条件判断），支持版本管理与逐步确认
- **Skills 体系**：基于 Spring AI Alibaba Agent Framework 的文件技能（`mongo-query-assistant`、`chart-generation`）
- **MCP 集成**：Spring AI MCP Client，SSE 连接 MCP Server 自动发现 `@Tool`

## 技术栈

| 层级 | 技术 |
|------|------|
| 后端 | Java 17（JDK 21 编译）、Spring Boot 3.5.13、Spring AI 1.1.x、Spring AI Alibaba 1.1.2.2 |
| 数据 | MongoDB（业务数据）、Milvus（768 维向量库，IP/COSINE 度量） |
| AI 模型 | Anthropic 兼容协议（`qwen3.6-plus`）、OpenAI 兼容协议（`meta/llama-3.3-70b-instruct`）、智谱（`glm-4-flash`） |
| Embedding | 本地 ONNX `bge-base-zh-v1.5`（dev 环境用 `bge-small-zh-v1.5`） |
| 重排序 | Python Rerank 服务（bge-reranker-base，端口 8001） |
| 文档解析 | PDFBox、POI（.docx）、Tess4J OCR |
| 工作流 | LiteFlow |
| 前端 | Vue 3 + Vite + Element Plus + ECharts + Pinia |

## 项目结构

```
springcloud-ai-alibaba-ctl-v1/
├── pom.xml                            # Maven 父工程（版本管理）
├── springcloud-ai-embedding-chat/     # 后端主模块
│   └── src/main/java/com/ctl/ai/
│       ├── AiClientApplication.java   # 启动入口
│       ├── controller/                # REST 控制器（Chat/知识库/工作流/设备等 19 个）
│       ├── service/chat/              # 核心编排：ChatOrchestrator + 意图路由
│       │   └── handler/               # 10 个 IntentHandler 实现
│       ├── service/                   # rag / knowledge / embedding / chart / export / device / energy / workflow / mongo / iot / model
│       ├── tools/                     # Spring AI @Tool（MongoQuery、MongoAggregate 等）
│       ├── advisor/ client/ config/   # Advisor、LLM 客户端、配置类
│       ├── model/ repository/ dto/ vo/ constant/  # 实体、仓储、DTO、意图枚举、集合名常量
│       └── resources/                 # application.yml、application-ctl.yml、skill prompts、初始化数据
├── frontend/                          # Vue 3 前端（端口 5173，/api 代理到 8080）
├── python-server/                     # Rerank 服务（uv + FastAPI，端口 8001）
├── skills/                            # Skills 目录（mongo-assistant、chart-generation）
├── files/                             # 上传/下载/图表输出目录
└── docs/                              # 架构、需求、数据库等设计文档
```

## 快速开始

### 环境要求

- JDK 21（系统 JDK 可能为 17 JRE，需 `JAVA_HOME=/home/software/jdk-21.0.2`）
- Maven、Node.js/npm、Python 3.12 + uv
- MongoDB、Milvus 实例
- 本地 ONNX 模型：`/home/software/AI/Xenova/bge-base-zh-v1.5/`、`bge-reranker-base`

### 1. 启动 Rerank 服务

```bash
cd python-server
./run.sh start    # 端口 8001，{start|stop|restart} [main|reranker]
```

### 2. 启动后端

```bash
JAVA_HOME=/home/software/jdk-21.0.2 mvn clean package -DskipTests -Dmaven.compiler.release=
# 或开发模式
JAVA_HOME=/home/software/jdk-21.0.2 mvn spring-boot:run -pl springcloud-ai-embedding-chat -Dspring.profiles.active=ctl
```

> `-Dmaven.compiler.release=` 必填：父 POM 固定 release 21，须清空该值。`ctl` profile 使用本地 MongoDB/Milvus 与 `bge-small-zh` 模型。

### 3. 启动前端

```bash
cd frontend
npm install
npm run dev    # :5173，/api 代理到 :8080
# 生产构建（输出到后端 static 目录）
npm run build
```

> 注意：`npm run build` 会清空并覆盖 `springcloud-ai-embedding-chat/src/main/resources/static`。

## 关键配置

配置位于 `springcloud-ai-embedding-chat/src/main/resources/`：

- **`application.yml`**：远程环境（MongoDB `172.16.51.83:27018`、Milvus `172.16.126.30:19530`、bge-base-zh）
- **`application-ctl.yml`**：本地开发（MongoDB `127.0.0.1`、Milvus `127.0.0.1`、bge-small-zh），默认模型 `GML`（glm-4-flash）

| 配置项 | 说明 |
|--------|------|
| `spring.ai.anthropic.*` | Anthropic 兼容协议对话模型（`ANTHROPIC_API_KEY`） |
| `spring.ai.openai.*` / `gml` | OpenAI / 智谱对话模型（`NVIDIA_API_KEY`、`GML_API_KEY`） |
| `spring.ai.vectorstore.milvus` | Milvus 连接与向量维度 |
| `spring.ai.embedding.transformer` | 本地 ONNX Embedding 模型路径 |
| `milvus.collections` | 知识库四类集合名（chunk/question/faq-question/faq-answer） |
| `rag.*` | 分块大小、重叠比例、Top-K、相似度阈值 |
| `rerank.server-url` | Python Rerank 服务地址（默认 `http://localhost:8001`） |
| `app.skills.path` | Skills 目录、图表输出目录 |
| `system.default.model` | 默认模型：`ANTHROPIC` / `OPENAI` / `GML` |

## 对话流程

```
POST /api/chat → ChatOrchestrator.process2(ChatRequest)
  → 意图缓存命中检查
  → IntentRouterService.classify2()（LLM 多轮意图分类，最多 10 轮澄清）
  → IntentHandlerRegistry.resolve(intentType)   // 自动装配 10 个 Handler
  → IntentHandler.handle()                       // 知识库/数据/图表/导出/控制/工作流…
  → ChatResponse（responseType 驱动前端渲染）
```

### 意图类型与处理模块

| 意图 | 处理方式 |
|------|----------|
| `INTENT_KNOWLEDGE_QA` | Milvus 三路检索 → Rerank → RAG 生成（附来源） |
| `INTENT_DATA_LIST` / `INTENT_DATA_AGG` | MongoDB find / aggregate（Mongo Skill + @Tool） |
| `INTENT_DATA_ANALYSIS` | 数据洞察分析 |
| `INTENT_FAULT_REPORT` | 设备故障反馈 |
| `INTENT_CHART_VISUALIZATION` | 生成 ECharts 配置 |
| `INTENT_REPORT_EXPORT` | 导出 CSV/XLSX |
| `INTENT_TASK_EXECUTION` | IoT 设备指令下发（含安全校验/二次确认） |
| `INTENT_CHITCHAT` | 兜底闲聊 |
| `CLARIFICATION_NEEDED` | 多轮澄清追问 |

响应通过 `responseType`（`TEXT`/`CHART`/`TABLE`/`COMMAND_CONFIRM`/`WORKFLOW_STEP`/`PRESET_QUESTIONS`）驱动前端渲染。

## 主要 API（前缀 `/api`）

| 模块 | 接口 |
|------|------|
| 对话 | `POST /api/chat`、`GET /api/chat/stream`（SSE）、`POST /api/chat/rag` |
| 会话 | `GET/POST /api/sessions` 等 |
| 知识库 | `GET/POST /api/documents`、`POST /api/documents/upload`、分块/问题/FAQ/Embedding CRUD |
| 图表 | `POST /api/charts/generate` |
| 导出 | `POST /api/export` |
| 设备 | `POST /api/devices/{id}/commands`（下发）、查询执行状态 |
| 工作流 | CRUD、版本历史/回滚、执行与执行记录 |
| 其他 | 意图记录、DB 设计、文本转查询、脱敏规则、停用词、用户与权限、LLM 生成 |

详情见 `docs/项目技术架构文档.md`。

## 文档索引

- `docs/项目技术架构文档.md` — 系统架构与模块设计
- `docs/需求文档.md` — 需求说明
- `docs/多轮对话系统设计文档.md` — 意图识别与多轮对话
- `docs/vector_db.md` / `docs/db_design.md` / `docs/mongo_assistant.md` — 向量库与 MongoDB 设计
- `skills/` — 各 Skill 使用说明
- `python-server/readme.md` — Rerank 服务说明