Java + AI 应用入门

用 Spring AI 和 Ollama 跑通第一个 Java 大模型应用

用 JDK 21 和 Spring AI 连接本地 Ollama,用 curl 与 ChatClient 对照两次真实回答,再排查模型名写错和服务未启动。

第一次把大模型接进 Java 应用,遇到报错时,很难马上判断是服务没起来、模型名配错,还是 Java 这边出了问题。我把这三处拆开测。先用 curl 问 Ollama,再让 Spring AI 的 ChatClient 问同一个问题。拿到回答后,再故意改错模型名、停掉服务,看两种错误在终端里长什么样。

用 完整 Maven 工程 跟跑。下文命令从解压后的 spring-ai-ollama-first-chat 目录执行,使用 Docker 和 Bash。模型和 Maven 依赖首次需要下载,实验调用在隔离网络里完成,不需要模型 API 密钥。原始实测日志

准备模型和 Maven 依赖

本轮用 CPU 跑 qwen3:0.6b。给 Ollama 准备一个独立的 Docker 卷,下载模型后停止下载容器。运行实验时再把这个卷挂回去,模型还在。 官方模型权重约 523 MB,本次用的 ARM64 镜像在 Docker 里约 7.2 GB。

docker pull ollama/ollama:0.40.16
docker pull maven:3.9.9-eclipse-temurin-21

docker volume create cxykk-ollama-04016-models
docker run -d --pull=never --name cxykk-ollama-04016-download --cpus 3 --memory 3g \
  --mount type=volume,source=cxykk-ollama-04016-models,target=/root/.ollama \
  ollama/ollama:0.40.16
docker exec cxykk-ollama-04016-download ollama pull qwen3:0.6b
docker exec cxykk-ollama-04016-download ollama list
docker rm -f cxykk-ollama-04016-download

project="$PWD"
cache="$project/.m2-lab"
mkdir -p "$cache"
docker run --rm --pull=never --cpus 3 --memory 2g \
  --mount "type=bind,source=$project,target=/work" \
  --mount "type=bind,source=$cache,target=/root/.m2" -w /work \
  maven:3.9.9-eclipse-temurin-21 mvn -B -ntp package

然后启动隔离实验。Maven 客户端放在内部网络里,Ollama 共享客户端的网络命名空间。这样客户端里的 127.0.0.1:11434 就是 Ollama,宿主机无需开放端口。先确认版本和模型都能查到,再开始请求。

network=cxykk-ollama-04016-private
client=cxykk-ollama-04016-client
server=cxykk-ollama-04016-server
jar=target/spring-ai-ollama-first-chat-1.0.0.jar

docker network create --internal "$network"
docker run -d --pull=never --name "$client" --network "$network" --cpus 3 --memory 2g \
  --mount "type=bind,source=$project,target=/work" \
  --mount "type=bind,source=$cache,target=/root/.m2" \
  -w /work maven:3.9.9-eclipse-temurin-21 sleep infinity
docker exec "$client" java -version
docker exec "$client" mvn -B -ntp -o package
docker run -d --pull=never --name "$server" --network "container:$client" --cpus 3 --memory 3g \
  --mount type=volume,source=cxykk-ollama-04016-models,target=/root/.ollama \
  ollama/ollama:0.40.16

for attempt in $(seq 1 30); do
  if docker exec "$client" curl --silent --fail http://127.0.0.1:11434/api/version; then
    printf '\n'
    break
  fi
  sleep 1
done
docker exec "$client" curl -fsS http://127.0.0.1:11434/api/tags

/api/version 返回 0.40.16,/api/tags 中应能看到 qwen3:0.6b。本次下载时容器访问模型 CDN 连续失败,改由宿主机从 Ollama 官方仓库下载相同的清单和模型文件,按清单逐个校验 SHA-256 后导入模型卷。镜像摘要、模型摘要和校验结果都保存在原始日志里。

先用 curl 拿到第一条回答

问题是「用一句中文解释 Java 中的线程池。」这里用 stream:false,让 Ollama 在一个 JSON 响应里返回回答。函数接收模型名,后面故意填错时还能用同一条请求。

ask_ollama() {
  local model="$1"
  local payload
  printf -v payload '{"model":"%s","messages":[{"role":"user","content":"用一句中文解释 Java 中的线程池。"}],"stream":false,"think":false,"options":{"temperature":0,"num_predict":160}}' "$model"
  docker exec "$client" curl --silent --show-error --fail-with-body --max-time 120 \
    --write-out '\nHTTP %{http_code}\n' -H 'Content-Type: application/json' \
    --data-binary "$payload" http://127.0.0.1:11434/api/chat
}
ask_ollama qwen3:0.6b

这次收到 HTTP 200。正文在 message.content,done 为 true,服务端还给出了本次生成的 token 数。

