告别云端束缚：基于Spring AI与Ollama构建企业级本地MCP应用栈

在AI应用开发如火如荼的今天，一个核心的痛点始终困扰着许多对数据安全、成本控制和响应延迟有严苛要求的企业与开发者：对云端API的深度依赖。每一次模型调用，都意味着数据离开本地环境，面临潜在的安全风险、不可预测的网络延迟以及持续累积的API成本。对于金融、医疗、法律等敏感行业，或是需要在离线、内网环境中稳定运行的工业场景，这种依赖几乎成了不可逾越的障碍。

那么，是否存在一种方案，能够让我们在享受大语言模型强大能力的同时，将一切掌控在自己手中？答案是肯定的。本文将深入探讨如何利用 Spring AI 这一新兴的Java生态AI框架，结合 Ollama 这一轻量级本地模型运行引擎，构建一套完全本地化、可高度定制化的 MCP 应用栈。我们不仅会实现一个简单的问答Demo，更会聚焦于如何将本地AI能力与您现有的业务系统、工具链乃至智能设备无缝集成，打造真正属于您自己的、安全可控的“智能大脑”。无论您是希望为内部知识库添加智能问答，还是为自动化流程注入决策能力，这套方案都将为您提供一条清晰、可行的技术路径。

1. 技术栈选型与核心概念解析

在动手搭建之前，我们需要清晰地理解手中每一块“积木”的作用，以及它们如何协同工作，构成一个稳固的本地AI应用架构。

1.1 为什么是Spring AI + Ollama？

这个组合并非偶然，它精准地解决了Java开发者进入AI领域时面临的几个关键问题：生态隔离、部署复杂和集成困难。

Spring AI 的出现，可以看作是Spring生态向AI领域的一次系统性扩张。它并非另一个AI模型，而是一个抽象层和集成框架。其核心价值在于，它为各种AI服务（无论是OpenAI、Azure OpenAI这样的云端服务，还是Ollama、LocalAI这样的本地模型）提供了一套统一的、Spring风格的编程模型。这意味着，开发者无需为切换不同的模型提供商而重写大量业务代码，只需修改配置，即可将调用从云端无缝切换到本地。它提供了诸如ChatClient、PromptTemplate、VectorStore等高级抽象，让开发者可以更专注于业务逻辑，而非底层的HTTP调用和JSON解析。

Ollama 则专注于解决另一个痛点：本地大模型的“易用性”。它通过一个简单的命令行工具和RESTful API，将模型下载、加载、运行和管理的复杂性全部封装起来。你可以把它想象成本地的“模型应用商店”和“运行时容器”。通过几条命令，就能让诸如Llama 3、DeepSeek Coder、Qwen等主流开源模型在您的笔记本或服务器上跑起来。Ollama负责处理GPU内存管理、模型格式转换等底层细节，为上层应用提供了一个干净、一致的交互接口。

将两者结合，其优势显而易见：

  • 技术栈统一：Java/Spring开发者无需学习Python生态的复杂工具链，可以在熟悉的Spring Boot项目中直接集成AI能力。
  • 彻底的数据隐私：所有数据（用户输入、模型参数、生成结果）均在本地闭环，满足最高级别的合规要求。
  • 极致的成本控制：一次性的硬件投入，无持续的API调用费用，特别适合高频调用场景。
  • 可离线运行：不依赖外部网络，在专网、隔离环境或网络不稳定地区也能稳定服务。
  • 高度可定制：可以针对特定领域数据对开源模型进行微调，并将其无缝集成到Ollama和Spring AI的流程中。

1.2 深入理解MCP：模型上下文协议

MCP，即 Model Context Protocol，是一个正在兴起的重要概念。虽然其具体规范仍在演进中，但其核心思想非常明确：为AI模型提供动态、结构化、可编程的上下文信息，使其能够更准确、更可靠地调用外部工具、访问特定数据或执行复杂任务。

我们可以通过一个类比来理解：传统的提示词工程（Prompt Engineering）像是给AI模型一本厚厚的、静态的说明书。而MCP则像是为AI模型配备了一个智能的、可交互的仪表盘和工具箱。这个“协议”定义了AI模型如何发现、理解并调用外部工具（如查询数据库、调用API、执行系统命令），以及外部系统如何将结构化的上下文（如当前用户信息、业务状态、实时数据）安全地传递给模型。

