Skip to content

Commit 6be6b58

Browse files
tzolovtzolov
committed
Add a dedicated doc page for openai chat client
1 parent 86327f4 commit 6be6b58

File tree

3 files changed

+104
-39
lines changed

3 files changed

+104
-39
lines changed

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
* xref:getting-started.adoc[Getting Started]
44
* xref:api/index.adoc[]
55
** xref:api/chatclient.adoc[]
6-
*** xref:api/clients/openai.adoc[]
6+
*** xref:api/clients/openai-chat.adoc[]
77
*** xref:api/clients/azure-openai.adoc[]
88
*** xref:api/clients/bedrock.adoc[]
99
*** xref:api/clients/huggingface.adoc[]

‎spring-ai-docs/src/main/antora/modules/ROOT/pages/api/clients/openai.adoc renamed to ‎spring-ai-docs/src/main/antora/modules/ROOT/pages/api/clients/openai-chat.adoc

Lines changed: 94 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
= OpenAI
1+
= OpenAI Chat
22

33
Spring AI supports ChatGPT, the AI language model by OpenAI. ChatGPT has been instrumental in sparking interest in AI-driven text generation, thanks to its creation of industry-leading text generation models and embeddings.
44

@@ -17,11 +17,80 @@ Exporting an environment variable is one way to set that configuration property:
1717
export SPRING_AI_OPENAI_API_KEY=<INSERT KEY HERE>
1818
----
1919

20-
== Project Dependencies
20+
=== Configure the OpenAI Chat Client Manually
2121

22-
Refer to the xref:getting-started.adoc#_dependency_management[Dependency Management] section to add Milestone and/or Snapshot Repositories to your build file.
22+
Add the `spring-ai-openai` dependency to your project's Maven `pom.xml` file:
23+
[source, xml]
24+
----
25+
<dependency>
26+
<groupId>org.springframework.ai</groupId>
27+
<artifactId>spring-ai-openai</artifactId>
28+
<version>0.8.0-SNAPSHOT</version>
29+
</dependency>
30+
----
31+
32+
or to your Gradle `build.gradle` build file.
33+
34+
[source,groovy]
35+
----
36+
dependencies {
37+
implementation 'org.springframework.ai:spring-ai-openai:0.8.0-SNAPSHOT'
38+
}
39+
----
40+
41+
NOTE: The `spring-ai-openai` dependency provides access also to the `OpenAiEmbeddingClient`. For more information about the `OpenAiEmbeddingClient` refer to the link:../embeddings/openai-embeddings.html[OpenAI Embeddings Client] section.
42+
43+
Next, create an `OpenAiChatClient` instance and use it to compute the similarity between two input texts:
44+
45+
[source,java]
46+
----
47+
var openAiApi = new OpenAiApi(System.getenv("OPENAI_API_KEY"));
48+
49+
var chatClient = new OpenAiChatClient(openAiApi)
50+
.withDefaultOptions(OpenAiChatOptions.builder()
51+
.withModel("gpt-35-turbo")
52+
.withTemperature(0.4)
53+
.withMaxTokens(200)
54+
.build());
55+
56+
ChatResponse response = chatClient.call(
57+
new Prompt("Generate the names of 5 famous pirates."));
58+
59+
// Or with streaming responses
60+
Flux<ChatResponse> response = chatClient.stream(
61+
new Prompt("Generate the names of 5 famous pirates."));
62+
----
63+
64+
The `OpenAiChatOptions` provides the configuration information for the chat requests.
65+
The `OpenAiChatOptions.Builder` is fluent options builder.
66+
67+
==== OpenAiChatOptions
68+
69+
The https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-openai/src/main/java/org/springframework/ai/openai/OpenAiChatOptions.java[OpenAiChatOptions.java] provides provides the configuration information for the chat requests, such as the model to use, the temperature, the frequency penalty, etc.
70+
71+
The default options can be configured using the `spring.ai.openai.chat.options` properties as well.
2372

