Spring AIは、Spring BootアプリケーションからOpenAIやAnthropicなどの生成AIを呼び出すためのSpring公式フレームワークです。2026年10月26日時点の最新版は2.0.2(Maven Centralへの公開は2026年10月22日)で、Spring Boot 4.0/4.1が前提です。日本語の解説記事の多くは2024年〜2025年前半に書かれており、旧スターター名や1.x系のAPIをそのまま写すとビルドが通りません。ここではMaven Centralの公開履歴と公式のアップグレードノートに合わせて、依存関係・設定・ChatClientの実装・MCPサーバー化・1.xからの移行を、手を動かす順に整理します。
まとめ:Spring AIの最新バージョン2.0.2と導入の要点
- 新規に組むなら2.0.2:Spring AI 2.0.xはSpring Boot 4.0.x/4.1.xに対応します。1.0.xと1.1.xの無償(OSS)サポートは2026年6月30日で終わっており、Boot 3.5で1.1.8を使い続けると、以後のパッチは有償サポートでしか届きません。
- 依存関係はBOM+スターター1つ:
spring-ai-bomをimportし、spring-ai-starter-model-openaiを版指定なしで足します。Maven Central配布なので、マイルストーン用リポジトリは要りません。 - 旧スターター名は1.0.0-M6で止まっている:
spring-ai-openai-spring-boot-starterは2025年2月の公開が最後で、古い記事のpom.xmlは依存解決で失敗します。 - 2.0の設定は
.options.を外して書く:spring.ai.openai.chat.modelの形が正です。旧キーは置き換え先を示した非推奨のプロパティとして残っていますが、非推奨のため将来の版で外れる可能性があります。 - ツール呼び出しとMCPはChatClientに統合:
@Toolを渡せばToolCallingAdvisorが自動で往復を回します。@McpToolを付ければSpringのBeanをMCPサーバーとして公開できますが、HTTPの口は既定で認証がありません。
Spring AIの役割と2026年10月時点のバージョン
Spring AIは、生成AIとの通信をSpringのDI・自動構成に載せるフレームワークです。モデル・埋め込み・ベクトルストアに共通の抽象があるため、OpenAIで書いたコードを依存関係と設定の差し替えだけでAnthropicやローカルのOllamaへ向け直せます。
アプリケーションが直接触る4つの部品
- ChatClient:プロンプト送信と応答取得の入口。出揃うまで待つ
call()と逐次出力のstream()を持ちます。 - Advisor:会話履歴の付与、ツール呼び出しの往復、RAGの検索結果注入など、モデル呼び出しの前後に処理を挟む仕組みです。2.0ではツール実行のループもここに移りました。
- VectorStore:埋め込みの保存と類似検索の担当です。pgvector(PostgreSQL)やRedisなどを同じAPIで扱います。
- ToolCallback:在庫照会やDB検索など、モデルが知り得ない処理をモデルに呼ばせるための登録単位です。
リリース系統とOSSサポート期限
Spring公式のサポート表(spring.ioのプロジェクトAPI)とMaven Centralのspring-ai-bomの公開日を突き合わせると、2026年10月26日時点の状況は次のとおりです。
| 系統 | 最新(OSS) | 対応Spring Boot | OSSサポート終了 | 有償サポート終了 |
|---|---|---|---|---|
| 2.0.x | 2.0.2(2026-10-22) | 4.0.x / 4.1.x | 2027-07-31 | 2028-07-31 |
| 1.1.x | 1.1.8(2026-06-12) | 3.5.x | 2026-06-30(終了) | 2032-06-30 |
| 1.0.x | 1.0.9(2026-06-12) | 3.4.x / 3.5.x | 2026-06-30(終了) | 2027-06-30 |
表の日付はMaven Centralへの公開日で、公式ブログの告知は1日遅れることがあります(2.0.2は10月23日の告知)。1.1.8と1.0.9は2.0.0と同じ2026年6月12日に出たのが最後で、その後のOSS版はありません。2.0.0のGAでは内部のSpring BootとMCP Java SDKがそれぞれ4.1.0・2.0.0に上がり、2.0.2ではMCP Java SDKが2.1.0になっています。
次の2.1で変わる箇所(2.1.0-RC1時点)
2.1系は2026年9月24日に2.1.0-M1、10月22日に2.1.0-RC1がMaven Centralに出ています。GitHubのリリースノートによると、土台がSpring Boot 4.2に上がり、OpenAIのResponses APIへの対応、ツール実行前の確認(tool call confirmation)、会話履歴の新方式であるsession memoryが入りました。2.1.0-RC1の告知によると、ChatMemory・MessageChatMemoryAdvisor・JDBCなどの履歴リポジトリは非推奨になり、削除は3.0.0の予定です。会話IDのキーも MemoryAdvisor.CONVERSATION_ID(値は同じ)に移りました。2.1に上げてもすぐには壊れませんが、新しく作るなら3.0.0までにsession memoryへ移す前提で組んでください。GA日の発表はまだありませんが、GitHubの2.1.0マイルストーンの期限は2026年11月19日に設定されています。
Spring Bootとの版対応と、2.0/1.1の選び方
導入でつまずく原因の大半は、コードではなく版の組み合わせです。公式のGetting Startedは「Spring AI 2.0.x supports Spring Boot 4.0.x and 4.1.x」と明記しています。Spring Boot 3.5に2.0.xを載せる構成はサポート範囲外で、起動時の NoSuchMethodError や NoClassDefFoundError として表に出ます。
判断は次の順で決まります。
- 新規開発、またはBoot 4.0/4.1へ移行済み:2.0.2を使います。
- Boot 3.5のまま当面動かす既存アプリ:1.1.8が動く最後の版です。ただしSpring Boot 3.5自体も2026年6月25日の3.5.16が最後のOSSリリースと発表されており、無償の脆弱性修正はもう届きません。延命するなら有償サポート、そうでなければBoot 4への移行計画を先に立ててください。
- Boot 3.4以前:1.0.9までが対象です。新しくAI機能を足す土台としては選ばないでください。
Boot 4系の実行にはJava 17以上が必要です。Boot 4で何が変わるかはSpring Boot 4とは?最新バージョン4.1の変更点・新機能とSpring Boot 3との違い、各版の期限はSpring Bootバージョン一覧とサポート期限(EOL)で確認できます。移行とAI導入を同じスプリントに詰め込むと、どちらの不具合か切り分けられなくなるので、Boot 4への移行を先に終わらせてからSpring AIを足してください。
自分のプロジェクトが実際にどの版を引いているかは、Mavenなら mvn dependency:tree -Dincludes=org.springframework.ai、Gradleなら gradle dependencyInsight --dependency spring-ai で確かめられます。BOMの版とスターターの解決結果が食い違っていれば、別のBOMや親POMが版を上書きしています。
依存関係の書き方:spring-ai-bomとスターター1つ
Spring AIの依存関係は、BOMで版を一元管理し、使うモデルのスターターだけを足す形が標準です。スターター側には版を書きません。Mavenなら次のとおりです。
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-bom</artifactId>
<version>2.0.2</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では次の2行です。
implementation platform('org.springframework.ai:spring-ai-bom:2.0.2')
implementation 'org.springframework.ai:spring-ai-starter-model-openai'
新規プロジェクトなら、Spring InitializrでSpring Boot 4.1系を選び、依存関係から「OpenAI」を追加すればBOMとスターター入りの雛形が出ます。Spring Boot自体の最小構成はSpring Bootとは|4.1系の依存名の変更と最小Web APIの作り方が参考になります。2024年〜2025年前半の記事にある repo.spring.io/milestone の追加は、1.0.0-M4以前がMaven Centralに無かった頃の手順で、1.0.0-M5(2025年1月)以降は不要です。
旧スターター名と現行名の対応
古い記事のpom.xmlが最初に失敗するのはここです。Maven Centralの旧アーティファクトは1.0.0-M6(2025年2月14日)が最後で、以降の版は公開されていません。1.0.0-M7で「spring-ai-starter-model-プロバイダ名」の命名に統一されました。
| 旧アーティファクト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 |
Azure OpenAIを使っていた場合、2.0で spring-ai-starter-model-azure-openai を含むazure-openaiモジュールが削除されたため、spring-ai-openai へ移し、クラス名のAzure接頭辞と設定プロパティを書き換えます。
application.propertiesの必須キーとモデル指定
OpenAIを使う場合、必須なのはAPIキーだけです。モデル名は環境変数から渡す形にしておくと、モデルの世代交代のたびにビルドし直さずに済みます。
spring.ai.openai.api-key=${OPENAI_API_KEY}
spring.ai.openai.chat.model=${OPENAI_MODEL:gpt-5-mini}
${OPENAI_MODEL:gpt-5-mini} のようにコロンの後ろへ既定値を書いておかないと、環境変数が未設定のとき ${OPENAI_MODEL} という文字列がそのままモデル名として送られます。モデル名の行ごと省いた場合は、2.0.2の OpenAiChatOptions に定義された既定値 gpt-5-mini が使われます。OpenAIのモデルIDは数か月単位で世代が変わるので、指定するときはOpenAIの公式モデル一覧で現行のIDを確認してください。
.optionsの非推奨と、既定値の移動
2.0では設定キーから .options. の段が外れました。spring.ai.openai.chat.options.model や spring.ai.openai.embedding.options.model は1.1系までの書き方で、2.0では spring.ai.openai.chat.model、spring.ai.openai.embedding.model と書きます。公式のアップグレードノートは旧キーを「移行を滑らかにするための非推奨プロパティ」として残すと説明しており、2.0.2の自動構成のメタデータでも旧キーは置き換え先つきの非推奨です。そのため旧キーでもすぐには壊れません。ただし非推奨の扱いなので、上げたタイミングで書き換えてください。
もう1つの変更は既定値の置き場所です。モデル名やtemperatureの既定値は、Model実装や *Properties クラスからオプションのコンストラクタへ移されました。2.0.2のOpenAIでは temperature に既定値が入らず、指定しなければAPI側の既定で動きます。1.x時代の0.7を前提に応答のばらつきを調整していたなら明示が必要です。ただし公式のOpenAI Chatのページのとおり、gpt-5・gpt-5-mini・gpt-5-nanoなどGPT-5系の推論モデルはtemperatureを受け付けず、指定するとエラーになります。spring.ai.openai.chat.temperature を書くのは、gpt-5-chatなど対応するモデルを使うときだけにしてください。
APIキーの直書き禁止と環境変数・Secretからの注入
spring.ai.openai.api-key=sk-xxxx の直書きは、application.propertiesごとリポジトリとビルド成果物に入ります。環境変数を参照し、値はKubernetes SecretやAWS Secrets Managerから注入してください。Kubernetes Secretをファイルとしてマウントするなら、spring.config.import=optional:configtree:/etc/secrets/ でファイル名をプロパティ名として読み込めます。
ChatClientによる応答・履歴・ツール呼び出しの実装
依存関係と設定が入っていれば、自動構成が ChatClient.Builder をBeanとして用意します。コントローラに注入すれば数行で応答を返せます。
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 builder) {
this.chatClient = builder
.defaultSystem("あなたは社内システムのサポート担当です。簡潔に回答してください。")
.build();
}
@GetMapping("/chat")
public String chat(@RequestParam String message) {
return chatClient.prompt()
.user(message)
.call()
.content();
}
}
呼び出しごとにオプションを変えたいときは、2.0から options() にビルダーを渡します。1.xのように build() した ChatOptions を渡すとコンパイルが通りません。
import org.springframework.ai.openai.OpenAiChatOptions;
String reply = chatClient.prompt()
.user(message)
.options(OpenAiChatOptions.builder().model("gpt-5-nano"))
.call()
.content();
stream()とFluxによる逐次表示
call() は応答が出揃うまで待ちます。文字を流して表示したい場合は stream() に替えて Flux<String> を返します。
import org.springframework.http.MediaType;
import reactor.core.publisher.Flux;
@GetMapping(value = "/chat-stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public Flux<String> chatStream(@RequestParam String message) {
return chatClient.prompt().user(message).stream().content();
}
Fluxの扱いはSpring WebFluxとは?MVCとの違い・Mono/Fluxの基本とSpring Boot 4.1での使い方、画面をReactで作るときの接続はSpring BootとReactの連携方法が参考になります。
ChatMemoryによる会話履歴と会話IDの渡し方
ChatClientは単発の呼び出しでは前の発言を覚えていません。MessageChatMemoryAdvisor を登録し、会話IDは呼び出しのたびに ChatMemory.CONVERSATION_ID で渡します。2.0では会話IDが必須になり、ビルダーで既定のIDを固定する .conversationId() は削除されました(1.xのコードはコンパイルが通りません)。
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();
}
履歴をDBに保存する JdbcChatMemoryRepository を1.xから使っている場合、2.0ではテーブルに sequence_id 列が増えています。MySQLやMariaDBのTIMESTAMPは既定で秒単位のため、同じ秒に保存した発言の順序が入れ替わる問題への対処で、1.xで作った既存テーブルは列を足すまで動きません。前述のとおり ChatMemory は2.1で非推奨になり、3.0.0で削除される予定です。
@ToolとToolCallingAdvisorによるツール呼び出し
在庫照会や社内DB検索のように、モデルが知り得ない情報はツールとして渡します。メソッドに @Tool を付けたBeanを tools() に渡せば、モデルが必要と判断したときに実行されます。
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();
2.0では、各モデルの内部に埋め込まれていたツール実行のループが撤去され、ChatClientに自動登録される ToolCallingAdvisor が往復を回す形に変わりました。モデルの応答を1回ずつ検査してから実行したい場合は、AdvisorParams.toolCallingAdvisorAutoRegister(false) で自動登録を外し、ToolCallingManager で自分でループを回します。全体で外すなら spring.ai.chat.client.tool-calling.enabled=false です。
ツールが数十〜数百に増えると、全ツールの定義を毎回プロンプトに載せるだけでトークンを消費します。その場合は spring-ai-starter-tool-search-advisor を足して spring.ai.chat.client.tool-search-advisor.enabled=true を設定すると、ToolSearchToolCallingAdvisor が既定のToolCallingAdvisorに替わり、キーワード検索か意味検索で関連するツールだけを送るようになります。JSONで受け取る構造化出力の崩れには、スキーマで検証して失敗時に呼び直す StructuredOutputValidationAdvisor が同じAdvisorの仕組みで用意されています。
@McpToolによるMCPサーバー化とトランスポートの選び方
MCP(Model Context Protocol)は、Claude DesktopやIDEのAIエージェントなどの外部クライアントに、自社のツールやデータを標準の形で渡すためのプロトコルです。Spring AI 2.0ではMCPのアノテーションがコアに取り込まれ、既存のSpringサービスに @McpTool を付けるだけでMCPサーバーの機能として公開できます。依存関係は spring-ai-starter-mcp-server-webmvc(WebFluxなら -webflux)です。1.x時代にコミュニティ版のアノテーションを使っていた場合は、パッケージが org.springaicommunity.mcp.annotation から org.springframework.ai.mcp.annotation に変わっています。
@Component
public class OrderTools {
private final OrderService orderService;
public OrderTools(OrderService orderService) {
this.orderService = orderService;
}
@McpTool(name = "order-status", description = "注文番号から出荷状況を返す")
public String orderStatus(
@McpToolParam(description = "注文番号", required = true) String orderNo) {
return orderService.status(orderNo);
}
}
spring.ai.mcp.server.name=order-mcp
spring.ai.mcp.server.protocol=STREAMABLE
エンドポイントは既定で /mcp です。2.0ではStreamable HTTPが既定なので、protocolの行は省いても同じ動作になります。
MCP Server Boot Starterの公式ドキュメントでは、SSEは「2.0.0で非推奨、STREAMABLEを使う」とされています。スケールアウトする構成なら STATELESS、同じマシンのプロセス連携なら spring-ai-starter-mcp-server と spring.ai.mcp.server.stdio=true を選びます。2.0.0が準拠するのはMCP仕様の2025-11-25版で、その後に出た2026-07-28版との差はMCP仕様2026-07-28版とは:ステートレス化の変更点と2025-11-25版からの移行手順で解説しています。
HTTPのMCPサーバーの既定は認証なし:Spring Securityでの保護
同じ公式ドキュメントは、HTTP系のトランスポート(SSE・Streamable-HTTP・Stateless)は既定で認証の無いJSON-RPCの口を開け、スターターは認証も認可もかけないと明記しています。到達できるクライアントなら、登録した全ツールの一覧取得と実行ができる状態です。社内の注文DBや在庫DBをツールにしたまま社内ネットワークへ出すと、それだけで情報の出口になります。localhost以外へ公開する前に、Spring Securityでエンドポイントを保護するか、APIゲートウェイの背後に置いてください。フィルタの組み方はSecurityFilterChainとは?Spring Securityのフィルタ実行順序と設定例が土台になります。
1.xから2.0への移行で止まる箇所
Spring AIは1.0.0のGA(2025年5月)と2.0.0のGA(2026年6月)で、公開APIと設定を二度作り直しています。「動かない」の原因はたいてい書き間違いではなく、参照している情報の世代です。症状から原因と対処を次の表で引けます。
| 症状 | 原因 | 対処 |
|---|---|---|
| 依存解決に失敗 | 旧スターター名 | spring-ai-starter-model-openai |
| NoSuchMethodError など | Boot 3.5+Spring AI 2.0 | Boot 4.1へ上げる |
| Azureのスターターが無い | azure-openai削除 | spring-ai-openaiへ移す |
| toolNames() が無い | 名前解決の廃止 | @Tool/ToolCallbackで登録 |
| options() が型エラー | ビルダー受け取りに変更 | build() を外して渡す |
| JDBC履歴の取得で失敗 | sequence_id列の追加 | 既存テーブルに列を足す |
| ChatModel直呼びでツールが動かない | 内部ループの撤去 | ChatClient経由にする |
| Bean登録だけのツールが呼ばれない | フォールバック既定無効(2.0.1) | tools()で渡す |
| 会話IDなしで例外 | 会話IDが必須に | CONVERSATION_IDを渡す |
特に、Function のBeanに名前を付けて登録し、名前でツールを解決させる2025年前半の書き方は、SpringBeanToolCallbackResolver と toolNames() ごと削除されました。当時のRAG・ツール呼び出しのサンプルはほぼ動かないと考え、@Tool か FunctionToolCallback による明示登録に書き換えます。
Jackson 3の非チェック例外化とcatch句の点検
Spring AI 2.0はBoot 4に合わせてJSON処理がJackson 3になりました。Jacksonの移行ガイドによると、グループIDとパッケージは com.fasterxml.jackson から tools.jackson になりました。例外の基底クラスも、2.xの JsonProcessingException(IOException を継承)から、3.xの JacksonException(RuntimeException を継承)に変わっています。catch (IOException e) でJSONの失敗を拾っていた箇所は、tryの中がJackson呼び出しだけならコンパイルエラーで気づけます。危ないのはファイル読み込みなど IOException を投げる処理と同じtryに入っている場合で、コンパイルは通ったままJSONの失敗だけがcatchを素通りし、上位に抜けます。パッケージの置換はOpenRewriteのJackson 2→3レシピで機械化できますが、catch句の意味の変化は手で探すしかありません。
Boot 3系からの移行順序(4段階)
Boot 3系のアプリにSpring AI 2.0を入れるときは、次の順に1段ずつ進めます。
- Spring Boot 3.5に上げ、非推奨警告をすべて消す(3.5で非推奨のAPIは4.0で消える)
- Spring Boot 4.1に上げ、テストを通す(必要なら非推奨の
spring-boot-jackson2でJackson 2を一時的に併用) - Jackson 2から3へ移し、catch句を点検する
- Spring AIのBOMを2.0.2にし、スターター名・設定キー・ツール登録を書き換える
Spring AIとLangChain4jの選び分け
JavaでLLMを組む選択肢は、Spring AIとLangChain4j(Maven Centralの最新は2026年10月7日公開の1.22.0)の2つが中心です。決め手は、Spring Bootの資産があるかどうかです。
| 観点 | Spring AI 2.0 | LangChain4j |
|---|---|---|
| 前提スタック | Spring Boot 4.0/4.1 | 素のJava・Quarkus・Spring Boot |
| 設定の流儀 | 自動構成+properties | コードで部品を組む |
| サポート | Spring公式・有償延長あり | OSSコミュニティ |
Spring Bootで動いている業務システムにAI機能を足すなら、DI・設定・監視の流儀がそのまま使えるSpring AIを選んでください。Quarkusや素のJavaで書く、あるいはBoot 4必須の縛りを受け入れられないならLangChain4jが合います。Boot 3.5から動けない既存システムに、いまから1.1.8で新規のAI機能を作り込むのは避けるべきです。無償の修正が止まった版の上に新しいコードを積むことになるためです。
業務システムへの生成AIの組み込みを、設計から外部に任せたい場合は生成AI開発・AI受託開発でも相談を受けています。
よくある質問
Spring AIとは何ですか?
Spring公式の、生成AIアプリケーション向けフレームワークです。OpenAI・Anthropic・Ollamaなどのモデル、埋め込み、ベクトルストアに共通の抽象とSpring Bootの自動構成を提供し、モデルごとのSDKを直接書かずにAI機能を組み込めます。2026年10月26日時点の最新版は2.0.2です。
Spring AIの最新バージョンはいくつですか?
正式版の最新は2026年10月22日公開の2.0.2です。同じ日に次期版の2.1.0-RC1も出ています。1.1系の最終は1.1.8、1.0系は1.0.9で、どちらも2026年6月30日にOSSサポートを終えています。
Spring AI 2.0はSpring Boot 3で使えますか?
使えません。2.0.xの対応はSpring Boot 4.0.xと4.1.xです。Boot 3.5のままなら1.1.8が動く最後の版ですが、無償の修正はもう出ないため、Boot 4への移行を先に計画してください。
pom.xmlにSpring AIのバージョンを書く必要はありますか?
スターター側には書きません。spring-ai-bom をdependencyManagementでimportし、そこで2.0.2などの版を一元管理します。スターターはartifactIdだけを指定します。
application.propertiesには何を設定すればよいですか?
最低限は spring.ai.openai.api-key だけです。モデルを指定するなら spring.ai.openai.chat.model、temperatureに対応するモデル(gpt-5-chatなど)なら spring.ai.openai.chat.temperature も足せますが、GPT-5系の推論モデルでは指定するとエラーになります。2.0では .options. を含まない形で書きます。
OpenAI以外のモデルも使えますか?
使えます。Anthropic、Google GenAI、Amazon Bedrock、Mistral AI、DeepSeek、ローカル実行のOllamaなどに対応しており、スターター(spring-ai-starter-model-anthropic など)と接続設定を差し替えます。ChatClientを使った側のコードはほぼそのまま流用できます。