一、技术栈整体介绍

1.1 核心组件说明

• Ollama：本地大模型运行容器，支持一键拉取、运行、管理各类开源大模型，提供标准化 HTTP 接口，无需复杂部署配置。

• Spring AI：Spring 官方 AI 开发框架，统一封装模型调用、向量检索、提示词模板、智能体编排等能力，适配多厂商模型。

• RAG（检索增强生成）：解决大模型幻觉、知识滞后问题，通过检索私有知识库内容，让模型基于真实业务数据回答。

• Graph Agent（图智能体）：基于有向图编排多步骤任务，实现工具调用、任务拆解、链式推理，适配复杂 AI 业务场景。

• 向量数据库：本文采用 Spring AI 默认集成的 内存向量库 做演示，可无缝替换为 Chroma、Milvus、Redis 等生产级向量库。

1.2 整体架构流程

私有文档 → 文本切片 → 向量化存储 → 用户提问 → 问题向量化 → 相似内容检索 → 提示词拼接 → 大模型生成答案（RAG）→ 复杂任务拆解 + 工具调用（Graph Agent）→ 最终结果返回

二、环境搭建（从零配置）

2.1 安装 Ollama 并部署大模型

1、官网下载安装 Ollama：https://ollama.com/，支持 Windows/Mac/Linux 全平台

2、安装完成后，打开终端，拉取轻量高效的开源模型（本文以 Qwen 1.8B 为例，低配电脑也能流畅运行）

ollama pull qwen:1.8b

3、验证模型运行，终端执行测试对话：

ollama run qwen:1.8b

4、默认服务地址：http://localhost:11434，后续 Spring AI 将通过该接口调用模型

2.2 Spring Boot 项目初始化

基于 Spring Boot 3.x 搭建项目，引入 Spring AI 核心依赖，JDK 版本要求 17+

Maven 核心依赖

<!-- Spring AI Ollama 核心依赖 -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-ollama-spring-boot-starter</artifactId>
    <version>1.0.0-M1</version>
</dependency>

<!-- 向量存储、文档解析依赖 -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-core</artifactId>
</dependency>

<!-- 工具类简化代码 -->
<dependency>
    <groupId>cn.hutool</groupId>
    <artifactId>hutool-all</artifactId>
    <version>5.8.32</version>
</dependency>

2.3 配置文件 application.yml

spring:
  ai:
    ollama:
      # Ollama 服务地址
      base-url: http://localhost:11434
      # 使用的模型名称，与 ollama pull 模型一致
      chat:
        model: qwen:1.8b
      embedding:
        model: qwen:1.8b
# 日志配置，方便查看请求、检索细节
logging:
  level:
    org.springframework.ai: DEBUG

三、基础能力：实现简单 AI 对话

先完成最基础的模型调用，验证环境是否通畅，为后续 RAG、智能体开发铺垫。

3.1 基础对话 Controller

@RestController
@RequestMapping("/ai/chat")
public class ChatController {

    // 自动注入 Ollama 对话客户端
    private final OllamaChatModel ollamaChatModel;

    public ChatController(OllamaChatModel ollamaChatModel) {
        this.ollamaChatModel = ollamaChatModel;
    }

    /**
     * 简单单轮对话
     */
    @GetMapping("/simple")
    public String simpleChat(@RequestParam String message) {
        return ollamaChatModel.call(message);
    }

    /**
     * 流式对话（实时返回打字机效果）
     */
    @GetMapping("/stream")
    public Flux<String> streamChat(@RequestParam String message) {
        return ollamaChatModel.stream(message);
    }
}

启动项目，访问接口即可完成 AI 对话，至此基础模型调用能力完成。

四、核心实战：RAG 检索增强问答落地

原生大模型存在知识滞后、幻觉严重、无法读取私有业务数据的问题，RAG 就是最优解决方案。核心逻辑：先将私有文档切片向量化存储，用户提问时检索相似内容，让模型基于检索结果回答。

4.1 RAG 核心配置类

配置文档切片器、内存向量库、检索器，快速构建 RAG 基础能力

@Configuration
public class RagConfig {

    /**
     * 文档切片器：按字符长度切片，避免单段文本过长
     */
    @Bean
    public TextSplitter textSplitter() {
        return new TokenTextSplitter(800, 150, 10, 5);
    }

    /**
     * 内存向量存储（演示专用，生产替换为 Milvus/Chroma）
     */
    @Bean
    public VectorStore vectorStore(EmbeddingModel embeddingModel) {
        return new InMemoryVectorStore(embeddingModel);
    }

    /**
     * 相似内容检索器
     */
    @Bean
    public RetrievalAdvisor retrievalAdvisor(VectorStore vectorStore) {
        return RetrievalAugmentationAdvisor.builder()
                .documentRetriever(VectorStoreDocumentRetriever.builder()
                        .vectorStore(vectorStore)
                        .similarityThreshold(0.7d) // 相似度阈值
                        .topK(3) // 检索Top3相似文档
                        .build())
                .build();
    }
}

4.2 知识库初始化工具类

实现本地文本/自定义文档加载、切片、存入向量库，项目启动自动加载知识库

@Component
public class RagKnowledgeLoader {

    private final VectorStore vectorStore;
    private final TextSplitter textSplitter;

    public RagKnowledgeLoader(VectorStore vectorStore, TextSplitter textSplitter) {
        this.vectorStore = vectorStore;
        this.textSplitter = textSplitter;
    }

