Spring AI 赋能 Java，Spring Boot 快速落地 LLM 的企业级解决方案

当下大模型开发热潮中，Python似乎成了默认选择，但在企业级开发场景里，Java生态的话语权依旧稳固。很多公司为了兼容既有的Spring Boot微服务体系，选择用Java搭建大模型后端，而Spring AI框架的出现，恰好解决了不同厂商大语言模型（LLM）接入的碎片化问题。

笔者在项目实践中，先后尝试过OpenAI、Ollama、Docker Model Runner以及AWS Bedrock四种接入方案，深刻体会到Spring AI以统一编程范式屏蔽底层API差异的优势。本文将结合实操经验，从框架核心认知出发，逐一拆解各方案的接入要点、原理细节与取舍逻辑，帮你快速掌握Spring Boot与大模型的无缝整合技巧，同时避开那些容易踩坑的环节。

一、Spring AI框架核心认知：两个抽象搞定大模型交互

在接触具体接入方案前，先搞懂Spring AI的核心价值与关键概念，后续实操就能事半功倍。Spring AI作为Spring生态下的AI开发工具集，最核心的作用体现在三个方面：一是为大模型交互提供高度抽象，不用关注不同厂商的API细节；二是以统一API抹平各类AI服务商的差异，切换模型时无需大幅修改代码；三是继承了Spring Boot Starter的自动配置能力，接入成本极低，开箱即用。

其实不用死记硬背太多概念，只需牢记两个核心抽象，就能应对绝大多数开发场景。第一个是ChatModel，它直接对应大语言模型本身，比如OpenAI的GPT-4、Meta的LLaMA 3等，Spring AI为不同厂商的模型提供了统一的ChatModel实现类，这是实现跨厂商兼容的核心；第二个是ChatClient，它是应用侧与大模型交互的入口，我们通过它发送提示词、接收响应，所有与模型的通信操作都通过这个入口完成。

简单理解就是，ChatModel是"模型本体"，ChatClient是"沟通桥梁"，Spring AI通过这两个抽象层，把复杂的模型调用逻辑封装起来，让我们只需关注业务场景，而非底层通信细节。这种设计思路与Spring的"约定大于配置"理念高度一致，也是它能快速融入Spring Boot生态的关键。

二、快速上手：OpenAI最小可运行示例

如果想快速验证Spring AI与大模型的整合效果，OpenAI是最优选择，它的接入流程最简单，能让我们在最短时间内跑通完整链路。下面从依赖引入到实际调用，一步步拆解实操细节，同时分享一些容易忽略的注意点。

2.1 依赖引入：精准选择 Starter

Spring Boot项目接入OpenAI，只需在pom.xml（Maven）或build.gradle（Gradle）中追加三个核心依赖。其中spring-boot-starter-web用于构建REST接口，方便我们通过接口测试模型交互；spring-boot-devtools是开发工具，支持热部署，提升开发效率；spring-ai-openai-spring-boot-starter是Spring AI针对OpenAI的 Starter，包含了所有必要的自动配置类与依赖。

这里有个小技巧，无需指定具体版本号，只要项目继承了Spring Boot的父工程，Spring AI会自动匹配对应的版本，避免版本冲突。如果是Gradle项目，依赖声明格式略有不同，但核心依赖一致，可参考Spring AI官方文档调整。

2.2 控制器骨架：注入ChatClient即可调用

依赖引入后，创建一个REST控制器就能实现模型调用。新建HelloWorldController类，添加@RestController注解，然后在构造方法中注入ChatClient.Builder，通过build()方法创建ChatClient实例。这里之所以注入Builder而非直接注入ChatClient，是因为Builder支持自定义配置，比如设置超时时间、默认提示词等，灵活性更高。

核心代码非常简洁，控制器类中只需持有ChatClient实例，后续就能通过它发起对话请求。需要注意的是，Spring AI会自动完成ChatClient的装配，无需我们手动创建，这就是Starter自动配置的便捷之处。

java 复制代码

@RestController
public class HelloWorldController {
    private final ChatClient chatClient;

    public HelloWorldController(ChatClient.Builder chatClientBuilder) {
        this.chatClient = chatClientBuilder.build();
    }
}

2.3 自动装配原理：看懂Bean的注册逻辑

