アップグレードノート

2.0.0 へのアップグレード

このセクションでは、Spring AI 1.1.x から 2.0.0 へのアップグレード時に発生するすべての互換性のない変更点と移行手順について説明します。

アドバイザー

spring-ai-advisors-vector-store が spring-ai-vector-store-advisor に名称変更されました

spring-ai-advisors-vector-store モジュールは、他の Spring AI モジュールの命名規則との整合性を高めるため、spring-ai-vector-store-advisor に名称変更されました。

ToolSearchToolCallingAdvisor が spring-ai-tool-search-advisor に移動しました

ToolSearchToolCallingAdvisor クラスは専用のモジュールとパッケージに移動されました。

  • 成果物 : spring-ai-tool-search-advisor (previously bundled in spring-ai-tool-search-tool)

  • パッケージ : org.springframework.ai.chat.client.advisor.toolsearch (previously org.springframework.ai.tool.toolsearch.advisor)

依存関係とインポートに関する記述を適宜更新してください。

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-tool-search-advisor</artifactId>
</dependency>

新規: ToolSearchToolCallingAdvisor 自動構成およびスターター

Spring Boot 自動構成（spring-ai-autoconfigure-tool-search-advisor）とそれに対応するスターター（spring-ai-starter-tool-search-advisor）が利用可能になりました。ToolSearchToolCallingAdvisor を有効にすると、自動構成の ChatClient 内のデフォルトの ToolCallingAdvisor が置き換えられ、呼び出しごとに LLM に送信されるツール定義が、最も関連性の高いもの（キーワード検索または意味検索による）のみに制限されます。

スターターを追加してプロパティを設定することでオプトインできます。

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-tool-search-advisor</artifactId>
</dependency>
spring.ai.chat.client.tool-search-advisor.enabled=true

# Choose the index type: regex (default), lucene, or vector
spring.ai.chat.client.tool-search-advisor.tool-index-type=regex

regex インデックスには追加の依存関係は必要ありません。lucene インデックスにはクラスパス上に org.apache.lucene:lucene-core が必要です。vector インデックスにはクラスパス上に VectorStore Bean（spring-ai-vector-store）が必要です。

変更: Advisor.DEFAULT_CHAT_MEMORY_PRECEDENCE_ORDER のデフォルト値

Advisor.DEFAULT_CHAT_MEMORY_PRECEDENCE_ORDER は Ordered.HIGHEST_PRECEDENCE + 1000 から Ordered.HIGHEST_PRECEDENCE + 200 に変更され、メモリアドバイザーを ToolCallingAdvisor （HIGHEST_PRECEDENCE + 300）の外側のデフォルトの順序で配置しました。

ToolCallingAdvisor は、デフォルトでツール呼び出しの反復処理全体にわたって会話履歴を内部的に管理するようになりました。メモリアドバイザーは最終的なユーザー / アシスタント間のやり取りのみを保存し、ツール呼び出しメッセージを ChatMemoryRepository に書き込むことはありません。これは、ほとんどのリポジトリ実装がこれらのメッセージ型をサポートしていないため、正しいデフォルト設定です。

ループ内でメモリが必要な場合（たとえば InMemoryChatMemoryRepository を使用する場合）、アドバイザーの順序を明示的に ToolCallingAdvisor.DEFAULT_ORDER より上に設定し、.disableInternalConversationHistory() を呼び出します。

var toolCallingAdvisor = ToolCallingAdvisor.builder()
    .disableInternalConversationHistory()
    .build();
var chatMemoryAdvisor = MessageChatMemoryAdvisor.builder(chatMemory)
    .advisorOrder(Ordered.HIGHEST_PRECEDENCE + 400)
    .build();
The spring-ai-session [GitHub] (英語) community project provides a session-aware memory implementation that fully supports tool-call messages and can be safely used inside the tool-call loop with any backend. It is planned to replace ChatMemory in Spring AI 2.1. See the spring-ai-session documentation (英語) for details.

ツール呼び出し

除去: ToolCallingChatOptions からの internalToolExecutionEnabled 

internalToolExecutionEnabled オプションは、ToolCallingChatOptions およびすべてのプロバイダ固有の ChatOptions クラス (例: OpenAiChatOptions、AnthropicChatOptions) から削除されました。対応する Spring Boot 構成プロパティ spring.ai.<provider>.chat.internal-tool-execution-enabled も削除されました。

インパクト

.internalToolExecutionEnabled(false) を設定してユーザー制御ツール実行を有効にするコードはコンパイルされなくなります。.internalToolExecutionEnabled(true) を設定するコード（内部ループを明示的に有効にするコード）もコンパイルされなくなり、そのコードが提案していた動作はもはや存在しません。モデルごとの内部ツール実行は、すべての ChatModel 実装から削除されました。

マイグレーション

.internalToolExecutionEnabled(…​) へのすべての呼び出しを削除してください。推奨される方法は以下のとおりです。

  • ToolCallingAdvisor via ChatClient (推奨) — ツールが存在する場合は自動的に登録されます。フラグは不要です。

  • User-controlled loop via ChatModel directly — ToolCallingAdvisor を使用せずに ChatModel を呼び出すだけで済みます。ツール呼び出しは自動的に実行されません。chatResponse.hasToolCalls() を自分で確認し、ToolCallingManager でループを駆動してください。

// Before
ChatOptions options = ToolCallingChatOptions.builder()
    .toolCallbacks(ToolCallbacks.from(new MyTools()))
    .internalToolExecutionEnabled(false)   // <-- remove this line
    .build();

// After
ChatOptions options = ToolCallingChatOptions.builder()
    .toolCallbacks(ToolCallbacks.from(new MyTools()))
    .build();

除去: ToolExecutionEligibilityPredicate および DefaultToolExecutionEligibilityPredicate

ToolExecutionEligibilityPredicate （2.0.0 以降非推奨）とそのデフォルト実装である DefaultToolExecutionEligibilityPredicate は削除されました。これらのインターフェースは、オプションベースのポリシーチェック（internalToolExecutionEnabled）とレスポンスチェック（hasToolCalls()）を組み合わせたものでした。オプションベースのフラグがなくなったため、ChatModel レベルでの代替機能はありません。

マイグレーション

ツール実行のタイミングをカスタマイズするために ToolExecutionEligibilityPredicate を実装した場合は、ToolExecutionEligibilityChecker に移行し (下記参照)、ToolCallingAdvisor に提供してください。

新規: ToolExecutionEligibilityChecker の ToolCallingAdvisor

ToolExecutionEligibilityChecker (Function<ChatResponse, Boolean>) は、ツール呼び出しループの反復タイミングをカスタマイズするために、ToolCallingAdvisor.Builder に設定できるようになりました。デフォルトは chatResponse → chatResponse != null && chatResponse.hasToolCalls() です。

これは、プロバイダ固有の停止理由ロジック（ツール呼び出しの有無に加えて終了理由を確認するなど）の拡張ポイントです。

ToolCallingAdvisor advisor = ToolCallingAdvisor.builder()
    .toolExecutionEligibilityChecker(response ->
        response != null && response.hasToolCalls()
            && !"stop".equals(response.getResult().getMetadata().getFinishReason()))
    .build();

Spring Boot ユーザーは ToolExecutionEligibilityChecker Bean を提供できます。これは自動構成された ToolCallingAdvisor.Builder によって自動的に取得されます。

@Bean
ToolExecutionEligibilityChecker myChecker() {
    return response -> response != null && response.hasToolCalls();
}

新規: spring.ai.chat.client.tool-calling.enabled プロパティ

新しいプロパティ spring.ai.chat.client.tool-calling.enabled （デフォルトは true）は、自動構成された ChatClient によって ToolCallingAdvisor が自動登録されるかどうかを制御します。これを false に設定すると、すべての呼び出しでツールの自動実行が無効になります。ツールは定義として AI モデルに送信されますが、ツール呼び出しのレスポンスは自動的に実行されません。

spring.ai.chat.client.tool-calling.enabled=false

これは、個々の呼び出しごとに AdvisorParams.toolCallingAdvisorAutoRegister(false) を使用する代わりに、グローバルな代替手段を提供するものです。

除去: Advisor Builders と自動構成による streamToolCallResponses 

streamToolCallResponses オプションは、ToolCallingAdvisor.Builder、ToolCallAdvisor.Builder、ToolSearchToolCallingAdvisor.Builder および対応する Spring Boot 自動構成プロパティから削除されました。

  • spring.ai.chat.client.tool-calling.stream-tool-call-responses

  • spring.ai.chat.client.tool-search-advisor.stream-tool-call-responses

なぜでしょうか

streamToolCallResponses=true の場合、中間ツール呼び出しリクエストチャンクは下流にストリーミングされていましたが、対応する ToolResponseMessage (LLM に返送されるもの) はストリーミングされていませんでした。これらのチャンクを記録した下流のメモリアドバイザは、対応するツールレスポンスのないツール呼び出しリクエストを受け取り、会話履歴が破損していました。この設計上の欠陥は、ChatClientResponse に互換性のない変更を導入しない限り修正できないため、このオプションは完全に削除されました。

インパクト

  • アドバイザービルダー上で .streamToolCallResponses(true) または .streamToolCallResponses(false) を呼び出すコードは、コンパイルに失敗します。

  • 削除されたプロパティに関する application.properties または application.yml のエントリは、すべて無視されます。

マイグレーション

ビルダーチェーンから .streamToolCallResponses(…​) への呼び出しをすべて削除してください。

// Before
var advisor = ToolCallingAdvisor.builder()
    .streamToolCallResponses(true)   // <-- remove this line
    .build();

// After
var advisor = ToolCallingAdvisor.builder().build();

ツール呼び出しループの各反復を可視化するには（これは streamToolCallResponses=true が対処することを意図したユースケースです）、自動登録されたアドバイザーを無効にして、AdvisorParams.toolCallingAdvisorAutoRegister(false) を使用してループを手動で実行します。

ToolCallingManager toolCallingManager = ToolCallingManager.builder().build();
ToolCallback[] tools = ToolCallbacks.from(new WeatherTools());
ChatOptions chatOptions = ToolCallingChatOptions.builder()
    .toolCallbacks(tools)
    .build();

String question = "What is the weather in Amsterdam and Paris?";
Prompt prompt = new Prompt(List.of(new UserMessage(question)), chatOptions);

ChatClientResponse response = chatClient.prompt()
    .user(question)
    .options(chatOptions)
    .advisors(AdvisorParams.toolCallingAdvisorAutoRegister(false))
    .call()
    .chatClientResponse();

while (response.chatResponse() != null && response.chatResponse().hasToolCalls()) {
    // inspect or forward the tool-call chunk here before executing
    ToolExecutionResult result = toolCallingManager.executeToolCalls(prompt, response.chatResponse());
    prompt = new Prompt(result.conversationHistory(), chatOptions);
    response = chatClient.prompt()
        .messages(result.conversationHistory())
        .options(chatOptions)
        .advisors(AdvisorParams.toolCallingAdvisorAutoRegister(false))
        .call()
        .chatClientResponse();
}
// forward or process the final answer here

ストリーミングパスを含む完全な例については、ユーザー制御ツールの実行 — ChatClient 付を参照してください。

JDBC チャットメモリ sequence_id 列

JdbcChatMemoryRepository スキーマでは、会話内のメッセージの順序を決定する sequence_id BIGINT 列が追加されます。以前は、順序は timestamp 列に依存していましたが、TIMESTAMP の精度はデータベースによって異なり、MySQL と MariaDB ではデフォルトの精度が 1 秒であるため、同じ秒内に保存されたメッセージは非決定的な順序で返されていました。専用の整数シーケンスを使用することで、サポートされているすべてのデータベースで同じ順序でメッセージが処理されます。

timestamp 列は保持されます。この列にはメッセージの作成時刻が格納され、JdbcChatMemoryRepository.CONVERSATION_TS キー（java.time.Instant）のメッセージメタデータに公開されるため、アプリケーションはメッセージの作成日時を表示できます。タイムスタンプは保存後も保持されます。会話を再保存しても、既存の各メッセージの元の作成時刻が保持されます。

インパクト

  • SPRING_AI_CHAT_MEMORY テーブルには、sequence_id 列（Oracle では BIGINT または NUMBER(19)、SQLite では INTEGER）と SPRING_AI_CHAT_MEMORY_CONVERSATION_ID_SEQUENCE_ID_IDX インデックスが追加されます。timestamp 列とそのインデックスは変更されません。

  • Spring AI 1.x によって作成された既存のテーブルは、メッセージが sequence_id で順序付けられるようになったため、機能するには新しい列が必要です。

  • リポジトリから読み取られたメッセージには、メタデータに作成日時が記録されるようになりました。メタデータが異なるため、取得したメッセージは、コード内で作成された同一のメッセージと等しくありません（Message.equals）。値によってメッセージを比較するコード、またはセットやマップ内でメッセージの同一性に依存するコードは、この点を考慮する必要があります。

マイグレーション

変化は加算的である: 新しい列を追加し、既存の会話ごとの順序からバックフィルします。データは失われず、timestamp 列は変更されません。PostgreSQL の場合:

ALTER TABLE SPRING_AI_CHAT_MEMORY ADD COLUMN sequence_id BIGINT;

WITH ordered AS (
    SELECT ctid, ROW_NUMBER() OVER (PARTITION BY conversation_id ORDER BY "timestamp") - 1 AS seq
    FROM SPRING_AI_CHAT_MEMORY
)
UPDATE SPRING_AI_CHAT_MEMORY t
SET sequence_id = o.seq
FROM ordered o
WHERE t.ctid = o.ctid;

ALTER TABLE SPRING_AI_CHAT_MEMORY ALTER COLUMN sequence_id SET NOT NULL;

CREATE INDEX SPRING_AI_CHAT_MEMORY_CONVERSATION_ID_SEQUENCE_ID_IDX
ON SPRING_AI_CHAT_MEMORY(conversation_id, sequence_id);

識別子の引用と行識別子式（上記の ctid）を、ご使用のデータベースに合わせて調整してください。ROW_NUMBER() OVER (PARTITION BY conversation_id ORDER BY <timestamp>) パターンは、サポートされているすべてのエンジンで、既存の会話ごとの順序を再現します。あるいは、チャットメモリには永続的な履歴ではなく、最近の会話のコンテキストが保持されるため、更新された schema-<platform>.sql スクリプトからテーブルを削除して再作成することもできます。

オプションの不変性とデフォルト値

オプションの厳密な不変性

オプションクラス（ChatOptions、EmbeddingOptions など）は、完全に不変になりました。オプション内のコレクション（toolCallbacks、stopSequences、customHeaders など）は、変更不可能なコレクションとして格納されます。さらに、値がない状態をより適切に表現するために、空のコレクションの代わりに null 許容コレクションが使用されるようになりました。