    /**
     * 项目启动加载私有知识库
     */
    @PostConstruct
    public void loadKnowledge() {
        // 自定义业务知识库内容（可替换为读取本地文件、数据库、接口文档）
        String knowledge = "Spring AI 是 Spring 生态官方 AI 开发框架，统一集成各类大模型、向量库、智能体能力。" +
                "支持 RAG 检索增强、工具调用、Graph 智能体、流式对话等核心功能。" +
                "Ollama 可本地部署开源大模型，配合 Spring AI 可快速实现私有化 AI 应用，无需联网。";

        // 文档封装 + 切片
        Document document = new Document(knowledge);
        List<Document> documentList = textSplitter.split(List.of(document));

        // 存入向量库
        vectorStore.add(documentList);
        System.out.println("知识库加载完成，切片数量：" + documentList.size());
    }
}

4.3 RAG 问答接口实现

@RestController
@RequestMapping("/ai/rag")
public class RagController {

    private final OllamaChatModel chatModel;
    private final RetrievalAdvisor retrievalAdvisor;

    public RagController(OllamaChatModel chatModel, RetrievalAdvisor retrievalAdvisor) {
        this.chatModel = chatModel;
        this.retrievalAdvisor = retrievalAdvisor;
    }

    /**
     * RAG 检索增强问答
     */
    @GetMapping("/query")
    public String ragQuery(@RequestParam String question) {
        // 构建用户请求，绑定 RAG 检索切面
        Prompt prompt = new Prompt(question);
        ChatResponse response = chatModel.call(
                ChatRequest.builder()
                        .prompt(prompt)
                        .advisors(retrievalAdvisor)
                        .build()
        );
        return response.getResult().getOutput().getContent();
    }
}

4.4 RAG 效果验证

提问：Spring AI 可以实现哪些 AI 功能？

模型会基于我们录入的私有知识库回答，而非通用训练数据，彻底解决幻觉、知识不匹配业务的问题。

五、进阶实战：Graph Agent 图智能体落地

RAG 只能实现单步检索问答，面对复杂任务（多步骤推理、工具调用、条件分支、任务拆解）无能为力。此时需要 Graph Agent 图智能体，通过有向图编排任务流程，实现自动化复杂任务处理。

5.1 Graph Agent 核心原理

Spring AI 的 Graph Agent 基于节点 + 边 + 条件分支构建工作流：

• 节点：单个任务单元（检索知识库、调用工具、模型推理、结果总结）

• 边：节点之间的执行流转关系

• 条件分支：根据任务结果判断下一步执行逻辑

5.2 自定义工具（智能体可调用）

先定义两个业务工具，供 Graph Agent 自动调用，实现任务联动

@Component
public class AiTools {

    /**
     * 工具1：查询 Spring AI 相关知识点
     */
    @Tool(description = "查询Spring AI相关技术知识点")
    public String querySpringAiKnowledge(@ToolParam(description = "用户提问关键词") String keyword) {
        return "Spring AI 核心能力包含：RAG检索增强、Graph智能体编排、多模型适配、流式对话、工具调用。";
    }

    /**
     * 工具2：查询 Ollama 部署优势
     */
    @Tool(description = "查询Ollama本地部署优势")
    public String queryOllamaAdvantage(@ToolParam(description = "用户提问关键词") String keyword) {
        return "Ollama支持本地私有化部署、无网络依赖、模型轻量化、调用速度快、完全免费开源。";
    }
}

5.3 Graph Agent 工作流编排

实现流程：用户提问 → 智能体判断问题类型 → 自动调用对应工具 → 模型整合结果输出

@Configuration
public class GraphAgentConfig {

    @Bean
    public GraphAgent graphAgent(OllamaChatModel chatModel, AiTools aiTools) {
        // 1. 构建工作流图
        StateGraph<AgentState> graph = new StateGraph<>(AgentState.class)
                // 定义智能体思考节点
                .addNode("agentThink", state -> {
                    // 绑定工具，让模型自主选择调用
                    ChatResponse response = chatModel.call(ChatRequest.builder()
                            .prompt(new Prompt(state.getQuestion()))
                            .tools(List.of(aiTools))
                            .build());
                    state.setAnswer(response.getResult().getOutput().getContent());
                    return state;
                })
                // 起始节点
                .startWith("agentThink")
                // 结束节点
                .endNode("agentThink");

        // 2. 构建 Graph 智能体
        return GraphAgent.builder()
                .graph(graph.build())
                .build();
    }
}

5.4 Graph Agent 接口测试

@RestController
@RequestMapping("/ai/agent")
public class GraphAgentController {

    private final GraphAgent graphAgent;

    public GraphAgentController(GraphAgent graphAgent) {
        this.graphAgent = graphAgent;
    }

    @GetMapping("/query")
    public String agentQuery(@RequestParam String question) {
        AgentState state = new AgentState();
        state.setQuestion(question);
        // 执行图智能体工作流
        AgentState result = graphAgent.invoke(state);
        return result.getAnswer();
    }
}

5.5 测试复杂问题

提问：Spring AI 和 Ollama 配合使用有什么优势？

智能体将自动拆解问题、调用两个工具、整合结果，输出完整答案，实现远超普通 RAG 的复杂任务处理能力。

六、生产级优化方案

以上代码完成了基础功能落地，生产环境可做以下优化，适配企业级场景：

6.1 RAG 优化

• 替换内存向量库为 Milvus/Chroma/Redis，支持海量知识库存储

• 优化切片规则：基于语义切片替代固定长度切片，提升检索精度

• 增加重排序模型（Rerank），过滤无效检索结果

• 实现知识库定时更新、增量更新

6.2 Graph Agent 优化

• 增加多节点分支编排：实现问题分类、工具重试、异常兜底节点

• 添加上下文记忆，支持多轮对话智能体

• 集成更多工具：接口调用、数据库查询、文件解析、代码执行

6.3 性能与稳定性优化

• 开启模型本地缓存、向量检索缓存

• 增加超时、重试、熔断机制

• 流式响应适配前端打字机效果，优化用户体验