很多开发者可能会好奇，为什么注入ChatClient.Builder就能直接使用。其实引入OpenAI Starter后，Spring Boot启动时会触发自动配置类的执行，该配置类会向Spring容器中注册一个ChatModel Bean，具体实现类是OpenAiChatModel，这个Bean封装了与OpenAI API通信的所有细节。

而ChatClient.Builder会自动关联容器中的ChatModel Bean，通过build()方法创建ChatClient实例时，会将ChatModel注入其中，从而实现通过ChatClient调用模型的功能。这里有个关键注意点，如果后续引入其他大模型的Starter，容器中会出现多个ChatModel实例，此时自动装配会失效，需要手动管理Bean的注册与注入，这个问题后面会详细讲解。

2.4 发起对话：三步完成提示词调用与响应提取

控制器创建完成后，添加一个接口方法就能发起对话。比如新增一个helloAI接口，接收用户输入的提示词，然后通过chatClient的prompt()方法封装提示词，call()方法触发模型推理，最后通过content()方法提取响应文本。整个调用流程只有一行核心代码，非常简洁。

java 复制代码

@GetMapping("/hello-ai")
public String helloAI(@RequestParam String prompt) {
    return chatClient.prompt(prompt).call().content();
}

这里拆解一下三个方法的作用，prompt()方法用于封装用户输入的提示词，也可以通过Prompt对象设置系统提示词、对话历史等；call()方法是同步调用模型，会阻塞当前线程直到获取响应，也可以使用callAsync()方法实现异步调用；content()方法用于提取响应中的文本内容，因为模型响应可能包含其他信息，比如token数量、响应时间等，content()方法会直接返回核心文本。

2.5 日志美化：可选但推荐的调试技巧

开发过程中，日志是排查问题的重要工具。默认的日志格式比较杂乱，我们可以在application.yml中配置日志格式，让日志更易读。比如设置控制台日志显示时间、日志级别、线程名、日志来源等信息，并用不同颜色区分，这样调试时能快速定位问题。

yaml 复制代码

logging:
  pattern:
    console: "%green(%d{HH:mm:ss.SSS}) %blue(%-5level) %red([%thread]) %yellow(%logger{15}) - %msg%n"

这个配置不是必须的，但推荐添加，尤其是在开发阶段，清晰的日志能大幅提升调试效率。如果是生产环境，可以根据需求调整日志格式，比如增加日志文件输出、调整日志级别等。

2.6 API Key配置：避免启动失败的关键步骤

OpenAI需要API Key才能调用，获取API Key的步骤很简单，访问OpenAI平台官网，完成注册并充值后，在个人中心创建密钥即可。需要注意的是，OpenAI充值最低约5美元，新手可以先充值少量金额测试。

获取API Key后，不建议直接硬编码在配置文件中，最好以环境变量的形式注入。在application.yml中通过${OPEN_API_KEY}引用环境变量，然后在部署环境中设置该环境变量，这样能提高密钥的安全性，避免泄露。

yaml 复制代码

spring:
  ai:
    openai:
      api-key: ${OPEN_API_KEY}

这里有个致命坑，如果缺失该环境变量，Spring Boot启动时会因为无法创建OpenAiChatModel Bean而直接失败，报错信息会提示缺少api-key配置，此时只需检查环境变量是否正确设置即可。

三、本地私有化部署：Ollama方案实操

在企业级场景中，很多项目因为数据合规要求或需要离线运行，无法使用公有云的大模型服务，此时本地私有化部署就成了刚需。Ollama作为一款开源的大模型运行时，能让我们在内网环境中零依赖运行大模型，搭配Spring AI接入，完美满足隐私敏感场景的需求。

3.1 Ollama安装与模型拉取：简单两步搞定本地部署

Ollama的安装非常简单，支持Windows、Mac、Linux等多种系统，以Linux系统为例，只需执行一条命令就能完成安装：curl -fsSL https://ollama.com/install.sh | sh。安装完成后，通过ollama run 模型名就能拉取并运行模型，比如拉取LLaMA 3.2 1B版本的命令是ollama run llama3.2:1b。

这里需要注意，模型拉取需要网络连接，建议在能访问外网的环境中完成拉取，然后迁移到内网环境。1B参数的模型体积较小，适合本地测试，生产环境可以根据需求选择更大参数的模型，比如LLaMA 3.2 7B，但需要注意本地硬件资源是否充足，更大参数的模型对CPU、内存的要求更高。

模型启动后，Ollama会默认在本地开启服务，Spring Boot项目通过本地端口就能与模型通信，无需额外配置端口，非常便捷。

