# chat-ollama

**Repository Path**: VictorInfo/chat-ollama

## Basic Information

- **Project Name**: chat-ollama
- **Description**: 这是一个整合langchain4j与spring ai的chat聊天的demo，并整合RAG
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 250
- **Forks**: 117
- **Created**: 2024-09-20
- **Last Updated**: 2026-05-06

## Categories & Tags

**Categories**: ai

**Tags**: SpringAI, langchain4j, ollama, AI, SpringAIAlibaba

## README



# Chat-Ollama

Chat-Ollama 是一个基于 Java 的智能对话项目，集成了 Ollama 本地大语言模型，提供聊天、文档问答（RAG）、PPT 生成、流式响应等核心功能。项目采用模块化设计，包含多个子模块以满足不同业务场景需求。

## 项目概述

Chat-Ollama 旨在为开发者提供一个灵活、可扩展的本地大模型应用框架。通过集成 Spring Boot 生态和 LangChain4j 等先进的 AI 技术栈，项目实现了完整的对话系统开发能力。项目支持流式响应、文档检索增强生成、对话历史记忆等高级特性，同时提供友好的 RESTful API 接口，方便与各类前端应用集成。

## 技术架构

### 核心技术栈

项目采用现代化的 Java 技术栈构建，所有模块均基于 Java 17+ 运行时环境。Spring Boot 提供了便捷的依赖管理和应用启动能力，Spring AI 框架则封装了大模型交互的复杂性。LangChain4j 作为Java 领域的 LangChain 实现，提供了丰富的 AI 工具链支持。Ollama 作为本地大模型运行框架，支持 llama3、mistral 等主流开源模型，确保大模型能够完全离线运行，保护数据隐私。

| 组件 | 版本要求 | 说明 |
|------|----------|------|
| Java | 17+ | 运行时环境 |
| Spring Boot | 3.x | 应用框架 |
| Spring AI | 最新版 | AI 集成框架 |
| LangChain4j | 最新版 | Java AI 工具链 |
| Ollama | 最新版 | 本地 LLM 运行时 |
| Redis | 最新版 | 聊天历史存储 |
| Maven | 3.6+ | 项目构建工具 |

### 模块说明

项目采用 Maven 多模块结构，包含以下核心子模块：

**langchain4j 模块** 提供了基于 LangChain4j 的大模型集成能力。该模块封装了聊天记忆、嵌入向量存储、文档检索等核心功能。通过 `ChatMemory` 机制支持多轮对话上下文，通过 `EmbeddingStore` 实现语义搜索能力。

**spring-mcp-server 模块** 实现了 MCP（Model Context Protocol）工具集成。该模块提供可扩展的工具回调机制，当前已实现获取当前时间等常用工具，开发者可以轻松添加自定义工具。

**springai 模块** 是项目的主体模块，提供 Spring AI 相关的所有服务。该模块实现了聊天服务（ChatService）、文档问答服务（RagService）、PPT 生成服务（PptService）等核心功能。

**springaialibaba 模块** 提供了 ChatFlow 编排能力，支持复杂对话流程的定制化开发。

**ui 模块** 包含简单的前端页面，基于 Vue.js 和 Tailwind CSS 构建，提供暗黑/亮色模式切换功能。

## 功能特性

### 聊天接口

项目提供多种聊天接口以满足不同场景需求。普通聊天接口适合简单的单轮问答场景，通过 `/springaiChat/message` 端点即可获得大模型的回复。流式聊天接口通过 `/springaiChat/message3` 提供 Server-Sent Events（SSE）流式响应能力，大模型生成的内容会实时推送给客户端。带有历史记录的聊天接口通过 `/springaiChat/message2` 支持多轮对话，传入 sessionId 即可维护独立的对话上下文。

所有聊天接口均支持自定义系统提示词（System Prompt），开发者可以通过配置文件或代码指定不同的系统角色和行为指令。

### RAG 文档问答

项目实现了完整的检索增强生成（Retrieval-Augmented Generation）能力。用户可以通过 `/springaiRag/upload` 端点上传文档，系统会自动将文档进行分块和向量化处理，存储到向量数据库中。问答时，系统会先检索与问题最相关的文档片段，然后将这些片段作为上下文提供给大模型，生成更加准确和详细的回答。

RAG 服务支持多种文本分割策略，包括基于语义的分割（SemanticQuestionSplitter）、基于向量的分割（VectorBasedSplitter）以及模型感知的分割（ModelAwareTextSplitter）。开发者可以根据实际文档特点选择合适的分割策略。

### PPT 生成

项目支持通过自然语言描述自动生成 PPT 内容。用户通过 `/springPpt/createPpt` 端点描述想要的 PPT 主题，大模型会生成符合要求的大纲结构，包括标题、幻灯片内容、布局类型等信息。生成的内容以 JSON 格式返回，方便前端进行渲染和展示。

### MCP 工具集成

