diff --git a/models/spring-ai-bedrock/README.md b/models/spring-ai-bedrock/README.md index 1b2b38072..daabdbdf0 100644 --- a/models/spring-ai-bedrock/README.md +++ b/models/spring-ai-bedrock/README.md @@ -2,7 +2,6 @@ [Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/what-is-bedrock.html) is a managed service that provides foundation models from various AI providers, available through a unified API. - Spring AI implements `API` clients for the [Bedrock models](https://docs.aws.amazon.com/bedrock/latest/userguide/model-ids-arns.html) along with implementations for the `ChatClient`, `StreamingChatClient` and the `EmbeddingClient`. The API clients provide structured, type-safe implementation for the Bedrock models, while the `ChatClient`, `StreamingChatClient` and the `EmbeddingClient` implementations provide Chat and Embedding clients compliant with the Spring-AI API. Later can be used interchangeably with the other (e.g. OpenAI, Azure OpenAI, @@ -21,64 +20,13 @@ Also Spring-AI provides Spring Auto-Configurations and Boot Starters for all cli Go to [Amazon Bedrock](https://us-east-1.console.aws.amazon.com/bedrock/home) and from the [Model Access](https://us-east-1.console.aws.amazon.com/bedrock/home?region=us-east-1#/modelaccess) menu on the left configure the access to the models you are going to use. -## Quick start +## User guides -Add the `spring-ai-bedrock-ai-spring-boot-starter` dependency to your project POM: +[Amazon Bedrock Overview](https://docs.spring.io/spring-ai/reference/api/bedrock.html) -```xml - - spring-ai-bedrock-ai-spring-boot-starter - org.springframework.ai - 0.8.0-SNAPSHOT - -``` - -### Connect to AWS Bedrock - -Use the `BedrockAwsConnectionProperties` to configure the AWS credentials and region: - -```shell -spring.ai.bedrock.aws.region=us-east-1 - -spring.ai.bedrock.aws.access-key=YOUR_ACCESS_KEY -spring.ai.bedrock.aws.secret-key=YOUR_SECRET_KEY -``` - -The `region` property is compulsory. - -The AWS credentials are resolved in the following this order: - -* Spring-AI Bedrock `spring.ai.bedrock.aws.access-key` and `spring.ai.bedrock.aws.secret-key` properties. -* Java System Properties - `aws.accessKeyId` and `aws.secretAccessKey` -* Environment Variables - `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` -* Web Identity Token credentials from system properties or environment variables -* Credential profiles file at the default location (`~/.aws/credentials`) shared by all AWS SDKs and the AWS CLI -* Credentials delivered through the Amazon EC2 container service if `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI`" environment variable is set and security manager has permission to access the variable, -* Instance profile credentials delivered through the Amazon EC2 metadata service or set the `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables. - -### Enable selected Bedrock model - -> **NOTE**: By default all models are disabled. You have to enable the chosen Bedrock models explicitly, using the `spring.ai.bedrock...enabled=true` property. - -Here are the supported `` and `` combinations: - -| Model | Chat | Chat Streaming | Embedding | -| ------------- | ------------- | ------------- | ------------- | -| llama2 | Yes | Yes | No | -| cohere | Yes | Yes | Yes | -| anthropic | Yes | Yes | No | -| jurassic2 | Yes | No | No | -| titan | Yes | Yes | Yes (no batch mode!) | - -For example to enable the bedrock Llama2 Chat client you need to set the -`spring.ai.bedrock.llama2.chat.enabled=true`. - -Next you can use the `spring.ai.bedrock...*` properties to configure each model as provided in its documentation: - -* [Spring AI Bedrock Llama2 Chat](./README_LLAMA2_CHAT.md) - `spring.ai.bedrock.llama2.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 Anthropic Chat](./README_ANTHROPIC_CHAT.md) - `spring.ai.bedrock.anthropic.chat.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` +- [Anthropic Chat Documentation](https://docs.spring.io/spring-ai/reference/api/clients/bedrock/bedrock-anthropic.html). +- [Cohere Chat Documentation](https://docs.spring.io/spring-ai/reference/api/clients/bedrock/bedrock-cohere.html). +- [Cohere Embedding Documentation](https://docs.spring.io/spring-ai/reference/api/embeddings/bedrock-cohere-embedding.html). +- [Llama2 Chat Documentation](https://docs.spring.io/spring-ai/reference/api/clients/bedrock/bedrock-llama2.html). +- [Titan Chat Documentation](https://docs.spring.io/spring-ai/reference/api/clients/bedrock/bedrock-titan.html). +- [Titan Embedding Documentation](https://docs.spring.io/spring-ai/reference/api/embeddings/bedrock-titan-embedding.html). diff --git a/models/spring-ai-bedrock/README_ANTHROPIC_CHAT.md b/models/spring-ai-bedrock/README_ANTHROPIC_CHAT.md deleted file mode 100644 index 4c55598e2..000000000 --- a/models/spring-ai-bedrock/README_ANTHROPIC_CHAT.md +++ /dev/null @@ -1,5 +0,0 @@ -# Bedrock Anthropic - -Provides Bedrock Anthropic Chat API and Spring-AI chat clients. - -Visit the Spring AI [Bedrock Anthropic Chat Documentation](https://docs.spring.io/spring-ai/reference/api/clients/bedrock/bedrock-anthropic.html). \ No newline at end of file diff --git a/models/spring-ai-bedrock/README_COHERE_CHAT.md b/models/spring-ai-bedrock/README_COHERE_CHAT.md deleted file mode 100644 index e539a0a58..000000000 --- a/models/spring-ai-bedrock/README_COHERE_CHAT.md +++ /dev/null @@ -1,5 +0,0 @@ -# Bedrock Cohere Chat - -Provides Bedrock Cohere Chat clients. - -Visit the Spring AI [Bedrock Cohere Chat Documentation](https://docs.spring.io/spring-ai/reference/api/clients/bedrock/bedrock-cohere.html). \ No newline at end of file diff --git a/models/spring-ai-bedrock/README_COHERE_EMBEDDING.md b/models/spring-ai-bedrock/README_COHERE_EMBEDDING.md deleted file mode 100644 index 76a2f660d..000000000 --- a/models/spring-ai-bedrock/README_COHERE_EMBEDDING.md +++ /dev/null @@ -1,4 +0,0 @@ -# Bedrock Cohere Embedding - -Visit the Spring AI [Bedrock Cohere Embedding Documentation](https://docs.spring.io/spring-ai/reference/api/embeddings/bedrock-cohere-embedding.html). - diff --git a/models/spring-ai-bedrock/README_LLAMA2_CHAT.md b/models/spring-ai-bedrock/README_LLAMA2_CHAT.md deleted file mode 100644 index fa7a39a82..000000000 --- a/models/spring-ai-bedrock/README_LLAMA2_CHAT.md +++ /dev/null @@ -1,5 +0,0 @@ -# Bedrock Llama2 - -Provides Bedrock Llama2 Chat API and Spring-AI chat clients. - -Visit the Spring AI [Bedrock Llama2 Chat Documentation](https://docs.spring.io/spring-ai/reference/api/clients/bedrock/bedrock-llama2.html). \ No newline at end of file diff --git a/models/spring-ai-bedrock/README_TITAN_CHAT.md b/models/spring-ai-bedrock/README_TITAN_CHAT.md deleted file mode 100644 index a01ae8deb..000000000 --- a/models/spring-ai-bedrock/README_TITAN_CHAT.md +++ /dev/null @@ -1,3 +0,0 @@ -# Bedrock Titan Chat - -Visit the Spring AI [Bedrock Titan Chat Documentation](https://docs.spring.io/spring-ai/reference/api/clients/bedrock/bedrock-titan.html). \ No newline at end of file diff --git a/models/spring-ai-bedrock/README_TITAN_EMBEDDING.md b/models/spring-ai-bedrock/README_TITAN_EMBEDDING.md deleted file mode 100644 index 7065f09f3..000000000 --- a/models/spring-ai-bedrock/README_TITAN_EMBEDDING.md +++ /dev/null @@ -1,95 +0,0 @@ -# 1. Bedrock Titan Embedding - -Use the [TitanEmbeddingBedrockApi.java](src/main/java/org/springframework/ai/bedrock/titan/api/TitanEmbeddingBedrockApi.java) Bedrock Embedding client to implement `EmbeddingClient`. - -Consult the the existing Cohere embedding client implementation. -Mind that Titan doesn't support batch embedding. You have to either emulate it (could be very expensive) or throw a not supported exception. - -## 1.1 TitanEmbeddingBedrockApi - -[TitanEmbeddingBedrockApi](./src/main/java/org/springframework/ai/bedrock/titan/api/TitanEmbeddingBedrockApi.java) provides is lightweight Java client on top of AWS Bedrock [Titan Embedding models](https://docs.aws.amazon.com/bedrock/latest/userguide/titan-embedding-models.html). - -> TitanEmbeddingBedrockApi supports Text and Image embedding. - - -> **NOTE:** TitanEmbeddingBedrockApi does NOT support batch embedding. - -Following class diagram illustrates the Llama2ChatBedrockApi interface and building blocks: - -![TitanEmbeddingBedrockApi Class Diagram](./src/test/resources/doc/Bedrock%20Titan%20Embedding%20API.jpg) - -The CohereEmbeddingBedrockApi supports the `amazon.titan-embed-image-v1` and `amazon.titan-embed-image-v1` models for single and batch embedding computation. - -Here is a simple snippet how to use the api programmatically: - -```java -TitanEmbeddingBedrockApi titanEmbedApi = new TitanEmbeddingBedrockApi( - TitanEmbeddingModel.TITAN_EMBED_TEXT_V1.id(), Region.US_EAST_1.id()); - -TitanEmbeddingRequest request = TitanEmbeddingRequest.builder() - .withInputText("I like to eat apples.") - .build(); - -TitanEmbeddingResponse response = titanEmbedApi.embedding(request); -``` - -To embed an image you need to convert it into base64 format: - -```java -TitanEmbeddingBedrockApi titanEmbedApi = new TitanEmbeddingBedrockApi( - TitanEmbeddingModel.TITAN_EMBED_IMAGE_V1.id(), Region.US_EAST_1.id()); - -byte[] image = new DefaultResourceLoader() - .getResource("classpath:/spring_framework.png") - .getContentAsByteArray(); - - -TitanEmbeddingRequest request = TitanEmbeddingRequest.builder() - .withInputImage(Base64.getEncoder().encodeToString(image)) - .build(); - -TitanEmbeddingResponse response = titanEmbedApi.embedding(request); -``` - -## 1.2 BedrockTitanEmbeddingClient - -[BedrockTitanEmbeddingClient](./src/main/java/org/springframework/ai/bedrock/titan/BedrockTitanEmbeddingClient.java) implements the Spring-Ai `EmbeddingClient` on top of the `TitanEmbeddingBedrockApi`. - -You can use like this: - -```java -@Bean -public TitanEmbeddingBedrockApi titanEmbeddingApi() { - return new TitanEmbeddingBedrockApi( - TitanEmbeddingModel.TITAN_EMBED_IMAGE_V1.id(), Region.US_EAST_1.id()); -} - -@Bean -public BedrockTitanEmbeddingClient titanEmbedding(TitanEmbeddingBedrockApi titanEmbeddingApi) { - return new BedrockTitanEmbeddingClient(titanEmbeddingApi); -} -``` - -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 Titan embedding client with `spring.ai.bedrock.titan.embedding.enabled=true`. -By default the client is disabled. - -Use the `BedrockTitanEmbeddingProperties` to configure the Bedrock Titan embedding 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.titan.embedding.enable | Enable Bedrock Titan embedding client. Disabled by default | false | -| spring.ai.bedrock.titan.embedding.model | The model id to use. See the `TitanEmbeddingModel` for the supported models. | amazon.titan-embed-image-v1 | -| spring.ai.bedrock.titan.embedding.inputType | Titan Embedding API input types. Could be either text or image (encoded in base64). | TEXT | diff --git a/models/spring-ai-bedrock/src/test/resources/doc/Bedrock Cohere Chat API.jpg b/models/spring-ai-bedrock/src/test/resources/doc/Bedrock Cohere Chat API.jpg deleted file mode 100644 index cecfae8e7..000000000 Binary files a/models/spring-ai-bedrock/src/test/resources/doc/Bedrock Cohere Chat API.jpg and /dev/null differ diff --git a/models/spring-ai-bedrock/src/test/resources/doc/Bedrock Cohere Embedding API.jpg b/models/spring-ai-bedrock/src/test/resources/doc/Bedrock Cohere Embedding API.jpg deleted file mode 100644 index 1516817e2..000000000 Binary files a/models/spring-ai-bedrock/src/test/resources/doc/Bedrock Cohere Embedding API.jpg and /dev/null differ diff --git a/models/spring-ai-bedrock/src/test/resources/doc/Bedrock Titan Chat API.jpg b/models/spring-ai-bedrock/src/test/resources/doc/Bedrock Titan Chat API.jpg deleted file mode 100644 index 0e5d6437d..000000000 Binary files a/models/spring-ai-bedrock/src/test/resources/doc/Bedrock Titan Chat API.jpg and /dev/null differ diff --git a/models/spring-ai-bedrock/src/test/resources/doc/Bedrock Titan Embedding API.jpg b/models/spring-ai-bedrock/src/test/resources/doc/Bedrock Titan Embedding API.jpg deleted file mode 100644 index 1fb9a7565..000000000 Binary files a/models/spring-ai-bedrock/src/test/resources/doc/Bedrock Titan Embedding API.jpg and /dev/null differ diff --git a/models/spring-ai-bedrock/src/test/resources/doc/Bedrock-Anthropic-Chat-API.jpg b/models/spring-ai-bedrock/src/test/resources/doc/Bedrock-Anthropic-Chat-API.jpg deleted file mode 100644 index acd5dddde..000000000 Binary files a/models/spring-ai-bedrock/src/test/resources/doc/Bedrock-Anthropic-Chat-API.jpg and /dev/null differ diff --git a/models/spring-ai-bedrock/src/test/resources/doc/Bedrock-Llama2-Chat-API.jpg b/models/spring-ai-bedrock/src/test/resources/doc/Bedrock-Llama2-Chat-API.jpg deleted file mode 100644 index 2c0d3c4f6..000000000 Binary files a/models/spring-ai-bedrock/src/test/resources/doc/Bedrock-Llama2-Chat-API.jpg and /dev/null differ diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/images/bedrock/bedrock-titan-embedding-low-level-api.jpg b/spring-ai-docs/src/main/antora/modules/ROOT/images/bedrock/bedrock-titan-embedding-low-level-api.jpg new file mode 100644 index 000000000..f0caf4f58 Binary files /dev/null and b/spring-ai-docs/src/main/antora/modules/ROOT/images/bedrock/bedrock-titan-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 7d6fcc17d..52449cfc3 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/nav.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/nav.adoc @@ -10,6 +10,7 @@ *** xref:api/embeddings/postgresml-embeddings.adoc[] *** xref:api/bedrock.adoc[Amazon Bedrock Embedding] **** xref:api/embeddings/bedrock-cohere-embedding.adoc[] +**** xref:api/embeddings/bedrock-titan-embedding.adoc[] ** xref:api/chatclient.adoc[] *** xref:api/clients/openai-chat.adoc[] *** xref:api/clients/azure-openai-chat.adoc[] diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/bedrock.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/bedrock.adoc index fa6abe2a0..e293b05e5 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/bedrock.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/bedrock.adoc @@ -74,7 +74,7 @@ Here are the supported `` and `` combinations: | llama2 | Yes | Yes | No | cohere | Yes | Yes | Yes | anthropic | Yes | Yes | No -| jurassic2 | Yes | No | No +| jurassic2 (WIP) | Yes | No | No | titan | Yes | Yes | Yes (however, no batch support) |==== @@ -89,5 +89,6 @@ For more information, refer to the documentation below for each supported model. * xref:api/clients/bedrock/bedrock-cohere.adoc[Spring AI Bedrock Cohere Chat]: `spring.ai.bedrock.cohere.chat.enabled=true` * xref:api/embeddings/bedrock-cohere-embedding.adoc[Spring AI Bedrock Cohere Embeddings]: `spring.ai.bedrock.cohere.embedding.enabled=true` * xref:api/clients/bedrock/bedrock-titan.adoc[Spring AI Bedrock Titan Chat]: `spring.ai.bedrock.titan.chat.enabled=true` +* xref:api/embeddings/bedrock-titan-embedding.adoc[Spring AI Bedrock Titan Embeddings]: `spring.ai.bedrock.titan.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/embeddings.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings.adoc index d50ee03bd..aa82d3855 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings.adoc @@ -156,3 +156,4 @@ Internally the various `EmbeddingClient` implementations use different low-level * xref:api/embeddings/onnx.adoc[Spring AI Transformers (ONNX) Embeddings] * xref:api/embeddings/postgresml-embeddings.adoc[Spring AI PostgresML Embeddings] * xref:api/embeddings/bedrock-cohere-embedding.adoc[Spring AI Bedrock Cohere Embeddings] +* xref:api/embeddings/bedrock-titan-embedding.adoc[Spring AI Bedrock Titan Embeddings] diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/bedrock-titan-embedding.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/bedrock-titan-embedding.adoc new file mode 100644 index 000000000..dd25e6d5b --- /dev/null +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/bedrock-titan-embedding.adoc @@ -0,0 +1,199 @@ += Titan Embedding + +Provides Bedrock Titan Embedding client. +link:https://aws.amazon.com/bedrock/titan/[Amazon Titan] foundation models (FMs) provide customers with a breadth of high-performing image, multimodal, and text model choices, via a fully managed API. +Amazon Titan models are created by AWS and pretrained on large datasets, making them powerful, general-purpose models built to support a variety of use cases, while also supporting the responsible use of AI. +Use them as is or privately customize them with your own data. + +NOTE: Bedrock Titan Embedding supports Text and Image embedding. + +NOTE: Bedrock Titan Embedding does NOT support batch embedding. + +The https://aws.amazon.com/bedrock/titan/[AWS Bedrock Titan 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 Titan Embedding Support + +By default the Titan embedding model is disabled. +To enable it set the `spring.ai.bedrock.titan.embedding.enabled` property to `true`. +Exporting environment variable is one way to set this configuration property: + +[source,shell] +---- +export SPRING_AI_BEDROCK_TITAN_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.titan.embedding` (defined in `BedrockTitanEmbeddingProperties`) is the property prefix that configures the embedding client implementation for Titan. + +[cols="3,4,1"] +|==== +| Property | Description | Default +| spring.ai.bedrock.titan.embedding.enabled | Enable or disable support for Titan embedding | false +| spring.ai.bedrock.titan.embedding.model | The model id to use. See the `TitanEmbeddingModel` for the supported models. | amazon.titan-embed-image-v1 +|==== + +Supported values are: `amazon.titan-embed-image-v1` and `amazon.titan-embed-text-v1`. +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]. + + +=== 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 Titan 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.titan.embedding.enabled=true +---- + +TIP: replace the `regions`, `access-key` and `secret-key` with your AWS credentials. + +This will create a `EmbeddingController` 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/titan/BedrockTitanEmbeddingClient.java[BedrockTitanEmbeddingClient] implements the `EmbeddingClient` and uses the <> to connect to the Bedrock Titan 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/titan/BedrockTitanEmbeddingClient.java[BedrockTitanEmbeddingClient] and use it for text embeddings: + +[source,java] +---- +var titanEmbeddingApi = new TitanEmbeddingBedrockApi( + TitanEmbeddingModel.TITAN_EMBED_IMAGE_V1.id(), Region.US_EAST_1.id()); + +var embeddingClient new BedrockTitanEmbeddingClient(titanEmbeddingApi); + +EmbeddingResponse embeddingResponse = embeddingClient + .embedForResponse(List.of("Hello World")); // NOTE titan does not support batch embedding. +---- + +== Low-level TitanEmbeddingBedrockApi 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/titan/api/TitanEmbeddingBedrockApi.java[TitanEmbeddingBedrockApi] provides is lightweight Java client on top of AWS Bedrock https://docs.aws.amazon.com/bedrock/latest/userguide/titan-multiemb-models.html[Titan Embedding models]. + +Following class diagram illustrates the TitanEmbeddingBedrockApi interface and building blocks: + +image::bedrock/bedrock-titan-embedding-low-level-api.jpg[align="center", width="500px"] + +The TitanEmbeddingBedrockApi supports the `amazon.titan-embed-image-v1` and `amazon.titan-embed-image-v1` models for single and batch embedding computation. + +Here is a simple snippet how to use the api programmatically: + +[source,java] +---- +TitanEmbeddingBedrockApi titanEmbedApi = new TitanEmbeddingBedrockApi( + TitanEmbeddingModel.TITAN_EMBED_TEXT_V1.id(), Region.US_EAST_1.id()); + +TitanEmbeddingRequest request = TitanEmbeddingRequest.builder() + .withInputText("I like to eat apples.") + .build(); + +TitanEmbeddingResponse response = titanEmbedApi.embedding(request); +---- + +To embed an image you need to convert it into `base64` format: + +[source,java] +---- +TitanEmbeddingBedrockApi titanEmbedApi = new TitanEmbeddingBedrockApi( + TitanEmbeddingModel.TITAN_EMBED_IMAGE_V1.id(), Region.US_EAST_1.id()); + +byte[] image = new DefaultResourceLoader() + .getResource("classpath:/spring_framework.png") + .getContentAsByteArray(); + + +TitanEmbeddingRequest request = TitanEmbeddingRequest.builder() + .withInputImage(Base64.getEncoder().encodeToString(image)) + .build(); + +TitanEmbeddingResponse response = titanEmbedApi.embedding(request); +---- \ No newline at end of file