Spring AIでSpring BootにAI機能を組み込む手順【2026年7月・2.0対応】

Spring AIは、Spring BootアプリケーションからOpenAIなどの生成AIを呼び出すためのSpring公式フレームワークです。2026年6月12日に2.0.0がGAとなり、Spring Boot 4系が前提になりました。一方で、Web上に残る解説記事の多くは2024年〜2025年前半の内容で、当時の依存関係や設定をそのまま写しても現在のプロジェクトではビルドが通りません。ここでは2026年7月時点の公式ドキュメントとMaven Centralの実体に合わせて、依存関係の書き方、application.propertiesの設定、ChatClientの実装、そして2.0と1.1のどちらを選ぶかの判断基準を整理します。

まとめ

• バージョン選定が最初の分岐点：Spring AI 2.0.x は Spring Boot 4.0.x／4.1.x、1.1.x は Spring Boot 3.4.x／3.5.x に対応する。Boot 3.5のまま2.0.0を入れる構成は成立しない。
• 依存関係はBOM＋スターター1つ：spring-ai-bom をdependencyManagementに取り込み、spring-ai-starter-model-openai をバージョン指定なしで追加する。Maven Centralで配布されており、マイルストーン用リポジトリの追加は不要。
• 旧スターター名は死んでいる：spring-ai-openai-spring-boot-starter は 1.0.0-M6（2025年2月14日）が最終公開で、以降のバージョンは存在しない。古い記事のpom.xmlを写すと依存解決に失敗する。
• 設定プロパティから .options. が消えた：2.0では spring.ai.openai.chat.model のようにフラット化され、temperatureのデフォルト値も廃止された（必要なら明示指定する）。
• 実装の入口はChatClient：chatClient.prompt().user(...).call().content() の数行でAI応答を得られる。会話履歴・ツール呼び出し・ストリーミングはAdvisorと stream() で段階的に足す。

Spring AIの役割と2026年7月時点のバージョン状況

Spring AIは、生成AIモデルとの通信をSpringのプログラミングモデル（DI・自動構成・Bean）に載せるためのフレームワークです。単なるHTTPクライアントのラッパーではなく、モデル・ベクトルストア・埋め込みといったAI要素に共通の抽象を与え、実装を差し替えられるようにする点が中心的な役割です。OpenAIで組んだコードを、依存関係と設定の変更だけでAnthropicやOllamaへ向け直せるのはこの抽象があるためです。

アプリケーションが直接触る4つのコンポーネント

• ChatClient：プロンプト送信と応答取得の入口。応答が出揃うまで待つ call() と、逐次出力の stream() を持つ。
• Advisor：会話履歴の付与、ツール呼び出し、RAGの検索結果注入など、モデル呼び出しの前後に処理を差し込む仕組み。
• VectorStore：埋め込みベクトルの保存と類似検索。PostgreSQL(pgvector)やRedisなどの実装を同一APIで扱う。RAGを組む際の土台になる。
• ToolCallback：モデルに呼び出させる自作処理の登録。在庫照会やDB検索など、モデルが知り得ない情報の取得を委譲する。

リリース状況と現役バージョンの見分け

2026年7月時点で公式がstableとして並べているのは 2.0.0、1.1.8、1.0.9 の3系統です。2.0.0は2026年6月12日にGAとなり、内部でSpring Boot 4.1.0とMCP SDK 2.0.0に追随しました。OpenAIモジュールは2.0.0-M5以降、公式の openai-java SDKを内部利用する構成に変わっています。

新規に組むなら2.0.0が既定の選択です。ただし後述のとおりSpring Bootのバージョンと連動するため、既存アプリへ後付けする場合はそちらの制約が先に来ます。

Spring AIとSpring Bootのバージョン対応（最初に決めること）

