Spring AI RAG 应用

这是一个基于Spring AI框架的检索增强生成(RAG)应用，集成了Ollama、Elasticsearch和MCP客户端功能，用于文档索引、检索和智能问答。

功能特点

• 智能RAG对话：集成检索增强生成，支持基于文档内容的智能问答
• 流式响应：支持实时流式聊天体验
• 文档处理：支持多种格式文档的上传、解析和向量化存储
• 会话管理：支持多轮对话和会话历史管理
• 工具集成：集成文档工具和通用工具，支持函数调用
• MCP支持：支持Model Context Protocol客户端功能
• 向量检索：基于Elasticsearch的语义检索和相似度搜索

系统架构

系统由以下主要模块组成：

1. RagService：RAG核心服务，集成向量检索和对话生成
2. DocumentService：文档处理服务，负责文档解析和索引
3. ChatService：基础聊天服务实现
4. ContextService：会话上下文和历史管理
5. DocumentTools：文档相关的工具函数
6. CommonTools：通用工具函数

技术栈

• Spring Boot: 3.2.5
• Spring AI: 1.0.0
• JDK: 21
• Ollama: LLM模型服务
  • 聊天模型: llama3.1
  • 嵌入模型: nomic-embed-text
• Elasticsearch: 9.0.1 (向量存储)
• Apache Tika: 2.8.0 (文档解析)
• MCP Client: Model Context Protocol客户端支持

快速开始

前置条件

• JDK 21
• Maven 3.6+
• Elasticsearch 8.0+
• Ollama服务

环境配置

1. 启动Elasticsearch

# 使用Docker启动Elasticsearch
docker run -d \
  --name elasticsearch \
  -p 9200:9200 \
  -e "discovery.type=single-node" \
  -e "xpack.security.enabled=false" \
  elasticsearch:8.0.0

2. 启动Ollama服务

# 安装并启动Ollama
ollama serve

# 拉取所需模型
ollama pull llama3.1
ollama pull nomic-embed-text

应用配置

项目使用application.yml配置文件，主要配置项：

spring:
  servlet:
    multipart:
       max-file-size: 50MB
       max-request-size: 50MB
  elasticsearch:
    uris: http://localhost:9200
  ai:
    ollama:
      embedding:
        options:
          model: nomic-embed-text
      base-url: http://localhost:11434
      chat:
        model: llama3.1
    vectorstore:
      elasticsearch:
        initialize-schema: true
        index-name: vector_docs_v4
    rag:
      question-answer-advisor:
        enabled: true
        retriever:
          top-k: 3
          similarity-threshold: 0.5

运行应用

# 克隆项目
git clone <repository-url>
cd newAi

# 编译运行
mvn clean spring-boot:run

应用将在 http://localhost:8080 启动。

API接口

文档管理 API (v2)

上传文档

POST /api/docs/v2/upload
Content-Type: multipart/form-data

curl -X POST -F "file=@document.pdf" http://localhost:8080/api/docs/v2/upload

搜索文档

GET /api/docs/v2/search?q={query}

curl "http://localhost:8080/api/docs/v2/search?q=关键词搜索"

获取文档详情

GET /api/docs/v2/detail/{documentId}

curl "http://localhost:8080/api/docs/v2/detail/doc123"

智能聊天 API (v2)

RAG聊天完成

POST /api/chat/v2/completion?q={query}&conversation_id={id}

curl -X POST "http://localhost:8080/api/chat/v2/completion?q=请解释文档中的主要概念&conversation_id=conv123"

增强RAG聊天完成（支持查询改写）

POST /api/chat/v2/enhanced-completion?q={query}&conversation_id={id}&use_query_rewrite={boolean}

curl -X POST "http://localhost:8080/api/chat/v2/enhanced-completion?q=请解释文档中的主要概念&conversation_id=conv123&use_query_rewrite=true"

流式聊天

POST /api/chat/v2/stream?q={query}&conversation_id={id}
Content-Type: text/event-stream

curl -X POST "http://localhost:8080/api/chat/v2/stream?q=你好&conversation_id=conv123"

增强流式聊天（支持查询改写）

POST /api/chat/v2/enhanced-stream?q={query}&conversation_id={id}&use_query_rewrite={boolean}
Content-Type: text/event-stream

curl -X POST "http://localhost:8080/api/chat/v2/enhanced-stream?q=你好&conversation_id=conv123&use_query_rewrite=true"

查询改写

POST /api/chat/v2/query-rewrite?q={query}&strategies={strategies}

curl -X POST "http://localhost:8080/api/chat/v2/query-rewrite?q=人工智能的发展历程&strategies=SYNONYM_REPLACEMENT,KEYWORD_EXTRACTION"

响应格式（结构化）：

{
  "original_query": "人工智能的发展历程",
  "applied_strategies": ["SYNONYM_REPLACEMENT", "KEYWORD_EXTRACTION"],
  "synonym_rewrites": ["AI技术的演进过程", "机器智能的历史发展"],
  "keyword_queries": ["人工智能 发展", "AI 历程"],
  "expanded_questions": [],
  "all_rewrites": ["AI技术的演进过程", "机器智能的历史发展", "人工智能 发展", "AI 历程"],
  "total_count": 4,
  "processing_time_ms": 1250,
  "has_errors": false
}

查询改写（简化版本）

POST /api/chat/v2/query-rewrite/simple?q={query}&strategies={strategies}

curl -X POST "http://localhost:8080/api/chat/v2/query-rewrite/simple?q=机器学习算法"

响应格式（向后兼容）：