インパクト

  • オプションが完全に不変になったため、ChatOptions#copy() および *Options#fromOptions(*Options) メソッドは削除されました。

  • オプション getter によって返されるコレクションを変更すると、UnsupportedOperationException がスローされます。

マイグレーション

オプションインスタンスの変更されたコピーを作成するには、copy() または fromOptions() の代わりに mutate() メソッドを使用します。

// Before
OllamaChatOptions options = originalOptions.copy();
options.setFoo("...");

// After
OllamaChatOptions options = originalOptions.mutate()
        .foo("...")
        .build();

デフォルト値がオプションコンストラクターに移動されました

オプションのデフォルト値（デフォルトのモデル名、温度など）は、Model の実装および *Properties の設定クラスから、オプションのコンストラクター自体に移動されました。*Properties クラスのデフォルト設定プロパティは不要になったため削除され、オプションレベルのデフォルト値と整合性が取れるようになりました。

インパクト

  • ChatModel#getDefaultOptions() は ChatModel#getOptions() を推奨して非推奨になりました。

  • *Properties クラスでは、デフォルト値が重複して使用されることはなくなりました。

マイグレーション

モデルのデフォルトオプションを取得する際は、getDefaultOptions() ではなく getOptions() を使用してください。

// Before
ChatOptions options = chatModel.getDefaultOptions();

// After
ChatOptions options = chatModel.getOptions();

構成プロパティのフラット化

上記で説明したチャット設定の変更に基づき、その他のすべてのモデル（埋め込み、イメージ、音声、モデレーション、OCR など）の設定プロパティでは、.options プレフィックスは使用されなくなりました。例: 以前の spring.ai.openai.embedding.options.model は、spring.ai.openai.embedding.model に変更されました。.options バリアントには、よりスムーズな移行を実現するために、非推奨の設定プロパティが提供されています。

インパクト

  • *Properties クラスの getOptions() メソッドは非推奨です。

  • *Properties 内にネストされた Options クラスは非推奨です。

  • toOptions() メソッドは、ネストされた Options クラスからルートクラスである *Properties クラスに移動されました。

マイグレーション

application.properties または application.yml を更新して、プロパティキーから .options セグメントを削除してください。

# Before
spring.ai.openai.embedding.options.model=text-embedding-3-small

# After
spring.ai.openai.embedding.model=text-embedding-3-small

Java コードでは、ルートプロパティクラスを直接使用してオプションにアクセスするか、toOptions() を呼び出します。

// Before
String model = properties.getOptions().getModel();
OpenAiEmbeddingOptions options = properties.getOptions().toOptions();

// After
String model = properties.getModel();
OpenAiEmbeddingOptions options = properties.toOptions();

オプションビルダーで N() を n() に名称変更しました

様々な *Options クラスおよび構成プロパティクラス内の N() ビルダーメソッドは、Java の命名規則に合わせるため、n() に名称変更されました。

インパクト

  • これらのビルダー上で .N(value) を呼び出す Java コードは、コンパイルに失敗します。

マイグレーション

コードを更新して、代わりに .n(value) を呼び出すようにしてください。

// Before
OpenAiChatOptions.builder().N(1).build();

// After
OpenAiChatOptions.builder().n(1).build();

Ollama

名前変更: spring.ai.ollama.chat.think-option から spring.ai.ollama.chat.think

spring.ai.ollama.chat.think-option 構成プロパティは spring.ai.ollama.chat.think に名称変更されました。

application.properties または application.yml を適切にアップデートしてください。

# Before
spring.ai.ollama.chat.think-option=true

# After
spring.ai.ollama.chat.think=true

Minimax 専用サポートは Anthropic サポートに置き換えられました

Minimax 専用サポートは、Minimax themselves (英語) の推奨に従い、Anthropic サポートを使用するように変更されました。代わりに、https://api.minimax.io/anthropic ベース URL と MiniMax モデルを使用して、Spring AI Anthropic サポートをご利用ください。埋め込み機能はサポートされなくなりました。

JSON ユーティリティリファクタリング

新規: JsonHelper とアップデートされた JacksonUtils

spring-ai-commons では、JSON の直列化と逆直列化を実行するための標準的な方法として、新しい JsonHelper クラスが導入されました。このクラスはインスタンス化可能で、カスタムの JsonMapper を受け入れるため、ユースケースごとに JSON の動作を簡単にカスタマイズできます。JacksonUtils には、共有の事前設定済み JsonMapper インスタンスを返す新しい静的メソッド getDefaultJsonMapper() が追加されました。

JsonHelper は、これまで JsonParser、ModelOptionsUtils、McpJsonParser に分散していた JSON 操作を一元化します。デフォルトのコンストラクターは、JacksonUtils.getDefaultJsonMapper() の共有マッパーを使用します。異なるシリアライゼーション設定が必要な場合は、カスタムの JsonMapper を挿入してください。

// Default — uses the shared JsonMapper from JacksonUtils
JsonHelper jsonHelper = new JsonHelper();

// Custom — supply your own JsonMapper
JsonMapper myMapper = JsonMapper.builder()
    .addModule(new JavaTimeModule())
    .build();
JsonHelper customHelper = new JsonHelper(myMapper);

非推奨: JsonParser

JsonParser （org.springframework.ai.util.json 内）は非推奨となり、削除予定です。すべてのメソッドは JsonHelper に処理を委譲するようになりました。

インパクト

JsonParser メソッドを呼び出すコードは、コンパイル時に非推奨警告が表示されます。

マイグレーション
前 後

JsonParser.getJsonMapper()

JacksonUtils.getDefaultJsonMapper()

JsonParser.fromJson(json, MyType.class)

jsonHelper.fromJson(json, MyType.class)

JsonParser.fromJson(json, type)

jsonHelper.fromJson(json, type)

JsonParser.toJson(object)

jsonHelper.toJson(object)

JsonParser.toTypedObject(value, type)

jsonHelper.convertToTypedObject(value, type)

除去: ModelOptionsUtils の JSON メソッド

モデルオプションが Jackson に直接依存しなくなったため、ModelOptionsUtils の以下のメンバーが削除されました。

メンバーを削除しました 置換文字列

ModelOptionsUtils.JSON_MAPPER

JacksonUtils.getDefaultJsonMapper()

ModelOptionsUtils.jsonToMap(String)

jsonHelper.fromJsonToMap(json)

ModelOptionsUtils.jsonToObject(String, Class<T>)

jsonHelper.fromJson(json, type)

ModelOptionsUtils.toJsonString(Object)

jsonHelper.toJson(object)

ModelOptionsUtils.toJsonStringPrettyPrinter(Object)

JacksonUtils.getDefaultJsonMapper().writerWithDefaultPrettyPrinter().writeValueAsString(object)

ModelOptionsUtils.getJsonSchema(Type, boolean)

JsonSchemaUtils.getJsonSchema(type, toUpperCase)

ModelOptionsUtils.getJsonSchema(Type)

JsonSchemaUtils.getJsonSchema(type)

ModelOptionsUtils.toUpperCaseTypeValues(ObjectNode)

JsonSchemaUtils.toUpperCaseTypeValues(node)

インパクト

削除されたフィールドまたはメソッドを参照するコードは、コンパイルエラーになります。

マイグレーション 
// Before
import org.springframework.ai.model.ModelOptionsUtils;

Map<String, Object> map = ModelOptionsUtils.jsonToMap(jsonString);
String json = ModelOptionsUtils.toJsonString(myObject);
JsonMapper mapper = ModelOptionsUtils.JSON_MAPPER;

// After
import org.springframework.ai.util.JsonHelper;
import org.springframework.ai.util.JacksonUtils;

private static final JsonHelper jsonHelper = new JsonHelper();

Map<String, Object> map = jsonHelper.fromJsonToMap(jsonString);
String json = jsonHelper.toJson(myObject);
JsonMapper mapper = JacksonUtils.getDefaultJsonMapper();

除去: McpJsonParser

McpJsonParser （org.springframework.ai.mcp.annotation.method.tool.utils 内）は削除されました。その機能は現在、JsonHelper によって代替されています。

マイグレーション
前 後

McpJsonParser.toMap(object)

jsonHelper.convertToMap(object)

McpJsonParser.fromMap(map, MyType.class)

jsonHelper.convertFromMap(map, MyType.class)

McpJsonParser.fromMap(map, typeReference)

jsonHelper.convertFromMap(map, parameterizedTypeReference)

MCP 誘発 API: TypeReference は ParameterizedTypeReference に置き換えられました

以前は McpAsyncRequestContext および McpSyncRequestContext で tools.jackson.core.type.TypeReference<T> を受け入れていた elicit(…​) オーバーロードは、現在 org.springframework.core.ParameterizedTypeReference<T> を受け入れるようになりました。

インパクト

これらのメソッドを Jackson TypeReference で呼び出すコードはコンパイルに失敗します。

影響を受けるメソッドのシグネチャー:

  • McpAsyncRequestContext.elicit(TypeReference<T>)

  • McpAsyncRequestContext.elicit(Consumer<ElicitationSpec>, TypeReference<T>)

  • McpSyncRequestContext.elicit(TypeReference<T>)

  • McpSyncRequestContext.elicit(Consumer<ElicitationSpec>, TypeReference<T>)

マイグレーション

Jackson TypeReference 匿名クラスを Spring ParameterizedTypeReference 匿名クラスに置き換えてください。

// Before
import tools.jackson.core.type.TypeReference;

Mono<StructuredElicitResult<Map<String, Object>>> result =
    context.elicit(e -> e.message("Please fill in the form"),
        new TypeReference<Map<String, Object>>() {});

// After
import org.springframework.core.ParameterizedTypeReference;

Mono<StructuredElicitResult<Map<String, Object>>> result =
    context.elicit(e -> e.message("Please fill in the form"),
        new ParameterizedTypeReference<Map<String, Object>>() {});

McpSyncRequestContext にも同じ変更が適用されます。

// Before
StructuredElicitResult<Person> result =
    context.elicit(e -> e.message("Provide your details"),
        new TypeReference<Person>() {});

// After
StructuredElicitResult<Person> result =
    context.elicit(e -> e.message("Provide your details"),
        new ParameterizedTypeReference<Person>() {});

Google GenAI 埋め込み: GoogleGenAiEmbeddingConnectionDetails パッケージの変更

GoogleGenAiEmbeddingConnectionDetails は org.springframework.ai.google.genai から org.springframework.ai.google.genai.embedding に移動されました。

インパクト

GoogleGenAiEmbeddingConnectionDetails を直接インポートするコードは、コンパイルエラーになります。

マイグレーション

インポート文を更新します。

// Before
import org.springframework.ai.google.genai.GoogleGenAiEmbeddingConnectionDetails;

// After
import org.springframework.ai.google.genai.embedding.GoogleGenAiEmbeddingConnectionDetails;

ChatClient ツール呼び出し

自動 ToolCallingAdvisor 登録

ChatClient は、明示的に無効にしない限り、アドバイザーチェーンに ToolCallingAdvisor を常に自動登録するようになりました。そのため、モデルによってリクエストされたツール呼び出しは、ツールが静的に構成されているか、実行時に別のアドバイザーによって注入されたかに関わらず、自動的に処理されます。

インパクト

すでに ToolCallingAdvisor を明示的に追加している既存のコードでは、アドバイザーがチェーンに 2 回存在することになります。1 回は明示的な追加によるもので、もう 1 回は自動登録によるものです。

マイグレーション

チェーンから明示的な ToolCallingAdvisor を削除し、自動登録に任せましょう。カスタム構成が必要な場合は、ChatClient 構築時に事前構成済みの ToolCallingAdvisor.Builder を指定するか ( デフォルトの ToolCallingAdvisor をカスタマイズするのセクションを参照)、自動登録を無効にしてアドバイザーを手動で登録してください。

// Before — manual registration
chatClient.prompt("What's the weather?")
    .tools(weatherTool)
    .advisors(ToolCallingAdvisor.builder().build())
    .call().content();

// After — auto-registration handles it; no explicit advisor needed
chatClient.prompt("What's the weather?")
    .tools(weatherTool)
    .call().content();

// Or, to keep full control, disable auto-registration explicitly
chatClient.prompt("What's the weather?")
    .tools(weatherTool)
    .advisors(
        AdvisorParams.toolCallingAdvisorAutoRegister(false),
        ToolCallingAdvisor.builder().build()
    )
    .call().content();

新規: ToolAdvisor マーカーインターフェース

ToolAdvisor マーカーインターフェースが追加されました。ToolCallingAdvisor はこのインターフェースを実装しています。DefaultChatClient はこのマーカーをチェックして、ToolCallingAdvisor を自動登録するかどうかを決定します。チェーン内のいずれかのアドバイザーがすでに ToolAdvisor を実装している場合は、自動登録はスキップされます。

ツール呼び出しのライフサイクルを管理するカスタムアドバイザーは、ToolCallingAdvisor が重複して自動的に追加されないように、ToolAdvisor を実装する必要があります。

新規: MemoryAdvisor マーカーインターフェース