Spring AIの導入でつまずく原因の大半は、コードではなくバージョンの組み合わせです。公式のGetting Startedは「Spring AI 2.0.xはSpring Boot 4.0.xと4.1.xをサポートする」と明記しており、1.1系のドキュメントは「Spring Boot 3.4.xと3.5.xをサポートする」と書き分けています。つまりSpring AIのメジャーバージョンはSpring Bootの世代とセットで決まります。

判断は単純です。Spring Boot 4.1へ上げられるなら2.0.0、上げられないなら1.1.8。稼働中のBoot 3.5アプリに2.0.0を組み合わせる構成は公式のサポート範囲外で、NoSuchMethodError や NoClassDefFoundError といった形で破綻します。ここを飛ばして「最新版だから」と2.0.0を選ぶと、AI機能の前にフレームワークの移行作業が始まります。なおSpring AI 2.0はSpring Boot 4系に載るため、実行環境はJava 17以上が前提です。Boot 4への移行そのものが未着手なら、Spring Boot 4とは？最新バージョン4.1の変更点・新機能とSpring Boot 3との違いで変更点を確認し、移行とAI導入を分けて計画してください。Boot 3.5をいつまで維持できるかはSpring Bootバージョン一覧とサポート期限のEOL情報が判断材料になります。

pom.xmlへの依存関係の追加（BOMとスターター）

Spring AIの依存関係は、BOMでバージョンを一元管理し、使うモデルのスターターだけを追加する形が標準です。スターター側にはバージョンを書きません。

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.springframework.ai</groupId>
      <artifactId>spring-ai-bom</artifactId>
      <version>2.0.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

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

Gradleであれば implementation platform('org.springframework.ai:spring-ai-bom:2.0.0') と implementation 'org.springframework.ai:spring-ai-starter-model-openai' の2行です。Spring Boot 3系で組むなら、BOMのバージョンを 1.1.8 に置き換えます。新規プロジェクトなら Spring Initializr（start.spring.io）の依存関係で「OpenAI」を選ぶと、BOMとスターターが入った状態で雛形が生成されます。

マイルストーンリポジトリ設定が不要になった理由

2024年〜2025年前半の解説記事は、repo.spring.io/milestone をrepositoriesに追加する手順を載せています。当時のSpring AIが正式リリース前でMaven Centralに無かったためです。1.0.0のGA以降はMaven Centralから取得できるため、この記述は不要です。残っていても害はありませんが、社内プロキシやミラー環境では余計な到達性の問題を持ち込むだけなので削っておくのが無難です。

1.0.0-M7でのスターター名変更と旧名の終端

古い記事のpom.xmlをそのまま使うと、まずここで失敗します。Maven Centralの実体を見ると、旧名の spring-ai-openai-spring-boot-starter は 1.0.0-M6（2025年2月14日公開）が最後で、その後のバージョンは一切公開されていません。現行名は spring-ai-starter-model-openai です。命名は「spring-ai-starter-model-プロバイダ名」に統一されており、AnthropicやOllamaも同じ規則に従います。

application.propertiesの設定とAPIキーの扱い

OpenAIを使う場合、最低限必要なのはAPIキーだけです。モデル名やtemperatureは任意ですが、2.0では既定のtemperatureが設定されなくなったため、以前の挙動（0.7）を前提にしているなら明示してください。

spring.ai.openai.api-key=${OPENAI_API_KEY}
spring.ai.openai.chat.model=gpt-5.6-luna
spring.ai.openai.chat.temperature=0.7

プロパティ名で注意すべき点が2つあります。ひとつは、2.0で .options. のセグメントが廃止されたことです。spring.ai.openai.chat.options.model や spring.ai.openai.embedding.options.model と書いている記事は1.1以前の記法で、2.0では spring.ai.openai.chat.model のようにフラットに書きます。もうひとつは、モデル名がOpenAI APIへそのまま渡る文字列だという点です。GPTのモデルIDは更新が速く（2026年7月時点の最新世代は gpt-5.6-sol ／ gpt-5.6-terra ／ gpt-5.6-luna）、記事に書かれたIDが数か月後には旧世代になります。実装時はOpenAIの公式モデル一覧で現行IDを確認してください。