3.2 Spring Boot配置：无需API Key的极简接入

Spring Boot接入Ollama，首先需要引入对应的Starter依赖，在pom.xml中添加spring-ai-ollama-spring-boot-starter依赖，与OpenAI Starter类似，它会自动完成配置类的注册。

xml 复制代码

<dependency>
  <groupId>org.springframework.ai</groupId>
  <artifactId>spring-ai-ollama-spring-boot-starter</artifactId>
</dependency>

配置文件方面，需要指定默认的聊天模型为ollama，并设置Ollama运行的模型名称，也就是我们之前拉取的llama3.2:1b。核心配置如下：

yaml 复制代码

spring:
  ai:
    model:
      chat: ollama
    ollama:
      chat:
        options:
          model: llama3.2:1b

最关键的一点是，Ollama作为本地部署的模型，无需配置API Key，模型完全在本地驻留，所有数据都不会出境，完美满足数据合规要求。配置完成后，启动Spring Boot项目，就能通过ChatClient像调用OpenAI一样调用Ollama模型，无需修改业务代码，这就是Spring AI统一API的优势。

这里有个小细节，Ollama支持自定义模型参数，比如设置温度、最大响应长度等，这些参数可以在options节点下配置，具体支持的参数可参考Ollama官方文档，根据业务需求调整即可。

四、容器化本地推理：Docker Model Runner方案

除了Ollama，Docker也提供了本地大模型运行方案，Docker Desktop现已内嵌Model Runner功能，处于Beta阶段，支持以容器方式运行大模型，适合喜欢用容器化部署的团队。这种方案兼顾了本地推理的隐私性与容器化的便捷性，部署与迁移都非常灵活。

4.1 启用Model Runner：四步完成环境配置

首先需要安装Docker Desktop，确保版本是较新的版本，因为Model Runner是新增功能，旧版本可能不支持。安装完成后，打开Docker Desktop的设置界面，在Features选项中勾选Model Runner，然后开启TCP端口，默认端口是12434，也可以根据需求自定义端口。配置完成后，重启Docker Desktop使设置生效。

环境配置完成后，可以通过两条命令验证是否生效：docker model version用于查看Model Runner的版本，docker model run ai/gemma3用于拉取并运行Gemma 3模型。拉取模型时需要注意网络环境，建议保持网络通畅，模型拉取完成后会自动启动容器运行模型。

需要注意的是，Model Runner目前处于Beta阶段，可能存在一些不稳定的情况，适合测试场景，生产环境建议谨慎使用，等待功能稳定后再迁移。

4.2 Spring Boot配置：伪装成OpenAI调用

Spring AI目前没有为Docker Model Runner提供专门的Starter，而是通过复用OpenAI客户端与Docker通信，因此需要将其伪装为OpenAI调用。首先确保项目中引入了spring-ai-openai-spring-boot-starter依赖，然后在配置文件中设置OpenAI的API Key为dummy-key，这是一个虚拟密钥，因为Model Runner不需要真实的API Key，但Starter启动时会校验API Key是否存在，所以必须填写一个非空值。

同时需要配置OpenAI的基础URL，指向Docker Model Runner的服务地址，也就是http://localhost:12434/engines，再指定模型名称为ai/gemma3，与我们之前运行的模型一致。核心配置如下：

yaml 复制代码

spring:
  ai:
    openai:
      api-key: dummy-key
      chat:
        base-url: http://localhost:12434/engines
        options:
          model: ai/gemma3

配置完成后，启动Spring Boot项目，就能通过ChatClient调用Docker中的Gemma 3模型，调用方式与OpenAI完全一致，无需修改业务代码。这种复用现有客户端的设计，体现了Spring AI的灵活性，能快速适配新的模型运行方案。

4.3 终止模型会话：简单指令即可关闭

与Ollama不同，Docker Model Runner运行模型时，通过发送/bye指令就能终止模型会话，关闭容器。这个指令可以直接在Docker Desktop的终端中输入，也可以通过代码发送请求触发，操作非常便捷。需要注意的是，终止会话后，模型容器会停止运行，再次调用时需要重新启动容器，或者设置容器为自动重启模式。

五、企业级托管方案：AWS Bedrock接入

对于大型企业而言，私有化部署的运维成本较高，而公有云模型的合规性又难以保障，此时AWS Bedrock就成了最优选择。AWS Bedrock通过统一API托管了多家基础模型（FMs），包括Amazon Titan、Anthropic Claude、Meta LLaMA、Cohere、Mistral等，既能满足企业级的合规要求，又能灵活切换模型，兼顾安全性与弹性。