24-
Then add the Spring Boot Starter dependency to your project's Maven `pom.xml` build file:
73+
On start-time use the `OpenAiChatClient#withDefaultOptions()` to set the default options applicable for all chat completion requests.
74+
At run-time you can override the default options with `OpenAiChatOptions` instance in the request `Prompt`.
75+
76+
For example to override the default model name and temperature for a specific request:
77+
78+
[source,java]
79+
----
80+
ChatResponse response = chatClient.call(
81+
new Prompt(
82+
"Generate the names of 5 famous pirates.",
83+
AzureOpenAiChatOptions.builder()
84+
.withModel("gpt-4-32k")
85+
.withTemperature(0.4)
86+
.build()
87+
));
88+
----
89+
90+
=== OpenAiChatClient Auto-configuration
91+
92+
Spring AI provides Spring Boot auto-configuration for the OpenAI Chat Client.
93+
To enable it add the following dependency to your project's Maven `pom.xml` file:
2594

2695
[source, xml]
2796
----
@@ -41,12 +110,29 @@ dependencies {
41110
}
42111
----
43112

113+
NOTE: Refer to the xref:getting-started.adoc#_dependency_management[Dependency Management] section to add Milestone and/or Snapshot Repositories to your build file.
114+
115+
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.
116+
117+
Exporting an environment variable is one way to set that configuration property:
118+
119+
[source,shell]
120+
----
121+
export SPRING_AI_OPENAI_API_KEY=<INSERT KEY HERE>
122+
----
44123

45-
== Sample Code
124+
==== Sample Code
46125

47126
This will create a `ChatClient` implementation that you can inject into your class.
48127
Here is an example of a simple `@Controller` class that uses the `ChatClient` implementation.
49128

129+
[source,application.properties]
130+
----
131+
spring.ai.openai.api-key=YOUR_API_KEY
132+
spring.ai.openai.chat.options.model=gpt-35-turbo
133+
spring.ai.openai.chat.options.temperature=0.7
134+
----
135+
50136
[source,java]
51137
----
52138
@RestController
@@ -74,18 +160,11 @@ public class ChatController {
74160
}
75161
----
76162

77-
== OpenAiChatOptions
78-
79-
The http://OpenAiChatOptions.java[OpenAiChatOptions.java] allows you to configure OpenAI options, such as the model to use, the temperature, the frequency penalty, etc.
80-
You can assign the default options, at startup, to the `OpenAiChatClient` using the `withDefaultOptions()` method. You can also override the default options at runtime by passing in the `OpenAiChatOptions` object to the `Prompt` constructor.
81-
82-
The default options can be configured using the `spring.ai.openai.chat.options` properties as well.
83-
84-
== OpenAI Properties
163+
== OpenAI Chat Properties
85164

86165
The prefix `spring.ai.openai` is used as the property prefix that lets you connect to OpenAI.
87166

88-
[cols="3,5,3"]
167+
[cols="3,5,1"]
89168
|====
90169
| Property | Description | Default
91170

@@ -95,7 +174,7 @@ The prefix `spring.ai.openai` is used as the property prefix that lets you conne
95174

96175
The prefix `spring.ai.openai.chat` is the property prefix that lets you configure the `ChatClient` implementation for OpenAI.
97176

98-
[cols="3,5,3"]
177+
[cols="3,5,1"]
99178
|====
100179
| Property | Description | Default
101180

@@ -117,21 +196,7 @@ The prefix `spring.ai.openai.chat` is the property prefix that lets you configur
117196
| spring.ai.openai.chat.options.user | A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. | -
118197
|====
119198

120-
The prefix `spring.ai.openai.embedding` is property prefix that configures the `EmbeddingClient` implementation for OpenAI.
121-
122-
[cols="3,5,3"]
123-
|====
124-
| Property | Description | Default
125-
| spring.ai.openai.embedding.base-url | Optional overrides the spring.ai.openai.base-url to provide chat specific url | -
126-
| spring.ai.openai.embedding.api-key | Optional overrides the spring.ai.openai.api-key to provide chat specific api-key | -
127-
| spring.ai.openai.embedding.options.model | The model to use | text-embedding-ada-002
128-
| spring.ai.openai.embedding.options.encodingFormat | The format to return the embeddings in. Can be either float or base64. | -
129-
| spring.ai.openai.embedding.options.user | A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. | -
130-
|====
131199