APIキーの管理（環境変数とシークレットストア）

解説記事の多くは spring.ai.openai.api-key=sk-xxxx と直書きしますが、application.propertiesはビルド成果物に含まれ、リポジトリにも入ります。上記の例のように環境変数を参照し、実際の値はデプロイ環境のシークレット管理（Kubernetes Secret、AWS Secrets Manager、Spring Cloud Config等）から注入する形にしてください。OpenAIのキーは流出すれば即座に課金へ直結するため、ここは利便性と引き換えにしてよい箇所ではありません。

ChatClientでAI機能を実装する

依存関係と設定が入っていれば、自動構成が ChatClient.Builder をBeanとして用意します。コントローラにインジェクトして、数行でAI応答を返せます。

import org.springframework.ai.chat.client.ChatClient;

@RestController
public class ChatController {

    private final ChatClient chatClient;

    public ChatController(ChatClient.Builder builder) {
        this.chatClient = builder
                .defaultSystem("あなたは社内システムのサポート担当です。簡潔に回答してください。")
                .build();
    }

    @GetMapping("/chat")
    public String chat(@RequestParam String message) {
        return chatClient.prompt()
                .user(message)
                .call()
                .content();
    }
}

call() は応答が出揃うまでブロックします。ChatGPTのように文字が流れる挙動にしたい場合は stream() に替え、Flux<String> を返します。

@GetMapping(value = "/chat-stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public Flux<String> chatStream(@RequestParam String message) {
    return chatClient.prompt().user(message).stream().content();
}

ストリーミングはリアクティブスタック側の理解が前提になるため、必要ならSpring WebFluxとは何か：概要と基本的な特徴で Flux の扱いを押さえてから着手すると手戻りがありません。画面側をReactで作るならSpring BootとReactを連携する方法のCORS・認証まわりの実装が接続部分の参考になります。なお ChatClient のAPIはKotlinからもそのまま呼べるため、Spring Boot 4のKotlinプロジェクトでも追加設定なくAI機能を組み込めます。

会話履歴の付与（ChatMemoryとconversationId）

ChatClientは単発の呼び出しでは前の発言を覚えていません。履歴を持たせるには MessageChatMemoryAdvisor をビルダーに登録し、会話IDは呼び出しのたびに渡します。ChatMemory は自動構成された MessageWindowChatMemory のBeanをそのままインジェクトできます。2.0では conversationId() をビルダーへ固定する書き方が廃止され、呼び出し時の指定が必須になりました（複数ユーザーの履歴が混ざる事故を防ぐための変更です）。

import org.springframework.ai.chat.client.advisor.MessageChatMemoryAdvisor;
import org.springframework.ai.chat.memory.ChatMemory;

public ChatController(ChatClient.Builder builder, ChatMemory chatMemory) {
    this.chatClient = builder
            .defaultAdvisors(MessageChatMemoryAdvisor.builder(chatMemory).build())
            .build();
}

public String chat(String message, String sessionId) {
    return chatClient.prompt()
            .user(message)
            .advisors(a -> a.param(ChatMemory.CONVERSATION_ID, sessionId))
            .call()
            .content();
}

ツール呼び出し（@Toolによる自作処理の委譲）

在庫照会や社内DB検索など、モデルが知り得ない情報を扱うにはツール呼び出しを使います。メソッドに @Tool を付けたクラスを tools() に渡せば、モデルが必要と判断したときに実行されます。DIした処理を呼ぶ場合はBeanとして登録し、コントローラ側でインジェクトして渡します。2.0ではツール呼び出し用のAdvisorが自動登録されるようになり、明示的な advisors(ToolCallingAdvisor...) の記述は不要になりました。

import org.springframework.ai.tool.annotation.Tool;
import org.springframework.ai.tool.annotation.ToolParam;

@Component
class StockTools {

    private final InventoryService inventoryService;

    StockTools(InventoryService inventoryService) {
        this.inventoryService = inventoryService;
    }

