# ai

**Repository Path**: yiynx/ai

## Basic Information

- **Project Name**: ai
- **Description**: AI Chat & 知识库
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-28
- **Last Updated**: 2026-04-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI Chat & 知识库

基于 Spring Boot 4 + Spring AI 的智能对话与知识库应用，支持 RAG（检索增强生成）。

## 功能特性

### AI 对话
- **同步对话** — 基于 Ollama 的 LLM 聊天，支持普通对话和知识库增强对话
- **流式对话** — SSE 流式响应，支持打字机效果实时显示
- **思考模式** — 启用后模型会进行更深入的分析和推理
- **工具调用** — 自动识别并调用工具（时间查询、联网搜索）
- **对话历史** — 自动保存对话记录到 localStorage，支持历史会话管理

### 知识库管理
- **文档管理** — 支持文档的增删改查操作
- **语义搜索** — 基于向量相似度的智能检索
- **元数据管理** — 支持名称、描述等元数据管理

### RAG 增强
- **上下文增强** — 聊天时可检索知识库内容，将匹配结果注入 Prompt
- **智能提示** — 如知识库无相关信息，会明确告知用户

### 前端界面
- **双主题支持** — 深色/浅色主题切换，设置持久化到 localStorage
- **字体大小调节** — 支持 12px-20px 字体大小调整
- **响应式设计** — 适配桌面端和移动端
- **Markdown 渲染** — 支持代码高亮、表格、列表等格式

### 系统特性
- **优雅降级** — Cassandra 不可用时知识库功能自动禁用，聊天仍可正常使用
- **Fallback 机制** — Embedding 模型不可用时使用默认维度配置
- **双通道数据访问** — 向量操作走 Spring AI VectorStore，元数据走 CQL 直接读写

## 技术栈

| 类别 | 技术 | 版本 |
|------|------|------|
| 框架 | Spring Boot | 4.0.5 |
| AI | Spring AI | 2.0.0-M4 |
| 语言 | Java | 21 |
| LLM | Ollama (qwen3:4b) | — |
| Embedding | Ollama (bge-m3, 1024维) | — |
| 向量数据库 | Cassandra 5.0+ | — |
| 前端 | Vanilla HTML/CSS/JS | — |
| 构建工具 | Maven | — |

## 环境依赖

- **Ollama** — 默认 `localhost:11434`，提供聊天模型和 Embedding 模型
- **Cassandra 5.0+** — 默认 `localhost:9042`，向量存储（需要支持 `vector` 类型和 SAI 索引）

## 快速开始

### 1. 启动外部服务

确保 Ollama 和 Cassandra 已启动运行：

```bash
# Ollama 拉取模型
ollama pull qwen3:4b
ollama pull bge-m3:latest
```

### 2. 配置本地环境

复制配置模板并按需修改：

```bash
cp src/main/resources/application-template.yaml src/main/resources/application-local.yaml
```

也可通过环境变量覆盖配置：

| 环境变量 | 默认值 | 说明 |
|---------|--------|------|
| `OLLAMA_BASE_URL` | `http://localhost:11434` | Ollama 服务地址 |
| `OLLAMA_CHAT_MODEL` | `qwen3:4b` | 聊天模型名称 |
| `OLLAMA_CHAT_TEMPERATURE` | `0.7` | 聊天温度 |
| `OLLAMA_EMBEDDING_MODEL` | `bge-m3:latest` | Embedding 模型名称 |
| `OLLAMA_EMBEDDING_DIMENSIONS` | `1024` | Embedding 维度 |
| `CASSANDRA_CONTACT_POINTS` | `localhost` | Cassandra 地址 |
| `CASSANDRA_PORT` | `9042` | Cassandra 端口 |
| `CASSANDRA_LOCAL_DATA_CENTER` | `datacenter1` | Cassandra 本地数据中心 |
| `TAVILY_API_KEY` | `` | Tavily 搜索 API Key（可选） |
| `TAVILY_API_URL` | `https://api.tavily.com` | Tavily API 地址 |

### 3. 初始化数据库

Cassandra 表结构定义在 `src/main/resources/db/cassandra/schema.cql`

```sql
-- 创建 Keyspace
CREATE KEYSPACE IF NOT EXISTS spring_ai_vectorstore
WITH REPLICATION = {'class': 'SimpleStrategy', 'replication_factor': 1};

-- 创建向量存储表
CREATE TABLE IF NOT EXISTS ai_vector_store (
    id text PRIMARY KEY,
    content text,
    embedding vector<float, 1024>,
    name text,
    description text
);

-- 创建向量索引
CREATE CUSTOM INDEX IF NOT EXISTS ai_vector_store_embedding_idx
ON ai_vector_store (embedding)
USING 'StorageAttachedIndex'
WITH OPTIONS = {'similarity_function': 'cosine'};

-- 创建元数据索引
CREATE INDEX IF NOT EXISTS ai_vector_store_name_idx ON ai_vector_store (name);
CREATE INDEX IF NOT EXISTS ai_vector_store_description_idx ON ai_vector_store (description);
```