项目集成了 MCP（Model Context Protocol）工具框架，当前已实现获取当前时间的工具。开发者可以通过 `/springaiChat/testMcp` 端点测试工具调用效果。MCP 工具机制允许大模型在回答过程中主动调用外部工具，获取实时信息或其他辅助能力。

### 聊天历史管理

项目使用 Redis 存储聊天历史记录，支持多个独立的会话记忆。每个会话通过唯一的 sessionId 进行标识，系统会自动维护每个会话的对话历史，并在回答时将历史上下文一并发送给大模型。聊天历史的最大保存数量可以通过配置项 `chat.history.max-size` 进行调整。

## 快速开始

### 环境准备

在运行项目之前，需要确保开发环境满足以下要求：

首先，安装 Java 17 或更高版本的 JDK，可以从 Adoptium 或 Oracle 官网下载安装。安装完成后，通过 `java -version` 命令验证安装是否成功。

其次，安装 Maven 3.6 或更高版本，可以从 Apache Maven 官网下载。安装完成后，通过 `mvn -version` 命令验证安装是否成功。

第三，安装并启动 Ollama 服务。Ollama 支持 macOS、Linux 和 Windows 系统，可以从 Ollama 官网下载安装。安装完成后，使用 `ollama pull llama3` 命令下载所需的模型，然后使用 `ollama list` 命令确认模型已成功下载。

第四，安装 Redis 服务（可选）。如果需要使用聊天历史功能，需要安装并启动 Redis。Redis 可以通过 Docker 或直接下载安装。如果不安装 Redis，项目可以使用内存存储进行替代，但重启后历史记录会丢失。

### 项目配置

在启动项目之前，需要修改配置文件以匹配本地环境。项目配置文件位于各模块的 `src/main/resources` 目录下，主要包括 `application.yaml` 或 `application.yml` 文件。

Ollama 配置项 `ollama.model` 用于指定默认使用的大模型名称，可以根据下载的模型进行修改。Redis 配置项包括主机地址、端口和密码，用于连接聊天历史存储服务。如果使用内存存储，可以跳过 Redis 相关配置。

### 构建与运行

项目使用 Maven 进行构建，在项目根目录下执行以下命令进行构建：

```bash
mvn clean install
```

构建完成后，进入各模块目录启动对应的应用。启动 Spring AI 主应用：

```bash
cd springai
mvn spring-boot:run
```

启动 LangChain4j 应用：

```bash
cd langchain4j
mvn spring-boot:run
```

应用启动后，可以通过浏览器访问 `http://localhost:8080` 查看前端界面（如果已配置前端资源映射）。

## API 接口参考

### 聊天接口

```bash
# 普通聊天
GET /springaiChat/message?message=你好

# 带历史的聊天
GET /springaiChat/message2?sessionId=1&message=你好

# 流式聊天
GET /springaiChat/message3?message=讲个笑话
```

### RAG 接口

```bash
# 上传文档
POST /springaiRag/upload
Content-Type: multipart/form-data
Body: file=@document.pdf

# 文档问答
GET /springaiRag/chat?message=文档中关于什么内容
```

### PPT 生成

```bash
# 生成PPT
GET /springPpt/createPpt?message=介绍人工智能的发展历史
```

### MCP 工具

```bash
# 测试MCP工具
GET /springaiChat/testMcp
```

## 扩展开发

### 添加自定义 MCP 工具

项目提供了灵活的 MCP 工具扩展机制。在 `spring-mcp-server` 模块中，可以按照现有工具的实现方式添加新的自定义工具。创建服务类并在方法上添加 `@Tool` 注解，定义工具描述和参数说明即可。

```java
@Service
public class CustomToolsService {
    @Tool(description = "工具功能描述")
    public String customMethod(@ToolParam(description = "参数描述") String param) {
        // 实现逻辑
        return result;
    }
}
```

### 更换 Embedding 模型

项目默认使用 Ollama 提供的嵌入模型。如果需要更换为其他模型，可以修改配置或实现自定义的 `EmbeddingModel` 接口。项目中使用了 `OllamaEmbeddingModel`，可以直接替换为 OpenAI、HuggingFace 等其他供应商的嵌入模型。

### 使用数据库存储聊天历史

当前项目使用内存或 Redis 存储聊天历史。如果需要更持久化的存储方案，可以实现 `ChatMemoryStore` 接口，连接到 MySQL、PostgreSQL 等数据库。项目中已有 `InMemoryChatMemoryStore` 的实现作为参考。

## 注意事项

Ollama 服务必须在应用启动前运行，并确保所需模型已下载。如果 Ollama 服务未启动，应用将无法正常响应请求。

文件上传功能需要确保临时文件目录具有写权限。Spring Boot 默认使用系统临时目录，通常无需额外配置。

前端页面依赖 Vue、Tailwind CSS、Marked.js 等资源，这些文件已包含在 `ui` 模块中。如果需要自定义前端样式，可以直接修改相关资源文件。