diff --git a/models/spring-ai-bedrock/README_COHERE_EMBEDDING.md b/models/spring-ai-bedrock/README_COHERE_EMBEDDING.md index e08e173ff..76a2f660d 100644 --- a/models/spring-ai-bedrock/README_COHERE_EMBEDDING.md +++ b/models/spring-ai-bedrock/README_COHERE_EMBEDDING.md @@ -1,74 +1,4 @@ -# 1. Bedrock Cohere Embedding +# Bedrock Cohere Embedding -## 1.1 CohereEmbeddingBedrockApi +Visit the Spring AI [Bedrock Cohere Embedding Documentation](https://docs.spring.io/spring-ai/reference/api/embeddings/bedrock-cohere-embedding.html). -[CohereEmbeddingBedrockApi](./src/main/java/org/springframework/ai/bedrock/cohere/api/CohereEmbeddingBedrockApi.java) provides is lightweight Java client on top of AWS Bedrock [Cohere Embed models](https://docs.aws.amazon.com/bedrock/latest/userguide/model-parameters-embed.html). - -Following class diagram illustrates the Llama2ChatBedrockApi interface and building blocks: - -![CohereEmbeddingBedrockApi Class Diagram](./src/test/resources/doc/Bedrock%20Cohere%20Embedding%20API.jpg) - -The CohereEmbeddingBedrockApi supports the `cohere.embed-english-v3` and `cohere.embed-multilingual-v3` models for single and batch embedding computation. - -Here is a simple snippet how to use the api programmatically: - -```java -CohereEmbeddingBedrockApi api = new CohereEmbeddingBedrockApi( - CohereEmbeddingModel.COHERE_EMBED_MULTILINGUAL_V1.id(), - EnvironmentVariableCredentialsProvider.create(), - Region.US_EAST_1.id(), new ObjectMapper()); - -CohereEmbeddingRequest request = new CohereEmbeddingRequest( - List.of("I like to eat apples", "I like to eat oranges"), - CohereEmbeddingRequest.InputType.search_document, - CohereEmbeddingRequest.Truncate.NONE); - -CohereEmbeddingResponse response = api.embedding(request); - -assertThat(response.embeddings()).hasSize(2); -assertThat(response.embeddings().get(0)).hasSize(1024); -``` - -## 1.2 BedrockCohereEmbeddingClient - -[BedrockCohereEmbeddingClient](./src/main/java/org/springframework/ai/bedrock/cohere/BedrockCohereEmbeddingClient.java) implements the Spring-Ai `EmbeddingClient` on top of the `CohereEmbeddingBedrockApi`. - -You can use like this: - -```java -@Bean -public CohereEmbeddingBedrockApi cohereEmbeddingApi() { - return new CohereEmbeddingBedrockApi(CohereEmbeddingModel.COHERE_EMBED_MULTILINGUAL_V1.id(), - EnvironmentVariableCredentialsProvider.create(), Region.US_EAST_1.id(), new ObjectMapper()); -} - -@Bean -public BedrockCohereEmbeddingClient cohereAiEmbedding(CohereEmbeddingBedrockApi cohereEmbeddingApi) { - return new BedrockCohereEmbeddingClient(cohereEmbeddingApi); -} -``` - -or you can leverage the `spring-ai-bedrock-ai-spring-boot-starter` Boot starter. For this add the following dependency: - -```xml - - spring-ai-bedrock-ai-spring-boot-starter - org.springframework.ai - 0.8.0-SNAPSHOT - -``` - -**NOTE:** You have to enable the Bedrock Cohere embedding client with `spring.ai.bedrock.cohere.embedding.enabled=true`. -By default the client is disabled. - -Use the `BedrockCohereEmbeddingProperties` to configure the Bedrock Cohere Chat client: - -| Property | Description | Default | -| ------------- | ------------- | ------------- | -| spring.ai.bedrock.aws.region | AWS region to use. | us-east-1 | -| spring.ai.bedrock.aws.accessKey | AWS credentials access key. | | -| spring.ai.bedrock.aws.secretKey | AWS credentials secret key. | | -| spring.ai.bedrock.cohere.embedding.enable | Enable Bedrock Cohere embedding client. Disabled by default | false | -| spring.ai.bedrock.cohere.embedding.model | The model id to use. See the `CohereEmbeddingModel` for the supported models. | cohere.embed-multilingual-v3 | -| spring.ai.bedrock.cohere.embedding.inputType | Prepends special tokens to differentiate each type from one another. You should not mix different types together, except when mixing types for for search and retrieval. In this case, embed your corpus with the search_document type and embedded queries with type search_query type. | search_document | -| spring.ai.bedrock.cohere.embedding.truncate | Specifies how the API handles inputs longer than the maximum token length. | NONE | diff --git a/models/spring-ai-bedrock/src/main/java/org/springframework/ai/bedrock/cohere/BedrockCohereEmbeddingClient.java b/models/spring-ai-bedrock/src/main/java/org/springframework/ai/bedrock/cohere/BedrockCohereEmbeddingClient.java index 8eecc855a..514b6385f 100644 --- a/models/spring-ai-bedrock/src/main/java/org/springframework/ai/bedrock/cohere/BedrockCohereEmbeddingClient.java +++ b/models/spring-ai-bedrock/src/main/java/org/springframework/ai/bedrock/cohere/BedrockCohereEmbeddingClient.java @@ -25,8 +25,10 @@ import org.springframework.ai.bedrock.cohere.api.CohereEmbeddingBedrockApi.Coher import org.springframework.ai.document.Document; import org.springframework.ai.embedding.AbstractEmbeddingClient; import org.springframework.ai.embedding.Embedding; +import org.springframework.ai.embedding.EmbeddingOptions; import org.springframework.ai.embedding.EmbeddingRequest; import org.springframework.ai.embedding.EmbeddingResponse; +import org.springframework.ai.model.ModelOptionsUtils; import org.springframework.util.Assert; /** @@ -41,35 +43,54 @@ public class BedrockCohereEmbeddingClient extends AbstractEmbeddingClient { private final CohereEmbeddingBedrockApi embeddingApi; - private CohereEmbeddingRequest.InputType inputType = CohereEmbeddingRequest.InputType.SEARCH_DOCUMENT; + private final BedrockCohereEmbeddingOptions defaultOptions; - private CohereEmbeddingRequest.Truncate truncate = CohereEmbeddingRequest.Truncate.NONE; + // private CohereEmbeddingRequest.InputType inputType = + // CohereEmbeddingRequest.InputType.SEARCH_DOCUMENT; + + // private CohereEmbeddingRequest.Truncate truncate = + // CohereEmbeddingRequest.Truncate.NONE; public BedrockCohereEmbeddingClient(CohereEmbeddingBedrockApi cohereEmbeddingBedrockApi) { + this(cohereEmbeddingBedrockApi, + BedrockCohereEmbeddingOptions.builder() + .withInputType(CohereEmbeddingRequest.InputType.SEARCH_DOCUMENT) + .withTruncate(CohereEmbeddingRequest.Truncate.NONE) + .build()); + } + + public BedrockCohereEmbeddingClient(CohereEmbeddingBedrockApi cohereEmbeddingBedrockApi, + BedrockCohereEmbeddingOptions options) { + Assert.notNull(cohereEmbeddingBedrockApi, "CohereEmbeddingBedrockApi must not be null"); + Assert.notNull(options, "BedrockCohereEmbeddingOptions must not be null"); this.embeddingApi = cohereEmbeddingBedrockApi; + this.defaultOptions = options; } - /** - * Cohere Embedding API input types. - * @param inputType the input type to use. - * @return this client. - */ - public BedrockCohereEmbeddingClient withInputType(CohereEmbeddingRequest.InputType inputType) { - this.inputType = inputType; - return this; - } + // /** + // * Cohere Embedding API input types. + // * @param inputType the input type to use. + // * @return this client. + // */ + // public BedrockCohereEmbeddingClient withInputType(CohereEmbeddingRequest.InputType + // inputType) { + // this.inputType = inputType; + // return this; + // } - /** - * Specifies how the API handles inputs longer than the maximum token length. If you - * specify LEFT or RIGHT, the model discards the input until the remaining input is - * exactly the maximum input token length for the model. - * @param truncate the truncate option to use. - * @return this client. - */ - public BedrockCohereEmbeddingClient withTruncate(CohereEmbeddingRequest.Truncate truncate) { - this.truncate = truncate; - return this; - } + // /** + // * Specifies how the API handles inputs longer than the maximum token length. If you + // specify LEFT or RIGHT, the + // * model discards the input until the remaining input is exactly the maximum input + // token length for the model. + // * @param truncate the truncate option to use. + // * @return this client. + // */ + // public BedrockCohereEmbeddingClient withTruncate(CohereEmbeddingRequest.Truncate + // truncate) { + // this.truncate = truncate; + // return this; + // } @Override public List embed(Document document) { @@ -80,7 +101,10 @@ public class BedrockCohereEmbeddingClient extends AbstractEmbeddingClient { public EmbeddingResponse call(EmbeddingRequest request) { Assert.notEmpty(request.getInstructions(), "At least one text is required!"); - var apiRequest = new CohereEmbeddingRequest(request.getInstructions(), this.inputType, this.truncate); + final BedrockCohereEmbeddingOptions optionsToUse = this.mergeOptions(request.getOptions()); + + var apiRequest = new CohereEmbeddingRequest(request.getInstructions(), optionsToUse.getInputType(), + optionsToUse.getTruncate()); CohereEmbeddingResponse apiResponse = this.embeddingApi.embedding(apiRequest); var indexCounter = new AtomicInteger(0); List embeddings = apiResponse.embeddings() @@ -90,4 +114,24 @@ public class BedrockCohereEmbeddingClient extends AbstractEmbeddingClient { return new EmbeddingResponse(embeddings); } + /** + * Merge the default and request options. + * @param requestOptions request options to merge. + * @return the merged options. + */ + BedrockCohereEmbeddingOptions mergeOptions(EmbeddingOptions requestOptions) { + + BedrockCohereEmbeddingOptions options = (this.defaultOptions != null) ? this.defaultOptions + : BedrockCohereEmbeddingOptions.builder() + .withInputType(CohereEmbeddingRequest.InputType.SEARCH_DOCUMENT) + .withTruncate(CohereEmbeddingRequest.Truncate.NONE) + .build(); + + if (requestOptions != null && !EmbeddingOptions.EMPTY.equals(requestOptions)) { + options = ModelOptionsUtils.merge(requestOptions, options, BedrockCohereEmbeddingOptions.class); + } + + return options; + } + } diff --git a/models/spring-ai-bedrock/src/main/java/org/springframework/ai/bedrock/cohere/BedrockCohereEmbeddingOptions.java b/models/spring-ai-bedrock/src/main/java/org/springframework/ai/bedrock/cohere/BedrockCohereEmbeddingOptions.java new file mode 100644 index 000000000..68594d40a --- /dev/null +++ b/models/spring-ai-bedrock/src/main/java/org/springframework/ai/bedrock/cohere/BedrockCohereEmbeddingOptions.java @@ -0,0 +1,89 @@ +/* + * Copyright 2024-2024 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.springframework.ai.bedrock.cohere; + +import com.fasterxml.jackson.annotation.JsonInclude; +import com.fasterxml.jackson.annotation.JsonInclude.Include; +import com.fasterxml.jackson.annotation.JsonProperty; + +import org.springframework.ai.bedrock.cohere.api.CohereEmbeddingBedrockApi.CohereEmbeddingRequest.InputType; +import org.springframework.ai.bedrock.cohere.api.CohereEmbeddingBedrockApi.CohereEmbeddingRequest.Truncate; + +/** + * @author Christian Tzolov + */ +@JsonInclude(Include.NON_NULL) +public class BedrockCohereEmbeddingOptions { + + // @formatter:off + /** + * Prepends special tokens to differentiate each type from one another. You should not mix + * different types together, except when mixing types for for search and retrieval. + * In this case, embed your corpus with the search_document type and embedded queries with + * type search_query type. + */ + private @JsonProperty("input_type") InputType inputType; + + /** + * Specifies how the API handles inputs longer than the maximum token length. If you specify LEFT or + * RIGHT, the model discards the input until the remaining input is exactly the maximum input token length for the + * model. + */ + private @JsonProperty("truncate") Truncate truncate; + // @formatter:on + + public static Builder builder() { + return new Builder(); + } + + public static class Builder { + + private BedrockCohereEmbeddingOptions options = new BedrockCohereEmbeddingOptions(); + + public Builder withInputType(InputType inputType) { + this.options.setInputType(inputType); + return this; + } + + public Builder withTruncate(Truncate truncate) { + this.options.setTruncate(truncate); + return this; + } + + public BedrockCohereEmbeddingOptions build() { + return this.options; + } + + } + + public InputType getInputType() { + return this.inputType; + } + + public void setInputType(InputType inputType) { + this.inputType = inputType; + } + + public Truncate getTruncate() { + return this.truncate; + } + + public void setTruncate(Truncate truncate) { + this.truncate = truncate; + } + +} diff --git a/models/spring-ai-bedrock/src/main/java/org/springframework/ai/bedrock/cohere/api/CohereEmbeddingBedrockApi.java b/models/spring-ai-bedrock/src/main/java/org/springframework/ai/bedrock/cohere/api/CohereEmbeddingBedrockApi.java index 59ca5ea75..682bd450a 100644 --- a/models/spring-ai-bedrock/src/main/java/org/springframework/ai/bedrock/cohere/api/CohereEmbeddingBedrockApi.java +++ b/models/spring-ai-bedrock/src/main/java/org/springframework/ai/bedrock/cohere/api/CohereEmbeddingBedrockApi.java @@ -163,7 +163,7 @@ public class CohereEmbeddingBedrockApi extends * @return The model id. */ public String id() { - return id; + return this.id; } CohereEmbeddingModel(String value) { diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/images/bedrock/bedrock-cohere-chat-api.jpg b/spring-ai-docs/src/main/antora/modules/ROOT/images/bedrock/bedrock-cohere-chat-api.jpg deleted file mode 100644 index d6a8898c2..000000000 Binary files a/spring-ai-docs/src/main/antora/modules/ROOT/images/bedrock/bedrock-cohere-chat-api.jpg and /dev/null differ diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/images/bedrock/bedrock-cohere-chat-low-level-api.jpg b/spring-ai-docs/src/main/antora/modules/ROOT/images/bedrock/bedrock-cohere-chat-low-level-api.jpg new file mode 100644 index 000000000..0e182f28a Binary files /dev/null and b/spring-ai-docs/src/main/antora/modules/ROOT/images/bedrock/bedrock-cohere-chat-low-level-api.jpg differ diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/images/bedrock/bedrock-cohere-embedding-low-level-api.jpg b/spring-ai-docs/src/main/antora/modules/ROOT/images/bedrock/bedrock-cohere-embedding-low-level-api.jpg new file mode 100644 index 000000000..cc187c2a6 Binary files /dev/null and b/spring-ai-docs/src/main/antora/modules/ROOT/images/bedrock/bedrock-cohere-embedding-low-level-api.jpg differ diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/nav.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/nav.adoc index 24814e73d..405a5c5f3 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/nav.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/nav.adoc @@ -8,10 +8,12 @@ *** xref:api/embeddings/ollama-embeddings.adoc[] *** xref:api/embeddings/azure-openai-embeddings.adoc[] *** xref:api/embeddings/postgresml-embeddings.adoc[] +*** xref:api/bedrock.adoc[Amazon Bedrock Embedding] +**** xref:api/embeddings/bedrock-cohere-embedding.adoc[] ** xref:api/chatclient.adoc[] *** xref:api/clients/openai-chat.adoc[] *** xref:api/clients/azure-openai-chat.adoc[] -*** xref:api/clients/bedrock.adoc[] +*** xref:api/bedrock.adoc[Amazon Bedrock Chat] **** xref:api/clients/bedrock/bedrock-anthropic.adoc[] **** xref:api/clients/bedrock/bedrock-llama2.adoc[] **** xref:api/clients/bedrock/bedrock-cohere.adoc[] diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/clients/bedrock.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/bedrock.adoc similarity index 87% rename from spring-ai-docs/src/main/antora/modules/ROOT/pages/api/clients/bedrock.adoc rename to spring-ai-docs/src/main/antora/modules/ROOT/pages/api/bedrock.adoc index d4f2644da..b7ba55479 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/clients/bedrock.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/bedrock.adoc @@ -1,4 +1,4 @@ -= Amazon Bedrock Chat += Amazon Bedrock link:https://docs.aws.amazon.com/bedrock/latest/userguide/what-is-bedrock.html[Amazon Bedrock] is a managed service that provides foundation models from various AI providers, available through a unified API. @@ -87,10 +87,5 @@ For more information, refer to the documentation below for each supported model. * xref:api/clients/bedrock/bedrock-anthropic.adoc[Spring AI Bedrock Anthropic Chat]: `spring.ai.bedrock.anthropic.chat.enabled=true` * xref:api/clients/bedrock/bedrock-llama2.adoc[Spring AI Bedrock Llama2 Chat]: `spring.ai.bedrock.llama2.chat.enabled=true` * xref:api/clients/bedrock/bedrock-cohere.adoc[Spring AI Bedrock Cohere Chat]: `spring.ai.bedrock.cohere.chat.enabled=true` - - -// * [Spring AI Bedrock Cohere Chat](./README_COHERE_CHAT.md) - `spring.ai.bedrock.cohere.chat.enabled=true` -// * [Spring AI Bedrock Cohere Embedding](./README_COHERE_EMBEDDING.md) - `spring.ai.bedrock.cohere.embedding.enabled=true` -// * [Spring AI Bedrock Titan Chat](./README_TITAN_CHAT.md) - `spring.ai.bedrock.titan.chat.enabled=true` -// * [Spring AI Bedrock Titan Embedding](./README_TITAN_EMBEDDING.md) - `spring.ai.bedrock.titan.embedding.enabled=true` -// * (WIP) [Spring AI Bedrock Ai21 Jurassic2 Chat](./README_JURASSIC2_CHAT.md) - `spring.ai.bedrock.jurassic2.chat.enabled=true` \ No newline at end of file +* xref:api/embeddings/bedrock-cohere-embedding.adoc[Spring AI Bedrock Cohere Embeddings]: `spring.ai.bedrock.cohere.embedding.enabled=true` +// * xref:api/clients/bedrock/bedrock-jurassic2-chat.adoc[(WIP)Spring AI Bedrock Jurassic Chat]: `spring.ai.bedrock.jurassic2.chat.enabled=true` diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/clients/bedrock/bedrock-anthropic.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/clients/bedrock/bedrock-anthropic.adoc index d97eb0409..c7610ebd7 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/clients/bedrock/bedrock-anthropic.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/clients/bedrock/bedrock-anthropic.adoc @@ -11,7 +11,7 @@ The https://aws.amazon.com/bedrock/claude[AWS Bedrock Anthropic Model Page] and == Prerequisites -Refer to the xref:api/clients/bedrock.adoc[Spring AI documentation on Amazon Bedrock] for setting up API access. +Refer to the xref:api/bedrock.adoc[Spring AI documentation on Amazon Bedrock] for setting up API access. == Auto-configuration diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/clients/bedrock/bedrock-cohere.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/clients/bedrock/bedrock-cohere.adoc index 58beea1c9..bd872cdf3 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/clients/bedrock/bedrock-cohere.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/clients/bedrock/bedrock-cohere.adoc @@ -7,7 +7,7 @@ The https://aws.amazon.com/bedrock/cohere-command-embed/[AWS Bedrock Cohere Mode == Prerequisites -Refer to the xref:api/clients/bedrock.adoc[Spring AI documentation on Amazon Bedrock] for setting up API access. +Refer to the xref:api/bedrock.adoc[Spring AI documentation on Amazon Bedrock] for setting up API access. == Auto-configuration @@ -106,7 +106,7 @@ TIP: In addition to the model specific https://github.com/spring-projects/spring https://start.spring.io/[Create] a new Spring Boot project and add the `spring-ai-bedrock-ai-spring-boot-starter` to your pom (or gradle) dependencies. -Add a `application.properties` file, under the `src/main/resources` directory, to enable and configure the Anthropic Chat client: +Add a `application.properties` file, under the `src/main/resources` directory, to enable and configure the Cohere Chat client: [source] ---- @@ -150,7 +150,7 @@ public class ChatController { == Manual Configuration -The https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-bedrock/src/main/java/org/springframework/ai/bedrock/cohere/BedrockCohereChatClient.java[BedrockCohereChatClient] implements the `ChatClient` and `StreamingChatClient` and uses the <> to connect to the Bedrock Anthropic service. +The https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-bedrock/src/main/java/org/springframework/ai/bedrock/cohere/BedrockCohereChatClient.java[BedrockCohereChatClient] implements the `ChatClient` and `StreamingChatClient` and uses the <> to connect to the Bedrock Cohere service. Add the `spring-ai-bedrock` dependency to your project's Maven `pom.xml` file: @@ -203,7 +203,7 @@ The https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-bedr Following class diagram illustrates the CohereChatBedrockApi interface and building blocks: -image::bedrock/bedrock-cohere-chat-api.jpg[CohereChatBedrockApi Class Diagram] +image::bedrock/bedrock-cohere-chat-low-level-api.jpg[align="center", width="800px"] The CohereChatBedrockApi supports the `cohere.command-light-text-v14` and `cohere.command-text-v14` models for both synchronous (e.g. `chatCompletion()`) and streaming (e.g. `chatCompletionStream()`) requests. diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/clients/bedrock/bedrock-llama2.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/clients/bedrock/bedrock-llama2.adoc index cf743bbbc..857796358 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/clients/bedrock/bedrock-llama2.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/clients/bedrock/bedrock-llama2.adoc @@ -11,7 +11,7 @@ The https://aws.amazon.com/bedrock/llama-2/[AWS Llama 2 Model Page] and https:// == Prerequisites -Refer to the xref:api/clients/bedrock.adoc[Spring AI documentation on Amazon Bedrock] for setting up API access. +Refer to the xref:api/bedrock.adoc[Spring AI documentation on Amazon Bedrock] for setting up API access. == Auto-configuration diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/azure-openai-embeddings.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/azure-openai-embeddings.adoc index a78def4ff..f19b72e70 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/azure-openai-embeddings.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/azure-openai-embeddings.adoc @@ -69,6 +69,28 @@ The prefix `spring.ai.azure.openai.embeddings` is the property prefix that confi | spring.ai.azure.openai.embedding.options.user | An identifier for the caller or end user of the operation. This may be used for tracking or rate-limiting purposes. | - |==== +TIP: All properties prefixed with `spring.ai.azure.openai.embedding.options` can be overridden at runtime by adding a request specific <> to the `EmbeddingRequest` call. + +=== Embedding Options [[embedding-options]] + +The `AzureOpenAiEmbeddingOptions` provides the configuration information for the embedding requests. +The `AzureOpenAiEmbeddingOptions` offers a builder to create the options. + +At start time use the `AzureOpenAiEmbeddingClient` constructor to set the default options used for all embedding requests. +At run-time you can override the default options, by passing a `AzureOpenAiEmbeddingOptions` instance with your to the `EmbeddingRequest` request. + +For example to override the default model name for a specific request: + +[source,java] +---- +EmbeddingResponse embeddingResponse = embeddingClient.call( + new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"), + AzureOpenAiEmbeddingOptions.builder() + .withModel("Different-Embedding-Model-Deployment-Name") + .build())); +---- + + === Sample Code This will create a `EmbeddingClient` implementation that you can inject into your class. @@ -89,7 +111,7 @@ public class EmbeddingController { private final EmbeddingClient embeddingClient; @Autowired - public ChatController(EmbeddingClient embeddingClient) { + public EmbeddingController(EmbeddingClient embeddingClient) { this.embeddingClient = embeddingClient; } @@ -146,22 +168,3 @@ EmbeddingResponse embeddingResponse = embeddingClient NOTE: the `text-embedding-ada-002` is actually the `Deployment Name` as presented in the Azure AI Portal. -=== Embedding Options - -The `AzureOpenAiEmbeddingOptions` provides the configuration information for the embedding requests. -The `AzureOpenAiEmbeddingOptions` offers a builder to create the options. - -At start time use the `AzureOpenAiEmbeddingClient` constructor to set the default options used for all embedding requests. -At run-time you can override the default options, by passing a `AzureOpenAiEmbeddingOptions` instance with your to the `EmbeddingRequest` request. - -For example to override the default model name for a specific request: - -[source,java] ----- -EmbeddingResponse embeddingResponse = embeddingClient.call( - new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"), - AzureOpenAiEmbeddingOptions.builder() - .withModel("Different-Embedding-Model-Deployment-Name") - .build())); ----- - diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/bedrock-cohere-embedding.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/bedrock-cohere-embedding.adoc new file mode 100644 index 000000000..6f2db5979 --- /dev/null +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/bedrock-cohere-embedding.adoc @@ -0,0 +1,204 @@ += Cohere Embedding + +Provides Bedrock Cohere Embedding client. +Integrate generative AI capabilities into essential apps and workflows that improve business outcomes. + +The https://aws.amazon.com/bedrock/cohere-command-embed/[AWS Bedrock Cohere Model Page] and https://docs.aws.amazon.com/bedrock/latest/userguide/what-is-bedrock.html[Amazon Bedrock User Guide] contains detailed information on how to use the AWS hosted model. + +== Prerequisites + +Refer to the xref:api/bedrock.adoc[Spring AI documentation on Amazon Bedrock] for setting up API access. + +== Auto-configuration + +Add the `spring-ai-bedrock-ai-spring-boot-starter` dependency to your project's Maven `pom.xml` file: + +[source,xml] +---- + + org.springframework.ai + spring-ai-bedrock-ai-spring-boot-starter + 0.8.0-SNAPSHOT + +---- + +or to your Gradle `build.gradle` build file. + +[source,gradle] +---- +dependencies { + implementation 'org.springframework.ai:spring-ai-bedrock-ai-spring-boot-starter:0.8.0-SNAPSHOT' +} +---- + +TIP: Refer to the xref:getting-started.adoc#_dependency_management[Dependency Management] section to add Milestone and/or Snapshot Repositories to your build file. + +=== Enable Cohere Embedding Support + +By default the Cohere model is disabled. +To enable it set the `spring.ai.bedrock.cohere.embedding.enabled` property to `true`. +Exporting environment variable is one way to set this configuration property: + +[source,shell] +---- +export SPRING_AI_BEDROCK_COHERE_EMBEDDING_ENABLED=true +---- + +=== Embedding Properties + +The prefix `spring.ai.bedrock.aws` is the property prefix to configure the connection to AWS Bedrock. + +[cols="3,4,1"] +|==== +| Property | Description | Default + +| spring.ai.bedrock.aws.region | AWS region to use. | us-east-1 +| spring.ai.bedrock.aws.access-key | AWS access key. | - +| spring.ai.bedrock.aws.secret-key | AWS secret key. | - +|==== + +The prefix `spring.ai.bedrock.cohere.embedding` (defined in `BedrockCohereEmbeddingProperties`) is the property prefix that configures the embedding client implementation for Cohere. + +[cols="3,4,1"] +|==== +| Property | Description | Default +| spring.ai.bedrock.cohere.embedding.enabled | Enable or disable support for Cohere | false +| spring.ai.bedrock.cohere.embedding.model | The model id to use. See the https://github.com/spring-projects/spring-ai/blob/056b95a00efa5b014a1f488329fbd07a46c02378/models/spring-ai-bedrock/src/main/java/org/springframework/ai/bedrock/cohere/api/CohereEmbeddingBedrockApi.java#L150[CohereEmbeddingModel] for the supported models. | cohere.embed-multilingual-v3 +| spring.ai.bedrock.cohere.embedding.options.input-type | Prepends special tokens to differentiate each type from one another. You should not mix different types together, except when mixing types for for search and retrieval. In this case, embed your corpus with the search_document type and embedded queries with type search_query type. | SEARCH_DOCUMENT +| spring.ai.bedrock.cohere.embedding.options.truncate | Specifies how the API handles inputs longer than the maximum token length. If you specify LEFT or RIGHT, the model discards the input until the remaining input is exactly the maximum input token length for the model. | NONE +|==== + +Look at the https://github.com/spring-projects/spring-ai/blob/056b95a00efa5b014a1f488329fbd07a46c02378/models/spring-ai-bedrock/src/main/java/org/springframework/ai/bedrock/cohere/api/CohereEmbeddingBedrockApi.java#L150[CohereEmbeddingModel] for other model IDs. +Supported values are: `cohere.embed-multilingual-v3` and `cohere.embed-english-v3`. +Model ID values can also be found in the https://docs.aws.amazon.com/bedrock/latest/userguide/model-ids-arns.html[AWS Bedrock documentation for base model IDs]. + +TIP: All properties prefixed with `spring.ai.bedrock.cohere.embedding.options` can be overridden at runtime by adding a request specific <> to the `EmbeddingRequest` call. + +=== Embedding Options [[embedding-options]] + +The https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-bedrock/src/main/java/org/springframework/ai/bedrock/cohere/BedrockCohereEmbeddingOptions.java[BedrockCohereEmbeddingOptions.java] provides model configurations, such as `input-type` or `truncate`. + +On start-up, the default options can be configured with the `BedrockCohereEmbeddingClient(api, options)` constructor or the `spring.ai.bedrock.cohere.embedding.options.*` properties. + +At run-time you can override the default options by adding new, request specific, options to the `EmbeddingRequest` call. +For example to override the default temperature for a specific request: + +[source,java] +---- +EmbeddingResponse embeddingResponse = embeddingClient.call( + new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"), + BedrockCohereEmbeddingOptions.builder() + .withInputType(InputType.SEARCH_DOCUMENT) + .build())); +---- + +=== Sample Controller (Auto-configuration) + +https://start.spring.io/[Create] a new Spring Boot project and add the `spring-ai-bedrock-ai-spring-boot-starter` to your pom (or gradle) dependencies. + +Add a `application.properties` file, under the `src/main/resources` directory, to enable and configure the Cohere Embedding client: + +[source] +---- +spring.ai.bedrock.aws.region=eu-central-1 +spring.ai.bedrock.aws.access-key=${AWS_ACCESS_KEY_ID} +spring.ai.bedrock.aws.secret-key=${AWS_SECRET_ACCESS_KEY} + +spring.ai.bedrock.cohere.embedding.enabled=true +spring.ai.bedrock.cohere.embedding.options.input-type=search-document +---- + +TIP: replace the `regions`, `access-key` and `secret-key` with your AWS credentials. + +This will create a `BedrockCohereEmbeddingClient` implementation that you can inject into your class. +Here is an example of a simple `@Controller` class that uses the chat client for text generations. + +[source,java] +---- +@RestController +public class EmbeddingController { + + private final EmbeddingClient embeddingClient; + + @Autowired + public EmbeddingController(EmbeddingClient embeddingClient) { + this.embeddingClient = embeddingClient; + } + + @GetMapping("/ai/embedding") + public Map embed(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) { + EmbeddingResponse embeddingResponse = this.embeddingClient.embedForResponse(List.of(message)); + return Map.of("embedding", embeddingResponse); + } +} +---- + +== Manual Configuration + +The https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-bedrock/src/main/java/org/springframework/ai/bedrock/cohere/BedrockCohereEmbeddingClient.java[BedrockCohereEmbeddingClient] implements the `EmbeddingClient` and uses the <> to connect to the Bedrock Cohere service. + +Add the `spring-ai-bedrock` dependency to your project's Maven `pom.xml` file: + +[source,xml] +---- + + org.springframework.ai + spring-ai-bedrock + 0.8.0-SNAPSHOT + +---- + +or to your Gradle `build.gradle` build file. + +[source,gradle] +---- +dependencies { + implementation 'org.springframework.ai:spring-ai-bedrock:0.8.0-SNAPSHOT' +} +---- + +TIP: Refer to the xref:getting-started.adoc#_dependency_management[Dependency Management] section to add Milestone and/or Snapshot Repositories to your build file. + +Next, create an https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-bedrock/src/main/java/org/springframework/ai/bedrock/cohere/BedrockCohereEmbeddingClient.java[BedrockCohereEmbeddingClient] and use it for text embeddings: + +[source,java] +---- +var cohereEmbeddingApi =new CohereEmbeddingBedrockApi( + CohereEmbeddingModel.COHERE_EMBED_MULTILINGUAL_V1.id(), + EnvironmentVariableCredentialsProvider.create(), Region.US_EAST_1.id(), new ObjectMapper()); + + +var embeddingClient new BedrockCohereEmbeddingClient(cohereEmbeddingApi); + +EmbeddingResponse embeddingResponse = embeddingClient + .embedForResponse(List.of("Hello World", "World is big and salvation is near")); +---- + +== Low-level CohereEmbeddingBedrockApi Client [[low-level-api]] + +The https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-bedrock/src/main/java/org/springframework/ai/bedrock/cohere/api/CohereEmbeddingBedrockApi.java[CohereEmbeddingBedrockApi] provides is lightweight Java client on top of AWS Bedrock https://docs.aws.amazon.com/bedrock/latest/userguide/model-parameters-cohere-command.html[Cohere Command models]. + +Following class diagram illustrates the CohereEmbeddingBedrockApi interface and building blocks: + +image::bedrock/bedrock-cohere-embedding-low-level-api.jpg[align="center", width="800px"] + +The CohereEmbeddingBedrockApi supports the `cohere.embed-english-v3` and `cohere.embed-multilingual-v3` models for single and batch embedding computation. + +Here is a simple snippet how to use the api programmatically: + +[source,java] +---- +CohereEmbeddingBedrockApi api = new CohereEmbeddingBedrockApi( + CohereEmbeddingModel.COHERE_EMBED_MULTILINGUAL_V1.id(), + EnvironmentVariableCredentialsProvider.create(), + Region.US_EAST_1.id(), new ObjectMapper()); + +CohereEmbeddingRequest request = new CohereEmbeddingRequest( + List.of("I like to eat apples", "I like to eat oranges"), + CohereEmbeddingRequest.InputType.search_document, + CohereEmbeddingRequest.Truncate.NONE); + +CohereEmbeddingResponse response = api.embedding(request); +---- + + diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/ollama-embeddings.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/ollama-embeddings.adoc index b51f38c4d..d3ae6156f 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/ollama-embeddings.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/ollama-embeddings.adoc @@ -78,7 +78,7 @@ The prefix `spring.ai.ollama.embedding.options` is the property prefix that conf | spring.ai.ollama.embedding.options.embedding-only | ??? | - | spring.ai.ollama.embedding.options.rope-frequency-base | ??? | - | spring.ai.ollama.embedding.options.rope-frequency-scale | ??? | - -| spring.ai.ollama.chat.options.num-thread | Sets the number of threads to use during computation. By default, Ollama will detect this for optimal performance. It is recommended to set this value to the number of physical CPU cores your system has (as opposed to the logical number of cores). | - +| spring.ai.ollama.embedding.options.num-thread | Sets the number of threads to use during computation. By default, Ollama will detect this for optimal performance. It is recommended to set this value to the number of physical CPU cores your system has (as opposed to the logical number of cores). | - | spring.ai.ollama.embedding.options.num-keep | ??? | - | spring.ai.ollama.embedding.options.seed | Sets the random number seed to use for generation. Setting this to a specific number will make the model generate the same text for the same prompt. | 0 | spring.ai.ollama.embedding.options.num-predict | Maximum number of tokens to predict when generating text. (Default: 128, -1 = infinite generation, -2 = fill context) | 128 @@ -100,7 +100,28 @@ The prefix `spring.ai.ollama.embedding.options` is the property prefix that conf NOTE: The `spring.ai.ollama.embedding.options.*` properties are based on the https://github.com/jmorganca/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values[Ollama Valid Parameters and Values] and https://github.com/jmorganca/ollama/blob/main/api/types.go[Ollama Types] -=== Sample Controller +TIP: All properties prefixed with `spring.ai.ollama.embedding.options` can be overridden at runtime by adding a request specific <> to the `EmbeddingRequest` call. + +=== Embedding Options [[embedding-options]] + +The https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-ollama/src/main/java/org/springframework/ai/ollama/api/OllamaOptions.java[OllamaOptions.java] provides the Ollama configurations, such as the model to use, the low level GPU and CPU tunning, etc. + +The default options can be configured using the `spring.ai.ollama.embedding.options` properties as well. + +At start-time use the `OllamaEmbeddingClient#withDefaultOptions()` to configure the default options used for all embedding requests. +At run-time you can override the default options, using a `OllamaOptions` instance as part of your `EmbeddingRequest`. + +For example to override the default model name for a specific request: + +[source,java] +---- +EmbeddingResponse embeddingResponse = embeddingClient.call( + new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"), + OllamaOptions.create() + .withModel("Different-Embedding-Model-Deployment-Name")); +---- + +=== Sample Controller (Auto-configuration) This will create a `EmbeddingClient` implementation that you can inject into your class. Here is an example of a simple `@Controller` class that uses the `EmbeddingClient` implementation. @@ -167,22 +188,3 @@ EmbeddingResponse embeddingResponse = embeddingClient ---- The `OllamaOptions` provides the configuration information for all embedding requests. - -=== Embedding Options - -The https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-ollama/src/main/java/org/springframework/ai/ollama/api/OllamaOptions.java[OllamaOptions.java] provides the Ollama configurations, such as the model to use, the low level GPU and CPU tunning, etc. - -The default options can be configured using the `spring.ai.ollama.embedding.options` properties as well. - -At start-time use the `OllamaEmbeddingClient#withDefaultOptions()` to configure the default options used for all embedding requests. -At run-time you can override the default options, using a `OllamaOptions` instance as part of your `EmbeddingRequest`. - -For example to override the default model name for a specific request: - -[source,java] ----- -EmbeddingResponse embeddingResponse = embeddingClient.call( - new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"), - OllamaOptions.create() - .withModel("Different-Embedding-Model-Deployment-Name")); ----- diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/onnx.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/onnx.adoc index 8a2c95bbd..d19b272d0 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/onnx.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/onnx.adoc @@ -29,7 +29,7 @@ The snippet exports the https://huggingface.co/sentence-transformers/all-MiniLM- In place of the all-MiniLM-L6-v2 you can pick any huggingface transformer identifier or provide direct file path. -== Using the ONNX models +== Using the ONNX Transformers models Add the `spring-ai-transformers` project to your maven dependencies: diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/openai-embeddings.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/openai-embeddings.adoc index c7e271ff2..67739292f 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/openai-embeddings.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/openai-embeddings.adoc @@ -4,7 +4,7 @@ Spring AI supports the OpenAI's text embeddings models. OpenAI’s text embeddings measure the relatedness of text strings. An embedding is a vector (list) of floating point numbers. The distance between two vectors measures their relatedness. Small distances suggest high relatedness and large distances suggest low relatedness. -== Pre-requisites +== Prerequisites You will need to create an API with OpenAI to access OpenAI embeddings models. @@ -72,7 +72,29 @@ The `spring.ai.openai.embedding.base-url` and `spring.ai.openai.embedding.api-ke Similarly, the `spring.ai.openai.embedding.base-url` and `spring.ai.openai.embedding.api-key` properties if set take precedence over the common properties. This is useful if you want to use different OpenAI accounts for different models and different model endpoints. -=== Sample Controller +TIP: All properties prefixed with `spring.ai.openai.embedding.options` can be overridden at runtime by adding a request specific <> to the `EmbeddingRequest` call. + +=== Embedding Options [[embedding-options]] + +The https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-openai/src/main/java/org/springframework/ai/openai/OpenAiEmbeddingOptions.java[OpenAiEmbeddingOptions.java] provides the OpenAI configurations, such as the model to use and etc. + +The default options can be configured using the `spring.ai.openai.embedding.options` properties as well. + +At start-time use the `OpenAiEmbeddingClient` constructor to set the default options used for all embedding requests. +At run-time you can override the default options, using a `OpenAiEmbeddingOptions` instance as part of your `EmbeddingRequest`. + +For example to override the default model name for a specific request: + +[source,java] +---- +EmbeddingResponse embeddingResponse = embeddingClient.call( + new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"), + OpenAiEmbeddingOptions.builder() + .withModel("Different-Embedding-Model-Deployment-Name") + .build())); +---- + +=== Sample Controller (Auto-configuration) This will create a `EmbeddingClient` implementation that you can inject into your class. Here is an example of a simple `@Controller` class that uses the `EmbeddingClient` implementation. @@ -147,23 +169,4 @@ EmbeddingResponse embeddingResponse = embeddingClient The `OpenAiEmbeddingOptions` provides the configuration information for the embedding requests. The options class offers a `builder()` for easy options creation. -=== Embedding Options - -The https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-openai/src/main/java/org/springframework/ai/openai/OpenAiEmbeddingOptions.java[OpenAiEmbeddingOptions.java] provides the OpenAI configurations, such as the model to use and etc. - -The default options can be configured using the `spring.ai.openai.embedding.options` properties as well. - -At start-time use the `OpenAiEmbeddingClient` constructor to set the default options used for all embedding requests. -At run-time you can override the default options, using a `OpenAiEmbeddingOptions` instance as part of your `EmbeddingRequest`. - -For example to override the default model name for a specific request: - -[source,java] ----- -EmbeddingResponse embeddingResponse = embeddingClient.call( - new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"), - OpenAiEmbeddingOptions.builder() - .withModel("Different-Embedding-Model-Deployment-Name") - .build())); ----- diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/postgresml-embeddings.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/postgresml-embeddings.adoc index 16aed87ef..2064decd6 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/postgresml-embeddings.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/postgresml-embeddings.adoc @@ -38,28 +38,54 @@ Use the `spring.ai.postgresml.embedding.options.*` properties to configure your === Embedding Properties -The prefix `spring.ai.postgres.embedding` is property prefix that configures the `EmbeddingClient` implementation for PostgresML embeddings. +The prefix `spring.ai.postgresml.embedding` is property prefix that configures the `EmbeddingClient` implementation for PostgresML embeddings. [cols="3,5,1"] |==== | Property | Description | Default -| spring.ai.postgres.embedding.options.transformer | The Huggingface transformer model to use for the embedding. | distilbert-base-uncased -| spring.ai.postgres.embedding.options.kwargs | Additional transformer specific options. | empty map -| spring.ai.postgres.embedding.options.vectorType | PostgresML vector type to use for the embedding. Two options are supported: `PG_ARRAY` and `PG_VECTOR`. | PG_ARRAY -| spring.ai.postgres.embedding.options.metadataMode | Document metadata aggregation mode | EMBED +| spring.ai.postgresml.embedding.options.transformer | The Huggingface transformer model to use for the embedding. | distilbert-base-uncased +| spring.ai.postgresml.embedding.options.kwargs | Additional transformer specific options. | empty map +| spring.ai.postgresml.embedding.options.vectorType | PostgresML vector type to use for the embedding. Two options are supported: `PG_ARRAY` and `PG_VECTOR`. | PG_ARRAY +| spring.ai.postgresml.embedding.options.metadataMode | Document metadata aggregation mode | EMBED |==== -=== Sample Controller + +TIP: All properties prefixed with `spring.ai.postgresml.embedding.options` can be overridden at runtime by adding a request specific <> to the `EmbeddingRequest` call. + +=== EmbeddingOptions [[embedding-options]] + +Use the https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-openai/src/main/java/org/springframework/ai/postgresml/PostgresMlEmbeddingOptions.java[PostgresMlEmbeddingOptions.java] to configure the `PostgresMlEmbeddingClient` with options, such as the model to use and etc. + + +On start you can pass a `PostgresMlEmbeddingOptions` to the `PostgresMlEmbeddingClient` constructor to configure the default options used for all embedding requests. + +At run-time you can override the default options, using a `PostgresMlEmbeddingOptions` in your `EmbeddingRequest`. + +For example to override the default model name for a specific request: + +[source,java] +---- + +EmbeddingResponse embeddingResponse = embeddingClient.call( + new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"), + PostgresMlEmbeddingOptions.builder() + .withTransformer("intfloat/e5-small") + .withVectorType(VectorType.PG_ARRAY) + .withKwargs(Map.of("device", "gpu")) + .build())); +---- + +=== Sample Controller (Auto-configuration) This will create a `EmbeddingClient` implementation that you can inject into your class. Here is an example of a simple `@Controller` class that uses the `EmbeddingClient` implementation. [source,application.properties] ---- -spring.ai.postgres.embedding.options.transformer=distilbert-base-uncased -spring.ai.postgres.embedding.options.vectorType=PG_ARRAY -spring.ai.postgres.embedding.options.metadataMode=EMBED -spring.ai.postgres.embedding.options.kwargs.device=cpu +spring.ai.postgresml.embedding.options.transformer=distilbert-base-uncased +spring.ai.postgresml.embedding.options.vectorType=PG_ARRAY +spring.ai.postgresml.embedding.options.metadataMode=EMBED +spring.ai.postgresml.embedding.options.kwargs.device=cpu ---- [source,java] @@ -140,27 +166,4 @@ public EmbeddingClient embeddingClient(JdbcTemplate jdbcTemplate) { } ---- -=== EmbeddingOptions - -Use the https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-openai/src/main/java/org/springframework/ai/postgresml/PostgresMlEmbeddingOptions.java[PostgresMlEmbeddingOptions.java] to configure the `PostgresMlEmbeddingClient` with options, such as the model to use and etc. - - -On start you can pass a `PostgresMlEmbeddingOptions` to the `PostgresMlEmbeddingClient` constructor to configure the default options used for all embedding requests. - -At run-time you can override the default options, using a `PostgresMlEmbeddingOptions` in your `EmbeddingRequest`. - -For example to override the default model name for a specific request: - -[source,java] ----- - -EmbeddingResponse embeddingResponse = embeddingClient.call( - new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"), - PostgresMlEmbeddingOptions.builder() - .withTransformer("intfloat/e5-small") - .withVectorType(VectorType.PG_ARRAY) - .withKwargs(Map.of("device", "gpu")) - .build())); ----- - diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/getting-started.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/getting-started.adoc index 1ae213bf2..99a2f4102 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/getting-started.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/getting-started.adoc @@ -51,7 +51,7 @@ repositories { * xref:api/clients/openai-chat.adoc[OpenAI] * xref:api/clients/azure-openai-chat.adoc[Azure OpenAI] * xref:api/clients/huggingface.adoc[HuggingFace] -* xref:api/clients/bedrock.adoc[Bedrock] +* xref:api/bedrock.adoc[Bedrock] * xref:api/clients/ollama-chat.adoc[Ollama] == Embedding Models diff --git a/spring-ai-spring-boot-autoconfigure/src/main/java/org/springframework/ai/autoconfigure/bedrock/cohere/BedrockCohereEmbeddingAutoConfiguration.java b/spring-ai-spring-boot-autoconfigure/src/main/java/org/springframework/ai/autoconfigure/bedrock/cohere/BedrockCohereEmbeddingAutoConfiguration.java index 7d2e16b7b..1477c60d6 100644 --- a/spring-ai-spring-boot-autoconfigure/src/main/java/org/springframework/ai/autoconfigure/bedrock/cohere/BedrockCohereEmbeddingAutoConfiguration.java +++ b/spring-ai-spring-boot-autoconfigure/src/main/java/org/springframework/ai/autoconfigure/bedrock/cohere/BedrockCohereEmbeddingAutoConfiguration.java @@ -1,5 +1,5 @@ /* - * Copyright 2023-2023 the original author or authors. + * Copyright 2023-2024 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -60,8 +60,7 @@ public class BedrockCohereEmbeddingAutoConfiguration { public BedrockCohereEmbeddingClient cohereEmbeddingClient(CohereEmbeddingBedrockApi cohereEmbeddingApi, BedrockCohereEmbeddingProperties properties) { - return new BedrockCohereEmbeddingClient(cohereEmbeddingApi).withInputType(properties.getInputType()) - .withTruncate(properties.getTruncate()); + return new BedrockCohereEmbeddingClient(cohereEmbeddingApi, properties.getOptions()); } } diff --git a/spring-ai-spring-boot-autoconfigure/src/main/java/org/springframework/ai/autoconfigure/bedrock/cohere/BedrockCohereEmbeddingProperties.java b/spring-ai-spring-boot-autoconfigure/src/main/java/org/springframework/ai/autoconfigure/bedrock/cohere/BedrockCohereEmbeddingProperties.java index fc1c56996..b0af03297 100644 --- a/spring-ai-spring-boot-autoconfigure/src/main/java/org/springframework/ai/autoconfigure/bedrock/cohere/BedrockCohereEmbeddingProperties.java +++ b/spring-ai-spring-boot-autoconfigure/src/main/java/org/springframework/ai/autoconfigure/bedrock/cohere/BedrockCohereEmbeddingProperties.java @@ -1,5 +1,5 @@ /* - * Copyright 2023-2023 the original author or authors. + * Copyright 2023-2024 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -16,10 +16,12 @@ package org.springframework.ai.autoconfigure.bedrock.cohere; +import org.springframework.ai.bedrock.cohere.BedrockCohereEmbeddingOptions; import org.springframework.ai.bedrock.cohere.api.CohereEmbeddingBedrockApi.CohereEmbeddingModel; import org.springframework.ai.bedrock.cohere.api.CohereEmbeddingBedrockApi.CohereEmbeddingRequest; import org.springframework.ai.bedrock.cohere.api.CohereEmbeddingBedrockApi.CohereEmbeddingRequest.InputType; import org.springframework.boot.context.properties.ConfigurationProperties; +import org.springframework.boot.context.properties.NestedConfigurationProperty; /** * Bedrock Cohere Embedding autoconfiguration properties. @@ -43,21 +45,14 @@ public class BedrockCohereEmbeddingProperties { */ private String model = CohereEmbeddingModel.COHERE_EMBED_MULTILINGUAL_V1.id(); - /** - * Prepends special tokens to differentiate each type from one another. You should not - * mix different types together, except when mixing types for for search and - * retrieval. In this case, embed your corpus with the search_document type and - * embedded queries with type search_query type. - */ - private InputType inputType = InputType.SEARCH_DOCUMENT; - - /** - * Specifies how the API handles inputs longer than the maximum token length. - */ - private CohereEmbeddingRequest.Truncate truncate = CohereEmbeddingRequest.Truncate.NONE; + @NestedConfigurationProperty + private BedrockCohereEmbeddingOptions options = BedrockCohereEmbeddingOptions.builder() + .withInputType(InputType.SEARCH_DOCUMENT) + .withTruncate(CohereEmbeddingRequest.Truncate.NONE) + .build(); public boolean isEnabled() { - return enabled; + return this.enabled; } public void setEnabled(boolean enabled) { @@ -65,31 +60,19 @@ public class BedrockCohereEmbeddingProperties { } public String getModel() { - return model; + return this.model; } public void setModel(String model) { this.model = model; } - public static String getConfigPrefix() { - return CONFIG_PREFIX; + public BedrockCohereEmbeddingOptions getOptions() { + return this.options; } - public void setInputType(InputType inputType) { - this.inputType = inputType; - } - - public InputType getInputType() { - return inputType; - } - - public CohereEmbeddingRequest.Truncate getTruncate() { - return truncate; - } - - public void setTruncate(CohereEmbeddingRequest.Truncate truncate) { - this.truncate = truncate; + public void setOptions(BedrockCohereEmbeddingOptions options) { + this.options = options; } } diff --git a/spring-ai-spring-boot-autoconfigure/src/test/java/org/springframework/ai/autoconfigure/bedrock/cohere/BedrockCohereEmbeddingAutoConfigurationIT.java b/spring-ai-spring-boot-autoconfigure/src/test/java/org/springframework/ai/autoconfigure/bedrock/cohere/BedrockCohereEmbeddingAutoConfigurationIT.java index 4aba1f8c8..f4de91be9 100644 --- a/spring-ai-spring-boot-autoconfigure/src/test/java/org/springframework/ai/autoconfigure/bedrock/cohere/BedrockCohereEmbeddingAutoConfigurationIT.java +++ b/spring-ai-spring-boot-autoconfigure/src/test/java/org/springframework/ai/autoconfigure/bedrock/cohere/BedrockCohereEmbeddingAutoConfigurationIT.java @@ -23,6 +23,8 @@ import org.junit.jupiter.api.condition.EnabledIfEnvironmentVariable; import software.amazon.awssdk.regions.Region; import org.springframework.ai.autoconfigure.bedrock.BedrockAwsConnectionProperties; +import org.springframework.ai.autoconfigure.openai.OpenAiConnectionProperties; +import org.springframework.ai.autoconfigure.openai.OpenAiEmbeddingProperties; import org.springframework.ai.bedrock.cohere.BedrockCohereEmbeddingClient; import org.springframework.ai.bedrock.cohere.api.CohereEmbeddingBedrockApi.CohereEmbeddingModel; import org.springframework.ai.bedrock.cohere.api.CohereEmbeddingBedrockApi.CohereEmbeddingRequest; @@ -47,8 +49,8 @@ public class BedrockCohereEmbeddingAutoConfigurationIT { "spring.ai.bedrock.aws.secret-key=" + System.getenv("AWS_SECRET_ACCESS_KEY"), "spring.ai.bedrock.aws.region=" + Region.US_EAST_1.id(), "spring.ai.bedrock.cohere.embedding.model=" + CohereEmbeddingModel.COHERE_EMBED_MULTILINGUAL_V1.id(), - "spring.ai.bedrock.cohere.embedding.inputType=SEARCH_DOCUMENT", - "spring.ai.bedrock.cohere.embedding.truncate=NONE") + "spring.ai.bedrock.cohere.embedding.options.inputType=SEARCH_DOCUMENT", + "spring.ai.bedrock.cohere.embedding.options.truncate=NONE") .withConfiguration(AutoConfigurations.of(BedrockCohereEmbeddingAutoConfiguration.class)); @Test @@ -91,8 +93,8 @@ public class BedrockCohereEmbeddingAutoConfigurationIT { "spring.ai.bedrock.aws.access-key=ACCESS_KEY", "spring.ai.bedrock.aws.secret-key=SECRET_KEY", "spring.ai.bedrock.aws.region=" + Region.EU_CENTRAL_1.id(), "spring.ai.bedrock.cohere.embedding.model=MODEL_XYZ", - "spring.ai.bedrock.cohere.embedding.inputType=CLASSIFICATION", - "spring.ai.bedrock.cohere.embedding.truncate=RIGHT") + "spring.ai.bedrock.cohere.embedding.options.inputType=CLASSIFICATION", + "spring.ai.bedrock.cohere.embedding.options.truncate=RIGHT") .withConfiguration(AutoConfigurations.of(BedrockCohereEmbeddingAutoConfiguration.class)) .run(context -> { var properties = context.getBean(BedrockCohereEmbeddingProperties.class); @@ -102,8 +104,8 @@ public class BedrockCohereEmbeddingAutoConfigurationIT { assertThat(awsProperties.getRegion()).isEqualTo(Region.EU_CENTRAL_1.id()); assertThat(properties.getModel()).isEqualTo("MODEL_XYZ"); - assertThat(properties.getInputType()).isEqualTo(InputType.CLASSIFICATION); - assertThat(properties.getTruncate()).isEqualTo(CohereEmbeddingRequest.Truncate.RIGHT); + assertThat(properties.getOptions().getInputType()).isEqualTo(InputType.CLASSIFICATION); + assertThat(properties.getOptions().getTruncate()).isEqualTo(CohereEmbeddingRequest.Truncate.RIGHT); assertThat(awsProperties.getAccessKey()).isEqualTo("ACCESS_KEY"); assertThat(awsProperties.getSecretKey()).isEqualTo("SECRET_KEY");