{
  "original_query": "机器学习算法",
  "rewritten_queries": ["机器学习算法", "ML算法", "智能学习方法", "算法 机器学习"],
  "count": 4
}

简单查询扩展

POST /api/chat/v2/simple-expand?q={query}

curl -X POST "http://localhost:8080/api/chat/v2/simple-expand?q=机器学习"

获取改写策略列表

GET /api/chat/v2/rewrite-strategies

curl "http://localhost:8080/api/chat/v2/rewrite-strategies"

查询改写测试 API

测试查询改写功能

POST /api/test/query-rewrite/test?q={query}

curl -X POST "http://localhost:8080/api/test/query-rewrite/test?q=深度学习算法"

比较普通RAG和增强RAG

POST /api/test/query-rewrite/compare?q={query}&conversation_id={id}

curl -X POST "http://localhost:8080/api/test/query-rewrite/compare?q=神经网络原理&conversation_id=test123"

获取查询改写统计信息

GET /api/test/query-rewrite/stats

curl "http://localhost:8080/api/test/query-rewrite/stats"

基础聊天 API (v1)

基础聊天

GET /api/chat/v1?q={query}
POST /api/chat/v1

curl "http://localhost:8080/api/chat/v1?q=你好"

基础文档 API (v1)

索引文档

POST /api/docs/v1/index

搜索文档

GET /api/docs/v1/search?q={query}

核心功能说明

RAG检索增强生成

• 使用QuestionAnswerAdvisor自动进行文档检索
• 配置相似度阈值为0.5，返回前3个最相关文档
• 支持中文语义理解和回答

会话管理

• 支持多轮对话历史记录
• 使用MessageWindowChatMemory管理会话上下文
• 每个会话使用唯一ID标识

工具集成

• DocumentTools: 文档处理相关工具函数
• CommonTools: 通用工具函数
• 支持函数调用和工具链执行

文档处理

• 支持多种文档格式（PDF、DOC、TXT等）
• 使用Apache Tika进行文档解析
• 自动向量化并存储到Elasticsearch

项目结构

src/main/java/com/ding/
├── AiApplication.java          # 主应用类
├── config/
│   └── RagConfiguration.java  # RAG配置类
├── controller/                 # 控制器层
│   ├── EnhancedChatController.java      # 增强聊天API (v2)
│   ├── EnhancedDocumentController.java  # 增强文档API (v2)
│   ├── ChatController.java              # 基础聊天API (v1)
│   └── DocumentController.java          # 基础文档API (v1)
├── service/                    # 服务层
│   ├── RagService.java        # RAG核心服务
│   ├── ChatService.java       # 聊天服务
│   ├── DocumentService.java   # 文档服务
│   └── ContextService.java    # 上下文服务
└── tools/                     # 工具类
    ├── DocumentTools.java     # 文档工具
    └── CommonTools.java       # 通用工具

日志配置

应用配置了完整的日志系统：

• 控制台日志：INFO级别
• 文件日志：保存到logs/application.log
• Spring AI组件：WARN级别，减少冗余日志

开发说明

扩展功能

1. MCP客户端：已集成MCP客户端支持，可连接外部MCP服务
2. 工具扩展：可在tools包下添加更多工具函数
3. 向量存储：可切换到其他向量数据库（如Pinecone、Chroma等）
4. 模型切换：支持切换不同的Ollama模型

性能优化

• 文件上传限制：最大50MB
• 向量检索优化：相似度阈值和TopK可调
• 内存管理：会话窗口大小可配置

故障排除

常见问题

1. Elasticsearch连接失败

   • 检查Elasticsearch服务是否启动
   • 确认端口9200是否可访问

2. Ollama模型未找到

   • 确认已下载所需模型
   • 检查模型名称配置是否正确

3. 文档上传失败

   • 检查文件大小是否超出限制
   • 确认文件格式是否支持

许可证

MIT License

查询改写功能详解

功能特点

• 多策略改写：支持同义词替换、关键词提取、问题扩展等多种改写策略
• 智能语义理解：基于LLM的智能查询理解和改写
• 提高召回率：通过多样化的查询变体提高文档检索的召回率
• 可配置性：支持自定义改写策略和参数配置
• 异步处理：支持并行执行多种改写策略，提高性能

改写策略

1. SYNONYM_REPLACEMENT（同义词替换）

   • 生成语义相似但表达方式不同的查询变体
   • 使用不同词汇表达相同概念
   • 适当调整句式结构

2. KEYWORD_EXTRACTION（关键词提取）

   • 从原始查询中提取核心关键词
   • 生成基于关键词的简化查询
   • 去除停用词和冗余信息

3. QUESTION_EXPANSION（问题扩展）

   • 将查询扩展为更详细的问题形式
   • 包含相关背景信息和上下文
   • 提高查询的专业性和准确性

配置参数

spring:
  ai:
    rag:
      query-rewrite:
        enabled: true              # 是否启用查询改写
        max-rewrites: 5            # 最大改写数量
        strategies:                # 默认改写策略
          - SYNONYM_REPLACEMENT
          - KEYWORD_EXTRACTION
        timeout-seconds: 10        # 改写超时时间

使用场景

1. 提高检索精度：通过多样化查询提高相关文档的召回率
2. 处理口语化查询：将口语化表达转换为标准查询
3. 同义词处理：处理同一概念的不同表达方式
4. 查询优化：自动优化用户输入的查询质量

性能优化

• 并行处理：多种改写策略并行执行
• 结果去重：自动去除重复的改写结果
• 数量限制：限制改写结果数量，避免过多查询
• 缓存机制：可配置查询改写结果缓存（未来功能）