在Spring AI的语境下，实现MCP能力，本质上是利用其 ToolCallback 或 Function Calling 机制，将您编写的Java方法（工具）暴露给AI模型，并教会模型在何时、以何种参数去调用它们。这超越了简单的问答，进入了AI智能体的领域。

注意：本文讨论的“实现MCP功能”，主要指在本地环境中，构建具备工具调用和上下文感知能力的AI应用，而非特指实现某个官方的MCP标准协议。这是一种面向能力的实践。

2. 本地开发环境全链路搭建

理论清晰后，我们开始实战。第一步是建立一个完整、可复现的本地开发环境。

2.1 基础环境准备

您需要确保本地已安装以下基础软件：

  1. Java Development Kit (JDK) 17或更高版本：Spring AI 对 LTS 版本有良好支持。
    # 检查Java版本
java -version
  2. Apache Maven 3.6+ 或 Gradle：用于项目管理与构建。本文示例使用Maven。
  3. Docker (可选但推荐)：虽然Ollama支持本地安装，但使用Docker能获得更好的环境隔离和一致性，尤其是在团队协作中。

2.2 Ollama的安装与模型部署

Ollama的安装极其简单。访问其官网下载对应操作系统的安装包即可。安装完成后，通过命令行即可拉取和运行模型。

这里我们以 DeepSeek-Coder 模型为例，它是一个在代码生成和理解方面表现优异的开源模型，非常适合开发者工具场景。

# 拉取DeepSeek-Coder模型（约6B参数版本，对硬件要求相对友好）
ollama pull deepseek-coder:6.7b

# 运行该模型，并暴露API服务（默认端口11434）
ollama run deepseek-coder:6.7b
# 通常情况下，Ollama服务会在后台运行。可以通过以下命令查看运行状态
ollama list

运行成功后，Ollama的REST API服务就在 http://localhost:11434 上就绪了。您可以通过简单的curl命令进行测试：

curl http://localhost:11434/api/generate -d '{
  "model": "deepseek-coder:6.7b",
  "prompt": "用Java写一个Hello World程序",
  "stream": false
}'

如果看到返回了生成的Java代码，说明Ollama和模型都已正常工作。

2.3 创建Spring Boot项目并集成Spring AI

接下来，我们创建一个全新的Spring Boot项目。使用Spring Initializr或IDE的创建向导，选择以下依赖：

  • Spring Web：提供Web能力。
  • Spring AI：核心AI抽象层。目前Spring AI的依赖管理需要通过BOM引入。

