# spring-ai

**Repository Path**: xcOschina/spring-ai

## Basic Information

- **Project Name**: spring-ai
- **Description**: 这是一个基于Spring Boot和Spring AI的现代化检索增强生成（RAG）应用程序，集成了多模态AI功能、个人身份信息（PII）检测、语义缓存、虚拟线程和成本监控等先进功能。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-27
- **Last Updated**: 2025-12-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

 # Spring AI RAG Demo

这是一个基于Spring Boot和Spring AI的现代化检索增强生成（RAG）应用程序，集成了多模态AI功能、个人身份信息（PII）检测、语义缓存、虚拟线程和成本监控等先进功能。

## 项目概述

本项目展示了如何构建一个企业级AI应用，包含以下核心功能：

- **检索增强生成（RAG）**：结合向量存储实现智能问答系统
- **多模态AI支持**：处理文本和图像的组合输入
- **PII检测与保护**：自动识别和脱敏敏感个人信息
- **语义缓存**：使用Redis实现响应缓存以降低成本
- **异步处理**：使用虚拟线程提高性能
- **成本监控**：跟踪AI模型调用的成本
- **流式响应**：支持服务器发送事件（SSE）和响应式流

## 技术栈

- **Spring Boot 3.5.0**：基础框架
- **Spring AI 1.1.0**：AI集成框架
- **OpenAI GPT-4o**：主要语言模型
- **OpenAI Embeddings**：向量嵌入模型
- **PGVector**：向量存储
- **Redis**：语义缓存
- **LangChain4j**：额外的AI功能
- **Resilience4j**：容错处理
- **WebSocket/SSE**：实时通信
- **Java 25**：运行时环境

## 核心功能

### 1. RAG服务

- 向量相似性搜索
- 上下文增强回答生成
- 语义缓存机制
- 异步处理
- 流式响应支持

### 2. 多模态AI

- 图像分析与描述
- 文本到图像生成
- 多模态内容处理
- 基础64图像处理

### 3. PII检测与保护

自动检测和脱敏以下类型的敏感信息：
- 电子邮件地址
- 电话号码
- 社会安全号码（SSN）
- 信用卡号
- IP地址
- 地址信息

### 4. 性能优化

- 虚拟线程处理
- 响应缓存
- 异步API调用
- 流式数据传输

### 5. 成本监控

- 令牌使用量跟踪
- 成本估算
- 使用指标统计

## 系统架构

```
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   前端客户端     │───▶│   Spring Boot    │───▶│   AI服务提供者   │
│  (Web/移动应用)  │    │     API层        │    │ (OpenAI等)     │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                              │
                   ┌──────────────────┐
                   │   业务逻辑层      │
                   │  (RAG, 多模态)   │
                   └──────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        │                     │                     │
┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│   向量存储       │  │    Redis缓存    │  │   安全组件       │
│   (PGVector)    │  │   (语义缓存)    │  │  (PII检测)      │
└─────────────────┘  └─────────────────┘  └─────────────────┘
```

## API端点

### RAG服务

- `POST /api/rag/query` - 同步查询RAG系统
- `GET /api/rag/stream-sse` - SSE流式响应
- `GET /api/rag/stream-flux` - 响应式流式响应
- `GET /api/rag/cost-metrics` - 获取成本指标

### 多模态服务

- `POST /api/multimodal/describe-image` - 图像描述
- `POST /api/multimodal/process-base64-image` - 处理Base64图像
- `POST /api/multimodal/upload-image` - 上传图像并处理
- `POST /api/multimodal/generate-image` - 图像生成
- `POST /api/multimodal/multimodal-query` - 多模态查询

## 配置要求

### 环境变量

```bash
OPENAI_API_KEY=your-openai-api-key
OPENAI_BASE_URL=https://api.openai.com/v1  # 可选
```

### 依赖服务

1. **Redis** - 用于语义缓存
   - 主机: localhost
   - 端口: 6379

2. **PGVector** - 用于向量存储
   - 需要配置PostgreSQL与PGVector扩展

3. **OpenAI API** - 用于AI服务
   - 需要有效的API密钥

## 安装与运行

### 前提条件

- Java 25 或更高版本
- Maven 3.6+
- Redis 服务器
- PostgreSQL with PGVector 扩展
- 有效的OpenAI API密钥

### 步骤

1. 克隆项目
```bash
git clone <repository-url>
cd spring-ai-rag-demo
```

2. 配置环境变量
```bash
export OPENAI_API_KEY=your-openai-api-key
```

3. 构建项目
```bash
mvn clean install
```

4. 运行应用
```bash
mvn spring-boot:run
```

5. 应用将在 `http://localhost:8080` 启动

## 安全特性

- **PII检测**：自动识别和脱敏敏感信息
- **输入验证**：所有用户输入都经过验证
- **访问控制**：集成Spring Security
- **速率限制**：防止API滥用

## 性能特性

- **虚拟线程**：Java 19+的虚拟线程支持
- **异步处理**：非阻塞API调用
- **语义缓存**：减少重复AI调用
- **流式传输**：实时响应传输

## 项目结构

```
src/
├── main/
│   ├── java/com/example/demo/
│   │   ├── config/           # 配置类
│   │   ├── controller/       # REST控制器
│   │   ├── service/          # 业务逻辑
│   │   ├── security/         # 安全组件
│   │   └── model/            # 数据模型
│   └── resources/
│       └── application.yaml  # 配置文件
└── test/
    └── java/                 # 测试代码
```

## 配置说明

### 应用配置

- `app.rag.vector-store.type` - 向量存储类型 (pgvector, milvus, mongodb, elasticsearch)
- `app.rag.cache.ttl-seconds` - 缓存TTL（秒）
- `app.security.pii-detection.enabled` - PII检测开关
- `app.ai.virtual-threads.enabled` - 虚拟线程开关

### AI模型配置

- `spring.ai.openai.chat.options.model` - 聊天模型 (默认: gpt-4o)
- `spring.ai.openai.embeddings.options.model` - 嵌入模型 (默认: text-embedding-3-small)

## 扩展指南

### 添加新的AI服务

1. 创建新的服务类继承基础服务
2. 配置相应的AI模型
3. 添加对应的控制器端点
4. 在配置文件中添加相应配置

### 集成其他向量数据库

项目设计支持多种向量数据库，可通过配置切换：
- PGVector
- Milvus
- MongoDB
- Elasticsearch

## 故障排除

### 常见问题

1. **API密钥错误**
   - 确保设置了正确的 `OPENAI_API_KEY`
   - 检查API密钥权限

2. **Redis连接失败**
   - 确保Redis服务正在运行
   - 检查配置文件中的Redis连接参数

3. **向量存储连接失败**
   - 确保向量数据库服务正在运行
   - 检查数据库连接参数

## 许可证

[在此处添加许可证信息]

## 联系方式

如有问题，请联系项目维护者。