版本：1.0.3

快速开始

本章节将带你从零开始，基于 Docker 部署 Ollama 本地大模型，搭建一个完整的 Spring AI 项目。

1. 环境要求

组件	最低版本	说明
JDK	17	Spring Boot 3.4.x 基线要求
Maven	3.6+	或 Gradle 7.x+
Spring Boot	3.5.0	Spring AI 1.0.3 兼容版本
Docker	20.10+	用于运行 Ollama 容器
磁盘空间	10GB+	大模型文件较大（qwen3:8b 约 5GB）

2. 部署 Ollama

Ollama 是目前国内最流行的本地大模型运行时，免 API Key、免翻墙、数据不出本机。

2.1 拉取并启动 Ollama

CPU 模式
GPU 模式

# 启动 Ollama 容器（CPU 模式）
docker run -d --name ollama \
  -p 11434:11434 \
  -v ollama_data:/root/.ollama \
  ollama/ollama

# 若使用 GPU（NVIDIA），加 --gpus all
docker run -d --name ollama \
  --gpus all \
  -p 11434:11434 \
  -v ollama_data:/root/.ollama \
  ollama/ollama

2.2 拉取模型

# 推荐：通义千问3（阿里开源，中文能力优秀）
docker exec -it ollama ollama pull qwen3:8b

# 或者使用其他模型
docker exec -it ollama ollama pull deepseek-r1:8b   # DeepSeek 推理模型
docker exec -it ollama ollama pull llama3:8b         # Meta Llama 3

2.3 验证模型

# 测试模型是否可用
docker exec -it ollama ollama run qwen3:8b "你好，请用一句话介绍自己"

正常返回即表示 Ollama 已就绪，API 地址为 http://localhost:11434。

3. 创建项目

3.1 新建 Maven 项目

mkdir spring-ai-quickstart && cd spring-ai-quickstart
mkdir -p src/main/java/com/example/demo
mkdir -p src/main/resources

3.2 编写 pom.xml

完整 pom.xml

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
         https://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.5.0</version>
        <relativePath/>
    </parent>

    <groupId>com.example</groupId>
    <artifactId>spring-ai-quickstart</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>spring-ai-quickstart</name>

    <properties>
        <java.version>17</java.version>
        <spring-ai.version>1.0.3</spring-ai.version>
    </properties>

    <dependencyManagement>
        <dependencies>
            <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>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <!-- Spring AI Ollama Starter（ChatClient + ChatModel + AutoConfiguration） -->
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-starter-model-ollama</artifactId>
        </dependency>
    </dependencies>

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

依赖说明：

依赖	作用
`spring-boot-starter-parent:3.5.0`	Spring Boot 父 POM，管理 Spring 生态所有版本
`spring-ai-bom:1.0.3`	Spring AI BOM，统一管理所有 Spring AI 模块版本
`spring-boot-starter-web`	提供 Web 能力（内嵌 Tomcat + Spring MVC）
`spring-ai-starter-model-ollama`	Ollama 集成 Starter，传递引入 ChatClient + OllamaChatModel + 自动配置

4. 配置 Ollama 连接

src/main/resources/application.yml
spring:
  ai:
    ollama:
      base-url: http://localhost:11434
      chat:
        options:
          model: qwen3:8b

核心配置项：

配置项	默认值	说明
`spring.ai.ollama.base-url`	`http://localhost:11434`	Ollama API 地址
`spring.ai.ollama.chat.options.model`	`mistral`	聊天模型名称，需与 `ollama pull` 一致

Ollama 是本地部署，无需 API Key，无需网络代理，开箱即用。

5. 编写第一个 AI 对话

5.1 启动类

src/main/java/com/example/demo/DemoApplication.java
package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

5.2 ChatController

ChatController.java

src/main/java/com/example/demo/ChatController.java
package com.example.demo;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class ChatController {

    private final ChatClient chatClient;

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

    @GetMapping("/chat")
    public String chat(@RequestParam(defaultValue = "用一句话介绍自己") String message) {
        return chatClient.prompt()
                .user(message)
                .call()
                .content();
    }
}

代码讲解：

ChatClient.Builder 由 Spring AI 自动配置提供（原型 Bean），直接注入即可。
chatClient.prompt().user(message).call().content() 是最简捷的调用链：构建提示词 → 发送请求 → 获取响应文本。
省略了显式的 ChatModel 依赖——ChatClient 内部封装了模型调用细节。

6. 启动并测试

6.1 启动应用

mvn spring-boot:run

启动成功后会看到：

INFO ... Tomcat started on port(s): 8080 (http)
INFO ... Started DemoApplication in 2.5 seconds

6.2 发送请求

# 默认问候
curl "http://localhost:8080/chat"

# 自定义问题
curl "http://localhost:8080/chat?message=用Java写一个HelloWorld"

示例返回：

你好！我是通义千问（Qwen3），由阿里云开发的AI大语言模型，基于Spring AI框架驱动。

6.3 完整项目结构

spring-ai-quickstart/
├── pom.xml
└── src/
    └── main/
        ├── java/com/example/demo/
        │   ├── DemoApplication.java
        │   └── ChatController.java
        └── resources/
            └── application.yml

7. ChatClient 核心调用链

ChatClient 是 Spring AI 最核心的入口，提供流式 API。以下是常用的调用模式速览：

// 1. 最简调用
String response = chatClient.prompt().user("Hello").call().content();

// 2. 指定系统提示词
String response = chatClient.prompt()
        .system("你是一个精通Java的编程助手")
        .user("解释Spring Boot自动配置原理")
        .call()
        .content();

// 3. 流式输出
Flux<String> stream = chatClient.prompt()
        .user("写一首关于AI的诗")
        .stream()
        .content();

// 4. 结构化输出（映射到 POJO）
MyResponse result = chatClient.prompt()
        .user("列出5个Java设计模式")
        .call()
        .entity(MyResponse.class);

8. 自动配置原理

Spring AI Starter 会自动配置 ChatClient、ChatModel 及相关的 Bean，无需手动声明。

9. 常见问题

Q: 启动时报 Ollama 连接失败？

确认 Ollama 容器在运行：

docker ps | grep ollama
curl http://localhost:11434/api/tags

Q: 提示模型未找到？

在 Ollama 中拉取对应模型：

docker exec -it ollama ollama pull qwen3:8b

确保 application.yml 中 spring.ai.ollama.chat.options.model 与拉取的模型名称一致。

Q: 首次响应很慢？

Ollama 首次推理需要将模型加载到内存，后续请求会显著加速。如果内存不足（8B 模型建议 16GB+ RAM），可换用更小的模型如 qwen3:4b 或 llama3.2:3b。

Q: 如何切换到其他模型厂商？

替换 Starter 依赖即可，ChatClient API 保持不变：

DeepSeek
OpenAI

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-deepseek</artifactId>
</dependency>

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>

1. 环境要求​

2. 部署 Ollama​

2.1 拉取并启动 Ollama​

2.2 拉取模型​

2.3 验证模型​

3. 创建项目​

3.1 新建 Maven 项目​

3.2 编写 pom.xml​

4. 配置 Ollama 连接​

5. 编写第一个 AI 对话​

5.1 启动类​

5.2 ChatController​

6. 启动并测试​

6.1 启动应用​

6.2 发送请求​

6.3 完整项目结构​

7. ChatClient 核心调用链​

8. 自动配置原理​

9. 常见问题​