5.1 选型理由：企业级场景的核心优势

选择AWS Bedrock，主要有四个核心优势。一是数据驻留AWS，所有数据都不会流出AWS生态，能满足金融、医疗等行业的严格合规要求；二是采用IAM身份鉴权，无需硬编码API Key，通过IAM Role、凭证文件或环境变量就能完成认证，安全性更高；三是按需计费，无需提前部署硬件资源，根据实际调用量付费，降低运维成本；四是模型可一键切换，支持多种主流模型，无需修改代码就能切换不同厂商的模型，适配不同业务场景。

笔者所在的项目需要对接多种模型，同时要求数据合规，采用AWS Bedrock后，不仅简化了模型接入流程，还降低了运维成本，切换模型时只需修改配置文件，无需调整业务代码，大幅提升了开发效率。

5.2 依赖引入与鉴权配置：优先级明确的认证方式

Spring Boot接入AWS Bedrock，需要引入对应的Starter依赖，Gradle项目的依赖声明为implementation 'org.springframework.ai:spring-ai-bedrock-spring-boot-starter'，Maven项目可参考官方文档调整依赖格式。

认证方式方面，AWS Bedrock支持三种方式，优先级从高到低依次为IAM Role、~/.aws/credentials凭证文件、环境变量。推荐使用IAM Role认证，尤其是在AWS ECS、EKS等容器服务中部署时，通过IAM Role能实现无凭证认证，安全性更高；如果是本地开发测试，可以使用环境变量或凭证文件认证。

以环境变量认证为例，需要设置三个环境变量：AWS_ACCESS_KEY_ID（Access Key）、AWS_SECRET_ACCESS_KEY（Secret Key）、AWS_REGION（区域，比如us-east-1）。这些信息可以在AWS控制台中获取，创建IAM用户时会生成Access Key与Secret Key，注意Secret Key只会显示一次，创建后要及时保存。

5.3 配置示例：以Claude v2模型为例

配置文件中，需要指定AWS Bedrock的区域，以及默认的聊天模型，这里以Anthropic Claude v2为例，模型名称为anthropic.claude-v2。核心配置如下：

yaml 复制代码

spring:
  ai:
    bedrock:
      aws:
        region: us-east-1
      chat:
        model: anthropic.claude-v2

启动流程非常清晰，Spring Boot启动时，Bedrock Starter会自动创建BedrockChatModel Bean，该Bean封装了与AWS Bedrock API通信的细节，ChatClient通过关联这个Bean，实现与AWS Bedrock托管模型的安全通信。调用方式与之前的OpenAI、Ollama完全一致，通过ChatClient的prompt()、call()方法就能发起对话请求。

这里有个注意点，AWS Bedrock需要开通对应的模型权限，在AWS控制台中，需要为IAM用户或角色分配Bedrock相关的权限，否则会出现权限不足的报错。具体需要分配的权限可参考AWS官方文档，根据需要调用的模型调整权限配置。

5.4 多模型并存：手动管理Bean的注入逻辑

实际项目中，可能需要同时启用多个大模型，比如同时使用OpenAI、Ollama与AWS Bedrock，此时自动装配会因为存在多个ChatModel实例而失效，需要手动关闭自动装配，然后声明多个ChatClient Bean。

首先在配置文件中关闭ChatClient的自动装配：

yaml 复制代码

spring:
  ai:
    chat:
      client:
        enable: false

然后创建配置类ChatClientConfig，在该类中手动声明三个ChatClient Bean，分别对应Bedrock、OpenAI与Ollama模型，每个Bean通过关联对应的ChatModel实现类创建。核心代码如下：

java 复制代码

@Configuration
public class ChatClientConfig {

    @Bean
    public ChatClient bedrockChatClient(BedrockChatModel bedrockChatModel) {
        return ChatClient.builder(bedrockChatModel).build();
    }

    @Bean
    public ChatClient openAiChatClient(OpenAiChatModel openAiChatModel) {
        return ChatClient.create(openAiChatModel);
    }

    @Bean
    public ChatClient ollamaChatClient(OllamaChatModel ollamaChatModel) {
        return ChatClient.builder(ollamaChatModel).build();
    }
}

