Skip to content

Commit 6cf2f86

Browse files
committed
Improve Embeddings API docs
1 parent 4c4e234 commit 6cf2f86

File tree

3 files changed

+73
-16
lines changed

3 files changed

+73
-16
lines changed
Loading

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings.adoc

Lines changed: 72 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -16,27 +16,83 @@ By providing straightforward methods like `embed(String text)` and `embed(Docume
1616

1717
== API Overview
1818

19-
This section provides a guide to the `EmbeddingClient` interface and associated classes.
19+
The Embedding API is built on top of the generic https://github.com/spring-projects/spring-ai/tree/main/spring-ai-core/src/main/java/org/springframework/ai/model[Spring AI Model API], which is a part of the Spring AI library.
20+
As such, the EmbeddingClient interface extends the `ModelClient` interface, which provides a standard set of methods for interacting with AI models. The `EmbeddingRequest` and `EmbeddingResponse` classes extend from the `ModelRequest` and `ModelResponse` are used to encapsulate the input and output of the embedding models, respectively.
2021

21-
=== EmbeddingClient
22-
Here is the `EmbeddingClient` interface definition:
22+
The Embedding API in turn is used by higher-level components to implement Embedding Clients for specific embedding models, such as OpenAI, Titan, Azure OpenAI, Ollie, and others.
2323

24-
```java
25-
public interface EmbeddingClient {
24+
Following diagram illustrates the Embedding API and its relationship with the Spring AI Model API and the Embedding Clients:
2625

27-
List<Double> embed(String text);
26+
image:embeddings-api.png[EmbeddingClient API]
2827

29-
List<Double> embed(Document document);
28+
=== EmbeddingClient
3029

31-
List<List<Double>> embed(List<String> texts);
30+
This section provides a guide to the `EmbeddingClient` interface and associated classes.
3231

33-
EmbeddingResponse embedForResponse(List<String> texts);
32+
[source,java]
33+
----
34+
public interface EmbeddingClient extends ModelClient<EmbeddingRequest, EmbeddingResponse> {
35+
36+
// EmbeddingResponse call(EmbeddingRequest request); from ModelClient
37+
38+
// Call method inherited from ModelClient<EmbeddingRequest, EmbeddingResponse>
39+
// and the embed methods defined below are the primary methods of the interface
40+
// the user needs to implement.
41+
42+
43+
/**
44+
* Embeds the given document's content into a vector.
45+
* @param document the document to embed.
46+
* @return the embedded vector.
47+
*/
48+
List<Double> embed(Document document);
49+
50+
/**
51+
* Embeds the given text into a vector.
52+
* @param text the text to embed.
53+
* @return the embedded vector.
54+
*/
55+
default List<Double> embed(String text) {
56+
Assert.notNull(text, "Text must not be null");
57+
return this.embed(List.of(text)).iterator().next();
58+
}
59+
60+
/**
61+
* Embeds a batch of texts into vectors.
62+
* @param texts list of texts to embed.
63+
* @return list of list of embedded vectors.
64+
*/
65+
default List<List<Double>> embed(List<String> texts) {
66+
Assert.notNull(texts, "Texts must not be null");
67+
return this.call(new EmbeddingRequest(texts, EmbeddingOptions.EMPTY))
68+
.getResults()
69+
.stream()
70+
.map(Embedding::getOutput)
71+
.toList();
72+
}
73+
74+
/**
75+
* Embeds a batch of texts into vectors and returns the {@link EmbeddingResponse}.
76+
* @param texts list of texts to embed.
77+
* @return the embedding response.
78+
*/
79+
default EmbeddingResponse embedForResponse(List<String> texts) {
80+
Assert.notNull(texts, "Texts must not be null");
81+
return this.call(new EmbeddingRequest(texts, EmbeddingOptions.EMPTY));
82+
}
83+
84+
/**
85+
* @return the number of dimensions of the embedded vectors. It is generative
86+
* specific.
87+
*/
88+
default int dimensions() {
89+
return embed("Test String").size();
90+
}
3491
35-
default int dimensions() {
36-
return embed("Test String").size();
37-
}
3892
}
39-
```
93+
----
94+
95+
4096

4197
The embed methods offer various options for converting text into embeddings, accommodating single strings, structured `Document` objects, or batches of text.
4298
The returned values are lists of doubles, representing the embeddings in a numerical vector format.
@@ -48,10 +104,11 @@ The dimensions method is a handy tool for developers to quickly ascertain the si
48104

49105
== Available Implementations
50106

51-
The `EmbeddingClient` interface has the following available implementations:
107+
Internally the various `EmbeddingClient` implementations use different low-level libraries and APIs to perform the embedding tasks. The following are some of the available implementations of the `EmbeddingClient` implementations:
52108

53-
* OpenAI: Using the https://github.com/TheoKanning/openai-java[Theo Kanning client library].
109+
* OpenAI: Using the https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-openai/src/main/java/org/springframework/ai/openai/api/OpenAiApi.java[Sprig AI OpenAiApi library].
54110
* Azure OpenAI: Using https://learn.microsoft.com/en-us/java/api/overview/azure/ai-openai-readme?view=azure-java-preview[Microsoft's OpenAI client library].
55111
* PostgresML: https://postgresml.org/docs/[PostgresML is a complete MLOps platform built on PostgreSQL]
56112
* Sentence embedding with local ONNX models: The https://djl.ai/[Deep Java Library] and the Microsoft https://onnxruntime.ai/docs/get-started/with-java.html[ONNX Java Runtime] libraries are applied to run the ONNX models and compute the embeddings in Java.
113+
* Vertex AI: Using the https://cloud.google.com/vertex-ai/docs[Google Cloud Vertex AI] client library.
57114

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/onnx.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
= ONNX
1+
= Transformers (ONNX) Embeddings
22

33
The `TransformersEmbeddingClient` is an `EmbeddingClient` implementation that locally computes https://www.sbert.net/examples/applications/computing-embeddings/README.html#sentence-embeddings-with-transformers[sentence embeddings] using a selected https://www.sbert.net/[sentence transformer].
44

0 commit comments

Comments
 (0)