--- title: "Spring AIでSpring BootにAI機能を組み込む手順【2026年7月・2.0対応】" url: "https://www.issoh.co.jp/tech/details/2590/" published: 2024-06-17 updated: 2026-07-16 categories: ["Java"] publisher: "株式会社一創" --- # 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 AI | 対応するSpring Boot | 最新版(2026年7月) | 選ぶ場面 | | --------- | --------------- | -------------------- | -------------------- | | 2.0.x | 4.0.x / 4.1.x | 2.0.0（2026-06-12 GA） | 新規開発、Boot 4へ移行済みのアプリ | | 1.1.x | 3.4.x / 3.5.x | 1.1.8 | Boot 3系を当面維持する既存アプリ | | 1.0.x | 3.4.x / 3.5.x | 1.0.9 | 1.0系で稼働中の保守のみ | 判断は単純です。**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との違い](https://www.issoh.co.jp/tech/details/10124/)で変更点を確認し、移行とAI導入を分けて計画してください。Boot 3.5をいつまで維持できるかは[Spring Bootバージョン一覧とサポート期限](https://www.issoh.co.jp/tech/details/5172/)のEOL情報が判断材料になります。 ## pom.xmlへの依存関係の追加（BOMとスターター） Spring AIの依存関係は、BOMでバージョンを一元管理し、使うモデルのスターターだけを追加する形が標準です。スターター側にはバージョンを書きません。 ``` org.springframework.ai spring-ai-bom 2.0.0 pom import org.springframework.ai spring-ai-starter-model-openai ``` 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も同じ規則に従います。 | 旧アーティファクトID（1.0.0-M6まで） | 現行アーティファクトID | | --------------------------------------- | --------------------------------- | | spring-ai-openai-spring-boot-starter | spring-ai-starter-model-openai | | spring-ai-anthropic-spring-boot-starter | spring-ai-starter-model-anthropic | | spring-ai-ollama-spring-boot-starter | spring-ai-starter-model-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` を返します。 ``` @GetMapping(value = "/chat-stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE) public Flux chatStream(@RequestParam String message) { return chatClient.prompt().user(message).stream().content(); } ``` ストリーミングはリアクティブスタック側の理解が前提になるため、必要なら[Spring WebFluxとは何か：概要と基本的な特徴](https://www.issoh.co.jp/tech/details/3208/)で `Flux` の扱いを押さえてから着手すると手戻りがありません。画面側をReactで作るなら[Spring BootとReactを連携する方法](https://www.issoh.co.jp/tech/details/1542/)の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と設定を二度作り直しています。したがって「動かない」の原因はコードの書き間違いではなく、参照している情報の世代であることがほとんどです。エラーメッセージから原因を引くより、次の順に確認するほうが速く終わります。 | 症状 | 原因 | 対処 | | ------------------- | -------------------------- | ------------------------------ | | 依存解決に失敗 | 旧スターター名（M6で終了） | spring-ai-starter-model-openai | | NoSuchMethodError 等 | Boot 3.5 + Spring AI 2.0.0 | 1.1.8 へ下げる／Boot 4.1へ上げる | | 設定が効かない | プロパティの .options. | spring.ai.openai.chat.model | | コンパイルエラー | toolNames() が削除 | @Tool／ToolCallback で明示登録 | | コンパイルエラー | options() がビルダー受け取りに変更 | build() を外して渡す | 特に `@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年最新】](https://www.issoh.co.jp/tech/details/10124/) - [Spring Bootバージョン一覧とサポート期限【2026年7月】最新4.1と3.5 EOL後の選び方](https://www.issoh.co.jp/tech/details/5172/) - [Spring WebFluxとは何か：概要と基本的な特徴](https://www.issoh.co.jp/tech/details/3208/) - [【2026年版】Spring BootとReactを連携する方法｜REST API・CORS・JWT認証まで実装解説](https://www.issoh.co.jp/tech/details/1542/) --- 出典: [Spring AIでSpring BootにAI機能を組み込む手順【2026年7月・2.0対応】]()（株式会社一創）