このバージョンはまだ開発中であり、まだ安定しているとは見なされていません。最新の安定バージョンについては、Spring AI 1.1.7 を使用してください！

アップグレードノート

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

アドバイザー

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

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

ToolSearchToolCallingAdvisor moved to spring-ai-tool-search-advisor

The ToolSearchToolCallingAdvisor class has been moved to a dedicated module and package:

  • 成果物 : 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)

Update your dependency and import statements accordingly:

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

変更: Advisor.DEFAULT_CHAT_MEMORY_PRECEDENCE_ORDER default value

Advisor.DEFAULT_CHAT_MEMORY_PRECEDENCE_ORDER changed from Ordered.HIGHEST_PRECEDENCE + 1000 to Ordered.HIGHEST_PRECEDENCE + 200, placing memory advisors at their default order outside the ToolCallingAdvisor (HIGHEST_PRECEDENCE + 300).

The ToolCallingAdvisor now manages conversation history internally across tool-call iterations by default. The memory advisor only stores the final user/assistant exchange, never writing tool-call messages to the ChatMemoryRepository. This is the correct default because most repository implementations do not support those message types.

If you need memory inside the loop (e.g. with InMemoryChatMemoryRepository), explicitly set the advisor order above ToolCallingAdvisor.DEFAULT_ORDER and call .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.

ツール呼び出し

除去: internalToolExecutionEnabled from ToolCallingChatOptions

The internalToolExecutionEnabled option has been removed from ToolCallingChatOptions and all provider-specific ChatOptions classes (e.g. OpenAiChatOptions, AnthropicChatOptions). The corresponding Spring Boot configuration property spring.ai.<provider>.chat.internal-tool-execution-enabled has also been removed.

インパクト

Code that sets .internalToolExecutionEnabled(false) to opt into user-controlled tool execution will no longer compile. Code that sets .internalToolExecutionEnabled(true) (explicitly enabling the internal loop) will no longer compile, and the behaviour it implied no longer exists — per-model internal tool execution has been removed from all ChatModel implementations.

マイグレーション

Remove all calls to .internalToolExecutionEnabled(…​). The recommended approaches are:

  • ToolCallingAdvisor via ChatClient (推奨) — auto-registered when tools are present; no flag needed.

  • User-controlled loop via ChatModel directly — simply invoke ChatModel without ToolCallingAdvisor. Tool calls will not be executed automatically; check chatResponse.hasToolCalls() yourself and drive the loop with 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 (previously deprecated since 2.0.0) and its default implementation DefaultToolExecutionEligibilityPredicate have been removed. These interfaces combined an options-based policy check (internalToolExecutionEnabled) with a response check (hasToolCalls()). Since the options-based flag is gone, there is no replacement at the ChatModel level.

マイグレーション

If you implemented ToolExecutionEligibilityPredicate to customize when tool execution fires, migrate to ToolExecutionEligibilityChecker (see below) and supply it to ToolCallingAdvisor.

新規: ToolExecutionEligibilityChecker の ToolCallingAdvisor

ToolExecutionEligibilityChecker (Function<ChatResponse, Boolean>) can now be set on ToolCallingAdvisor.Builder to customize when the tool-call loop iterates. The default is chatResponse → chatResponse != null && chatResponse.hasToolCalls().

This is the extension point for provider-specific stop-reason logic (e.g. checking a finish reason in addition to tool-call presence):

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

Spring Boot users can provide a ToolExecutionEligibilityChecker bean; it will be picked up automatically by the auto-configured ToolCallingAdvisor.Builder:

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

新規: spring.ai.chat.client.tool-calling.enabled Property

A new spring.ai.chat.client.tool-calling.enabled property (default true) controls whether the ToolCallingAdvisor is auto-registered by the auto-configured ChatClient. Set it to false to disable automatic tool execution for all calls — tools are still sent to the AI model as definitions, but tool call responses are not executed automatically.

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

This is a global alternative to using AdvisorParams.toolCallingAdvisorAutoRegister(false) on every individual call.

