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 a8f6acbf8..035cc9ebd 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/nav.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/nav.adoc @@ -3,7 +3,7 @@ * xref:getting-started.adoc[Getting Started] * xref:api/index.adoc[] ** xref:api/chatclient.adoc[] -*** xref:api/clients/openai.adoc[] +*** xref:api/clients/openai-chat.adoc[] *** xref:api/clients/azure-openai.adoc[] *** xref:api/clients/bedrock.adoc[] *** xref:api/clients/huggingface.adoc[] diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/clients/openai.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/clients/openai-chat.adoc similarity index 66% rename from spring-ai-docs/src/main/antora/modules/ROOT/pages/api/clients/openai.adoc rename to spring-ai-docs/src/main/antora/modules/ROOT/pages/api/clients/openai-chat.adoc index bcb429371..3b2c4db85 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/clients/openai.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/clients/openai-chat.adoc @@ -1,4 +1,4 @@ -= OpenAI += OpenAI Chat 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. @@ -17,11 +17,80 @@ Exporting an environment variable is one way to set that configuration property: export SPRING_AI_OPENAI_API_KEY= ---- -== Project Dependencies +=== Configure the OpenAI Chat Client Manually -Refer to the xref:getting-started.adoc#_dependency_management[Dependency Management] section to add Milestone and/or Snapshot Repositories to your build file. +Add the `spring-ai-openai` dependency to your project's Maven `pom.xml` file: +[source, xml] +---- + + org.springframework.ai + spring-ai-openai + 0.8.0-SNAPSHOT + +---- -Then add the Spring Boot Starter dependency to your project's Maven `pom.xml` build file: +or to your Gradle `build.gradle` build file. + +[source,groovy] +---- +dependencies { + implementation 'org.springframework.ai:spring-ai-openai:0.8.0-SNAPSHOT' +} +---- + +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. + +Next, create an `OpenAiChatClient` instance and use it to compute the similarity between two input texts: + +[source,java] +---- +var openAiApi = new OpenAiApi(System.getenv("OPENAI_API_KEY")); + +var chatClient = new OpenAiChatClient(openAiApi) + .withDefaultOptions(OpenAiChatOptions.builder() + .withModel("gpt-35-turbo") + .withTemperature(0.4) + .withMaxTokens(200) + .build()); + +ChatResponse response = chatClient.call( + new Prompt("Generate the names of 5 famous pirates.")); + +// Or with streaming responses +Flux response = chatClient.stream( + new Prompt("Generate the names of 5 famous pirates.")); +---- + +The `OpenAiChatOptions` provides the configuration information for the chat requests. +The `OpenAiChatOptions.Builder` is fluent options builder. + +==== OpenAiChatOptions + +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. + +The default options can be configured using the `spring.ai.openai.chat.options` properties as well. + +On start-time use the `OpenAiChatClient#withDefaultOptions()` to set the default options applicable for all chat completion requests. +At run-time you can override the default options with `OpenAiChatOptions` instance in the request `Prompt`. + +For example to override the default model name and temperature for a specific request: + +[source,java] +---- +ChatResponse response = chatClient.call( + new Prompt( + "Generate the names of 5 famous pirates.", + AzureOpenAiChatOptions.builder() + .withModel("gpt-4-32k") + .withTemperature(0.4) + .build() + )); +---- + +=== OpenAiChatClient Auto-configuration + +Spring AI provides Spring Boot auto-configuration for the OpenAI Chat Client. +To enable it add the following dependency to your project's Maven `pom.xml` file: [source, xml] ---- @@ -41,12 +110,29 @@ dependencies { } ---- +NOTE: Refer to the xref:getting-started.adoc#_dependency_management[Dependency Management] section to add Milestone and/or Snapshot Repositories to your build file. -== Sample Code +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. + +Exporting an environment variable is one way to set that configuration property: + +[source,shell] +---- +export SPRING_AI_OPENAI_API_KEY= +---- + +==== Sample Code This will create a `ChatClient` implementation that you can inject into your class. Here is an example of a simple `@Controller` class that uses the `ChatClient` implementation. +[source,application.properties] +---- +spring.ai.openai.api-key=YOUR_API_KEY +spring.ai.openai.chat.options.model=gpt-35-turbo +spring.ai.openai.chat.options.temperature=0.7 +---- + [source,java] ---- @RestController @@ -74,18 +160,11 @@ public class ChatController { } ---- -== OpenAiChatOptions - -The http://OpenAiChatOptions.java[OpenAiChatOptions.java] allows you to configure OpenAI options, such as the model to use, the temperature, the frequency penalty, etc. -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. - -The default options can be configured using the `spring.ai.openai.chat.options` properties as well. - -== OpenAI Properties +== OpenAI Chat Properties The prefix `spring.ai.openai` is used as the property prefix that lets you connect to OpenAI. -[cols="3,5,3"] +[cols="3,5,1"] |==== | Property | Description | Default @@ -95,7 +174,7 @@ The prefix `spring.ai.openai` is used as the property prefix that lets you conne The prefix `spring.ai.openai.chat` is the property prefix that lets you configure the `ChatClient` implementation for OpenAI. -[cols="3,5,3"] +[cols="3,5,1"] |==== | Property | Description | Default @@ -117,21 +196,7 @@ The prefix `spring.ai.openai.chat` is the property prefix that lets you configur | spring.ai.openai.chat.options.user | A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. | - |==== -The prefix `spring.ai.openai.embedding` is property prefix that configures the `EmbeddingClient` implementation for OpenAI. - -[cols="3,5,3"] -|==== -| Property | Description | Default -| spring.ai.openai.embedding.base-url | Optional overrides the spring.ai.openai.base-url to provide chat specific url | - -| spring.ai.openai.embedding.api-key | Optional overrides the spring.ai.openai.api-key to provide chat specific api-key | - -| spring.ai.openai.embedding.options.model | The model to use | text-embedding-ada-002 -| spring.ai.openai.embedding.options.encodingFormat | The format to return the embeddings in. Can be either float or base64. | - -| spring.ai.openai.embedding.options.user | A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. | - -|==== NOTE: You can override the common `spring.ai.openai.base-url` and `spring.ai.openai.api-key` for the `ChatClient` and `EmbeddingClient` implementations. The `spring.ai.openai.chat.base-url` and `spring.ai.openai.chat.api-key` properties if set take precedence over the common properties. -Similarly, the `spring.ai.openai.embedding.base-url` and `spring.ai.openai.embedding.api-key` properties if set take precedence over the common properties. This is useful if you want to use different OpenAI accounts for different models and different model endpoints. - -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`. diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/openai-embeddings.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/openai-embeddings.adoc index e5fae56e1..7f253280d 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/openai-embeddings.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/openai-embeddings.adoc @@ -19,7 +19,7 @@ Exporting an environment variable is one way to set that configuration property: export SPRING_AI_OPENAI_API_KEY= ---- -== Configure the OpenAI Embedding Client Manually +=== Configure the OpenAI Embedding Client Manually Add the `spring-ai-openai` dependency to your project's Maven `pom.xml` file: [source, xml] @@ -40,7 +40,7 @@ dependencies { } ---- -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. +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. Next, create an `OpenAiEmbeddingClient` instance and use it to compute the similarity between two input texts: @@ -61,9 +61,9 @@ EmbeddingResponse embeddingResponse = embeddingClient The `OpenAiEmbeddingOptions` provides the configuration information for the embedding requests. The options class offers a `builder()` for easy options creation. -== OpenAiEmbeddingOptions +==== OpenAiEmbeddingOptions -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. +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. The default options can be configured using the `spring.ai.openai.embedding.options` properties as well. @@ -81,7 +81,7 @@ EmbeddingResponse embeddingResponse = embeddingClient.call( .build())); ---- -== Spring Boot Auto-configuration +=== OpenAiEmbeddingClient Auto-configuration Spring AI provides Spring Boot auto-configuration for the Azure OpenAI Embedding Client. 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= The `spring.ai.openai.embedding.options.*` properties are used to configure the default options used for all embedding requests. -=== Sample Code +==== Sample Embedding Controller This will create a `EmbeddingClient` implementation that you can inject into your class. Here is an example of a simple `@Controller` class that uses the `EmbeddingClient` implementation. @@ -136,7 +136,7 @@ public class EmbeddingController { private final EmbeddingClient embeddingClient; @Autowired - public ChatController(EmbeddingClient embeddingClient) { + public EmbeddingController(EmbeddingClient embeddingClient) { this.embeddingClient = embeddingClient; } @@ -152,7 +152,7 @@ public class EmbeddingController { The prefix `spring.ai.openai` is used as the property prefix that lets you connect to OpenAI. -[cols="3,5,3"] +[cols="3,5,1"] |==== | Property | Description | Default @@ -163,7 +163,7 @@ The prefix `spring.ai.openai` is used as the property prefix that lets you conne The prefix `spring.ai.openai.embedding` is property prefix that configures the `EmbeddingClient` implementation for OpenAI. -[cols="3,5,3"] +[cols="3,5,1"] |==== | Property | Description | Default | spring.ai.openai.embedding.base-url | Optional overrides the spring.ai.openai.base-url to provide embedding specific url | -