调用时，通过@Qualifier注解指定需要注入的ChatClient Bean名称，就能精准注入对应的模型客户端。比如在控制器中注入OpenAI与Ollama的ChatClient：

java 复制代码

@RestController
public class MultiModelChatController {

    private final ChatClient openAiChatClient;
    private final ChatClient ollamaChatClient;

    public MultiModelChatController(
        @Qualifier("openAiChatClient") ChatClient openAiChatClient,
        @Qualifier("ollamaChatClient") ChatClient ollamaChatClient) {
        this.openAiChatClient = openAiChatClient;
        this.ollamaChatClient = ollamaChatClient;
    }
}

这种方式能灵活管理多个模型，根据业务需求调用不同的模型，比如将对响应速度要求高的请求分配给Ollama本地模型，将复杂的推理请求分配给OpenAI或AWS Bedrock的模型，实现资源的最优利用。

六、四大方案对比总结：精准匹配业务场景

通过前面的实操讲解，我们已经掌握了OpenAI、Ollama、Docker Model Runner与AWS Bedrock四种接入方案的核心要点。为了帮助大家快速选择合适的方案，下面从多个维度进行对比，结合实际业务场景给出选型建议。

6.1 多维度对比表

对比维度	OpenAI	Ollama / Docker Model Runner	AWS Bedrock
部署形态	公有云API，无需本地部署	本地运行或容器化部署，需本地硬件资源	AWS托管，无需本地部署，按需调用
数据主权	数据出境，需关注合规要求	完全本地驻留，数据无出境风险	数据驻留AWS，满足企业合规要求
安全机制	API Key认证，需注意密钥安全	无额外认证，依赖本地环境安全	IAM身份鉴权，支持细粒度权限控制
模型质量	GPT-4等模型质量高，推理能力强	开源模型为主，质量中等，适合简单场景	多厂商模型可选，质量中高，适配多种场景
运维成本	零运维成本，只需支付API调用费用	运维成本高，需维护本地硬件与模型	运维成本低，AWS负责模型与基础设施维护
适用场景	原型开发、轻量应用、对模型质量要求高的场景	隐私敏感、离线运行、内网部署的场景	企业级应用、合规要求高、需要灵活切换模型的场景

6.2 选型建议与实践思考

结合项目实践经验，给出以下选型建议。如果是快速验证原型、开发轻量应用，优先选择OpenAI，它的接入成本最低，模型质量最高，能快速实现业务需求；如果是隐私敏感、需要离线运行的场景，比如内网部署的传统企业项目，Ollama是更好的选择，数据完全本地驻留，无需担心合规问题，Docker Model Runner可作为补充，适合喜欢容器化部署的团队；如果是企业级生产环境，尤其是对合规性、安全性、弹性有较高要求的场景，AWS Bedrock是最优解，它兼顾了模型丰富度、合规性与低运维成本，能适配复杂的业务需求。

除此之外，还有一些实践中的思考分享给大家。首先，Spring AI的统一API虽然便捷，但在切换模型时，需要注意不同模型的提示词适配问题，不同模型对提示词的敏感度不同，可能需要针对性调整提示词格式，才能获得最佳响应效果；其次，本地部署的模型对硬件资源要求较高，生产环境建议配备高性能的CPU或GPU，避免出现响应缓慢的问题；最后，企业级场景中，建议做好模型调用的监控与限流，比如记录调用日志、设置每秒最大调用次数，避免因突发流量导致服务雪崩。

七、总结与展望

Spring AI框架为Spring Boot项目接入大语言模型提供了统一的解决方案，通过ChatModel与ChatClient两个核心抽象，屏蔽了不同厂商模型的API差异，让开发者能专注于业务场景，无需关注底层通信细节。本文通过四大主流接入方案的实操拆解，详细讲解了OpenAI的快速上手、Ollama的本地私有化部署、Docker Model Runner的容器化推理以及AWS Bedrock的企业级托管，同时通过多维度对比给出了选型建议，希望能帮助大家快速掌握Spring AI的实战技巧。

随着大模型技术的不断发展，Spring AI的功能也在持续迭代，未来可能会支持更多厂商的模型、更丰富的交互方式以及更精准的模型调优工具。对于企业而言，基于Spring AI构建大模型应用，既能兼容既有的Java生态，又能快速适配大模型技术的发展，是实现业务创新的重要抓手。相信在Spring生态的加持下，大模型与企业级应用的融合会更加顺畅，为各行业带来更多创新可能。