JDBC Chat Memory sequence_id Column

The JdbcChatMemoryRepository schema adds a sequence_id BIGINT column that determines message ordering within a conversation. Previously, ordering relied on the timestamp column, but TIMESTAMP precision differs across databases — on MySQL and MariaDB the default precision is one second, so messages saved within the same second were returned in a non-deterministic order. A dedicated integer sequence orders identically across every supported database.

The timestamp column is retained. It now stores the message creation time and is exposed in the message metadata under the JdbcChatMemoryRepository.CONVERSATION_TS key (a java.time.Instant), so applications can display when a message was created. The timestamp is preserved across saves: re-saving a conversation keeps each existing message’s original creation time.

インパクト

  • The SPRING_AI_CHAT_MEMORY table gains a sequence_id column (BIGINT, or NUMBER(19) on Oracle and INTEGER on SQLite) and a SPRING_AI_CHAT_MEMORY_CONVERSATION_ID_SEQUENCE_ID_IDX index. The timestamp column and its index are unchanged.

  • Existing tables created by Spring AI 1.x require the new column before they will work, since messages are now ordered by sequence_id.

  • Messages read from the repository now carry their creation timestamp in metadata. Because the metadata differs, a retrieved message is no longer equal (Message.equals) to an otherwise-identical message constructed in code. Code that compares messages by value, or relies on message identity in sets or maps, should account for this.

マイグレーション

The change is additive: add the new column and backfill it from the existing per-conversation order. No data is lost and the timestamp column is untouched. For 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);

Adapt the identifier quoting and the row-identity expression (ctid above) to your database. The ROW_NUMBER() OVER (PARTITION BY conversation_id ORDER BY <timestamp>) pattern reproduces the existing per-conversation order on every supported engine. Alternatively, since chat memory holds recent conversation context rather than permanent history, you can drop and recreate the table from the updated schema-<platform>.sql script.

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

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

Options classes (like ChatOptions, EmbeddingOptions, etc.) are now strictly immutable. Collections within options (like toolCallbacks、stopSequences、customHeaders) are now stored as unmodifiable collections. Additionally, nullable collections are now used instead of empty ones to better represent the absence of a value.

インパクト

  • ChatOptions#copy() and *Options#fromOptions(*Options) methods have been removed because options are now strictly immutable.

  • Modifying collections returned by options getter will throw an UnsupportedOperationException.

マイグレーション

To create a modified copy of an options instance, use the mutate() method instead of copy() or fromOptions():

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

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

Default Values Moved to Options Constructors

Default values for options (like default model names, temperatures, etc.) have been moved from the Model implementations and *Properties configuration classes to the options constructors themselves. Default configuration properties in *Properties classes have been removed as they are no longer needed and should be consistent with the options-level defaults.

インパクト

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

  • Default values are no longer duplicated in *Properties classes.

マイグレーション

Use getOptions() instead of getDefaultOptions() when retrieving the default options for a model:

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

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

Configuration Properties Flattening

Building on the changes introduced in 2.0.0-M6 for Chat models, the configuration properties for all other models (Embedding, Image, Audio, Moderation, OCR, etc.) no longer use the .options prefix. For example, the former spring.ai.openai.embedding.options.model is now spring.ai.openai.embedding.model. Deprecated configuration properties are provided for the .options variants to ensure a smoother migration experience.

インパクト

  • The getOptions() method in *Properties classes is deprecated.

  • The nested Options classes within *Properties are deprecated.

  • The toOptions() method has been moved from the nested Options class to the root *Properties class.

マイグレーション

Update your application.properties or application.yml to remove the .options segment from the property keys.

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

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

In Java code, use the root properties class directly to access options or call toOptions():

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

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

Renamed N() to n() in Options Builders

The N() builder method in various *Options and configuration properties classes has been renamed to n() to align with Java naming conventions.

インパクト

  • Any Java code calling .N(value) on these builders will fail to compile.

マイグレーション