以下是手动创建 pom.xml 关键部分的示例：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
         http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.2.0</version> <!-- 使用与Spring AI兼容的版本 -->
        <relativePath/>
    </parent>

    <groupId>com.example</groupId>
    <artifactId>local-mcp-demo</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>local-mcp-demo</name>

    <properties>
        <java.version>17</java.version>
        <spring-ai.version>1.0.0-M3</version> <!-- 请使用最新稳定版 -->
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <!-- Spring AI Ollama 集成 -->
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-ollama-spring-boot-starter</artifactId>
        </dependency>
        <!-- 用于工具调用（MCP核心） -->
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-starter-mcp-server-webflux</artifactId>
        </dependency>
    </dependencies>

    <dependencyManagement>
        <dependencies>
            <!-- 引入Spring AI BOM统一管理版本 -->
            <dependency>
                <groupId>org.springframework.ai</groupId>
                <artifactId>spring-ai-bom</artifactId>
                <version>${spring-ai.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

在 application.properties 或 application.yml 中，配置Spring AI连接到本地的Ollama服务：

# application.properties
spring.ai.ollama.base-url=http://localhost:11434
# 指定要使用的模型，必须与Ollama中拉取的模型名称一致
spring.ai.ollama.chat.model=deepseek-coder:6.7b

# 可选：配置日志级别，便于调试
logging.level.org.springframework.ai=DEBUG

至此，基础环境搭建完毕。启动Spring Boot应用，如果没有报错，说明Spring AI已经成功连接到了本地的DeepSeek-Coder模型。

3. 从简单问答到工具调用：实现MCP核心能力

现在，我们让这个本地AI“活”起来，从最基本的对话开始，逐步赋予它调用外部工具的能力。

3.1 实现基础聊天接口

首先，我们创建一个简单的REST控制器，来验证AI模型的基本对话功能。这能帮助我们快速建立信心。

import org.springframework.ai.chat.ChatClient;
import org.springframework.ai.chat.prompt.Prompt;
import org.springframework.ai.chat.prompt.SystemPromptTemplate;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class SimpleChatController {

    private final ChatClient chatClient;

    @Autowired
    public SimpleChatController(ChatClient chatClient) {
        this.chatClient = chatClient;
    }

    @GetMapping("/chat")
    public String chat(@RequestParam(value = "message", defaultValue = "你好") String message) {
        // 可以添加系统指令，塑造AI的角色和行为
        String systemInstruction = """
                你是一个专业的Java开发助手，擅长代码生成、解释和调试。
                请用简洁、准确的中文回答用户关于编程的问题。
                """;
        SystemPromptTemplate systemPromptTemplate = new SystemPromptTemplate(systemInstruction);
        Prompt prompt = new Prompt(systemPromptTemplate.createMessage(), message);

        // 调用本地模型生成回复
        String response = chatClient.call(prompt).getResult().getOutput().getContent();
        return response;
    }
}

访问 http://localhost:8080/chat?message=解释一下Java中的Stream API，你应该能收到来自本地DeepSeek-Coder模型的详细解答。这证明了从Spring Boot应用调用本地模型的通路已经完全打通。

3.2 定义与注册AI工具（实现MCP的关键）

MCP的精髓在于工具调用。假设我们有一个内部系统，AI需要能查询某个城市的天气信息。我们首先定义一个“天气服务”工具。

import org.springframework.ai.tool.Tool;
import org.springframework.stereotype.Service;

@Service
public class WeatherService {

    /**
     * 一个模拟的天气查询工具。
     * @Tool 注解告诉Spring AI这是一个可供模型调用的工具。
     * @param cityName 城市名称，例如“北京”、“上海”
     * @return 该城市的模拟天气信息
     */
    @Tool(description = "根据城市名称查询当前的天气情况。")
    public String getWeather(String cityName) {
        // 这里应该是调用真实天气API的逻辑。
        // 为了演示，我们返回模拟数据。
        // 在实际项目中，这里可以集成任何内部或外部的REST API、数据库查询等。
        return String.format("城市【%s】的天气是：晴，温度25°C，湿度60%%。", cityName);
    }

    /**
     * 另一个工具示例：计算器。
     */
    @Tool(description = "执行两个数字之间的基本算术运算。")
    public double calculate(double a, double b, String operation) {
        switch (operation.toLowerCase()) {
            case "add": case "+": return a + b;
            case "subtract": case "-": return a - b;
            case "multiply": case "*": return a * b;
            case "divide": case "/":
                if (b == 0) throw new IllegalArgumentException("除数不能为零");
                return a / b;
            default:
                throw new IllegalArgumentException("不支持的运算: " + operation);
        }
    }
}

接下来，我们需要创建一个配置类，将这些工具注册到Spring AI的上下文中，使得ChatClient在对话时能够感知并使用它们。

import org.springframework.ai.tool.ToolCallbackProvider;
import org.springframework.ai.tool.MethodToolCallbackProvider;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class ToolConfig {

    @Bean
    public ToolCallbackProvider toolCallbackProvider(WeatherService weatherService) {
        // MethodToolCallbackProvider 会自动扫描被 @Tool 注解的方法
        // 并将其注册为AI可调用的工具。
        return MethodToolCallbackProvider.builder()
                .toolObjects(weatherService) // 可以传入多个Service实例
                .build();
    }
}

3.3 创建具备工具调用能力的智能聊天端点

现在，我们创建一个新的控制器，使用注入了工具能力的 ChatClient。Spring AI会自动将工具的描述信息作为上下文的一部分发送给模型，并在模型认为需要时，执行相应的工具调用。

import org.springframework.ai.chat.ChatClient;
import org.springframework.ai.chat.prompt.Prompt;
import org.springframework.ai.chat.prompt.SystemPromptTemplate;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class SmartChatController {

    private final ChatClient chatClient;

    // 使用@Qualifier注入支持工具调用的ChatClient
    public SmartChatController(@Qualifier("toolCallbackChatClient") ChatClient chatClient) {
        this.chatClient = chatClient;
    }

    @PostMapping("/smart-chat")
    public String smartChat(@RequestBody UserQuery query) {
        String userMessage = query.getMessage();

        // 更复杂的系统提示，引导AI使用工具
        String systemInstruction = """
                你是一个智能助手，可以回答用户问题并使用工具。
                你拥有以下工具：
                1. getWeather: 查询城市天气。
                2. calculate: 执行数学计算。
                当用户的问题涉及到天气查询或数学计算时，你应该主动、准确地调用相应的工具来获取信息，然后将工具返回的结果整合到你的最终回答中。
                请用友好、专业的中文进行回复。
                """;

        SystemPromptTemplate systemPromptTemplate = new SystemPromptTemplate(systemInstruction);
        Prompt prompt = new Prompt(systemPromptTemplate.createMessage(), userMessage);

        // 此次调用，Spring AI会在后台处理工具调用的逻辑。
        // 如果模型决定调用工具，框架会拦截响应，执行对应Java方法，并将结果再次发送给模型进行总结。
        String response = chatClient.call(prompt).getResult().getOutput().getContent();
        return response;
    }

    // 简单的请求体
    public static class UserQuery {
        private String message;
        // getter and setter ...
    }
}

你需要一个对应的 ChatClient Bean配置来启用工具回调。这通常在配置类中完成：

@Configuration
public class ChatClientConfig {

    @Bean
    @Primary
    public ChatClient simpleChatClient(OllamaChatClient ollamaChatClient) {
        return ollamaChatClient;
    }

    @Bean(name = "toolCallbackChatClient")
    public ChatClient toolCallbackChatClient(OllamaChatClient ollamaChatClient,
                                             ToolCallbackProvider toolCallbackProvider) {
        // 将ToolCallbackProvider与ChatClient关联
        return ollamaChatClient.withToolCallbackProvider(toolCallbackProvider);
    }
}

现在，让我们测试这个强大的端点。使用Postman或curl发送一个POST请求：

curl -X POST http://localhost:8080/smart-chat \
  -H "Content-Type: application/json" \
  -d '{"message": "北京今天的天气怎么样？另外，请帮我计算一下123乘以456等于多少？"}'

观察返回结果。理想情况下，AI的回复会包含两部分：

  1. 调用 getWeather("北京") 工具后得到的天气信息。
  2. 调用 calculate(123, 456, "multiply") 工具后得到的计算结果。 并且，AI会将这些信息自然地组织成一段连贯的回答，例如：“北京今天天气晴朗，温度25°C。另外，123乘以456的计算结果是56088。”

这个过程完美诠释了MCP的核心：AI模型理解用户意图 -> 选择并调用合适的工具 -> 获取结构化数据 -> 生成最终的自然语言回复。所有这一切，都在您的本地服务器上完成，没有一丝数据离开您的环境。

4. 性能调优、监控与生产级部署建议

让应用跑起来只是第一步，要使其在生产环境中稳定、高效地服务，还需要考虑更多。

4.1 模型与硬件性能优化

本地运行大模型，性能是首要考虑因素。以下是一些关键优化点：

  • 模型量化与选择：Ollama支持多种量化版本的模型（如q4_K_M, q8_0等）。量化能在轻微损失精度的情况下大幅降低内存占用和提升推理速度。对于DeepSeek-Coder，可以尝试 deepseek-coder:6.7b-q4_K_M。使用 ollama pull 拉取不同量化版本进行测试。
  • GPU加速：如果您的服务器配有NVIDIA GPU，确保Ollama能够利用CUDA进行加速。安装正确的NVIDIA驱动和CUDA工具包后，Ollama通常会自动检测并使用GPU。可以通过 ollama run 时的日志或 nvidia-smi 命令来确认。
  • 参数调整：通过Ollama的Modelfile或Spring AI的配置，可以调整推理参数以平衡速度与质量。
    # 在Spring AI中配置Ollama参数示例
spring.ai.ollama.chat.options.temperature=0.7
spring.ai.ollama.chat.options.top-p=0.9
spring.ai.ollama.chat.options.num-predict=512
    • temperature：控制随机性（0-1），值越低输出越确定。
    • top-p：核采样，影响词汇选择的多样性。
    • num-predict：限制生成的最大token数。

4.2 应用层优化与监控

  • 连接池与超时：配置HTTP客户端（如WebClient）的连接池和超时时间，防止长时间等待拖垮服务。
  • 异步与非阻塞：对于高并发场景，考虑使用Spring WebFlux实现非阻塞的API端点，避免线程被长时间的模型推理阻塞。
  • 健康检查与就绪探针：为Spring Boot应用和Ollama服务分别配置Kubernetes的livenessProbe和readinessProbe，确保服务的弹性。
  • 日志与追踪：集中收集Spring AI和Ollama的日志。对于关键的业务流程（如工具调用），添加详细的业务日志和链路追踪（如使用Micrometer和Zipkin），便于问题排查。
  • 限流与降级：使用Resilience4j或Sentinel为AI服务接口添加限流、熔断和降级策略，保护后端模型服务不被突发流量击垮。

4.3 生产部署架构示例

一个典型的生产级部署架构可能如下所示：

[外部客户端] -> [负载均衡器 (Nginx/HAProxy)]
                    |
                    v
        [Spring Boot应用集群 (Docker/K8s Pods)]
                    | (HTTP调用)
                    v
        [Ollama服务集群 (独立部署)]
                    |
        [共享存储 (模型文件)]

关键决策点：

  1. Ollama与Spring App的部署关系：可以选择“Sidecar”模式（每个Spring App Pod附带一个Ollama容器）或“独立服务”模式（Ollama作为独立集群）。前者隔离性好，后者资源利用率高。
  2. 模型文件存储：将模型文件放在持久化存储卷（如NFS、Ceph）中，多个Ollama实例可以共享，避免重复下载。
  3. 配置管理：使用ConfigMap或环境变量管理Spring AI的连接配置、模型名称和推理参数。

4.4 安全加固

  • API网关与认证：在Spring Boot应用前部署API网关（如Spring Cloud Gateway），集成JWT或OAuth2.0认证，保护AI服务端点。
  • 输入输出过滤与审查：对用户输入进行严格的清洗和过滤，防止提示词注入攻击。对模型输出内容（特别是当集成工具能执行系统命令或访问敏感数据时）进行安全审查。
  • 网络隔离：将Ollama服务部署在内网，仅允许Spring Boot应用集群访问其API端口（11434），禁止公网直接访问。

通过以上步骤，您已经掌握了从零开始，基于Spring AI和Ollama构建一个安全、高效、可扩展的本地化MCP应用的全套方法论。这套方案将AI能力从云端“请”回了本地，赋予了开发者在数据主权、成本控制和系统集成上前所未有的灵活性。在实际项目中，您可以根据业务需求，定义更丰富的工具（如数据库查询、工单创建、文档检索），不断拓展这个本地智能体的能力边界，使其真正成为您业务系统中不可或缺的智能组件。

# Ollama # DeepSeek
Logo
AI Agent技术社区

Agent 垂直技术社区，欢迎活跃、内容共建。

更多推荐

cover

AI Agent 对比和选型

avatar AI Agent技术社区

2026企业微信AI Agent实测：7款技术方案对比

会话审计、敏感词管理、聊天质检、敏感行为识别、舆情、属性、词频及竞品分析覆盖服务风险；线索公海、客户、产品、商机、订单、回款、发票和业绩目标则连接销售全过程。快创助手负责快速建运营任务，策略生成把目标拆成方案，智能客服回答系统使用咨询，数据报表处理自然语言查数，AI洞察联合标签、订单和会话分析客户。我们设计了客户筛选、订单关联、销售交接、会话质检和异常恢复任务，配合技术访谈与行业公开资料复核。准备

avatar AI Agent技术社区
cover

如何构建 AI Agent Harness 2.0，让 AI Agent 比 99% 的开发者更工程化

avatar AI Agent技术社区