Skip to content

Commit 86327f4

Browse files
tzolovtzolov
committed
Add a dedicated openai-embedding.adoc page
1 parent 5b4784f commit 86327f4

File tree

2 files changed

+180
-0
lines changed

2 files changed

+180
-0
lines changed

‎spring-ai-docs/src/main/antora/modules/ROOT/nav.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@
1313
** xref:api/etl-pipeline.adoc[]
1414
** xref:api/embeddings.adoc[]
1515
*** xref:api/embeddings/onnx.adoc[]
16+
*** xref:api/embeddings/openai-embeddings.adoc[]
1617
** xref:api/vectordbs.adoc[]
1718
*** xref:api/vectordbs/azure.adoc[]
1819
*** xref:api/vectordbs/chroma.adoc[]

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

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
= OpenAI Embeddings
2+
3+
Spring AI supports the OpenAI's text embeddings models.
4+
OpenAI’s text embeddings measure the relatedness of text strings.
5+
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.
6+
7+
== Getting Started
8+
9+
You will need to create an API with OpenAI to access OpenAI embeddings models.
10+
11+
Create an account at https://platform.openai.com/signup[OpenAI signup page] and generate the token on the https://platform.openai.com/account/api-keys[API Keys page].
12+
13+
The Spring AI project defines a configuration property named `spring.ai.openai.api-key` that you should set to the value of the `API Key` obtained from openai.com.
14+
15+
Exporting an environment variable is one way to set that configuration property:
16+
17+
[source,shell]
18+
----
19+
export SPRING_AI_OPENAI_API_KEY=<INSERT KEY HERE>
20+
----
21+
22+
== Configure the OpenAI Embedding Client Manually
23+
24+
Add the `spring-ai-openai` dependency to your project's Maven `pom.xml` file:
25+
[source, xml]
26+
----
27+
<dependency>
28+
<groupId>org.springframework.ai</groupId>
29+
<artifactId>spring-ai-openai</artifactId>
30+
<version>0.8.0-SNAPSHOT</version>
31+
</dependency>
32+
----
33+
34+
or to your Gradle `build.gradle` build file.
35+
36+
[source,groovy]
37+
----
38+
dependencies {
39+
implementation 'org.springframework.ai:spring-ai-openai:0.8.0-SNAPSHOT'
40+
}
41+
----
42+
43+
NOTE: The `spring-ai-openai` dependency provides access also to the `OpenAiChatClient`. For more information about the `AzureOpenAiChatClient` refer to the link:../Clients/openai.html[OpenAI Chat Client] section.
44+
45+
Next, create an `OpenAiEmbeddingClient` instance and use it to compute the similarity between two input texts:
46+
47+
[source,java]
48+
----
49+
var openAiApi = new OpenAiApi(System.getenv("OPENAI_API_KEY"));
50+
51+
var embeddingClient = new OpenAiEmbeddingClient(openAiApi)
52+
.withDefaultOptions(OpenAiEmbeddingOptions.builder()
53+
.withModel("text-embedding-ada-002")
54+
.withUser("user-6")
55+
.build());
56+
57+
EmbeddingResponse embeddingResponse = embeddingClient
58+
.embedForResponse(List.of("Hello World", "World is big and salvation is near"));
59+
----
60+
61+
The `OpenAiEmbeddingOptions` provides the configuration information for the embedding requests.
62+
The options class offers a `builder()` for easy options creation.
63+
64+
== OpenAiEmbeddingOptions
65+
66+
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] provide the OpenAI configures, such as the model to use, the temperature, the frequency penalty, etc.
67+
68+
The default options can be configured using the `spring.ai.openai.embedding.options` properties as well.
69+
70+
At start-time use the `OpenAiEmbeddingClient#withDefaultOptions()` to configure the default options used for all embedding requests.
71+
At run-time you can override the default options, using a `OpenAiEmbeddingOptions` instance as part of your `EmbeddingRequest``.
72+
73+
For example to override the default model name for a specific request:
74+
75+
[source,java]
76+
----
77+
EmbeddingResponse embeddingResponse = embeddingClient.call(
78+
new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"),
79+
OpenAiEmbeddingOptions.builder()
80+
.withModel("Different-Embedding-Model-Deployment-Name")
81+
.build()));
82+
----
83+
84+
== Spring Boot Auto-configuration
85+
86+
Spring AI provides Spring Boot auto-configuration for the Azure OpenAI Embedding Client.
87+
To enable it add the following dependency to your project's Maven `pom.xml` file:
88+
89+
[source, xml]
90+
----
91+
<dependency>
92+
<groupId>org.springframework.ai</groupId>
93+
<artifactId>spring-ai-openai-spring-boot-starter</artifactId>
94+
<version>0.8.0-SNAPSHOT</version>
95+
</dependency>
96+
----
97+
98+
or to your Gradle `build.gradle` build file.
99+
100+
[source,groovy]
101+
----
102+
dependencies {
103+
implementation 'org.springframework.ai:spring-ai-openai-spring-boot-starter:0.8.0-SNAPSHOT'
104+
}
105+
----
106+
107+
NOTE: Refer to the xref:getting-started.adoc#_dependency_management[Dependency Management] section to add Milestone and/or Snapshot Repositories to your build file.
108+
109+
The Spring AI project defines a configuration property named `spring.ai.openai.api-key` that you should set to the value of the `API Key` obtained from openai.com.
110+
111+
Exporting an environment variable is one way to set that configuration property:
112+
113+
[source,shell]
114+
----
115+
export SPRING_AI_OPENAI_API_KEY=<INSERT KEY HERE>
116+
----
117+
118+
The `spring.ai.openai.embedding.options.*` properties are used to configure the default options used for all embedding requests.
119+
120+
=== Sample Code
121+
122+
This will create a `EmbeddingClient` implementation that you can inject into your class.
123+
Here is an example of a simple `@Controller` class that uses the `EmbeddingClient` implementation.
124+
125+
[source,application.properties]
126+
----
127+
spring.ai.openai.api-key=YOUR_API_KEY
128+
spring.ai.openai.embedding.options.model=text-embedding-ada-002
129+
----
130+
131+
[source,java]
132+
----
133+
@RestController
134+
public class EmbeddingController {
135+
136+
private final EmbeddingClient embeddingClient;
137+
138+
@Autowired
139+
public ChatController(EmbeddingClient embeddingClient) {
140+
this.embeddingClient = embeddingClient;
141+
}
142+
143+
@GetMapping("/ai/embedding")
144+
public Map embed(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
145+
EmbeddingResponse embeddingResponse = this.embeddingClient.embedForResponse(List.of(message));
146+
return Map.of("embedding", embeddingResponse);
147+
}
148+
}
149+
----
150+
151+
== OpenAI Embedding Properties
152+
153+
The prefix `spring.ai.openai` is used as the property prefix that lets you connect to OpenAI.
154+
155+
[cols="3,5,3"]
156+
|====
157+
| Property | Description | Default
158+
159+
| spring.ai.openai.base-url | The URL to connect to | https://api.openai.com
160+
| spring.ai.openai.api-key | The API Key | -
161+
|====
162+
163+
164+
The prefix `spring.ai.openai.embedding` is property prefix that configures the `EmbeddingClient` implementation for OpenAI.
165+
166+
[cols="3,5,3"]
167+
|====
168+
| Property | Description | Default
169+
| spring.ai.openai.embedding.base-url | Optional overrides the spring.ai.openai.base-url to provide embedding specific url | -
170+
| spring.ai.openai.embedding.api-key | Optional overrides the spring.ai.openai.api-key to provide embedding specific api-key | -
171+
| spring.ai.openai.embedding.options.model | The model to use | text-embedding-ada-002
172+
| spring.ai.openai.embedding.options.encodingFormat | The format to return the embeddings in. Can be either float or base64. | -
173+
| spring.ai.openai.embedding.options.user | A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. | -
174+
|====
175+
176+
NOTE: You can override the common `spring.ai.openai.base-url` and `spring.ai.openai.api-key` for the `ChatClient` and `EmbeddingClient` implementations.
177+
The `spring.ai.openai.embedding.base-url` and `spring.ai.openai.embedding.api-key` properties if set take precedence over the common properties.
178+
Similarly, the `spring.ai.openai.embedding.base-url` and `spring.ai.openai.embedding.api-key` properties if set take precedence over the common properties.
179+
This is useful if you want to use different OpenAI accounts for different models and different model endpoints.

0 commit comments

Comments
 (0)