# spring-ai-faiss-tongyi

**Repository Path**: JavaBigDataStudy/spring-ai-faiss-tongyi

## Basic Information

- **Project Name**: spring-ai-faiss-tongyi
- **Description**: No description available
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-28
- **Last Updated**: 2025-12-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Spring AI + FAISS + 通义千问 DDD 智能问答系统

## 项目概述

本项目采用领域驱动设计（DDD）思想，实现了一个基于本地知识库（FAISS向量库）和通义千问大模型的智能问答系统。核心功能是加载本地文档，将其向量化存储到FAISS向量库，然后根据用户问题检索相似文档，结合大模型生成精准回答。

## 技术栈

| 技术/框架 | 版本 | 作用 |
|----------|------|------|
| Spring Boot | 3.2.5 | 基础开发框架 |
| Spring AI | 1.0.6 | 大模型/向量存储集成 |
| FAISS | 1.7.4 | 本地向量数据库 |
| 通义千问SDK | 0.10.0 | 调用大模型API |
| LangChain4j | 0.24.0 | 文档加载/文本分割 |
| Lombok | 1.18.30 | 简化POJO代码 |
| SpringDoc OpenAPI | 2.3.0 | 接口文档 |

## 项目结构（DDD分层）

```
src/main/java/com/example/ai/
├── AiApplication.java                // 应用入口
├── application/                      // 应用层：协调领域服务
│   ├── query/                        // 查询用例
│   │   ├── DocumentQueryService.java // 文档问答服务
│   │   └── dto/                      // DTO
│   │       ├── QueryRequest.java
│   │       └── QueryResponse.java
├── domain/                           // 领域层：核心业务逻辑
│   ├── model/                        // 领域模型
│   │   ├── Document.java
│   │   └── VectorizedDocument.java
│   └── service/                      // 领域服务
│       ├── DocumentVectorService.java
│       └── KnowledgeRetrievalService.java
├── infrastructure/                   // 基础设施层：外部依赖实现
│   ├── document/                     // 文档加载
│   │   └── LocalDocumentLoader.java
│   ├── llm/                          // 大模型客户端
│   │   └── TongyiQwenLlmClient.java
│   └── vectorstore/                  // 向量存储
│       └── FaissVectorStore.java
└── interface/                        // 接口层：对外API
    └── rest/                         // REST接口
        └── DocumentQueryController.java
```

## 核心功能

### 1. 知识库初始化

将本地文档（TXT/MD格式）加载并向量化存储到FAISS向量库。

### 2. 智能问答

- 用户提问
- 问题向量化
- 相似文档检索
- 结合上下文生成回答

## 配置说明

### 1. Maven依赖

项目使用Spring AI和通义千问SDK，需要在`pom.xml`中添加相应依赖。

### 2. 配置文件

在`src/main/resources/application.yml`中配置：

```yaml
spring:
  application:
    name: spring-ai-faiss-tongyi-demo
  ai:
    tongyi:
      api-key: your-tongyi-api-key  # 替换为您的通义千问API-KEY
      model: qwen-turbo
  faiss:
    index-path: ./faiss-index
    dimension: 1536
server:
  port: 8080
springdoc:
  api-docs:
    path: /api-docs
  swagger-ui:
    path: /swagger-ui.html
    operationsSorter: method
```

## 运行步骤

### 1. 准备工作

- 获取通义千问API-KEY（从阿里云百炼平台获取）
- 在项目根目录创建`docs`文件夹，放入知识库文档（如`knowledge.txt`）

### 2. 构建项目

```bash
mvn clean package -DskipTests
```

### 3. 运行应用

```bash
java -jar target/spring-ai-faiss-tongyi-0.0.1-SNAPSHOT.jar
```

### 4. 测试接口

#### 4.1 初始化知识库

```bash
POST /api/v1/query/init?filePath=./docs/knowledge.txt
```

响应：
```
知识库初始化成功！
```

#### 4.2 智能问答

```bash
POST /api/v1/query
Content-Type: application/json

{
  "question": "Spring AI的核心特性有哪些？",
  "topK": 3
}
```

响应示例：
```json
{
  "answer": "Spring AI的核心特性包括：大模型客户端、向量存储、提示词模板、函数调用等。",
  "referenceDocs": [
    "Spring AI的核心特性包括：大模型客户端、向量存储、提示词模板、函数调用等。"
  ],
  "responseTime": 856
}
```

## API文档

启动应用后，访问Swagger UI文档：

```
http://localhost:8080/swagger-ui.html
```

## 扩展优化

1. **向量存储优化**：生产环境可使用`IndexIVFFlat`或`IndexHNSW`替代`IndexFlatL2`
2. **文档持久化**：添加MySQL/Redis存储文档元数据
3. **错误处理**：增加全局异常处理器
4. **批量加载**：支持多文件批量加载
5. **提示词优化**：使用`PromptTemplate`简化提示词构建

## 注意事项

- 首次运行需要配置通义千问API-KEY
- FAISS索引文件默认存储在`./faiss-index`
- 文档大小建议控制在合理范围内，避免过长
- 向量维度必须与通义千问embedding模型一致（默认1536）

## 许可证

MIT