Embedding Service

The EmbeddingService provides functionality to generate text embeddings using IBM watsonx.ai encoder models. It converts text inputs into dense vector representations that can be used for semantic search, similarity comparison, clustering, and retrieval-augmented generation (RAG).

How text embeddings work

A text embedding is a numerical representation of a sentence or passage as a vector of real numbers. By converting sentences to number vectors, operations on sentences become more like math equations that computers can evaluate quickly.

When an embedding model creates a vector, it assigns values that capture the semantic meaning of the text and positions the vector in a multidimensional space so that sentences with similar meanings are nearer to one another. This is what powers semantic search: unlike keyword search (which checks whether a word is present), semantic search weighs the context in which the word is used, which typically produces better results.

Generated vectors can be stored in a vector database. When the same embedding model is used to convert all documents in the database, the vector store can leverage the inherent groupings among vectors to return relevant search results quickly.

Quick Start

EmbeddingService embeddingService = EmbeddingService.builder()
    .apiKey(WATSONX_API_KEY)
    .projectId(WATSONX_PROJECT_ID)
    .baseUrl(CloudRegion.DALLAS)
    .modelId("ibm/granite-embedding-278m-multilingual")
    .build();

EmbeddingResponse response = embeddingService.embed("Hello, world!");
System.out.println(response.results().get(0).embedding());
// → [-0.029937625, 0.05433679, 0.013135133, 0.018311847, ...]

Note: To see the list of available embedding models, refer to supported encoder models. You can also query available embedding models programmatically. See Foundation Model Service and filter by function("function_embedding").

Overview

The EmbeddingService enables you to:

Embed single or multiple text inputs in one call.
Configure token truncation to handle long inputs gracefully.
Optionally return the original input text alongside each embedding vector.
Build semantic search, similarity, and RAG applications.

Service Configuration

Basic Setup

Create an EmbeddingService instance with the minimum required configuration:

EmbeddingService embeddingService = EmbeddingService.builder()
    .apiKey(WATSONX_API_KEY)
    .projectId(WATSONX_PROJECT_ID)
    .baseUrl("https://us-south.ml.cloud.ibm.com")
    .modelId("ibm/granite-embedding-278m-multilingual")
    .build();

Using CloudRegion

Instead of manually specifying the baseUrl, you can use the CloudRegion to automatically configure the correct endpoint.

EmbeddingService embeddingService = EmbeddingService.builder()
    .apiKey(WATSONX_API_KEY)
    .projectId(WATSONX_PROJECT_ID)
    .baseUrl(CloudRegion.DALLAS)
    .modelId("ibm/granite-embedding-278m-multilingual")
    .build();

Builder Parameters

Parameter	Type	Required	Description
`apiKey`	String	Conditional	API key for IBM Cloud authentication
`authenticator`	Authenticator	Conditional	Custom authentication (alternative to `apiKey`)
`projectId`	String	Conditional	Project ID where the model is deployed
`spaceId`	String	Conditional	Space ID (alternative to `projectId`)
`baseUrl`	String/CloudRegion	Yes	watsonx.ai service base URL
`modelId`	String	Yes	Embedding model ID
`timeout`	Duration	No	Request timeout (default: 60 seconds)
`logRequests`	Boolean	No	Enable request logging (default: false)
`logResponses`	Boolean	No	Enable response logging (default: false)
`httpClient`	HttpClient	No	Custom HTTP client
`verifySsl`	Boolean	No	SSL certificate verification (default: true)
`version`	String	No	API version override

Either apiKey or authenticator must be provided. Either projectId or spaceId must be specified.

Examples

Embedding a Single Input

In the simplest use case you pass a single string and retrieve its vector representation.

EmbeddingResponse response = embeddingService.embed("Embedding this!");
List<Float> vector = response.results().get(0).embedding();
System.out.println("Vector size: " + vector.size());
// → Vector size: 768

Embedding Multiple Inputs

Pass multiple strings in a single call. Results are returned in the same order as the inputs.

EmbeddingResponse response = embeddingService.embed(
    "First input",
    "Second input",
    "Third input"
);

var firstEmbedding = response.results().get(0);
var secondEmbedding = response.results().get(1);
var thirdEmbedding = response.results().get(2);

System.out.println(firstEmbedding);
// → [0.01608275, 0.033017233, 0.01521849, 0.022984304, ...]

System.out.println(secondEmbedding);
// → [-0.0025639886, 0.018150007, -8.951856E-4, 0.030161599, ...]

System.out.println(thirdEmbedding);
// → [0.024885714, -0.005718433, 0.0036718687, 0.03666839, ...]

You can also pass a List<String>:

List<String> inputs = List.of("apple", "banana", "cherry");
EmbeddingResponse response = embeddingService.embed(inputs);

Customizing Generation Parameters

You can pass any number of inputs. When the list exceeds 1,000 items the SDK automatically splits it into batches and runs them in parallel, so you do not need to manage chunking yourself. Each input must still conform to the embedding model's maximum token limit per input, so use truncateInputTokens to handle inputs that may be too long (truncation happens from the right, preserving the beginning of the text).

Use EmbeddingParameters to control token truncation and whether to include the original input text in the response.

EmbeddingParameters parameters = EmbeddingParameters.builder()
    .truncateInputTokens(512)
    .inputText(true)
    .build();

EmbeddingResponse response = embeddingService.embed(
    List.of("A very long document that might exceed the model's token limit..."),
    parameters
);

EmbeddingResponse.Result result = response.results().get(0);
System.out.println("Input text: " + result.input());
System.out.println("Vector: " + result.embedding());

Embedding Parameters

The EmbeddingParameters class allows you to fine-tune how inputs are processed.

Builder Reference

Parameter	Type	Description
`truncateInputTokens`	Integer	Maximum number of tokens per input. Inputs exceeding this limit are truncated from the right (the start is preserved).
`inputText`	Boolean	When `true`, each result includes the original input text in the `input()` field.
`modelId`	String	Override the default model for this request.
`projectId`	String	Override the default Project ID for this request.
`spaceId`	String	Override the default Space ID for this request.
`transactionId`	String	Request tracking ID.
`crypto`	String	Key reference for encrypting the inference request (e.g., IBM Key Protect CRN).

EmbeddingResponse

The EmbeddingResponse contains the generated vectors and usage metadata.

Field	Type	Description
`modelId()`	String	The model used to generate the embeddings
`createdAt()`	String	Timestamp of when the embeddings were generated
`results()`	List<Result>	One result per input, in the same order as the request
`inputTokenCount()`	Integer	Total number of input tokens processed across all inputs

Each Result in the list exposes:

Field	Type	Description
`embedding()`	List<Float>	The vector representation of the input text
`input()`	String	The original input text (only populated when `inputText(true)` is set)

How text embeddings work​

Quick Start​

Overview​

Service Configuration​

Basic Setup​

Using CloudRegion​

Builder Parameters​

Examples​

Embedding a Single Input​

Embedding Multiple Inputs​

Customizing Generation Parameters​

Embedding Parameters​

Builder Reference​

EmbeddingResponse​

Related Resources​