# hawkeye-ai

**Repository Path**: luguangdong/hawkeye-ai

## Basic Information

- **Project Name**: hawkeye-ai
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 6
- **Forks**: 5
- **Created**: 2025-04-30
- **Last Updated**: 2026-01-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



# Hawkeye AI

Hawkeye AI 是一个基于 Spring Boot 的智能对话与自然语言转 SQL (NL2SQL) 系统。该项目集成了检索增强生成 (RAG) 技术，支持多种大语言模型 (LLM)，提供知识库问答、对话管理以及将自然语言转换为 SQL 查询等功能。

## 功能特性

### 核心功能
- **智能对话系统**：支持多轮对话、对话历史管理、对话状态持久化
- **检索增强生成 (RAG)**：基于向量数据库的知识检索与问答
- **自然语言转 SQL (NL2SQL)**：将自然语言转换为数据库查询语句
- **多模型支持**：兼容 OpenAI、智谱 AI (ZhiPu AI) 等主流大语言模型

### API 接口
| 接口 | 功能描述 |
|------|----------|
| `/chat/conversation` | 普通对话接口 |
| `/chat/conversationV1` | 支持对话类型的对话接口 |
| `/chat/conversationV2` | 流式对话接口 |
| `/chat/train` | 训练数据写入接口 |
| `/chat/generateSql` | SQL 生成接口 |
| `/conversation/create` | 创建新对话 |
| `/conversation/edit` | 编辑对话标题 |
| `/conversation/list` | 获取对话列表 |
| `/conversation/get` | 获取对话详情 |
| `/conversation/del` | 删除对话 |
| `/rag/write` | 写入文档到知识库 |
| `/rag/search` | 知识检索 |

## 技术架构

### 核心模块
```
hawkeye-ai/
├── advisor/           # 对话记忆管理
├── agent/             # AI Agent 抽象
├── api/               # REST API 控制器
├── common/            # 公共工具类
├── config/            # 配置类
├── domain/            # 领域模型
├── model/             # ChatClient 工厂
├── nl2sql/            # NL2SQL 引擎
├── prompt/            # 提示词模板
├── rag/               # RAG 引擎
├── service/           # 业务服务层
└── vector/            # 向量存储引擎
```

### 技术栈
- **框架**：Spring Boot 3.x
- **AI 框架**：Spring AI
- **向量数据库**：PgVector (PostgreSQL)
- **LLM 提供商**：OpenAI、智谱 AI
- **数据库**：PostgreSQL (含向量扩展)

## 快速开始

### 环境要求
- JDK 17+
- PostgreSQL 15+ (需安装 pgvector 扩展)
- Maven 3.8+

### 配置说明

在 `application.yml` 中配置以下关键参数：

```yaml
spring:
  ai:
    openai:
      api-key: your-openai-api-key
      base-url: https://api.openai.com/v1
    zhipuai:
      api-key: your-zhipu-api-key
  datasource:
    pgvector:
      url: jdbc:postgresql://localhost:5432/hawkeye
      username: postgres
      password: your-password
```

### 构建与运行

```bash
# 编译项目
mvn clean package -DskipTests

# 启动服务
java -jar target/hawkeye-ai.jar
```

## 使用示例

### 创建对话
```bash
curl "http://localhost:8080/conversation/create?conversationType=CHAT"
```

### 发送对话消息
```bash
curl "http://localhost:8080/chat/conversationV2?conversationId=xxx&chatType=CHAT&message=你好"
```

### 写入知识库
```bash
curl -X POST "http://localhost:8080/rag/write" \
  -F "file=@document.pdf"
```

### 生成 SQL
```bash
curl "http://localhost:8080/chat/generateSql?conversationId=xxx&content=查询用户数量"
```

## 模块说明

### 对话管理 (Conversation)
提供对话的创建、编辑、列表、查询和删除功能，支持多种对话类型。

### RAG 服务 (RagService)
- **文档写入**：支持多种文档格式，通过 Apache Tika 解析
- **语义检索**：基于向量相似度搜索的知识检索
- **知识库管理**：支持按对话 ID 分区存储

### NL2SQL 服务 (Nl2SqlService)
- **SQL 生成**：基于提示词工程将自然语言转换为 SQL
- **SQL 执行**：支持动态数据源连接与查询执行
- **结果总结**：对 SQL 查询结果进行智能总结

### 向量存储
系统使用三种向量存储：
- **docVectorStore**：文档知识库存储
- **chatMemoryVectorStore**：对话历史存储
- **nl2sqlVectorStore**：NL2SQL 训练数据存储

## 项目结构

```
src/main/java/com/lucifer/hawkeye/ai/
├── HawkeyeAiServer.java          # 应用入口
├── advisor/                       # 对话顾问
├── agent/                         # Agent 抽象
├── api/                           # REST API
├── common/                        # 公共组件
├── config/                        # 配置类
├── domain/                        # 领域模型
├── model/                         # 模型工厂
├── nl2sql/                        # NL2SQL 引擎
├── prompt/                        # 提示词模板
├── rag/                           # RAG 引擎
├── service/                       # 业务服务
└── vector/                        # 向量存储
```

## 依赖管理

项目使用 Maven 进行依赖管理，主要依赖包括：
- Spring Boot Starters
- Spring AI
- PgVector JDBC
- Apache Tika (文档解析)

父项目版本管理在 `pom.xml` 中统一配置。

## 许可证

本项目遵循 [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0) 协议。