MemoryAdvisor マーカーインターフェースが追加されました。BaseChatMemoryAdvisor はこのインターフェースを継承します。DefaultChatClient はこのマーカーを使用して下流のメモリアドバイザーを検出し、存在する場合は ` ToolCallingAdvisor の内部会話履歴を無効にします。

BaseChatMemoryAdvisor を継承しないが、ツール呼び出しの自動登録ロジックと統合する必要があるカスタムメモリアドバイザーは、MemoryAdvisor を実装する必要があります。

新規: カスタム ToolCallingAdvisor 構成のための ChatClient.builder() オーバーロード

新しい 5 引数 ChatClient.builder() 静的メソッドと、それに対応する DefaultChatClientBuilder コンストラクターは、自動登録中に使用されるアドバイザーを設定するために ToolCallingAdvisor.Builder<?> を受け取ります。

ChatClient chatClient = ChatClient
    .builder(chatModel, observationRegistry, null, null,
            ToolCallingAdvisor.builder().toolCallingManager(myToolCallingManager))
    .build();

Spring Boot ユーザーは、代わりに以下のいずれかを選択してください。

  • spring.ai.chat.client.tool-calling.advisor-order を設定して、チェーンにおけるアドバイザーの位置を制御します。

  • 自動構成されたビルダーを完全に置き換えるために、ToolCallingAdvisor.Builder<?> Bean を宣言します (@ConditionalOnMissingBean によって抑制されます)。

除去: ChatClient 上の ToolSpec コンシューマー API

tools(Consumer<ToolSpec>) / defaultTools(Consumer<ToolSpec>) API および ChatClient.ToolSpec インターフェースは削除されました。tools(Object…​) / defaultTools(Object…​) メソッドは、ToolCallback、ToolCallbackProvider、@Tool アノテーションが付与された POJO インスタンス、およびこれらの型のコレクションまたは配列を直接受け入れるようになりました。コンテキストは、専用の toolContext() / defaultToolContext() メソッドを使用して別途設定されます。

マイグレーション 
// Before
chatClient.prompt()
    .tools(t -> t.callbacks(myCallback).context("tenantId", "acme"))
    .call().content();

// After
chatClient.prompt()
    .tools(myCallback)
    .toolContext(Map.of("tenantId", "acme"))
    .call().content();

ChatClientRequestSpec 上の toolCallbacks() メソッドと ChatClient.Builder 上の defaultToolCallbacks() メソッドは、tools(Object…​) / defaultTools(Object…​) に置き換えられたため、非推奨となりました。

変更: MethodToolCallbackProvider は IllegalStateException の代わりに IllegalArgumentException をスローする

MethodToolCallbackProvider は、以下の 2 つのケースで IllegalArgumentException (IllegalStateException の代わりに) をスローするようになりました。

  • ツールオブジェクトに @Tool アノテーション付きメソッドがない場合。

  • 複数のツールオブジェクトが、重複する名前のコールバックを生成する場合。

インパクト

MethodToolCallbackProvider から IllegalStateException を捕捉するコード（直接または ToolCallbacks.from() 経由）を更新する必要があります。

// Before
try {
    ToolCallbacks.from(myObject);
}
catch (IllegalStateException e) { ... }

// After
try {
    ToolCallbacks.from(myObject);
}
catch (IllegalArgumentException e) { ... }

除去: Spring Bean ツールの解決 (SpringBeanToolCallbackResolver)

SpringBeanToolCallbackResolver と、裸の Function / Supplier / Consumer Bean を宣言し、toolNames() を介して名前で参照するパターンは削除されました。toolNames() メソッドは、すべてのチャットオプションクラスと ChatClient から削除されました。

マイグレーション

生の関数型ビーンではなく、ToolCallback ビーンを直接宣言します。

// Before — bare Function bean resolved by name at runtime
@Bean
@Description("Get the weather in location")
Function<WeatherRequest, WeatherResponse> currentWeather() {
    return weatherService::getWeather;
}

// After — explicit ToolCallback bean
@Bean
ToolCallback currentWeather() {
    return FunctionToolCallback.builder("currentWeather", weatherService::getWeather)
        .description("Get the weather in location")
        .inputType(WeatherRequest.class)
        .build();
}

次に、Bean を tools() に直接登録します。

chatClient.prompt("What's the weather like in Copenhagen?")
    .tools(currentWeather)
    .call().content();

あるいは、宣言的なアプローチには、@Tool アノテーション付きメソッドを使用してください（Tools API を参照）。

クラウドバインディング

github.com/spring-cloud/spring-cloud-bindings (英語) との統合機能を提供していた spring-ai-spring-cloud-bindings モジュールは削除されました。

BeanOutputConverter JSON スキーマ生成

BeanOutputConverter は JSON スキーマの生成を JsonSchemaGenerator に委譲するようになり、構造化出力の変換がツール呼び出しに使用される JSON スキーマの動作と一致するようになりました。

インパクト

  • プライマリコンストラクターでオプションである（null 許容またはデフォルト値で宣言されている）Kotlin プロパティは、JSON スキーマ required 配列に含まれなくなりました。

  • @JsonProperty(required = false) でアノテーションが付けられたプロパティ（required が指定されていない @JsonProperty 宣言を含む）は、必須プロパティとして扱われなくなりました。

  • 生成されるスキーマには、ツール呼び出しで使用されるフォーマット規則に一致する、プリミティブ型に対する OpenAPI スタイルの format ヒント (例: int の場合は int32、long の場合は int64、LocalDateTime の場合は date-time ) が含まれるようになりました。

  • BeanOutputConverter.postProcessSchema(JsonNode) 拡張ポイントは削除されました。このメソッドをオーバーライドするカスタムサブクラスはコンパイルエラーになります。

マイグレーション

JSON スキーマの生成をカスタマイズするには、代わりに BeanOutputConverter.generateSchema() をオーバーライドしてください。サブクラスは、super.generateSchema() に処理を委譲することで、デフォルトのスキーマを後処理できます。

// Before
class CustomConverter extends BeanOutputConverter<MyType> {

    CustomConverter() {
        super(MyType.class);
    }

    @Override
    protected void postProcessSchema(JsonNode schema) {
        // mutate schema
    }
}

// After
class CustomConverter extends BeanOutputConverter<MyType> {

    CustomConverter() {
        super(MyType.class);
    }

    @Override
    protected String generateSchema() {
        String schema = super.generateSchema();
        // post-process schema
        return schema;
    }
}

Azure Cosmos DB サポート

Azure Cosmos DB ベクトルストア（spring-ai-azure-cosmos-db-store）およびチャットメモリリポジトリ（spring-ai-model-chat-memory-repository-cosmos-db）モジュールは、対応する自動構成とスターターとともに、Spring AI プロジェクトから削除されました。

Azure Cosmos DB のサポートが、Azure Cosmos DB チームによって保守される外部モジュールとして利用可能になりました。ドキュメントと依存関係については、azurecosmosdb.github.io/spring-ai/docs/index.html (英語) を参照してください。

MCP SDK の互換性のない変更点: 必須フィールド

MCP SDK は、コンパクトレコードコンストラクターにおいて、Assert.notNull() を介して、これまでオプションであったフィールドを構築時に必須フィールドとして強制します。

速報: CreateMessageResult — model が必要になりました 

// Before
CreateMessageResult.builder()
    .content(new TextContent(response))
    .build();

// After
CreateMessageResult.builder(Role.ASSISTANT, response, modelHint)
    .build();

速報: CreateMessageRequest — maxTokens が必要になりました 

// Before
CreateMessageRequest.builder()
    .messages(messages)
    .build();

// After
CreateMessageRequest.builder(messages, 500)
    .build();

非推奨のビルダー API

以下の引数なしコンストラクターおよび builder() メソッドは非推奨となり、代わりに必須引数を事前に必要とするファクトリメソッドが推奨されます。

非推奨 置換文字列

new TextContent(text)

TextContent.builder(text).build()

new ReadResourceResult(contents)

ReadResourceResult.builder(contents).build()

new GetPromptResult(description, messages)

GetPromptResult.builder(messages).description(description).build()

new ProgressNotification(token, progress, total, message)

ProgressNotification.builder(token, progress).total(total).message(message).build()

LoggingMessageNotification.builder()

LoggingMessageNotification.builder(level, data)

ElicitRequest.builder()

ElicitRequest.builder(message, requestedSchema)

CallToolRequest.builder()

CallToolRequest.builder(name)

可観測性

ツール呼び出し

ツール呼び出し操作に関して生成された観測値は、以下のように変更されました。

  • span 名は tool_call <tool-name> ではなく execute_tool <tool-name> です。

  • メトリクス / スパン属性 gen_ai.operation.name の値は、framework ではなく execute_tool です。

  • ツール型（例: function）をキャプチャーするための新しい spring.ai.tool.type メトリクス / スパン属性が導入されました。

  • チャットモデルによって識別されるツール呼び出し ID をキャプチャーするために、新しい spring.ai.tool.call.id スパン属性が導入されました。

削除されたモジュール

spring-ai-hanadb-store モジュールの取り外し

spring-ai-hanadb-store モジュールは Spring AI から削除されました。

チャットメモリアドバイザー: 会話 ID が必須になりました

組み込みメモリアドバイザー（MessageChatMemoryAdvisor および VectorStoreChatMemoryAdvisor）では、会話 ID は必須となりました。これらのアドバイザーを介したすべての呼び出しにおいて、アドバイザーコンテキストを介して ChatMemory.CONVERSATION_ID を指定する必要があります。値が指定されていない場合、または null が指定されている場合は、アドバイザーは直ちに IllegalArgumentException 例外をスローします。

除去: ChatMemory.DEFAULT_CONVERSATION_ID

定数 ChatMemory.DEFAULT_CONVERSATION_ID （値 "default"）は、ChatMemory インターフェースから削除されました。

インパクト

この定数を参照するコードはコンパイルエラーになります。

マイグレーション

ChatMemory.DEFAULT_CONVERSATION_ID への参照はすべて、明示的な会話 ID 文字列、またはセッション / ユーザーコンテキストから取得した値に置き換えてください。

// Before
String conversationId = ChatMemory.DEFAULT_CONVERSATION_ID;

// After
String conversationId = "my-conversation-id";

除去: メモリアドバイザーにおける .conversationId() ビルダーメソッド

.conversationId(String) ビルダーメソッドは、MessageChatMemoryAdvisor.Builder および VectorStoreChatMemoryAdvisor.Builder から削除されました。構築時にデフォルトの会話 ID を設定する機能はサポートされなくなりました。

インパクト

これらのビルダーのいずれかで .conversationId() を呼び出すコードはコンパイルに失敗します。

マイグレーション

.conversationId() ビルダー呼び出しを削除し、ChatMemory.CONVERSATION_ID を使用してアドバイザーコンテキストを介して呼び出し時に常に会話 ID を提供するようにしてください。

// Before
ChatClient chatClient = ChatClient.builder(chatModel)
    .defaultAdvisors(MessageChatMemoryAdvisor.builder(chatMemory)
        .conversationId("my-session")
        .build())
    .build();

chatClient.prompt()
    .user("Hello!")
    .call()
    .content();

// After
ChatClient chatClient = ChatClient.builder(chatModel)
    .defaultAdvisors(MessageChatMemoryAdvisor.builder(chatMemory).build())
    .build();

chatClient.prompt()
    .user("Hello!")
    .advisors(a -> a.param(ChatMemory.CONVERSATION_ID, "my-session"))
    .call()
    .content();

変更: BaseChatMemoryAdvisor.getConversationId() 署名

デフォルトのメソッド BaseChatMemoryAdvisor.getConversationId(Map, String) は getConversationId(Map) に置き換えられました。

インパクト

2 引数形式をオーバーライドまたは呼び出すカスタムアドバイザー実装は、コンパイルに失敗します。

マイグレーション

オーバーライドと呼び出し箇所を単一引数形式に更新してください。メソッドを呼び出す前に、コンテキストに必ず ChatMemory.CONVERSATION_ID が含まれていることを確認してください。

// Before
String conversationId = getConversationId(context, this.defaultConversationId);

// After
String conversationId = getConversationId(context); // throws if CONVERSATION_ID is absent

除去: PromptChatMemoryAdvisor

PromptChatMemoryAdvisor は削除されました。代わりに MessageChatMemoryAdvisor を使用してください。

インパクト

PromptChatMemoryAdvisor をインポートまたは参照するコードはコンパイルに失敗します。

マイグレーション

PromptChatMemoryAdvisor を MessageChatMemoryAdvisor に置き換えてください。ビルダー API は同じです。MessageChatMemoryAdvisor は、メモリをプレーンテキストとしてシステムプロンプトに挿入する代わりに、会話履歴をチャットメッセージとしてプロンプトに直接含めます。

// Before
ChatClient chatClient = ChatClient.builder(chatModel)
    .defaultAdvisors(PromptChatMemoryAdvisor.builder(chatMemory).build())
    .build();

// After
ChatClient chatClient = ChatClient.builder(chatModel)
    .defaultAdvisors(MessageChatMemoryAdvisor.builder(chatMemory).build())
    .build();

ChatClient オプションにはビルダーが必要になりました

ChatClient を使用する場合、.options() / .defaultOptions() メソッドは、完全に構築された ChatOptions インスタンスではなく、ChatOptions.Builder (またはプロバイダ固有のビルダーサブ型) を受け入れるようになりました。この変更は、メソッドの汎用型制約 <B extends ChatOptions.Builder<?>> によってコンパイル時に強制されます。

オプションビルダーは、最初のアドバイザーが呼び出される前にモデルのデフォルトオプションとマージされるため、明示的に設定したフィールドのみがデフォルト設定を上書きします。

// Before — passing a built ChatOptions instance (no longer compiles with ChatClient)
ChatOptions opts = AnthropicChatOptions.builder()
    .maxTokens(100)
    .temperature(0.7)
    .build();
String response = chatClient.prompt("Tell me a joke")
    .options(opts)
    .call().content();

// After — pass the builder directly
String response = chatClient.prompt("Tell me a joke")
    .options(AnthropicChatOptions.builder()
        .maxTokens(100)
        .temperature(0.7))
    .call().content();
この制限は ChatClient にのみ適用されます。ChatModel.call(Prompt) を直接呼び出す場合、プロンプトにはモデルが想定する具象型の完全に構築された ChatOptions インスタンス ( 例 : AnthropicChatModel の場合は AnthropicChatOptions ) が含まれている必要があります。ChatModel はオプションをマージしません。Prompt.getOptions() が null でない場合はそのまま使用され、null の場合はモデル独自のデフォルトオプションが代わりに使用されます。ChatModel レベルでは部分的なマージは行われません。

buildRequestPrompt がパブリック API から削除されました

buildRequestPrompt メソッドは、もはや公開 API の一部ではありません。以前は誤って公開されていましたが、現在はプライベートまたはパッケージプライベートの可視性に戻されています。

OpenAI Java SDK 移行

Spring AI は、spring-ai-openai モジュール内のすべての OpenAI モデル（チャット、埋め込み、イメージ、音声認識、音声文字起こし、モデレーション）において、内部的に公式の openai-java SDK を使用するようになりました。

移行はスムーズに行われ、spring-ai-openai モジュールの既存ユーザーにとって大きな互換性の問題は発生しない見込みです。すべてのプロパティ（spring.ai.openai.* プレフィックス付き）、ビルダー、オプションは完全にそのまま維持されます。既存の extraBody 構成パラメーターは、openai-java SDK の基盤となる additionalBodyProperties に透過的にマッピングされます。

spring-ai-azure-openai モジュールの取り外し

spring-ai-azure-openai モジュール（およびそれに関連する Spring Boot スターター spring-ai-starter-model-azure-openai と自動構成 spring-ai-autoconfigure-model-azure-openai）は、Spring AI から削除されました。

既存のユーザーは、代わりに spring-ai-openai モジュール（および関連するスターターと自動構成）を使用し、クラス名（たとえば Azure の接頭辞を削除するなど）と構成プロパティをそれに応じて変更する必要があります。

spring-ai-openai-sdk モジュールの取り外し

spring-ai-openai-sdk モジュール（およびそれに関連する Spring Boot スターター spring-ai-starter-model-openai-sdk と自動構成 spring-ai-autoconfigure-model-openai-sdk）は、Spring AI から削除されました。

既存のユーザーは、代わりに spring-ai-openai モジュール（および関連するスターターと自動構成）を使用し、クラス名（たとえば Sdk サフィックスを削除するなど）と構成プロパティを適切に調整してください。

spring-ai-oci-genai モジュールの取り外し

関連モジュールは現在、github.com/oracle/spring-cloud-oracle/tree/main/spring-ai-oracle (英語) で入手できます。

MCP Java SDK が 2.0.0 にアップグレードされました

Spring AI 2.0.0 では、MCP Java SDK が 1.1.x から 2.0.0 にアップグレードされます。このリリースでは、SDK レベルでいくつかの互換性のない変更が導入されており、MCP 型と直接やり取りするアプリケーションに影響を与える可能性があります。

サーバーサイドツールの入力検証はデフォルトで有効になっています

MCP サーバーは、ツールハンドラーを呼び出す前に、受信したツール引数をツールの JSON スキーマと照合して検証するようになりました。検証に失敗した場合は、CallToolResult と isError=true、および詳細なエラーメッセージが表示されます。

インパクト

これまで型が曖昧なツール引数や引数が欠落しているツール引数を受け入れていた既存の MCP サーバーは、今後は規格外の引数を送信してきたクライアントに対して検証エラーを返すようになる。

マイグレーション

ツール定義に正確な JSON スキーマが含まれていること、およびすべてのクライアントが準拠した引数を送信していることを確認してください。検証を無効にして 2.0 より前の動作に戻すには、サーバービルダーで validateToolInputs(false) を設定してください。

McpServer.sync(transportProvider)
    .validateToolInputs(false)
    .tool(myTool, handler)
    .build();
@McpTool アノテーションを使用すると、Spring AI はメソッドパラメーターから JSON スキーマを自動的に生成します。これらのスキーマは組み込みのバリデーターと互換性があり、追加の操作は不要です。

Tool.inputSchema が JsonSchema から Map<String, Object> に変更されました

McpSchema.Tool.inputSchema() （および outputSchema()）は、以前の JsonSchema レコードの代わりに Map<String, Object> を返すようになりました。これにより、任意の JSON スキーマダイアレクトキーワード（$ref、unevaluatedProperties、ベンダー拡張機能）がトリミングされることなく往復できるようになります。

インパクト

tool.inputSchema() を JsonSchema オブジェクトとして使用するコードはコンパイルエラーになります。

マイグレーション

Map<String, Object> に切り替える:

// Before
McpSchema.JsonSchema schema = tool.inputSchema();

// After
Map<String, Object> schema = tool.inputSchema();

McpSchema.Tool.Builder を介してツールを構築する場合、非推奨の inputSchema(JsonSchema) ヘルパーは後方互換性のために引き続き使用できますが、inputSchema(Map) または inputSchema(McpJsonMapper, String) の使用を推奨します。

@McpTool アノテーションまたは Spring AI の SyncMcpToolProvider / AsyncMcpToolProvider を使用するアプリケーションは影響を受けません。Spring AI が内部的にスキーマ生成を処理します。

Builder.customizeRequest() が HTTP クライアントトランスポートから削除されました

非推奨となった Builder.customizeRequest() メソッドは、HttpClientSseClientTransport.Builder および HttpClientStreamableHttpTransport.Builder から削除されました。

インパクト

これらのビルダー型に対して .customizeRequest() を直接呼び出すコードは、コンパイルに失敗します。

マイグレーション

customizeRequest() を httpRequestCustomizer() （同期）または asyncHttpRequestCustomizer() （非同期）に置き換えてください。

// Before
HttpClientSseClientTransport.builder(baseUrl)
    .customizeRequest(req -> req.header("Authorization", "Bearer token"))
    .build();

// After
HttpClientSseClientTransport.builder(baseUrl)
    .httpRequestCustomizer(req -> req.header("Authorization", "Bearer token"))
    .build();
すでに McpClientCustomizer<B> API に移行済みであれば、追加の操作は必要ありません。

シールされた MCP スキーマインターフェースが削除されました

以下のインターフェースはもはや sealed ではありません: McpSchema.JSONRPCMessage、McpSchema.Request、McpSchema.Result、McpSchema.Notification、McpSchema.ResourceContents、McpSchema.CompleteReference、McpSchema.Content。

インパクト

これらの型に対する、完全性のためにシールされた階層に依存する網羅的な switch 式は、default ブランチなしではコンパイルされなくなりました。

マイグレーション

これらの型に対する網羅的な switch に default ブランチを追加します。

// Before (no default needed when McpSchema.Content was sealed)
String text = switch (content) {
    case McpSchema.TextContent tc   -> tc.text();
    case McpSchema.ImageContent ic  -> "[image]";
    case McpSchema.EmbeddedResource er -> "[resource]";
};

// After
String text = switch (content) {
    case McpSchema.TextContent tc   -> tc.text();
    case McpSchema.ImageContent ic  -> "[image]";
    case McpSchema.EmbeddedResource er -> "[resource]";
    default -> throw new IllegalArgumentException("Unknown content type: " + content);
};
この変更は、アノテーションや Spring AI のより高レベルの抽象化を通じて MCP とやり取りする Spring AI ユーザーのほとんどには影響しないと考えられます。

Usage における統合キャッシュ使用状況メトリクス

org.springframework.ai.chat.metadata.Usage インターフェースに、getCacheReadInputTokens() と getCacheWriteInputTokens() という 2 つのデフォルトメソッドが追加されました。プロバイダが値を報告しない場合、どちらのメソッドも null を返します。

Anthropic、Bedrock Converse、OpenAI、Google GenAI は、それぞれキャッシュにデータを格納します。Anthropic と Bedrock は双方向で、OpenAI と Google はキャッシュ読み取り専用です。

これらの数値をネイティブ型にキャストしたり、プロバイダ固有のメタデータキーを読み取ったりするコードは、インターフェースメソッドに切り替えることができます。例については、プロンプトキャッシュ使用状況メトリクスを参照してください。

Anthropic モジュール

spring-ai-anthropic は、以前のように独自に開発した RestClient / WebClient の実装ではなく、com.anthropic:anthropic-java をベースに構築されるようになりました。

ほとんどのアプリケーションにとって、この変更は透過的です。Maven アーティファクト、spring.ai.anthropic.* 構成、AnthropicChatModel / AnthropicChatOptions / ChatClient API は維持され、ChatClient または ChatModel.call(Prompt) を経由するコードは更新する必要がありません。

org.springframework.ai.anthropic.api からインポートしたコード、AnthropicApi 引数を使用して AnthropicChatModel を構築したコード、古い maxTokens のデフォルト値に依存しているコードは、注意が必要です。

インパクト

  • org.springframework.ai.anthropic.api.AnthropicApi およびそのネストされたレコード型 (ChatCompletionRequest、ContentBlock、Tool、ToolChoice*、ストリーミングイベントレコード) はすべて削除されました。これらを参照するコードはコンパイルできません。

  • 公開コンストラクター AnthropicChatModel(AnthropicApi, AnthropicChatOptions, …​) は廃止されました。AnthropicChatModel.builder() を使用してください。

  • AnthropicChatOptions#maxTokens は、500 ではなく 4096 にデフォルト設定されます。以前の上限に達したレスポンスは、処理時間が長くなり、それに伴ってトークンの使用量も増加します。

  • AnthropicCacheOptions、AnthropicCacheStrategy、AnthropicCacheTtl、CacheBreakpointTracker、CacheEligibilityResolver は api （および api.utils）からルートパッケージである org.springframework.ai.anthropic に移行しました。

  • AnthropicCacheType、StreamHelper、metadata.AnthropicRateLimit は削除され、同等の SDK 型（CacheControlEphemeral、AsyncStreamResponse<RawMessageStreamEvent>、RateLimitException）が直接使用されます。

  • CitationDocument は AnthropicCitationDocument に名称変更されました。

  • com.anthropic:anthropic-java は推移的に com.squareup.okhttp3:okhttp をクラスパスに追加します。

マイグレーション

移動したキャッシュクラスと引用クラスのインポートを更新します。

前 後

org.springframework.ai.anthropic.api.AnthropicCacheOptions

org.springframework.ai.anthropic.AnthropicCacheOptions

org.springframework.ai.anthropic.api.AnthropicCacheStrategy

org.springframework.ai.anthropic.AnthropicCacheStrategy

org.springframework.ai.anthropic.api.AnthropicCacheTtl

org.springframework.ai.anthropic.AnthropicCacheTtl

org.springframework.ai.anthropic.api.utils.CacheBreakpointTracker

org.springframework.ai.anthropic.CacheBreakpointTracker

org.springframework.ai.anthropic.api.utils.CacheEligibilityResolver

org.springframework.ai.anthropic.CacheEligibilityResolver

org.springframework.ai.anthropic.api.CitationDocument

org.springframework.ai.anthropic.AnthropicCitationDocument

AnthropicCacheStrategy (NONE、TOOLS_ONLY、SYSTEM_ONLY、SYSTEM_AND_TOOLS、CONVERSATION_HISTORY) と AnthropicCacheTtl (FIVE_MINUTES、ONE_HOUR) は同じ列挙値を保持します。

コンストラクターを直接使用する代わりに、ビルダーを使用してください。

// Before
AnthropicApi anthropicApi = new AnthropicApi(apiKey);
AnthropicChatModel chatModel = new AnthropicChatModel(anthropicApi, options);

// After
AnthropicChatModel chatModel = AnthropicChatModel.builder()
    .apiKey(apiKey)
    .defaultOptions(options)
    .build();

500 -token のデフォルト値を使用してコストを制限している場合は、明示的に設定してください。

AnthropicChatOptions.builder()
    .maxTokens(500)
    // ...
    .build();

残りは Anthropic モジュールを公式 Java SDK に移行するがカバーします: SDK への直接アクセス、ストリーミング動作、プロンプトのキャッシュ、引用、削除された型。

新しいチャットオプション

spring-ai-anthropic には、新たに 4 つのチャットオプションが追加されました。それぞれの詳細な説明は Anthropic チャットに記載されています。主な変更点は以下のとおりです。

オプション 追加されるもの

思考表示

Display.SUMMARIZED and Display.OMITTED on the thinkingEnabled / thinkingAdaptive builders, so Claude can use a thinking budget without surfacing the full reasoning.

Service tier

AnthropicServiceTier.AUTO / STANDARD_ONLY for Anthropic’s priority capacity tier. Property spring.ai.anthropic.chat.service-tier.

Built-in web search

AnthropicWebSearchTool lets Claude search the web during a request. Properties under spring.ai.anthropic.chat.web-search-tool.*.

Inference geo

inferenceGeo("us") or inferenceGeo("eu") for data-residency routing. Property spring.ai.anthropic.chat.inference-geo.
If you are upgrading from 1.1.x (or 1.0.x), see Migrating the Anthropic Module to the Official Java SDK for the full RestClient → SDK transition guide.

MCP Annotations Migrated into Spring AI

The org.springaicommunity:mcp-annotations external library has been removed as a dependency of the mcp-annotations module. Its classes are now part of Spring AI itself under a new package structure.

Impact

  • All MCP annotation and provider classes have new fully-qualified names.

  • The org.springaicommunity:mcp-annotations artifact is no longer provided transitively by Spring AI.

  • Any code importing from org.springaicommunity.mcp.* will fail to compile.

Package Rename

Old Package New Package

org.springaicommunity.mcp.annotation.*

org.springframework.ai.mcp.annotation.*

org.springaicommunity.mcp.method.*

org.springframework.ai.mcp.annotation.method.*

org.springaicommunity.mcp.provider.*

org.springframework.ai.mcp.annotation.provider.*

マイグレーション

アプリケーションコード内のすべてのインポートを更新してください。

// Before
import org.springaicommunity.mcp.annotation.McpTool;
import org.springaicommunity.mcp.annotation.McpPrompt;
import org.springaicommunity.mcp.annotation.McpResource;
import org.springaicommunity.mcp.annotation.McpSampling;
import org.springaicommunity.mcp.provider.tool.SyncMcpToolProvider;
import org.springaicommunity.mcp.provider.prompt.AsyncMcpPromptProvider;

// After
import org.springframework.ai.mcp.annotation.McpTool;
import org.springframework.ai.mcp.annotation.McpPrompt;
import org.springframework.ai.mcp.annotation.McpResource;
import org.springframework.ai.mcp.annotation.McpSampling;
import org.springframework.ai.mcp.annotation.provider.tool.SyncMcpToolProvider;
import org.springframework.ai.mcp.annotation.provider.prompt.AsyncMcpPromptProvider;

org.springaicommunity:mcp-annotations を Maven または Gradle の直接的な依存関係として宣言していた場合は、それを削除してください。これらのクラスは現在、Spring AI の spring-ai-mcp-annotations モジュールによって提供されています。

OpenRewrite による自動移行

提供されている OpenRewrite レシピを使用すれば、すべてのインポートと依存関係の変更を自動化できます。

コマンドラインから migrate-to-2-0-0-M3.yaml [GitHub] (英語) レシピを適用します。

mvn org.openrewrite.maven:rewrite-maven-plugin:6.32.0:run \
  -Drewrite.configLocation=https://raw.githubusercontent.com/spring-projects/spring-ai/refs/heads/main/src/rewrite/migrate-to-2-0-0-M3.yaml \
  -Drewrite.activeRecipes=org.springframework.ai.migration.M3MigrateMcpAnnotations \
  -Dmaven.compiler.failOnError=false

このレシピでは、以下の 2 つの変更が自動的に行われます。

  1. 除去は org.springaicommunity:mcp-annotations と Maven の依存関係にある。

  2. Rewrites は、.java ファイル全体にわたるすべての import ステートメントを新しい org.springframework.ai.mcp.annotation.* パッケージを指すように変更します。

すべての M3 移行を一度に実行するには、包括的 レシピを使用します。[run-all-m3-migrations] を参照してください。

MCP Spring 輸送モジュールが Spring AI に移動されました

mcp-spring-webflux および mcp-spring-webmvc トランスポートモジュールは、MCP Java SDK には同梱されなくなりました。Spring AI 2.0 以降、これらは Spring AI プロジェクト自体の一部となっています。

インパクト

  • 両方のアーティファクトの Maven グループ ID が変更されました。

  • Spring 固有のトランスポートクラスすべてについて、Java パッケージ名が変更されました。

  • MCP Java SDK のバージョン要件が 0.18.x から 1.0.x にプルアップられました。

Maven 依存グループ ID の変更

前 
<dependency>
    <groupId>io.modelcontextprotocol.sdk</groupId>
    <artifactId>mcp-spring-webflux</artifactId>
</dependency>

<dependency>
    <groupId>io.modelcontextprotocol.sdk</groupId>
    <artifactId>mcp-spring-webmvc</artifactId>
</dependency>
後 
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>mcp-spring-webflux</artifactId>
</dependency>

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>mcp-spring-webmvc</artifactId>
</dependency>
spring-ai-bom または Spring AI MCP スターター（spring-ai-starter-mcp-server-webflux、spring-ai-starter-mcp-server-webmvc、spring-ai-starter-mcp-client-webflux）を使用する場合、明示的なバージョン指定は不要です。BOM が自動的に管理します。

Java パッケージの再配置

Spring 固有のトランスポートクラスはすべて org.springframework.ai パッケージに移行しました。

表 1: サーバートランスポート
クラス 古いパッケージ 新規パッケージ

WebFluxSseServerTransportProvider

io.modelcontextprotocol.server.transport

org.springframework.ai.mcp.server.webflux.transport

WebFluxStreamableServerTransportProvider

io.modelcontextprotocol.server.transport

org.springframework.ai.mcp.server.webflux.transport

WebFluxStatelessServerTransport

io.modelcontextprotocol.server.transport

org.springframework.ai.mcp.server.webflux.transport

WebMvcSseServerTransportProvider

io.modelcontextprotocol.server.transport

org.springframework.ai.mcp.server.webmvc.transport

WebMvcStreamableServerTransportProvider

io.modelcontextprotocol.server.transport

org.springframework.ai.mcp.server.webmvc.transport

WebMvcStatelessServerTransport

io.modelcontextprotocol.server.transport

org.springframework.ai.mcp.server.webmvc.transport

表 2: クライアント輸送
クラス 古いパッケージ 新規パッケージ

WebFluxSseClientTransport

io.modelcontextprotocol.client.transport

org.springframework.ai.mcp.client.webflux.transport

WebClientStreamableHttpTransport

io.modelcontextprotocol.client.transport

org.springframework.ai.mcp.client.webflux.transport

マイグレーション

Java のインポートを更新してください。

// Before
import io.modelcontextprotocol.server.transport.WebFluxSseServerTransportProvider;
import io.modelcontextprotocol.server.transport.WebMvcSseServerTransportProvider;
import io.modelcontextprotocol.client.transport.WebFluxSseClientTransport;
import io.modelcontextprotocol.client.transport.WebClientStreamableHttpTransport;

// After
import org.springframework.ai.mcp.server.webflux.transport.WebFluxSseServerTransportProvider;
import org.springframework.ai.mcp.server.webmvc.transport.WebMvcSseServerTransportProvider;
import org.springframework.ai.mcp.client.webflux.transport.WebFluxSseClientTransport;
import org.springframework.ai.mcp.client.webflux.transport.WebClientStreamableHttpTransport;
Spring AI スターターを介した Spring Boot の自動構成のみに依存する場合は、Java コードの変更は不要です。上記の説明に従って、pom.xml/build.gradle の依存関係座標を更新するだけで済みます。

MCP トランスポート移行に関する完全なリファレンスについては、Spring AI 2.0 へのアップグレードを参照してください。

OpenRewrite による自動移行

提供されている OpenRewrite レシピを使用すると、Maven のすべての依存関係と Java インポートの変更を自動化できます。

mvn org.openrewrite.maven:rewrite-maven-plugin:6.32.0:run \
  -Drewrite.configLocation=https://raw.githubusercontent.com/spring-projects/spring-ai/refs/heads/main/src/rewrite/migrate-to-2-0-0-M3.yaml \
  -Drewrite.activeRecipes=org.springframework.ai.migration.M3MigrateMcpSpringTransports \
  -Dmaven.compiler.failOnError=false
プロジェクトで明示的な <version> (BOM でバージョン管理される) を指定せずに io.modelcontextprotocol.sdk:mcp-spring-webflux または mcp-spring-webmvc を宣言した場合、Maven は pom.xml の解析を拒否し、レシピは実行されません。まずこれらのファイルを事前にパッチしてから、OpenRewrite を実行してください。
# Step 1 – patch the groupIds directly so Maven can load the modules
find . -name "pom.xml" -print0 \
  | xargs -0 perl -i -0pe \
    's{<groupId>io\.modelcontextprotocol\.sdk</groupId>(\s+)<artifactId>mcp-spring-webflux</artifactId>}{<groupId>org.springframework.ai</groupId>$1<artifactId>mcp-spring-webflux</artifactId>}g;
     s{<groupId>io\.modelcontextprotocol\.sdk</groupId>(\s+)<artifactId>mcp-spring-webmvc</artifactId>}{<groupId>org.springframework.ai</groupId>$1<artifactId>mcp-spring-webmvc</artifactId>}g'

# Step 2 – run OpenRewrite to migrate Java imports and remaining POM changes
mvn org.openrewrite.maven:rewrite-maven-plugin:6.32.0:run \
  -Drewrite.configLocation=https://raw.githubusercontent.com/spring-projects/spring-ai/refs/heads/main/src/rewrite/migrate-to-2-0-0-M3.yaml \
  -Drewrite.activeRecipes=org.springframework.ai.migration.M3MigrateMcpSpringTransports \
  -Dmaven.compiler.failOnError=false

すべての M3 移行を一度に実行するには、包括的 レシピを使用します。[run-all-m3-migrations] を参照してください。

MCP クライアントカスタマイザー API 統合版

McpAsyncClientCustomizer と McpSyncClientCustomizer は削除され、単一の汎用インターフェース McpClientCustomizer<B> に置き換えられました。

インパクト

  • McpAsyncClientCustomizer はもはや存在しません — Bean を実装するすべてのコードでコンパイルエラーが発生します。

  • McpSyncClientCustomizer はもはや存在しません — Bean を実装するすべてのコードでコンパイルエラーが発生します。

  • McpSyncClientConfigurer および McpAsyncClientConfigurer コンストラクターは、従来の型固有のリストの代わりに List<McpClientCustomizer<…​>> を受け入れるようになりました。

  • In the HttpClient-based transport auto-configurations (SseHttpClientTransportAutoConfiguration, StreamableHttpHttpClientTransportAutoConfiguration), the SDK-level McpSyncHttpClientRequestCustomizer and McpAsyncHttpClientRequestCustomizer beans are no longer applied. Transport-level customization now goes through McpClientCustomizer<HttpClientSseClientTransport.Builder> and McpClientCustomizer<HttpClientStreamableHttpTransport.Builder> respectively.

マイグレーション

Replace your customizer beans with the new generic interface, parameterized by the spec or builder type you need:

// Before
@Bean
public McpSyncClientCustomizer mySyncCustomizer() {
    return (name, spec) -> spec.requestTimeout(Duration.ofSeconds(30));
}

@Bean
public McpAsyncClientCustomizer myAsyncCustomizer() {
    return (name, spec) -> spec.requestTimeout(Duration.ofSeconds(30));
}

// After
@Bean
public McpClientCustomizer<McpClient.SyncSpec> mySyncCustomizer() {
    return (name, spec) -> spec.requestTimeout(Duration.ofSeconds(30));
}

@Bean
public McpClientCustomizer<McpClient.AsyncSpec> myAsyncCustomizer() {
    return (name, spec) -> spec.requestTimeout(Duration.ofSeconds(30));
}

For HttpClient transport customization (previously done via McpSyncHttpClientRequestCustomizer / McpAsyncHttpClientRequestCustomizer):

// Before
@Bean
public McpSyncHttpClientRequestCustomizer myRequestCustomizer() {
    return requestBuilder -> requestBuilder.header("Authorization", "Bearer token");
}

// After
@Bean
public McpClientCustomizer<HttpClientSseClientTransport.Builder> mySseTransportCustomizer() {
    return (name, builder) -> builder.httpRequestCustomizer(
        req -> req.header("Authorization", "Bearer token")
    );
}

OpenRewrite による自動移行

You can automate the import and type changes using the provided OpenRewrite recipe:

mvn org.openrewrite.maven:rewrite-maven-plugin:6.32.0:run \
  -Drewrite.configLocation=https://raw.githubusercontent.com/spring-projects/spring-ai/refs/heads/main/src/rewrite/migrate-to-2-0-0-M3.yaml \
  -Drewrite.activeRecipes=org.springframework.ai.migration.M3MigrateMcpClientCustomizer \
  -Dmaven.compiler.failOnError=false

The recipe performs the following changes automatically:

  1. 置換 the McpAsyncClientCustomizer and McpSyncClientCustomizer imports with McpClientCustomizer and adds the required import io.modelcontextprotocol.client.McpClient;.

  2. Rewrites implements McpAsyncClientCustomizer to implements McpClientCustomizer<McpClient.AsyncSpec>.

  3. Rewrites implements McpSyncClientCustomizer to implements McpClientCustomizer<McpClient.SyncSpec>.

  4. Rewrites all remaining usages (return types, variable declarations, parameter types).

McpSyncHttpClientRequestCustomizer and McpAsyncHttpClientRequestCustomizer beans are no longer applied by the transport auto-configurations. Their migration to McpClientCustomizer<TransportBuilder> requires a manual step — the target builder type depends on which transport you are configuring (SSE vs. Streamable HTTP).

すべての M3 移行を一度に実行するには、包括的 レシピを使用します。[run-all-m3-migrations] を参照してください。

MCP WebMvc Transport Headers Normalized to Lowercase

In WebMvcSseServerTransportProvider、WebMvcStatelessServerTransport、WebMvcStreamableServerTransportProvider, the Map<String, List<String>> passed to securityValidator.validateHeaders(headers) now has all header names normalized to lowercase.

Previously, header names were passed with their original HTTP case (e.g. "Authorization", "Content-Type"). They are now always lowercase (e.g. "authorization", "content-type").

インパクト

Custom ServerTransportSecurityValidator implementations that look up headers by their mixed-case names will silently fail to find them.

マイグレーション

Update all header name lookups in your ServerTransportSecurityValidator to use lowercase keys:

// Before
public void validateHeaders(Map<String, List<String>> headers) {
    List<String> authHeader = headers.get("Authorization");
    // ...
}

// After
public void validateHeaders(Map<String, List<String>> headers) {
    List<String> authHeader = headers.get("authorization");
    // ...
}

ToolContext から会話履歴が削除されました

会話履歴は ToolContext に自動的に追加されなくなりました。TOOL_CALL_HISTORY 定数と getToolCallHistory() メソッドは ToolContext クラスから削除されました。

インパクト

  • ToolContext.TOOL_CALL_HISTORY 定数はもう存在しません

  • ToolContext.getToolCallHistory() 法はもう存在しない

  • ToolContext では会話履歴が自動的に入力されなくなりました

Why This Change?

  1. Memory Efficiency : Prevents unbounded memory growth in long conversations

  2. 関心の分離 : Tools should operate on their parameters, not manage conversation state

  3. Architecture Alignment : Conversation context belongs at the advisor level, not in tool execution

マイグレーション

If your application needs conversation history management, use ToolCallingAdvisor:

Managing Conversation History with ToolCallingAdvisor
ChatClient chatClient = ChatClient.builder()
    .defaultAdvisors(
        ToolCallingAdvisor.builder()
            .conversationHistoryEnabled(true)  // Full history (default)
            .build()
    )
    .build();

How ToolCallingAdvisor Works:

The ToolCallingAdvisor manages conversation history at the advisor level:

  • conversationHistoryEnabled=true (default): Full conversation history is maintained and sent to the LLM between tool call iterations, allowing the LLM to synthesize results with full context

  • conversationHistoryEnabled=false : Only the most recent tool response is sent to the LLM (useful when ChatMemory advisor manages history separately)

Key Point : The conversation history is used by the LLM to understand context and formulate responses, not by the tools themselves. Tools receive only their input parameters and any custom context you explicitly provide.

Custom Context in Tools:

ToolContext remains available for passing custom, application-specific data to tools:

Passing Custom Context to Tools
ChatResponse response = chatClient.prompt()
    .user("What's the weather in SF?")
    .toolContext(Map.of("userId", "user123", "apiKey", "secret"))
    .call()
    .chatResponse();

Example Flow:

  1. User asks: "What’s the weather in SF and LA?"

  2. LLM requests tool calls: getWeather(SF) および getWeather(LA)

  3. Tools execute with only their parameters (no conversation history)

  4. ToolCallingAdvisor collects tool results and conversation history

  5. LLM receives conversation context from advisor and synthesizes: "The weather in SF is 72 ° F and in LA is 85 ° F"

The LLM sees the full conversation through the advisor chain, not through ToolContext.

The access level of model internal methods changed to private

  • All internalCall and internalStream methods in model classes have been changed to private.

インパクト

  • Direct calls xxxModel.internalCall or xxxModel.internalStream method, will fail to compile.

マイグレーション

  • Replace all calls to xxxModel.internalCall with xxxModel.call.

  • Replace all calls to xxxModel.internalStream with xxxModel.stream.

    // Before
ChatResponse response = model.internalCall(prompt, previousChatResponse);
Flux<ChatResponse> responseFlux = model.internalStream(prompt, previousChatResponse);

// After
ChatResponse response = model.call(prompt);
Flux<ChatResponse> responseFlux = model.stream(prompt);

OpenSearch Dependencies Upgraded

The OpenSearch vector store dependencies have been upgraded to newer versions:

  • OpenSearch Java クライアント : 2.23.0 → 3.6.0

  • OpenSearch Testcontainers : 2.0.1 → 4.1.0

バックグラウンド

This upgrade was necessary for compatibility with Spring Boot 4.1.x, which uses HttpClient5 (org.apache.httpcomponents.client5:httpclient5) version 5.6. This version of HttpClient has a gzip content formatter breaking change that required the OpenSearch Java Client upgrade. See OpenSearch Java PR #1851 [GitHub] (英語) for details.

インパクト

The OpenSearch Java Client 3.x introduces breaking API changes that affect custom code interacting directly with the native OpenSearch client.

マイグレーション

If you’re using the OpenSearch vector store through Spring AI’s VectorStore interface, no action is required. The upgrade is transparent.

Testcontainers class renamed : OpensearchContainer → OpenSearchContainer (proper camelCase)

Spring AI’s internal implementation has been updated to handle these changes automatically.

AbstractFilterExpressionConverter: doSingleValue is now abstract

In AbstractFilterExpressionConverter (used by vector store filter expression converters), the method doSingleValue(Object value, StringBuilder context) has been changed from a concrete method to an abstract method. Custom vector store implementations that extend AbstractFilterExpressionConverter must now implement this method explicitly.

インパクト

  • Any custom FilterExpressionConverter that extends AbstractFilterExpressionConverter and did not override doSingleValue() will fail to compile.

  • Implementations must convert a single filter value (String, Number, Boolean, Date, etc.) into the target format and append it to the provided StringBuilder context.

マイグレーション

Implement doSingleValue(Object value, StringBuilder context) in your custom converter. You can use the provided static helper methods:

  • JSON-based filters (e.g. PostgreSQL JSONPath, Neo4j Cypher, Weaviate): use emitJsonValue(Object value, StringBuilder context) to serialize values with proper quoting and escaping.

  • Lucene-based filters (e.g. Elasticsearch, OpenSearch, GemFire): use emitLuceneString(String value, StringBuilder context) for string values, and handle other types (numbers, booleans, dates) according to your store’s query syntax.

  • Other formats : implement your own logic and append the result to context.

The framework normalizes values (e.g. ISO date strings converted to Date) before invoking doSingleValue, so your implementation receives already-normalized values. The static helper normalizeDateString(Object) is available if you need the same normalization when building expressions outside of the standard flow.

MongoDB チャットメモリのメッセージ順序の修正

MongoChatMemoryRepository は、他のすべてのチャットメモリリポジトリ実装と一致するように、送信された順序（古いものから新しいものへ）でメッセージを返すように修正されました。以前は、メッセージを逆順（新しいものから古いものへ）で誤って返していたため、LLM の会話フローが中断されていました。

インパクト

アプリケーションが MongoChatMemoryRepository を使用しており、誤った順序付けを回避するための対策（たとえば、取得後にメッセージを逆順にするなど）を講じていた場合は、その回避策を削除する必要があります。

マイグレーション

MongoDB チャットメモリから取得したメッセージの順序を反転させるコードをすべて削除してください。

// BEFORE (with workaround for bug):
List<Message> messages = chatMemoryRepository.findByConversationId(conversationId);
Collections.reverse(messages); // Remove this workaround

// AFTER (correct ordering):
List<Message> messages = chatMemoryRepository.findByConversationId(conversationId);
// Messages are now correctly ordered chronologically

すべてのチャットメモリリポジトリは、メッセージが送信された順序（古いものから新しいものへ）で一貫して返されるようになりました。これは、LLM の会話履歴として想定される形式です。

開発時のサービス

  • MongoDB Atlas の Docker Compose および Testcontainers サポートは、MongoDB モジュール Spring Boot によってネイティブに提供されるようになりました。移行は透過的であり、コード変更は必要ありません。依存関係については、org.springframework.ai:spring-ai-spring-boot-testcontainers をインポートする必要はなくなりました。org.springframework.boot:spring-boot-testcontainers への依存関係で十分です。

デフォルトの温度設定が削除されました

Spring AI は、チャットモデルの自動構成プロパティのデフォルトの温度値を提供しなくなりました。以前は、Spring AI はほとんどのチャットモデルに対してデフォルトの温度を 0.7 に設定していました。このデフォルト設定は削除され、各 AI プロバイダーのネイティブのデフォルト温度が使用されるようになりました。

インパクト

アプリケーションで温度値を明示的に設定せず、Spring AI のデフォルトである 0.7 に依存していた場合、アップグレード後に動作が異なる場合があります。実際のデフォルトは各 AI プロバイダーの API によって決定され、異なる場合があります。

  • 一部のプロバイダーはデフォルトで 1.0 を使用しています

  • 一部のプロバイダーはデフォルトで 0.7 を使用しています

  • 一部のプロバイダではモデル固有のデフォルトがあります

マイグレーション

以前の動作を維持する場合は、構成で温度を明示的に設定します。

# Example for OpenAI
spring.ai.openai.chat.temperature=0.7

# Example for Anthropic
spring.ai.anthropic.chat.temperature=0.7

# Example for Azure OpenAI
spring.ai.azure.openai.chat.temperature=0.7

またはリクエストを構築するときにプログラムで次のようにします。

ChatResponse response = chatModel.call(
    new Prompt("Your prompt here",
        OpenAiChatOptions.builder()
            .temperature(0.7)
            .build()));

1.1.0-RC1 へのアップグレード

重大な変更

テキスト読み上げ (TTS) API の移行

OpenAI 音声合成（TTS）の実装は、プロバイダ固有のクラスから共有インターフェースに移行されました。これにより、複数の TTS プロバイダ（OpenAI、ElevenLabs、将来のプロバイダ）で動作する移植性の高いコードの作成が可能になります。

削除されたクラス

次の非推奨クラスは org.springframework.ai.openai.audio.speech パッケージから削除されました。

  • SpeechModel → TextToSpeechModel を使用 (org.springframework.ai.audio.tts より)

  • StreamingSpeechModel → StreamingTextToSpeechModel を使用 (org.springframework.ai.audio.tts より)

  • SpeechPrompt → TextToSpeechPrompt を使用 (org.springframework.ai.audio.tts より)

  • SpeechResponse → TextToSpeechResponse を使用 (org.springframework.ai.audio.tts より)

  • SpeechMessage → TextToSpeechMessage を使用 (org.springframework.ai.audio.tts より)

  • Speech (org.springframework.ai.openai.audio.speech 内) → Speech を使用 (org.springframework.ai.audio.tts より)

さらに、他の TTS プロバイダーとの一貫性を保つために、すべての OpenAI TTS コンポーネントで speed パラメーター型が Float から Double に変更されました。

移行手順

  1. インポートの更新 : org.springframework.ai.openai.audio.speech. からのすべてのインポートを org.springframework.ai.audio.tts. に置き換えます

  2. 型参照の更新 : 古いクラス名をすべて新しいクラス名に置き換えます。

    Find:    SpeechModel
Replace: TextToSpeechModel

Find:    StreamingSpeechModel
Replace: StreamingTextToSpeechModel

Find:    SpeechPrompt
Replace: TextToSpeechPrompt

Find:    SpeechResponse
Replace: TextToSpeechResponse

Find:    SpeechMessage
Replace: TextToSpeechMessage

  3. 速度パラメーターの更新 : Float から Double への変更:

    Find:    .speed(1.0f)
Replace: .speed(1.0)

Find:    Float speed
Replace: Double speed

  4. アップデート依存性注入 : SpeechModel を挿入する場合は、TextToSpeechModel に更新します。

    // Before
public MyService(SpeechModel speechModel) { ... }

// After
public MyService(TextToSpeechModel textToSpeechModel) { ... }
メリット

  • ポータビリティ : 一度コードを記述すれば、OpenAI、ElevenLabs、その他の TTS プロバイダーを簡単に切り替えることができます。

  • 一貫性 : ChatModel や他の Spring AI 抽象化と同じパターン

  • 型安全性 : 適切なインターフェース実装による型階層の改善

  • 将来を見据えた : 新しい TTS プロバイダーは既存のコードで自動的に動作します

追加リソース

詳細なコード例を含む包括的な移行ガイドについては、以下を参照してください。

1.0.0-SNAPSHOT へのアップグレード

概要

1.0.0-SNAPSHOT バージョンでは、アーティファクト ID、パッケージ名、モジュール構造に大幅な変更が加えられています。このセクションでは、SNAPSHOT バージョンの使用に関する具体的なガイダンスを提供します。

スナップショットリポジトリの追加

1.0.0-SNAPSHOT バージョンを使用するには、スナップショットリポジトリをビルドファイルに追加する必要があります。詳細な手順については、「入門」ガイドのスナップショット - スナップショットリポジトリの追加セクションを参照してください。

アップデート依存関係管理

ビルド構成で、Spring AI BOM バージョンを 1.0.0-SNAPSHOT に更新します。依存関係管理を構成する詳細な手順については、「入門ガイド」の依存関係管理セクションを参照してください。

アーティファクト ID、パッケージ、モジュールの変更

1.0.0-SNAPSHOT には、アーティファクト ID、パッケージ名、モジュール構造の変更が含まれています。

詳細について: - 一般的なアーティファクト ID の変更 - 一般的なパッケージの変更 - 共通モジュール構造

1.0.0-RC1 へのアップグレード

OpenRewrite レシピを使えば、1.0.0-RC1 へのアップグレードプロセスを自動化できます。このレシピは、このバージョンに必要な多くのコード変更を適用できます。レシピと使用方法は Arconia Spring AI 移行 [GitHub] (英語) を参照してください。

重大な変更

チャットクライアントとアドバイザー

エンドユーザーコードに影響を与える主な変更は次のとおりです。

  • VectorStoreChatMemoryAdvisor の場合:

    • 定数 CHAT_MEMORY_RETRIEVE_SIZE_KEY の名前が TOP_K に変更されました。

    • 定数 DEFAULT_CHAT_MEMORY_RESPONSE_SIZE (値: 100) の名前が DEFAULT_TOP_K に変更され、新しいデフォルト値は 20 になりました。

  • 定数 CHAT_MEMORY_CONVERSATION_ID_KEY は CONVERSATION_ID に名前が変更され、AbstractChatMemoryAdvisor から ChatMemory インターフェースに移動されました。インポート時に org.springframework.ai.chat.memory.ChatMemory.CONVERSATION_ID を使用するように更新してください。

アドバイザーの自己完結型テンプレート

プロンプト拡張を実行する組み込みアドバイザーが、自己完結型のテンプレートを使用するように更新されました。これにより、各アドバイザーは、他のアドバイザーのテンプレート化やプロンプト決定に影響を与えず、また影響を受けずにテンプレート化操作を実行できるようになります。

次のアドバイザーにカスタムテンプレートを提供していた場合は、必要なプレースホルダーがすべて含まれるようにテンプレートを更新する必要があります。

  • QuestionAnswerAdvisor では、次のプレースホルダーを含むテンプレートが必要です ( 詳細については、こちらを参照してください)。

    • ユーザーの質問を受け取るための query プレースホルダー。

    • 取得したコンテキストを受け取るための question_answer_context プレースホルダー。

  • VectorStoreChatMemoryAdvisor では、次のプレースホルダーを含むテンプレートが必要です ( 詳細については、こちらを参照してください)。

    • 元のシステムメッセージを受信するための instructions プレースホルダー。

    • 取得した会話メモリを受け取るための long_term_memory プレースホルダー。

可観測性

  • トレースの代わりにログを使用するようにコンテンツ監視をリファクタリングしました (ca843e8 [GitHub] (英語) )

    • コンテンツ監視フィルターをログハンドラーに置き換えました

    • 目的をより適切に反映するために、構成プロパティの名前を変更しました。

      • include-prompt → log-prompt

      • include-completion → log-completion

      • include-query-response → log-query-response

    • トレース認識ログ用の TracingAwareLoggingObservationHandler を追加

    • micrometer-tracing-bridge-otel を micrometer-tracing に置き換えました

    • イベントベースのトレースを削除し、直接ログ記録を導入しました

    • OTel SDK への直接的な依存関係を削除しました

    • 観測プロパティで includePrompt を logPrompt に名前変更しました (ChatClientBuilderProperties、ChatObservationProperties、ImageObservationProperties)

チャットメモリリポジトリモジュールと自動構成の名前変更

コードベース全体にリポジトリサフィックスを追加することで、チャットメモリコンポーネントの命名パターンを標準化しました。この変更は Cassandra、JDBC、Neo4j の実装に影響し、アーティファクト ID、Java パッケージ名、クラス名の明確化に役立ちます。

アーティファクト Id

すべてのメモリ関連のアーティファクトは、一貫したパターンに従うようになりました。

  • spring-ai-model-chat-memory- → spring-ai-model-chat-memory-repository-

  • spring-ai-autoconfigure-model-chat-memory- → spring-ai-autoconfigure-model-chat-memory-repository-

  • spring-ai-starter-model-chat-memory- → spring-ai-starter-model-chat-memory-repository-

Java パッケージ

  • パッケージパスに .repository. セグメントが含まれるようになりました

  • サンプル: org.springframework.ai.chat.memory.jdbc → org.springframework.ai.chat.memory.repository.jdbc

構成クラス

  • メイン自動構成クラスは Repository サフィックスを使用するようになりました

  • サンプル: JdbcChatMemoryAutoConfiguration → JdbcChatMemoryRepositoryAutoConfiguration

プロパティ

  • 構成プロパティの名前が spring.ai.chat.memory.<storage>…​ から spring.ai.chat.memory.repository.<storage>…​ に変更されました

移行が必要 : - 新しいアーティファクト ID を使用するように Maven/Gradle の依存関係を更新します。- 古いパッケージ名またはクラス名を使用していたインポート、クラス参照、構成を更新します。

メッセージアグリゲーターリファクタリング

変更

  • MessageAggregator クラスは、spring-ai-client-chat モジュールの org.springframework.ai.chat.model パッケージから spring-ai-model モジュールに移動されました。(同じパッケージ名)

  • aggregateChatClientResponse メソッドは MessageAggregator から削除され、org.springframework.ai.chat.client パッケージの新しいクラス ChatClientMessageAggregator に移動されました。

移行ガイド

MessageAggregator の aggregateChatClientResponse メソッドを直接使用していた場合は、代わりに新しい ChatClientMessageAggregator クラスを使用する必要があります。

// Before
new MessageAggregator().aggregateChatClientResponse(chatClientResponses, aggregationHandler);

// After
new ChatClientMessageAggregator().aggregateChatClientResponse(chatClientResponses, aggregationHandler);

適切なインポートを追加することを忘れないでください。

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

ワトソン

Watson AI モデルは、新しいチャット生成モデルが利用可能になったため、時代遅れとみなされる古いテキスト生成に基づいていたため削除されました。Watson が Spring AI の将来のバージョンで再び登場することを期待しています。

MoonShot および QianFan

Moonshot と Qianfan は中国国外からアクセスできないため削除されました。これらは Spring AI コミュニティリポジトリに移動されました。

ベクトルストアを削除しました

メモリ管理

メッセージとテンプレート API

追加のクライアント API の変更

パッケージ構造の変更

依存関係

動作の変更

Azure OpenAI

  • クリーンな自動構成を備えた Azure OpenAI 用の Entra ID アイデンティティ管理を追加しました (3dc86d3 [GitHub] (英語) )

一般的なクリーンアップ

1.0.0-M8 へのアップグレード

OpenRewrite レシピを使えば、1.0.0-M8 へのアップグレードプロセスを自動化できます。このレシピは、このバージョンに必要な多くのコード変更を適用できます。レシピと使用方法は Arconia Spring AI 移行 [GitHub] (英語) を参照してください。

重大な変更

Spring AI 1.0 M7 から 1.0 M8 へのアップグレード時に、ツールコールバックを登録していたユーザーは、ツール呼び出し機能がサイレントエラーとなる重大な変更に遭遇しています。これは特に、非推奨の tools() メソッドを使用していたコードに影響を及ぼしています。

サンプル

以下は、M7 では動作していたが、M8 では期待どおりに動作しなくなったコードの例です。

// This worked in M7 but silently fails in M8
ChatClient chatClient = new OpenAiChatClient(api)
    .tools(List.of(
        new Tool("get_current_weather", "Get the current weather in a given location",
            new ToolSpecification.ToolParameter("location", "The city and state, e.g. San Francisco, CA", true))
    ))
    .toolCallbacks(List.of(
        new ToolCallback("get_current_weather", (toolName, params) -> {
            // Weather retrieval logic
            return Map.of("temperature", 72, "unit", "fahrenheit", "description", "Sunny");
        })
    ));

ソリューション

解決策としては、非推奨の tools() メソッドの代わりに toolSpecifications() メソッドを使用することです。

// This works in M8
ChatClient chatClient = new OpenAiChatClient(api)
    .toolSpecifications(List.of(
        new Tool("get_current_weather", "Get the current weather in a given location",
            new ToolSpecification.ToolParameter("location", "The city and state, e.g. San Francisco, CA", true))
    ))
    .toolCallbacks(List.of(
        new ToolCallback("get_current_weather", (toolName, params) -> {
            // Weather retrieval logic
            return Map.of("temperature", 72, "unit", "fahrenheit", "description", "Sunny");
        })
    ));

削除された実装と API

メモリ管理

クライアント API

メッセージとテンプレート API

モデルの実装

パッケージ構造の変更

依存関係

動作の変更

可観測性

  • トレースの代わりにログを使用するようにコンテンツ監視をリファクタリングしました (ca843e8 [GitHub] (英語) )

    • コンテンツ監視フィルターをログハンドラーに置き換えました

    • 目的をより適切に反映するために、構成プロパティの名前を変更しました。

      • include-prompt → log-prompt

      • include-completion → log-completion

      • include-query-response → log-query-response

    • トレース認識ログ用の TracingAwareLoggingObservationHandler を追加

    • micrometer-tracing-bridge-otel を micrometer-tracing に置き換えました

    • イベントベースのトレースを削除し、直接ログ記録を導入しました

    • OTel SDK への直接的な依存関係を削除しました

    • 観測プロパティで includePrompt を logPrompt に名前変更しました (ChatClientBuilderProperties、ChatObservationProperties、ImageObservationProperties)

Azure OpenAI

  • クリーンな自動構成を備えた Azure OpenAI 用の Entra ID アイデンティティ管理を追加しました (3dc86d3 [GitHub] (英語) )

一般的なクリーンアップ

1.0.0-M7 へのアップグレード

変更の概要

Spring AI 1.0.0-M7 は、RC1 および GA リリース前の最後のマイルストーンリリースです。アーティファクト ID、パッケージ名、モジュール構造にいくつかの重要な変更が導入されており、最終リリースでも維持されます。

アーティファクト ID、パッケージ、モジュールの変更

1.0.0-M7 には 1.0.0-SNAPSHOT と同じ構造変更が含まれています。

詳細について: - 一般的なアーティファクト ID の変更 - 一般的なパッケージの変更 - 共通モジュール構造

MCP Java SDK の 0.9.0 へのアップグレード

Spring AI 1.0.0-M7 は現在、MCP Java SDK バージョン 0.9.0 を使用しています。このバージョンには、以前のバージョンからの大幅な変更が含まれています。アプリケーションで MCP を使用している場合は、これらの変更に対応するためにコードを更新する必要があります。

主な変更点は次のとおりです。

インターフェース名の変更

  • ClientMcpTransport → McpClientTransport

  • ServerMcpTransport → McpServerTransport

  • DefaultMcpSession → McpClientSession または McpServerSession

  • すべての *Registration クラス→ *Specification クラス

サーバー作成の変更

  • ServerMcpTransport の代わりに McpServerTransportProvider を使用する 

// Before
ServerMcpTransport transport = new WebFluxSseServerTransport(objectMapper, "/mcp/message");
var server = McpServer.sync(transport)
    .serverInfo("my-server", "1.0.0")
    .build();

// After
McpServerTransportProvider transportProvider = new WebFluxSseServerTransportProvider(objectMapper, "/mcp/message");
var server = McpServer.sync(transportProvider)
    .serverInfo("my-server", "1.0.0")
    .build();

ハンドラーシグネチャーの変更

すべてのハンドラーは、最初の引数として exchange パラメーターを受け取るようになりました。

// Before
.tool(calculatorTool, args -> new CallToolResult("Result: " + calculate(args)))

// After
.tool(calculatorTool, (exchange, args) -> new CallToolResult("Result: " + calculate(args)))

Exchange 経由のクライアントインタラクション

以前はサーバー上で使用可能だったメソッドは、交換オブジェクトを介してアクセスされるようになりました。

// Before
ClientCapabilities capabilities = server.getClientCapabilities();
CreateMessageResult result = server.createMessage(new CreateMessageRequest(...));

// After
ClientCapabilities capabilities = exchange.getClientCapabilities();
CreateMessageResult result = exchange.createMessage(new CreateMessageRequest(...));

ルート変更ハンドラー 

// Before
.rootsChangeConsumers(List.of(
    roots -> System.out.println("Roots changed: " + roots)
))

// After
.rootsChangeHandlers(List.of(
    (exchange, roots) -> System.out.println("Roots changed: " + roots)
))

MCP コードの移行に関する完全なガイドについては、MCP 移行ガイド [GitHub] (英語) を参照してください。

モデルの自動構成の有効化 / 無効化

モデルの自動構成を有効 / 無効にするための以前の構成プロパティは削除されました。

  • spring.ai.<provider>.chat.enabled

  • spring.ai.<provider>.embedding.enabled

  • spring.ai.<provider>.image.enabled

  • spring.ai.<provider>.moderation.enabled

デフォルトでは、モデルプロバイダ（例: OpenAI、Ollama）がクラスパス上に見つかった場合、関連するモデル型（チャット、埋め込みなど）の自動構成が有効になります。同じモデル型に複数のプロバイダが存在する場合（例: spring-ai-openai-spring-boot-starter と spring-ai-ollama-spring-boot-starter の両方）、以下のプロパティを使用して、どのプロバイダの自動構成を有効にするかを選択できます。これにより、特定のモデル型に対して他のプロバイダの自動構成が実質的に無効になります。

特定のモデル型に対する自動構成を完全に無効にするには、プロバイダーが 1 つしか存在しない場合でも、対応するプロパティをクラスパス上のどのプロバイダーとも一致しない値 (例: none または disabled) に設定します。

既知のプロバイダー値のリストについては、SpringAIModels [GitHub] (英語) 列挙を参照できます。

  • spring.ai.model.audio.speech=<model-provider|none>

  • spring.ai.model.audio.transcription=<model-provider|none>

  • spring.ai.model.chat=<model-provider|none>

  • spring.ai.model.embedding=<model-provider|none>

  • spring.ai.model.embedding.multimodal=<model-provider|none>

  • spring.ai.model.embedding.text=<model-provider|none>

  • spring.ai.model.image=<model-provider|none>

  • spring.ai.model.moderation=<model-provider|none>

AI を使ったアップグレードの自動化

提供されたプロンプトを使用して、Claude コード CLI ツールを使用して 1.0.0-M7 へのアップグレードプロセスを自動化できます。

  1. Claude コード CLI ツール (英語) をダウンロード

  2. update-to-m7.txt [GitHub] (英語) ファイルからプロンプトをコピーします

  3. プロンプトを Claude コード CLI に貼り付けます

  4. AI がプロジェクトを分析し、必要な変更を加えます

自動アップグレードプロンプトは現在、アーティファクト ID の変更、パッケージの再配置、モジュール構造の変更に対応していますが、MCP 0.9.0 へのアップグレードに関する自動変更はまだ含まれていません。MCP をご利用の場合は、MCP Java SDK アップグレードセクションのガイダンスに従ってコードを手動で更新する必要があります。

バージョン間での共通の変更点

アーティファクト ID の変更

Spring AI スターターアーティファクトの命名パターンが変更されました。以下のパターンに従って依存関係を更新する必要があります。

  • モデルスターター: spring-ai-{model}-spring-boot-starter → spring-ai-starter-model-{model}

  • ベクトルストアスターター: spring-ai-{store}-store-spring-boot-starter → spring-ai-starter-vector-store-{store}

  • MCP スターター: spring-ai-mcp-{type}-spring-boot-starter → spring-ai-starter-mcp-{type}

サンプル

  • Maven

  • Gradle

<!-- BEFORE -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
</dependency>

<!-- AFTER -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>
// BEFORE
implementation 'org.springframework.ai:spring-ai-openai-spring-boot-starter'
implementation 'org.springframework.ai:spring-ai-redis-store-spring-boot-starter'

// AFTER
implementation 'org.springframework.ai:spring-ai-starter-model-openai'
implementation 'org.springframework.ai:spring-ai-starter-vector-store-redis'

Spring AI 自動構成アーティファクトの変更

Spring AI 自動構成は、単一のモノリシックアーティファクトから、モデル、ベクトルストア、その他のコンポーネントごとに個別の自動構成アーティファクトに変更されました。この変更は、Google プロトコルバッファー、Google RPC などの異なるバージョンの依存ライブラリが競合することによる影響を最小限に抑えるために行われました。自動構成をコンポーネント固有のアーティファクトに分離することで、不要な依存関係が取り込まれるのを防ぎ、アプリケーションでのバージョン競合のリスクを軽減できます。

オリジナルのモノリシックアーティファクトは利用できなくなりました。

<!-- NO LONGER AVAILABLE -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-spring-boot-autoconfigure</artifactId>
    <version>${project.version}</version>
</dependency>

代わりに、各コンポーネントには次のパターンに従う独自の自動構成アーティファクトが含まれるようになりました。

  • モデルの自動構成: spring-ai-autoconfigure-model-{model}

  • ベクトルストアの自動構成: spring-ai-autoconfigure-vector-store-{store}

  • MCP 自動構成: spring-ai-autoconfigure-mcp-{type}

新しい自動構成アーティファクトの例

  • モデル

  • ベクトルストア

  • MCP

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

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-autoconfigure-model-anthropic</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-autoconfigure-vector-store-redis</artifactId>
</dependency>

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-autoconfigure-vector-store-pgvector</artifactId>
</dependency>

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-autoconfigure-vector-store-chroma</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-autoconfigure-mcp-client</artifactId>
</dependency>

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-autoconfigure-mcp-server</artifactId>
</dependency>
ほとんどの場合、これらの自動構成依存関係を明示的に追加する必要はありません。対応するスターター依存関係を使用すると、それらは推移的に含まれます。

パッケージ名の変更

IDE は、新しいパッケージの場所へのリファクタリングを支援する必要があります。

  • KeywordMetadataEnricher および SummaryMetadataEnricher は org.springframework.ai.transformer から org.springframework.ai.chat.transformer に移動しました。

  • Content、MediaContent、Media は org.springframework.ai.model から org.springframework.ai.content に移動しました。

モジュール構造

このプロジェクトでは、モジュールとアーティファクトの構造に大幅な変更が行われました。以前は spring-ai-core にすべての中心的なインターフェースが含まれていましたが、現在はアプリケーションにおける不要な依存関係を削減するため、専用のドメインモジュールに分割されています。

Spring AI Dependencies

spring-ai-commons

他の Spring AI モジュールに依存しないベースモジュール。以下が含まれます: - コアドメインモデル（Document、TextSplitter） - JSON ユーティリティとリソース処理 - 構造化ログと可観測性のサポート

spring-ai-model

AI 機能の抽象化を提供する: - ChatModel、EmbeddingModel、ImageModel のようなインターフェース - メッセージ型とプロンプトテンプレート - 関数呼び出しフレームワーク（ToolDefinition、ToolCallback） - コンテンツフィルタリングと監視のサポート

spring-ai-vector-store

統一されたベクトルデータベース抽象化: - 類似検索のための VectorStore インターフェース - SQL のような表現による高度なフィルタリング - メモリ内使用のための SimpleVectorStore - 埋め込みのバッチ処理サポート

spring-ai-client-chat

高レベルの会話型 AI API: - ChatClient インターフェース - ChatMemory による会話の持続 - OutputConverter によるレスポンス変換 - アドバイザーベースのインターセプト - 同期およびリアクティブストリーミングのサポート

spring-ai-vector-store-advisor

RAG のベクトルストアとチャットを橋渡しします: - QuestionAnswerAdvisor: プロンプトにコンテキストを挿入します - VectorStoreChatMemoryAdvisor: 会話履歴を保存 / 取得します

spring-ai-model-chat-memory-cassandra

ChatMemory の Apache Cassandra 永続性: - CassandraChatMemory 実装 - Cassandra の QueryBuilder を使用した型安全な CQL ==== spring-ai-model-chat-memory-neo4j

チャット会話のための Neo4j グラフデータベースの永続性。

spring-ai-rag

検索拡張生成のための包括的なフレームワーク: - RAG パイプラインのモジュラーアーキテクチャ - メインエントリポイントとしての RetrievalAugmentationAdvisor - 構成可能なコンポーネントを備えた関数型プログラミングの原則

依存関係の構造

依存関係の階層は次のように要約できます。

  • spring-ai-commons (財団)

  • spring-ai-model (コモンズに依存する)

  • spring-ai-vector-store および spring-ai-client-chat (どちらもモデルによって異なります)

  • spring-ai-vector-store-advisor および spring-ai-rag (クライアントチャットとベクトルストアの両方に依存する)

  • spring-ai-model-chat-memory-* モジュール (クライアントチャットに依存する)

ToolContext の変更

ToolContext クラスは、明示的および暗黙的なツール解決をサポートするように拡張されました。ツールは以下の方法で指定できます。

  1. 明示的に含まれる : プロンプトで明示的にリクエストされ、モデルの呼び出しに含まれるツール。

  2. 暗黙的に利用可能 : 実行時の動的解決に使用できるツールですが、明示的にリクエストされない限り、モデルへの呼び出しには含まれません。

1.0.0-M7 以降、ツールは、プロンプトで明示的にリクエストされた場合、または呼び出しに明示的に含まれている場合にのみ、モデルの呼び出しに含まれます。

さらに、ToolContext クラスは final クラスとしてマークされ、拡張できなくなりました。このクラスは元々サブクラス化されることを想定していませんでした。ToolContext をインスタンス化する際に必要なコンテキストデータはすべて、Map<String, Object> の形式で追加できます。詳細については、[ ドキュメント ]( docs.spring.io/spring-ai/reference/api/tools.html#_tool_context ) を参照してください。

1.0.0-M6 へのアップグレード

使用インターフェースと DefaultUsage 実装の変更

Usage インターフェースとそのデフォルト実装 DefaultUsage には、次の変更が加えられました。

  1. メソッド名の変更:

    • getGenerationTokens() は getCompletionTokens() になりました

  2. 型の変更:

    • DefaultUsage のすべてのトークンカウントフィールドが Long から Integer に変更されました。

      • promptTokens

      • completionTokens (旧 generationTokens)

      • totalTokens

必要なアクション

  • getGenerationTokens() へのすべての呼び出しを getCompletionTokens() に置き換えます

  • DefaultUsage コンストラクター呼び出しを更新します。

// Old (M5)
new DefaultUsage(Long promptTokens, Long generationTokens, Long totalTokens)

// New (M6)
new DefaultUsage(Integer promptTokens, Integer completionTokens, Integer totalTokens)
使用方法の詳細については、こちらを参照してください。

JSON Ser/Deser の変更

M6 は generationTokens フィールドの JSON デシリアライゼーションの下位互換性を維持していますが、このフィールドは M7 で削除されます。古いフィールド名を使用している永続化された JSON ドキュメントは、completionTokens を使用するように更新する必要があります。

新しい JSON 形式の例:

{
  "promptTokens": 100,
  "completionTokens": 50,
  "totalTokens": 150
}

ツール呼び出しにおける FunctionCallingOptions の使用箇所の変更

各 ChatModel インスタンスは、構築時に、モデルの呼び出しに使用されるデフォルトのツールを構成するために使用できるオプションの ChatOptions または FunctionCallingOptions インスタンスを受け入れます。

1.0.0-M6 以前:

  • デフォルトの FunctionCallingOptions インスタンスの functions() メソッドを介して渡されたツールは、その ChatModel インスタンスからのモデルへの各呼び出しに含まれており、ランタイムオプションによって上書きされている可能性があります。

  • デフォルトの FunctionCallingOptions インスタンスの functionCallbacks() メソッドを介して渡されるツールは、実行時の動的解決 ( ツール解決を参照) でのみ使用可能になり、明示的にリクエストされない限り、モデルへの呼び出しには含まれません。

1.0.0-M6 の開始:

  • functions() メソッドまたはデフォルトの FunctionCallingOptions インスタンスの functionCallbacks() を介して渡されるすべてのツールは、同じ方法で処理されるようになりました。つまり、その ChatModel インスタンスからのモデルへの各呼び出しに含まれ、ランタイムオプションによって上書きされる可能性があります。これにより、モデルへの呼び出しにツールが含まれる方法に一貫性が保たれ、functionCallbacks() と他のすべてのオプションの動作の違いによる混乱が回避されます。

ツールを実行時の動的解決に利用できるようにし、明示的にリクエストされた場合にのみモデルへのチャットリクエストに含める場合は、ツール解決で説明されているいずれかの戦略を使用できます。

1.0.0-M6 では、ツール呼び出しを処理するための新しい API が導入されました。上記のシナリオを除き、すべてのシナリオにおいて古い API との後方互換性が維持されています。古い API は引き続き利用可能ですが、非推奨となり、1.0.0-M7 で削除されます。

非推奨となりた Amazon Bedrock チャットモデルの削除

1.0.0-M6 以降、Spring AI は Spring AI のすべてのチャット会話実装に Amazon、Bedrock の Converse API を使用するようになりました。Amazon、Bedrock のすべてのチャットモデルは、Cohere と Titan の埋め込みモデルを除き、削除されました。

チャットモデルの使用については、Bedrock コンバースのドキュメントを参照してください。

依存関係管理に Spring Boot 3.4.2 を使用するように変更

Spring AI は、依存関係管理に Spring Boot 3.4.2 を使用するようにアップデートされました。Spring Boot 3.4.2 で管理されている依存関係については、こちら [GitHub] (英語) を参照してください。

必要なアクション

  • Spring Boot 3.4.2 にアップグレードする場合は、REST クライアントの設定に必要な変更について、このドキュメントを必ず参照してください。特に、クラスパスに HTTP クライアントライブラリがない場合、以前は SimpleClientHttpRequestFactory が使用されていた場所が JdkClientHttpRequestFactory に置き換えられる可能性があります。SimpleClientHttpRequestFactory を使用するように切り替えるには、spring.http.client.factory=simple を設定する必要があります。

  • 異なるバージョンの Spring Boot (たとえば Spring Boot 3.3.x) を使用しており、依存関係の特定のバージョンが必要な場合は、ビルド構成でそれをオーバーライドできます。

ベクトルストア API の変更

バージョン 1.0.0-M6 では、VectorStore インターフェースの delete メソッドが、Optional<Boolean> を返すのではなく、void 操作になるように変更されました。以前のコードで削除操作の戻り値をチェックしていた場合は、このチェックを削除する必要があります。削除が失敗した場合、この操作は例外をスローするようになり、より直接的なエラー処理が可能になります。

1.0.0-M6 以前:

Optional<Boolean> result = vectorStore.delete(ids);
if (result.isPresent() && result.get()) {
    // handle successful deletion
}

1.0.0-M6 以降:

vectorStore.delete(ids);
// deletion successful if no exception is thrown

1.0.0.M5 へのアップグレード

  • ベクトルビルダーは一貫性を保つためにリファクタリングされました。

  • 現在の VectorStore 実装コンストラクターは非推奨になっています。ビルダーパターンを使用してください。

  • VectorStore 実装パッケージは、アーティファクト間での競合を回避するために、一意のパッケージ名に移動されました。たとえば、org.springframework.ai.vectorstore から org.springframework.ai.pgvector.vectorstore へ。

1.0.0.RC3 へのアップグレード

  • ポータブルチャットオプション（frequencyPenalty、presencePenalty、temperature、topP）の型が Float から Double に変更されました。

1.0.0.M2 へのアップグレード

  • Chroma ベクトルストアの構成プレフィックスは、他のベクトルストアの命名規則に合わせるために、spring.ai.vectorstore.chroma.store から spring.ai.vectorstore.chroma に変更されました。

  • スキーマを初期化できるベクトルストアの initialize-schema プロパティのデフォルト値が、false に設定されました。つまり、アプリケーションの起動時にスキーマが作成される場合、アプリケーションは、サポートされているベクトルストアでスキーマの初期化を明示的にオプトインする必要があります。すべてのベクトルストアがこのプロパティをサポートしているわけではありません。詳細については、対応するベクトルストアのドキュメントを参照してください。現在 initialize-schema プロパティをサポートしていないベクトルストアは次のとおりです。

    1. Pinecone

    2. Weaviate

  • Bedrock Jurassic 2 では、チャットオプション countPenalty、frequencyPenalty、presencePenalty の名前が countPenaltyOptions、frequencyPenaltyOptions、presencePenaltyOptions に変更されました。さらに、チャットオプション stopSequences の型が String[] から List<String> に変更されました。

  • Azure、OpenAI では、チャットオプション frequencyPenalty および presencePenalty の型が、他のすべての実装と一致するように、Double から Float に変更されました。

1.0.0.M1 へのアップグレード

1.0.0 M1 のリリースに向けて、いくつかの重大な変更を加えました。申し訳ありませんが、これは最善の策です。

ChatClient の変更点

大きな変更が行われ、旧 ChatClient の機能が ChatModel に移行しました。新 ChatClient は ChatModel のインスタンスを使用するようになりました。これは、Spring エコシステム内の他のクライアントクラス（RestClient、WebClient、JdbcClient など）と同様のスタイルでプロンプトを作成・実行するための Fluent API をサポートするためです。Fluent API の詳細については、[JavaDoc] ( ドキュメント ) を参照してください。正式なリファレンスドキュメントは近日公開予定です。

旧 ModelClient を Model に改名し、実装クラスの名前も変更しました。たとえば、ImageClient は ImageModel に変更されました。Model 実装は、Spring AI API と基盤となる AI モデル API 間の変換を行う移植性レイヤーを表しています。

新しいパッケージ model には、あらゆる入出力データ型の組み合わせに対応した AI モデルクライアントの作成をサポートするインターフェースと基本クラスが含まれています。現在、チャットモデルとイメージモデルのパッケージで実装されています。埋め込みパッケージも近日中にこの新しいモデルにアップデートする予定です。

新しい「ポータブルオプション」設計パターン。ModelCall は、様々なチャットベースの AI モデル間で可能な限り高い移植性を提供することを目的としています。共通の生成オプションセットと、モデルプロバイダー固有のオプションがあります。一種の「ダックタイピング」アプローチが採用されています。モデルパッケージ内の ModelOptions は、このクラスの実装がモデルのオプションを提供することを示すマーカーインターフェースです。すべての text → image ImageModel 実装に共通するポータブルオプションを定義するサブインターフェースである ImageOptions を参照してください。そして、StabilityAiImageOptions と OpenAiImageOptions は、各モデルプロバイダー固有のオプションを提供します。すべてのオプションクラスは、Fluent API ビルダーによって作成され、すべてポータブルな ImageModel API に渡すことができます。これらのオプションデータ型は、ImageModel 実装の自動構成 / 構成プロパティで使用されます。

アーティファクト名の変更

POM アーティファクト名を変更しました: - spring-ai-qdrant → spring-ai-qdrant-store - spring-ai-cassandra → spring-ai-cassandra-store - spring-ai-pinecone → spring-ai-pinecone-store - spring-ai-redis → spring-ai-redis-store - spring-ai-qdrant → spring-ai-qdrant-store - spring-ai-gemfire → spring-ai-gemfire-store - spring-ai-azure-vector-store-spring-boot-starter → spring-ai-azure-store-spring-boot-starter - spring-ai-redis-spring-boot-starter → spring-ai-starter-vector-store-redis

0.8.1 へのアップグレード

以前の spring-ai-vertex-ai は spring-ai-vertex-ai-palm2 に、spring-ai-vertex-ai-spring-boot-starter は spring-ai-vertex-ai-palm2-spring-boot-starter に名前が変更されました。

依存関係を次から変更する必要があります 

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-vertex-ai</artifactId>
</dependency>

To

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-vertex-ai-palm2</artifactId>
</dependency>

Palm2 モデルに関連する Boot スターター 

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-vertex-ai-spring-boot-starter</artifactId>
</dependency>

to

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-vertex-ai-palm2-spring-boot-starter</artifactId>
</dependency>

  • 名前変更されたクラス (01.03.2024)

    • VertexAiApi → VertexAiPalm2Api

    • VertexAiClientChat → VertexAiPalm2ChatClient

    • VertexAiEmbeddingClient → VertexAiPalm2EmbeddingClient

    • VertexAiChatOptions → VertexAiPalm2ChatOptions

0.8.0 へのアップグレード

2024 年 1 月 24 日更新

  • prompt、messages、metadata パッケージを org.springframework.ai.chat のサブパッケージに移動する

  • 新しい機能は、テキストからイメージへのクライアントです。クラスは OpenAiImageModel および StabilityAiImageModel です。使用箇所については統合テストを参照してください。ドキュメントは近日公開予定です。

  • 新しいパッケージ model には、あらゆる入出力データ型の組み合わせに対応した AI モデルクライアントの作成をサポートするインターフェースと基本クラスが含まれています。現在、チャットモデルとイメージモデルのパッケージで実装されています。埋め込みパッケージも近日中にこの新しいモデルにアップデートする予定です。

  • 新しい「ポータブルオプション」設計パターン。ModelCall は、様々なチャットベースの AI モデル間で可能な限り高い移植性を提供することを目的としています。共通の生成オプションセットと、モデルプロバイダー固有のオプションがあります。一種の「ダックタイピング」アプローチが採用されています。モデルパッケージ内の ModelOptions は、このクラスの実装がモデルのオプションを提供することを示すマーカーインターフェースです。すべての text → image ImageModel 実装に共通するポータブルオプションを定義するサブインターフェースである ImageOptions を参照してください。そして、StabilityAiImageOptions と OpenAiImageOptions は、各モデルプロバイダー固有のオプションを提供します。すべてのオプションクラスは、Fluent API ビルダーによって作成され、すべてポータブルな ImageModel API に渡すことができます。これらのオプションデータ型は、ImageModel 実装の自動構成 / 構成プロパティで使用されます。

2024 年 1 月 13 日更新

以下の OpenAi 自動構成チャットプロパティが変更されました

  • spring.ai.openai.model から spring.ai.openai.chat.model まで。

  • spring.ai.openai.temperature から spring.ai.openai.chat.temperature まで。

OpenAi プロパティに関する更新されたドキュメントを検索します: 参照: openai-chat.html

2023 年 12 月 27 日更新

SimplePersistentVectorStore と InMemoryVectorStore を SimpleVectorStore にマージします * InMemoryVectorStore を SimpleVectorStore に置き換えます

2023 年 12 月 20 日更新

Ollama クライアントと関連クラスおよびパッケージ名のリファクタリング

  • org.springframework.ai.ollama.client.OllamaClient を org.springframework.ai.ollama.OllamaModelCall に置き換えます。

  • OllamaChatClient メソッドのシグネチャーが変更されました。

  • org.springframework.ai.autoconfigure.ollama.OllamaProperties の名前を org.springframework.ai.model.ollama.autoconfigure.OllamaChatProperties に変更し、サフィックスを spring.ai.ollama.chat に変更します。一部のプロパティも変更されました。

2023 年 12 月 19 日更新

AiClient および関連クラスおよびパッケージ名の変更

  • AiClient の名前を ChatClient に変更します

  • AiResponse の名前を ChatResponse に変更します

  • AiStreamClient の名前を StreamingChatClient に変更します

  • パッケージの名前を org.sf.ai.client から org.sf.ai.chat に変更します

アーティファクト ID の名前を変更します

  • transformers-embedding から spring-ai-transformers

Maven モジュールを最上位ディレクトリと embedding-clients サブディレクトリからすべて 1 つの models ディレクトリに移動しました。

2023 年 12 月 1 日

プロジェクトのグループ ID を移行しています。

  • FROM: org.springframework.experimental.ai

  • TO: org.springframework.ai

以下に示すように、アーティファクトは引き続きスナップショットリポジトリでホストされます。

メインの ブランチはバージョン 0.8.0-SNAPSHOT に移行します。1 ～ 2 週間は不安定になります。最新の状態を望まない場合は、0.7.1-SNAPSHOT を使用してください。

以前と同様に 0.7.1-SNAPSHOT アーティファクトにアクセスでき、引き続き 0.7.1-SNAPSHOT ドキュメント (英語) にアクセスできます。

0.7.1-SNAPSHOT の依存関係

  • Azure OpenAI

    <dependency>
    <groupId>org.springframework.experimental.ai</groupId>
    <artifactId>spring-ai-azure-openai-spring-boot-starter</artifactId>
    <version>0.7.1-SNAPSHOT</version>
</dependency>

  • OpenAI

    <dependency>
    <groupId>org.springframework.experimental.ai</groupId>
    <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
    <version>0.7.1-SNAPSHOT</version>
</dependency>