Update your code to call .n(value) instead.

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

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

Minimax dedicated support superseded by Anthropic support

Minimax dedicated support has been removed in favor of using Anthropic support as recommended by Minimax themselves (英語) . Please use the Spring AI Anthropic support instead, configuring it with the https://api.minimax.io/anthropic base URL and MiniMax models. Embeddings are not support anymore.

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)

除去: JSON Methods from ModelOptionsUtils

The following members of ModelOptionsUtils have been removed, since model options no longer depend on Jackson directly.

Removed member 置換文字列

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)

インパクト

Code that references the removed fields or methods will fail to compile.

マイグレーション 
// 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 (in org.springframework.ai.mcp.annotation.method.tool.utils) has been deleted. Its functionality is now covered by 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 Elicitation API: TypeReference Replaced by ParameterizedTypeReference

The elicit(…​) overloads that previously accepted tools.jackson.core.type.TypeReference<T> in McpAsyncRequestContext and McpSyncRequestContext now accept org.springframework.core.ParameterizedTypeReference<T>.

インパクト

Any code that calls these methods with a Jackson TypeReference will fail to compile.

Affected method signatures:

  • McpAsyncRequestContext.elicit(TypeReference<T>)

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

  • McpSyncRequestContext.elicit(TypeReference<T>)

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

マイグレーション

Replace the Jackson TypeReference anonymous class with a Spring ParameterizedTypeReference anonymous class:

// 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>>() {});

The same change applies to 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 Embedding: GoogleGenAiEmbeddingConnectionDetails Package Change

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

インパクト

Any code that directly imports GoogleGenAiEmbeddingConnectionDetails will fail to compile.

マイグレーション

Update the import statement:

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

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

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

ChatClient ツール呼び出し

新規: 自動 ToolCallingAdvisor 登録

ChatClient は、呼び出し時にツールが構成されると (.tools(…​)、.toolCallbacks(…​)、ビルダーで設定されたデフォルト値経由)、アドバイザーチェーンに ToolCallingAdvisor を自動的に登録するようになりました。以前は、呼び出し元が ToolCallingAdvisor を手動で追加する必要がありました。

インパクト

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

マイグレーション

Remove the explicit ToolCallingAdvisor from the chain and let auto-registration handle it. If you need a custom configuration, either supply a pre-configured ToolCallingAdvisor.Builder at ChatClient construction time (see the Customizing the Default ToolCallingAdvisor section), or disable auto-registration and register the advisor manually:

// 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 Marker Interface

A ToolAdvisor marker interface has been added. ToolCallingAdvisor implements it. DefaultChatClient checks for this marker to decide whether to auto-register a ToolCallingAdvisor — if any advisor in the chain already implements ToolAdvisor, auto-registration is skipped.

Custom advisors that own the tool-call lifecycle should implement ToolAdvisor to prevent a duplicate ToolCallingAdvisor from being added automatically.

新規: MemoryAdvisor Marker Interface