### 4. 构建与运行

```bash
# 构建
./mvnw package

# 运行
./mvnw spring-boot:run
```

启动后访问 `http://localhost:8080` 即可使用。

## API 接口

### 对话接口

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/chat` | 同步对话，支持 `useKnowledge` 字段启用 RAG |
| POST | `/api/chat/stream` | 流式对话（SSE），支持 `useKnowledge` 和 `deepThinking` |

**请求体示例：**

```json
{
  "message": "介绍一下 Spring AI",
  "useKnowledge": true,
  "deepThinking": false
}
```

**流式响应格式：**

```json
{"thinking": "模型思考内容..."}
{"content": "回答内容片段..."}
```

### 知识库接口

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/knowledge` | 创建知识库条目 |
| POST | `/api/knowledge/documents` | 添加文档 |
| POST | `/api/knowledge/documents/batch` | 批量添加文档 |
| GET | `/api/knowledge/documents` | 列出所有文档 |
| GET | `/api/knowledge/documents/{id}` | 获取文档详情 |
| PUT | `/api/knowledge/documents/{id}` | 更新文档 |
| DELETE | `/api/knowledge/documents/{id}` | 删除文档 |
| GET | `/api/knowledge/search?query=&topK=5` | 语义搜索 |

**文档请求体示例：**

```json
{
  "name": "Spring AI 文档",
  "description": "Spring AI 框架使用指南",
  "content": "Spring AI 是 Spring 框架的 AI 集成扩展..."
}
```

## 项目结构

```
cn.yiynx.ai
├── AiApplication              — Spring Boot 启动类
├── config/
│   ├── ToolConfig             — 工具调用配置（时间工具、搜索工具）
│   └── VectorStoreConfig      — Cassandra 向量存储配置（手动装配，含 Embedding 降级处理）
├── controller/
│   ├── ChatController         — 对话接口（同步 + SSE 流式）
│   └── KnowledgeController    — 知识库 CRUD 接口
├── dto/
│   ├── KnowledgeRequest       — 知识库请求 DTO
│   └── KnowledgeResponse      — 知识库响应 DTO
├── service/
│   ├── KnowledgeService       — 知识库服务（向量操作 + CQL 双通道访问）
│   └── SearchService          — 搜索服务（Tavily API 封装）
└── resources/
    ├── application.yaml       — 应用主配置
    ├── db/cassandra/schema.cql — Cassandra 初始化脚本
    └── static/index.html      — 前端单页应用
```

### 关键设计

1. **Cassandra 自动配置排除**：手动装配 `CassandraVectorStore`，支持 Embedding 降级和双通道数据访问
2. **Fallback EmbeddingModel**：Ollama 不可用时返回配置的默认维度，避免启动失败
3. **双通道数据访问**：
   - 向量操作走 Spring AI `VectorStore`（相似度搜索、向量存储）
   - `name`/`description` 列走 CQL 直接读写（列表查询、元数据管理）
4. **优雅降级**：`VectorStore` 和 `CqlSession` 均为可选注入，不可用时返回 503
5. **工具调用框架**：基于 Spring AI `ToolCallback` 实现自动工具选择，支持时间查询和联网搜索

## 前端功能

### 快捷键

| 快捷键 | 功能 |
|--------|------|
| `Enter` | 发送消息 |
| `Shift + Enter` | 换行 |
| `Ctrl + N` | 新建对话 |

### 界面特性

- **主题切换** — 支持深色/浅色主题，自动保存偏好
- **字体调节** — 支持 12-20px 字体大小调整
- **代码高亮** — 支持多种编程语言的语法高亮
- **消息操作** — 支持复制、重新生成回答
- **流式取消** — 支持在生成过程中取消响应

## 测试

```bash
# 运行全部测试
./mvnw test

# 运行单个测试类
./mvnw test -Dtest=ChatControllerTest

# 运行单个测试方法
./mvnw test -Dtest=ChatControllerTest#chat_ShouldReturnResponse_WhenRequestIsValid
```

> 注意：`AiApplicationTests` 上下文加载测试需要 Cassandra 和 Ollama 服务运行。

## 工具调用

系统内置以下工具，模型会根据用户问题自动选择调用：

| 工具名 | 描述 | 触发条件 |
|--------|------|----------|
| `getCurrentTime` | 获取当前日期时间 | 用户询问时间相关问题 |
| `webSearch` | Tavily 联网搜索 | 需要实时信息、新闻、数据等 |

## License

详见 [LICENSE](LICENSE) 文件。