    @Tool(description = "商品コードから在庫数を返す")
    int stockCount(@ToolParam(description = "商品コード") String itemCode) {
        return inventoryService.count(itemCode);
    }
}

// 呼び出し側（StockTools をインジェクト済み）
String reply = chatClient.prompt()
        .user("商品A-100の在庫は？")
        .tools(stockTools)
        .call()
        .content();

旧記事のコードが動かない理由と、移行時の確認箇所

Spring AIは1.0.0のGA（2025年5月）と2.0.0のGA（2026年6月）で、公開APIと設定を二度作り直しています。したがって「動かない」の原因はコードの書き間違いではなく、参照している情報の世代であることがほとんどです。エラーメッセージから原因を引くより、次の順に確認するほうが速く終わります。

特に @Bean に @Description を付けて Function を登録し、名前でツールを解決させる書き方は、2.0で SpringBeanToolCallbackResolver ごと削除されました。2025年前半のRAG・ツール呼び出しの記事はこの形が主流だったため、当時のサンプルはほぼ全滅と考えてください。移行するなら FunctionToolCallback または @Tool による明示登録に書き換えます。

逆に言えば、Spring AIの記事を読むときは公開日ではなくコード内のアーティファクトIDを見るのが最短の判別法です。spring-ai-openai-spring-boot-starter と書かれていれば2025年2月以前の情報、.options. 付きのプロパティが出てくれば1.1系までの情報だと判断できます。

よくある質問

Spring AIとは何ですか

Spring公式のAIアプリケーション向けフレームワークです。OpenAIなどの生成AIモデル、ベクトルストア、埋め込みへの共通の抽象とSpring Bootの自動構成を提供し、モデルごとのSDKを直接書かずにAI機能を組み込めるようにします。2026年7月時点の最新版は2.0.0です。

Spring AIは2.0と1.1のどちらを使うべきですか

使っているSpring Bootのバージョンで決まります。Spring Boot 4.0／4.1なら2.0.0、Spring Boot 3.4／3.5なら1.1.8です。Boot 3系のまま2.0.0を入れることはできないため、AI機能の追加とBoot 4への移行は別のタスクとして計画してください。

pom.xmlにSpring AIのバージョンを書く必要はありますか

スターター側には書きません。spring-ai-bom をdependencyManagementでimportし、そこでバージョン（2.0.0など）を一元管理します。スターターは artifactId だけを指定すれば、BOMが解決します。

application.propertiesには何を設定すればよいですか

最低限は spring.ai.openai.api-key だけです。モデルを指定するなら spring.ai.openai.chat.model、応答のばらつきを制御するなら spring.ai.openai.chat.temperature を追加します。2.0ではプロパティ名から .options. が外れ、temperatureのデフォルト値も設定されなくなった点に注意してください。

OpenAI以外のモデルも使えますか

使えます。Anthropic、Google GenAI、Mistral、ローカル実行のOllamaなどに対応しており、スターター（spring-ai-starter-model-anthropic 等）と接続設定を差し替えます。ChatClientを使ったアプリケーション側のコードは、モデルを変えてもほぼそのまま流用できます。

RAGやベクトルストアも扱えますか

扱えます。VectorStore の抽象を通じてpgvector（PostgreSQL）やRedisなどに埋め込みを保存し、Advisorで検索結果をプロンプトへ注入する形でRAGを構成します。ベクトルストアもスターター単位で追加するため、実装を差し替えてもアプリケーション側のコードはほぼ変わりません。

関連記事

• Spring Boot 4とは？最新バージョン4.1の変更点・新機能とSpring Boot 3との違いを解説【2026年最新】
• Spring Bootバージョン一覧とサポート期限【2026年7月】最新4.1と3.5 EOL後の選び方
• Spring WebFluxとは何か：概要と基本的な特徴
• 【2026年版】Spring BootとReactを連携する方法｜REST API・CORS・JWT認証まで実装解説