A MemoryAdvisor marker interface has been added. BaseChatMemoryAdvisor now extends it. DefaultChatClient uses this marker to detect downstream memory advisors and disable the `ToolCallingAdvisor’s internal conversation history when one is present.

Custom memory advisors that do not extend BaseChatMemoryAdvisor but should integrate with the tool-call auto-registration logic should implement MemoryAdvisor.

新規: ChatClient.builder() Overload for Custom ToolCallingAdvisor Configuration

A new 5-argument ChatClient.builder() static method and a matching DefaultChatClientBuilder constructor accept a ToolCallingAdvisor.Builder<?> to configure the advisor used during auto-registration:

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

Spring Boot users should prefer one of the following instead:

  • Set spring.ai.chat.client.tool-calling.advisor-order to control the advisor’s position in the chain.

  • Declare a ToolCallingAdvisor.Builder<?> bean to fully replace the auto-configured builder (suppressed via @ConditionalOnMissingBean).

除去: ToolSpec Consumer API on ChatClient

The tools(Consumer<ToolSpec>) / defaultTools(Consumer<ToolSpec>) API and the ChatClient.ToolSpec interface have been removed. The tools(Object…​) / defaultTools(Object…​) methods now directly accept ToolCallback、ToolCallbackProvider、@Tool -annotated POJO instances, and collections or arrays of any of these types. Context is set separately via the dedicated toolContext() / defaultToolContext() methods.

マイグレーション 
// 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();

The individual toolCallbacks() methods on ChatClientRequestSpec and defaultToolCallbacks() on ChatClient.Builder are deprecated in favour of tools(Object…​) / defaultTools(Object…​).

変更: MethodToolCallbackProvider throws IllegalArgumentException instead of IllegalStateException

MethodToolCallbackProvider now throws IllegalArgumentException (instead of IllegalStateException) in two cases:

  • When a tool object has no @Tool -annotated methods.

  • When multiple tool objects produce callbacks with duplicate names.

インパクト

Code that catches IllegalStateException from MethodToolCallbackProvider (directly or via ToolCallbacks.from()) must be updated.

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

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

除去: Spring Bean Tool Resolution (SpringBeanToolCallbackResolver)

SpringBeanToolCallbackResolver and the pattern of declaring bare Function / Supplier / Consumer beans and referencing them by name via toolNames() have been removed. The toolNames() method has been removed from all chat options classes and from ChatClient.

マイグレーション

Declare ToolCallback beans directly instead of raw functional beans:

// 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();
}

Then register the bean directly with tools():

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

Alternatively, use @Tool -annotated methods for the declarative approach (see Tools API ).

クラウドバインディング

The spring-ai-spring-cloud-bindings module that provided integration for github.com/spring-cloud/spring-cloud-bindings (英語) has been removed.

BeanOutputConverter JSON Schema Generation

BeanOutputConverter now delegates JSON Schema generation to JsonSchemaGenerator, aligning structured output conversion with the JSON Schema behavior used for tool calling.

インパクト

  • Kotlin properties that are optional in their primary constructor (nullable or declared with a default value) are no longer included in the JSON Schema required array.

  • Properties annotated with @JsonProperty(required = false), including @JsonProperty declarations where required is not specified, are no longer treated as required.

  • Generated schemas now include OpenAPI-style format hints for primitive types (e.g., int32 for int, int64 for long, date-time for LocalDateTime), matching the format conventions used for tool calling.

  • The BeanOutputConverter.postProcessSchema(JsonNode) extension point has been removed. Custom subclasses overriding this method will fail to compile.

マイグレーション

To customize JSON Schema generation, override BeanOutputConverter.generateSchema() instead. Subclasses can post-process the default schema by delegating to 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 Support

The Azure Cosmos DB vector store (spring-ai-azure-cosmos-db-store) and chat memory repository (spring-ai-model-chat-memory-repository-cosmos-db) modules, along with their corresponding auto-configurations and starters, have been removed from the Spring AI project.

Azure Cosmos DB support is now available as an external module maintained by the Azure Cosmos DB team. See azurecosmosdb.github.io/spring-ai/docs/index.html (英語) for documentation and dependency coordinates.

MCP SDK 2.0.0-M3

Spring AI now depends on MCP SDK 2.0.0-M3, which makes previously optional fields mandatory and enforces them at construction time via Assert.notNull() in compact record constructors.

Breaking: CreateMessageResult — model now required

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

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

Breaking: CreateMessageRequest — maxTokens now required

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

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

Deprecated Builder API

The following no-arg constructors and builder() methods are deprecated in favour of factory methods that require mandatory arguments upfront:

非推奨 置換文字列

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)

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

オプションとプロパティ

構成プロパティでは、.options は使用されなくなりました。たとえば、以前の spring.ai.openai.chat.options.model は spring.ai.openai.chat.model に変更されています。よりスムーズな移行を実現するために、.options の構成プロパティには非推奨の設定プロパティが用意されています。

setter はオプションクラスから削除されました。代わりに builder を使用してください。

可観測性

ツール呼び出し

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

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

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

  • a new spring.ai.tool.type metric/span attribute has been introduced to capture the tool type (e.g. function).

  • a new spring.ai.tool.call.id span attribute has been introduced to capture the tool call ID, as identified by the chat model.

Removed Modules

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

The spring-ai-hanadb-store module has been removed from Spring AI as of version 2.0.0-M6.

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

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

The conversation ID is no longer optional for the built-in memory advisors (MessageChatMemoryAdvisor and VectorStoreChatMemoryAdvisor). Every call through these advisors must supply ChatMemory.CONVERSATION_ID via the advisor context. If the value is absent or null, the advisor throws an IllegalArgumentException immediately.

除去: 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() ビルダーメソッド

The .conversationId(String) builder method has been removed from MessageChatMemoryAdvisor.Builder and VectorStoreChatMemoryAdvisor.Builder. Setting a default conversation ID at construction time is no longer supported.

インパクト

これらのビルダーのいずれかで .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 has been removed. Use MessageChatMemoryAdvisor as a replacement.

インパクト

Code that imports or references PromptChatMemoryAdvisor will fail to compile.

マイグレーション

Replace PromptChatMemoryAdvisor with MessageChatMemoryAdvisor. The builder API is identical. Instead of injecting memory as plain text into the system prompt, MessageChatMemoryAdvisor includes the conversation history directly as chat messages in the prompt.

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

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

2.0.0-M5 へのアップグレード

OpenAI Java SDK 移行

2.0.0-M5 バージョン以降、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）は、バージョン 2.0.0-M5 以降、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）は、バージョン 2.0.0-M5 以降、Spring AI から削除されました。

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

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

The related modules can now be found at github.com/oracle/spring-cloud-oracle/tree/main/spring-ai-oracle (英語) .

ChatOptions の取り扱い

ユーザーは ChatModels と 2 つの方法でやり取りできます。

Starting with Spring AI 2.0.0.M5, when using the ChatModel approach, options set in the prompt need to be of the concrete type used by the concrete model (e.g. AnthropicChatOptions when using AnthropicChatModel) and need to be either "full" (i.e. all relevant fields set) or null (in which case the default options set in the model will be used).

The ability to "merge" options has been moved to ChatClient (using a ChatOptions.Builder or more specific type) and happens prior to the first advisor being called.

Code that previously used a "half constructed" instance of ChatOptions now needs to an instance of Builder built in a similar way:

// Old
ChatClient client = ...;
ChatOptions opts = AnthropicChatOptions.builder()
    .maxTokens(100)
    .temperature(0.7)
    .disableParallelToolUse(true)
    .build();
String response = client.prompt("Tell me a joke")
    .options(opts)
    .call().content();

// New
ChatClient client = ...;
var customizer =  AnthropicChatOptions.builder()
    .maxTokens(100)
    .temperature(0.7)
    .disableParallelToolUse(true);
String response = client.prompt("Tell me a joke")
    .options(customizer)
    .call().content();

To easily merge a "delta" of options represented by a ChatOptions.Builder with the model’s default options at the ChatModel.call() level, simply use the following construct:

ChatModel model = ...;
var customizer =  AnthropicChatOptions.builder()
    .maxTokens(100)
    .temperature(0.7)
    .disableParallelToolUse(true);
Prompt prompt = Prompt.builder().message("Tell me a joke")
    .options(model.getDefaultOptions().mutate().combineWith(customize).build())
    .build();
var response = model.call(prompt);

MCP Java SDK Upgraded to 2.0.0

Spring AI 2.0.0-M5 upgrades the MCP Java SDK from 1.1.x to 2.0.0. This release introduces several breaking changes at the SDK level that may affect applications that interact with MCP types directly.

Server-Side Tool Input Validation Enabled by Default

MCP servers now validate incoming tool arguments against the tool’s JSON schema before invoking the tool handler. Failed validation produces a CallToolResult with isError=true and a descriptive error message.

インパクト

Existing MCP servers that previously accepted loosely-typed or missing tool arguments may now return validation errors to clients that send non-conforming arguments.

マイグレーション

Ensure that your tool definitions carry accurate JSON schemas and that all clients send conforming arguments. To disable validation and restore the pre-2.0 behavior, set validateToolInputs(false) on the server builder:

McpServer.sync(transportProvider)
    .validateToolInputs(false)
    .tool(myTool, handler)
    .build();
When using @McpTool annotations, Spring AI generates JSON schemas from method parameters automatically. These schemas are compatible with the built-in validator and require no extra action.

Tool.inputSchema Changed from JsonSchema to Map<String, Object>

McpSchema.Tool.inputSchema() (and outputSchema()) now returns Map<String, Object> instead of the former JsonSchema record. This allows arbitrary JSON Schema dialect keywords ($ref, unevaluatedProperties, vendor extensions) to round-trip without being trimmed.

インパクト

Code that uses tool.inputSchema() as a JsonSchema object will fail to compile.

マイグレーション

Switch to Map<String, Object>:

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

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

When constructing tools via McpSchema.Tool.Builder, the deprecated inputSchema(JsonSchema) helper is still available for backwards compatibility, but prefer inputSchema(Map) or inputSchema(McpJsonMapper, String).

Applications that use @McpTool annotations or Spring AI’s SyncMcpToolProvider / AsyncMcpToolProvider are not affected — Spring AI handles schema generation internally.

Builder.customizeRequest() Removed from HTTP Client Transports

The deprecated Builder.customizeRequest() method has been removed from HttpClientSseClientTransport.Builder and HttpClientStreamableHttpTransport.Builder.

インパクト

Any code calling .customizeRequest() directly on these builder types will fail to compile.

マイグレーション

Replace customizeRequest() with httpRequestCustomizer() (sync) or asyncHttpRequestCustomizer() (async):

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

// After
HttpClientSseClientTransport.builder(baseUrl)
    .httpRequestCustomizer(req -> req.header("Authorization", "Bearer token"))
    .build();
If you already migrated to the McpClientCustomizer<B> API introduced in 2.0.0-M3, no further action is required.

Sealed MCP Schema Interfaces Removed

The following interfaces are no longer sealed: McpSchema.JSONRPCMessage、McpSchema.Request、McpSchema.Result、McpSchema.Notification、McpSchema.ResourceContents、McpSchema.CompleteReference、McpSchema.Content.

インパクト

Exhaustive switch expressions over these types that relied on the sealed hierarchy for completeness no longer compile without a default branch.

マイグレーション

Add a default branch to any exhaustive switch over these types:

// 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);
};
This change is unlikely to affect most Spring AI users who interact with MCP through annotations or Spring AI’s higher-level abstractions.

Unified Cache Usage Metrics on Usage

The org.springframework.ai.chat.metadata.Usage interface gains two default methods, getCacheReadInputTokens() and getCacheWriteInputTokens(). Both return null when the provider doesn’t report a value.

Anthropic, Bedrock Converse, OpenAI, and Google GenAI populate them: Anthropic and Bedrock in both directions, OpenAI and Google for cache reads only.

Code that cast to native types or read provider-specific metadata keys for these numbers can switch to the interface methods. See プロンプトキャッシュ使用状況メトリクス for examples.

Anthropic Module Updates

spring-ai-anthropic picks up four new chat options and an SDK bump. The full reference for each is in Anthropic チャット ; the highlights:

オプション What it adds

Thinking display

Display.SUMMARIZED and Display.OMITTED on the thinkingEnabled / thinkingAdaptive builders, so Claude can use a thinking budget without surfacing the full reasoning. (GH-5642 [GitHub] (英語) )

Service tier

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

Built-in web search

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

Inference geo

inferenceGeo("us") or inferenceGeo("eu") for data-residency routing. Property spring.ai.anthropic.chat.options.inference-geo.

com.anthropic:anthropic-java is bumped from 2.16.1 (the version M3 shipped with) to 2.24.0, binary-compatible at every surface spring-ai-anthropic uses.

If you are upgrading from 1.1.x (or 1.0.x), the bigger change for the Anthropic module landed in M3. See Migrating the Anthropic Module to the Official Java SDK for the RestClient → SDK transition.

Upgrading to 2.0.0-M3

Anthropic Module Migrated to Official Java SDK

spring-ai-anthropic is now built on com.anthropic:anthropic-java instead of the hand-rolled RestClient / WebClient implementation.

For most applications the change is transparent. The Maven artifact, the spring.ai.anthropic.* configuration, and the AnthropicChatModel / AnthropicChatOptions / ChatClient API are preserved, and code that goes through ChatClient or ChatModel.call(Prompt) does not need updates.

Code that imported from org.springframework.ai.anthropic.api, constructed AnthropicChatModel with an AnthropicApi argument, or depended on the old maxTokens default does need attention.

Impact

  • org.springframework.ai.anthropic.api.AnthropicApi and all its nested record types (ChatCompletionRequest, ContentBlock, Tool, ToolChoice*, streaming event records) are gone. Code referencing these will not compile.

  • The public AnthropicChatModel(AnthropicApi, AnthropicChatOptions, …​) constructor is gone. Use AnthropicChatModel.builder().

  • AnthropicChatOptions#maxTokens defaults to 4096 instead of 500. Responses that hit the old cap will now run longer, with correspondingly higher token usage.

  • AnthropicCacheOptions, AnthropicCacheStrategy, AnthropicCacheTtl, CacheBreakpointTracker, and CacheEligibilityResolver moved out of api (and api.utils) into the root org.springframework.ai.anthropic package.

  • AnthropicCacheType, StreamHelper, and metadata.AnthropicRateLimit were removed; the equivalent SDK types (CacheControlEphemeral, AsyncStreamResponse<RawMessageStreamEvent>, RateLimitException) are used directly.

  • CitationDocument was renamed to AnthropicCitationDocument.

  • com.anthropic:anthropic-java brings com.squareup.okhttp3:okhttp onto the classpath transitively.

Migration

Update imports for the moved cache and citation classes:

Before After

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) and AnthropicCacheTtl (FIVE_MINUTES, ONE_HOUR) keep the same enum values.

Replace direct constructor usage with the builder:

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

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

If you relied on the 500 -token default to bound costs, set it explicitly:

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

Anthropic モジュールを公式 Java SDK に移行する covers the rest: direct SDK access, streaming behavior, prompt caching, citations, and removed types.

MCP アノテーションが Spring AI に移行されました

org.springaicommunity:mcp-annotations 外部ライブラリは、mcp-annotations モジュールの依存関係から削除されました。そのクラスは、新しいパッケージ構造の下、Spring AI 自体の一部となりました。

インパクト

  • すべての MCP アノテーションおよびプロバイダクラスに、新しい完全修飾名が付けられました。

  • org.springaicommunity:mcp-annotations アーティファクトは、Spring AI によって推移的に提供されなくなりました。

  • org.springaicommunity.mcp.* からインポートされたコードはすべてコンパイルに失敗します。

パッケージ名の変更

古いパッケージ 新規パッケージ

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 レシピを使用すれば、すべてのインポートと依存関係の変更を自動化できます。

Apply the migrate-to-2-0-0-M3.yaml [GitHub] (英語) recipe from the command line:

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

The recipe performs two changes automatically:

  1. 除去 the org.springaicommunity:mcp-annotations Maven dependency.

  2. Rewrites all import statements across .java files to point to the new org.springframework.ai.mcp.annotation.* packages.

To run all M3 migrations at once, use the umbrella recipe — see Running All M3 Migrations at Once.

MCP Spring Transport Modules Moved to Spring AI

The mcp-spring-webflux and mcp-spring-webmvc transport modules are no longer shipped by the MCP Java SDK. Starting with Spring AI 2.0, they are part of the Spring AI project itself.

インパクト

  • The Maven group ID for both artifacts has changed.

  • Java package names for all Spring-specific transport classes have changed.

  • The MCP Java SDK version requirement has been bumped from 0.18.x to 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>
When using the spring-ai-bom or a Spring AI MCP starter (spring-ai-starter-mcp-server-webflux、spring-ai-starter-mcp-server-webmvc、spring-ai-starter-mcp-client-webflux), no explicit version is needed — the BOM manages it automatically.

Java パッケージの再配置

All Spring-specific transport classes have moved to org.springframework.ai packages.

表 1: Server transports
クラス 古いパッケージ 新規パッケージ

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: Client transports
クラス 古いパッケージ 新規パッケージ

WebFluxSseClientTransport

io.modelcontextprotocol.client.transport

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

WebClientStreamableHttpTransport

io.modelcontextprotocol.client.transport

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

マイグレーション

Update your Java imports:

// 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;
If you rely exclusively on Spring Boot auto-configuration via the Spring AI starters, no Java code changes are required. Only update your pom.xml/build.gradle dependency coordinates as described above.

For the full MCP transport migration reference, see Spring AI 2.0 へのアップグレード。

OpenRewrite による自動移行

You can automate all Maven dependency and Java import 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.M3MigrateMcpSpringTransports \
  -Dmaven.compiler.failOnError=false
If your project declares io.modelcontextprotocol.sdk:mcp-spring-webflux or mcp-spring-webmvc without an explicit <version> (version managed via a BOM), Maven will refuse to parse the pom.xml and the recipe will never run. Pre-patch those files first, then run 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

To run all M3 migrations at once, use the umbrella recipe — see Running All M3 Migrations at Once.

MCP Client Customizer API Consolidated

McpAsyncClientCustomizer and McpSyncClientCustomizer have been removed and replaced by a single generic interface McpClientCustomizer<B>.

インパクト

  • McpAsyncClientCustomizer no longer exists — compile error for any implementing bean.

  • McpSyncClientCustomizer no longer exists — compile error for any implementing bean.

  • McpSyncClientConfigurer and McpAsyncClientConfigurer constructors now accept List<McpClientCustomizer<…​>> instead of the old type-specific lists.

  • 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).

To run all M3 migrations at once, use the umbrella recipe — see Running All M3 Migrations at Once.

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 ToolCallAdvisor
ChatClient chatClient = ChatClient.builder()
    .defaultAdvisors(
        new ToolCallAdvisor()
            .conversationHistoryEnabled(true)  // Full history (default)
    )
    .build();

How ToolCallAdvisor Works:

The ToolCallAdvisor 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?")
    .options(ChatOptionsBuilder.builder()
        .toolContext("userId", "user123")
        .toolContext("apiKey", "secret")
        .build())
    .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.

Running All M3 Migrations at Once

The umbrella recipe MigrateToSpringAI200M3 applies all three automated M3 migrations in a single pass:

RecipeWhat it does

M3MigrateMcpAnnotations

Removes org.springaicommunity:mcp-annotations dependency and rewrites imports to org.springframework.ai.mcp.annotation.*

M3MigrateMcpSpringTransports

Updates Maven <groupId> and Java imports for the moved Spring transport modules

M3MigrateMcpClientCustomizer

Replaces McpAsyncClientCustomizer / McpSyncClientCustomizer with McpClientCustomizer<B>

If any of your pom.xml files declare io.modelcontextprotocol.sdk:mcp-spring-webflux or mcp-spring-webmvc without an explicit <version>, run the Perl pre-patch first (see OpenRewrite による自動移行 ), then execute the umbrella 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.MigrateToSpringAI200M3 \
  -Dmaven.compiler.failOnError=false

2.0.0-M2 へのアップグレード

重大な変更

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 への依存関係で十分です。

2.0.0-M1 へのアップグレード

重大な変更

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

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.options.temperature=0.7

# Example for Azure OpenAI
spring.ai.azure.openai.chat.options.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>