132200
NOTE: You can override the common `spring.ai.openai.base-url` and `spring.ai.openai.api-key` for the `ChatClient` and `EmbeddingClient` implementations.
133201
The `spring.ai.openai.chat.base-url` and `spring.ai.openai.chat.api-key` properties if set take precedence over the common properties.
134-
Similarly, the `spring.ai.openai.embedding.base-url` and `spring.ai.openai.embedding.api-key` properties if set take precedence over the common properties.
135202
This is useful if you want to use different OpenAI accounts for different models and different model endpoints.
136-
137-
Also by default, the `spring.ai.openai.chat.options.model` is set to `gpt-35-turbo` and the `spring.ai.openai.embedding.options.model` is set to `text-embedding-ada-002`.

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

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ Exporting an environment variable is one way to set that configuration property:
1919
export SPRING_AI_OPENAI_API_KEY=<INSERT KEY HERE>
2020
----
2121

22-
== Configure the OpenAI Embedding Client Manually
22+
=== Configure the OpenAI Embedding Client Manually
2323

2424
Add the `spring-ai-openai` dependency to your project's Maven `pom.xml` file:
2525
[source, xml]
@@ -40,7 +40,7 @@ dependencies {
4040
}
4141
----
4242

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.
43+
NOTE: The `spring-ai-openai` dependency provides access also to the `OpenAiChatClient`. For more information about the `OpenAiChatClient` refer to the link:../clients/openai-chat.html[OpenAI Chat Client] section.
4444

4545
Next, create an `OpenAiEmbeddingClient` instance and use it to compute the similarity between two input texts:
4646

@@ -61,9 +61,9 @@ EmbeddingResponse embeddingResponse = embeddingClient
6161
The `OpenAiEmbeddingOptions` provides the configuration information for the embedding requests.
6262
The options class offers a `builder()` for easy options creation.
6363

64-
== OpenAiEmbeddingOptions
64+
==== OpenAiEmbeddingOptions
6565

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.
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] provides the OpenAI configures, such as the model to use, the temperature, the frequency penalty, etc.
6767

6868
The default options can be configured using the `spring.ai.openai.embedding.options` properties as well.
6969

@@ -81,7 +81,7 @@ EmbeddingResponse embeddingResponse = embeddingClient.call(
8181
.build()));
8282
----
8383

84-
== Spring Boot Auto-configuration
84+
=== OpenAiEmbeddingClient Auto-configuration
8585

8686
Spring AI provides Spring Boot auto-configuration for the Azure OpenAI Embedding Client.
8787
To enable it add the following dependency to your project's Maven `pom.xml` file:
@@ -117,7 +117,7 @@ export SPRING_AI_OPENAI_API_KEY=<INSERT KEY HERE>
117117

118118
The `spring.ai.openai.embedding.options.*` properties are used to configure the default options used for all embedding requests.
119119

120-
=== Sample Code
120+
==== Sample Embedding Controller
121121

122122
This will create a `EmbeddingClient` implementation that you can inject into your class.
123123
Here is an example of a simple `@Controller` class that uses the `EmbeddingClient` implementation.
@@ -136,7 +136,7 @@ public class EmbeddingController {
136136
private final EmbeddingClient embeddingClient;
137137
138138
@Autowired
139-
public ChatController(EmbeddingClient embeddingClient) {
139+
public EmbeddingController(EmbeddingClient embeddingClient) {
140140
this.embeddingClient = embeddingClient;
141141
}
142142
@@ -152,7 +152,7 @@ public class EmbeddingController {
152152

153153
The prefix `spring.ai.openai` is used as the property prefix that lets you connect to OpenAI.
154154

155-
[cols="3,5,3"]
155+
[cols="3,5,1"]
156156
|====
157157
| Property | Description | Default
158158

@@ -163,7 +163,7 @@ The prefix `spring.ai.openai` is used as the property prefix that lets you conne
163163

164164
The prefix `spring.ai.openai.embedding` is property prefix that configures the `EmbeddingClient` implementation for OpenAI.
165165

166-
[cols="3,5,3"]
166+
[cols="3,5,1"]
167167
|====
168168
| Property | Description | Default
169169
| spring.ai.openai.embedding.base-url | Optional overrides the spring.ai.openai.base-url to provide embedding specific url | -

0 commit comments

Comments
 (0)