# atable-chat

**Repository Path**: haohongbin1230/atable-chat

## Basic Information

- **Project Name**: atable-chat
- **Description**: 指标问答助手、sql生成智能体
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-05
- **Last Updated**: 2025-12-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# atable-chat

一个基于 Spring Boot 与 Spring AI 的对话与指标查询示例应用，集成了会话管理、SSE 流式回复、Embedding 生成、Milvus 向量库、Redis 缓存、MySQL 持久化等能力，并提供了基于 Knife4j 的在线接口文档。

### 功能特性
- 对话会话管理：创建、更新、置顶、归档、删除、分页/列表查询（`/session/**`）
- 指标查询与对话编排：基于 Alibaba Graph 的状态图编排，SSE 流式返回（`/item-query/chat/stream`、`/item-query/chat/resume`）
- Embedding 向量生成：调用 Spring AI 模型生成向量（`/embedding`）
- 健康检查：`/health`
- 数据持久化：MySQL（MyBatis-Plus）、Milvus（向量检索）
- 缓存与会话：Redis、Caffeine、本地/多级缓存
- 文档与可观测：Knife4j/OpenAPI、日志过滤器

### 运行环境
- JDK 21
- Maven 3.9+
- MySQL 8.0+
- Redis 6.0+
- Milvus 2.3+（本项目 `pom.xml` 适配 `milvus-sdk-java` 2.6.2）

### 快速开始
1) 克隆并进入项目目录
   - Windows: 使用 `mvnw.cmd`
   - macOS/Linux: 使用 `./mvnw`

2) 初始化数据库
   - 创建数据库 `atable-chat`
   - 执行 `src/main/resources/sql/schema.sql`

3) 配置应用
   编辑 `src/main/resources/application.yml`，示例：

```yaml
server:
  port: 8080
spring:
  application:
    name: atable-chat
  datasource:
    url: jdbc:mysql://<mysql-host>:3306/atable-chat?serverTimezone=Asia/Shanghai&useUnicode=true&characterEncoding=UTF-8&useSSL=false&allowPublicKeyRetrieval=true
    username: <mysql-user>
    password: <mysql-pass>
    driver-class-name: com.mysql.cj.jdbc.Driver
  ai:
    openai:
      api-key: <your-api-key-or-EMPTY>
      base-url: <llm-base-url>
      model: <chat-model-name>
      embedding:
        enabled: false
        base-url: <embedding-base-url>
        options:
          model: bge-m3:latest
          dimensions: 1024
    vectorstore:
      milvus:
        client:
          host: <milvus-host>
          port: 19530
          username: atable
          password: atable
  data:
    redis:
      host: <redis-host>
      port: 6379
      database: 0
      # password: <redis-pass-if-needed>

mybatis-plus:
  mapper-locations: classpath*:/mapper/**/*.xml
```

4) 启动应用
- 命令行：
  - Windows: `mvnw.cmd spring-boot:run`
  - macOS/Linux: `./mvnw spring-boot:run`
- 或在 IDE 中运行 `com.ics.atable.chat.AtableChatApplication`

5) 打开接口文档
- Knife4j 文档：`http://localhost:8080/doc.html`
- OpenAPI JSON：`http://localhost:8080/v3/api-docs`

### 主要接口概览（部分）

1) 健康检查
- GET `/health`

2) Embedding
- POST `/embedding`
  - 请求体：`["文本1", "文本2"]`
  - 返回：`EmbeddingResponse` 包装在统一响应体中

示例（PowerShell）
```bash
curl -Method POST -Uri http://localhost:8080/embedding -Headers @{"Content-Type"="application/json"} -Body '["hello world"]'
```

3) 会话管理（`/session/**`）
- POST `/session/create` 创建会话（请求体为 `ChatSession`）
- PUT `/session/sessions/{id}` 更新会话
- POST `/session/sessions/{id}/archive` 归档
- DELETE `/session/sessions/{id}` 逻辑删除
- POST `/session/sessions/{id}/pin?pinned=true|false` 置顶/取消置顶
- GET `/session/sessions?userId={userId}` 列表
- GET `/session/sessions/page?userId={id}&page=1&size=10` 分页
- POST `/session/message/history` 按会话分页查询历史（请求体为 `GetChatHistoryByPageDTO`）

4) 指标查询与对话编排（SSE）
- POST `/item-query/chat/stream`（`Content-Type: application/json`，`Accept: text/event-stream`）
  - 请求体 `ChatRequest` 字段示例：
    - `sessionId`：会话 ID（必填）
    - `type`：会话类型（与 `ResponseTypeEnum` 对应，必填）
    - `query`：用户输入（与 `interruptFeedback` 至少填一项）
    - `interruptFeedback`：中断反馈
- POST `/item-query/chat/resume`（SSE）
  - 请求体 `FeedbackRequest`：`sessionId`、`type`、`feedBack`、`feedBackContent`
- GET `/item-query/chat/close?sessionId=xxx` 关闭指定会话的流

示例（Windows PowerShell，SSE 需使用支持流的客户端）
```bash
curl -Method POST -Uri http://localhost:8080/item-query/chat/stream -Headers @{"Content-Type"="application/json";"Accept"="text/event-stream"} -Body '{"sessionId":"s1","type":1,"query":"查询某指标"}'
```

### 数据库与向量库
- MySQL 初始化脚本位于 `src/main/resources/sql/schema.sql`
- MyBatis-Plus XML 位于 `src/main/resources/mapper/*.xml`
- Milvus 连接配置在 `spring.ai.vectorstore.milvus.client.*`

### 构建与打包
- 运行：`spring-boot:run`
- 打包 Jar：`mvnw.cmd clean package -DskipTests`（Windows）或 `./mvnw clean package -DskipTests`
- 运行 Jar：`java -jar target/atable-chat-0.0.1-SNAPSHOT.jar`

### 常见问题
- 无法连接模型服务：检查 `spring.ai.openai.base-url`、`api-key`、`model`
- SSE 无响应：确认客户端支持 `text/event-stream`，并查看服务端日志
- Milvus 连接失败：检查主机与端口、账号密码、网络连通性
- 数据库错误：确认已执行 `schema.sql`，并更新 `datasource` 配置

### 许可证
本项目未显式声明开源许可证，请在使用前与项目作者确认授权方式。