{"model":"qwen3:0.6b","created_at":"2026-11-15T13:06:15.913518386Z","message":{"role":"assistant","content":"线程池是 Java 中用于管理多线程资源的工具,它允许你创建一个可扩展的线程集合,用于执行任务,从而提高程序的效率和资源利用率。"},"done":true,"done_reason":"stop","total_duration":4138345543,"load_duration":776154083,"prompt_eval_count":27,"prompt_eval_cached_count":0,"prompt_eval_duration":252337000,"eval_count":41,"eval_duration":3107653000}
HTTP 200

让 ChatClient 问同一个问题

Spring Boot 通过 Ollama starter 装配模型客户端。程序启动时从 ChatClient.Builder 构建客户端,把同一个问题发给模型,然后把 content() 打印到终端。整个工程只有三份文件,可直接用上面下载的版本。

src/main/java/site/cxykk/ollama/FirstChat.java

package site.cxykk.ollama;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.boot.ApplicationRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;

@SpringBootApplication
public class FirstChat {
  private static final String QUESTION = "用一句中文解释 Java 中的线程池。";

  public static void main(String[] args) {
    SpringApplication.run(FirstChat.class, args).close();
  }

  @Bean
  ApplicationRunner askOnce(ChatClient.Builder builder) {
    return arguments -> {
      String answer = builder.build()
          .prompt().user(QUESTION)
          .call().content();
      if (answer == null || answer.isBlank()) {
        throw new IllegalStateException("Ollama returned no assistant text");
      }
      System.out.println(answer);
    };
  }
}
查看完整 pom.xml 和 application.properties

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>4.1.2</version>
    <relativePath/>
  </parent>

  <groupId>site.cxykk.examples</groupId>
  <artifactId>spring-ai-ollama-first-chat</artifactId>
  <version>1.0.0</version>

  <properties>
    <java.version>21</java.version>
    <spring-ai.version>2.0.2</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.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>

src/main/resources/application.properties

spring.main.web-application-type=none
spring.main.banner-mode=off
spring.main.log-startup-info=false
logging.level.root=ERROR

spring.ai.ollama.base-url=http://127.0.0.1:11434
spring.ai.ollama.init.pull-model-strategy=never
spring.ai.ollama.chat.model=qwen3:0.6b
spring.ai.ollama.chat.think=false
spring.ai.ollama.chat.temperature=0
spring.ai.ollama.chat.num-predict=160
spring.ai.retry.max-attempts=1

pull-model-strategy=never 让模型安装留在准备步骤。下面改错模型名时,Spring AI 会把这个名字交给 Ollama,服务端会直接报告找不到模型。实验将 spring.ai.retry.max-attempts 设为 1,方便直接看到第一次调用失败的报错。

docker exec "$client" java -jar "$jar"

JDK 21.0.7、Spring Boot 4.1.2 和 Spring AI 2.0.2 这次打印了下面这一行。curl 输出里有协议字段,Java 里只打印了回答正文。两次回答都在解释线程池,措辞有些不同。复跑时可以先确认两个入口都拿到了回复,再核对内容是否回答了原问题。

线程池是 Java 中用于管理多线程资源的工具,它通过将任务放入队列并等待执行,从而提高资源利用率和系统吞吐量。

模型名写错时先查模型列表

把模型改成故意拼错的 qwen3:typo-0.6b。服务照常运行,两个命令都会以非零状态退出。

ask_ollama qwen3:typo-0.6b
docker exec "$client" java -jar "$jar" --spring.ai.ollama.chat.model=qwen3:typo-0.6b

curl 保留了 Ollama 的 404 响应体。这里合并记录了标准输出和错误输出,JSON 和 curl 的报错可能挨在一行。

{"error":"model 'qwen3:typo-0.6b' not found"}curl: (22) The requested URL returned error: 404

HTTP 404

Java 异常链里的原始行也包含同一个模型名和响应体。

org.springframework.ai.retry.NonTransientAiException: HTTP 404 - {"error":"model 'qwen3:typo-0.6b' not found"}

遇到这个错误,先在同一个 Ollama 实例上查 /api/tags,把 Spring 配置或命令行覆盖项改成列表里的完整标签。模型还没下载时,把 ollama pull 放回准备步骤。

Ollama 没启动时先恢复服务

停止 Ollama,保留客户端容器,再访问原来的地址。这次模型名已经改回 qwen3:0.6b。

docker stop "$server"
ask_ollama qwen3:0.6b
docker exec "$client" java -jar "$jar"

curl 没收到 HTTP 响应,退出码是 7。下面的 HTTP 000 是 --write-out 打印的占位值。

curl: (7) Failed to connect to 127.0.0.1 port 11434 after 0 ms: Couldn't connect to server

HTTP 000

Java 这次走到了连接失败。完整异常栈在原始日志里。

org.springframework.web.client.ResourceAccessException: I/O error on POST request for "http://127.0.0.1:11434/api/chat": Connection refused: /127.0.0.1:11434

先用 docker start "$server" 恢复服务,再查一次 /api/version。版本接口通了之后重新运行 JAR。实验结束可删除容器和内部网络,模型卷留给下次使用。

docker rm -f "$server" "$client"
docker network rm "$network"

回到 Java + AI 入门目录 · 复习固定响应的 ChatClient 示例 · 继续做最小 RAG 实验