From b2d5ff0693183d40f8e04ffd5107c4e3c68193b9 Mon Sep 17 00:00:00 2001 From: Soby Chacko Date: Fri, 16 May 2025 19:58:28 -0400 Subject: [PATCH] GH-3187: Replace Spring environment variables with custom alternatives Fixes: #3187 This commit addresses the issue with Spring environment variables that directly mirror Spring AI application properties, which can confuse users into thinking they should always set environment variables that match Spring property names. Instead, we've replaced all instances of SPRING_* prefixed environment variables in the documentation with custom-named alternatives that are referenced using Spring Expression Language (SpEL) or retrieved programmatically. Each documentation section now shows multiple configuration approaches: - Direct property setting in application.properties/yml - Using custom environment variables with SpEL - Accessing environment variables programmatically This gives users more flexibility while making it clear that using SPRING_* prefixed environment variables is not required or recommended. Signed-off-by: Soby Chacko --- .../ROOT/pages/api/chat/anthropic-chat.adoc | 40 +++++++++++-- .../pages/api/chat/azure-openai-chat.adoc | 59 ++++++++++++++++--- .../ROOT/pages/api/chat/deepseek-chat.adoc | 38 ++++++++++-- .../ROOT/pages/api/chat/groq-chat.adoc | 54 +++++++++++++---- .../ROOT/pages/api/chat/huggingface.adoc | 48 ++++++++++++--- .../ROOT/pages/api/chat/minimax-chat.adoc | 37 ++++++++++-- .../ROOT/pages/api/chat/mistralai-chat.adoc | 38 ++++++++++-- .../ROOT/pages/api/chat/openai-chat.adoc | 38 ++++++++++-- .../ROOT/pages/api/chat/perplexity-chat.adoc | 55 ++++++++++++++--- .../ROOT/pages/api/chat/zhipuai-chat.adoc | 37 ++++++++++-- .../embeddings/azure-openai-embeddings.adoc | 59 ++++++++++++++++--- .../embeddings/bedrock-cohere-embedding.adoc | 31 ++++++++-- .../embeddings/bedrock-titan-embedding.adoc | 33 +++++++++-- .../api/embeddings/minimax-embeddings.adoc | 35 +++++++++-- .../api/embeddings/mistralai-embeddings.adoc | 35 +++++++++-- .../api/embeddings/openai-embeddings.adoc | 35 +++++++++-- .../api/embeddings/zhipuai-embeddings.adoc | 35 +++++++++-- .../pages/api/image/azure-openai-image.adoc | 45 ++++++++++++-- .../ROOT/pages/api/image/openai-image.adoc | 38 ++++++++++-- .../pages/api/image/stabilityai-image.adoc | 34 +++++++++-- .../ROOT/pages/api/image/zhipuai-image.adoc | 36 +++++++++-- .../ROOT/pages/api/vectordbs/chroma.adoc | 2 +- .../ROOT/pages/api/vectordbs/couchbase.adoc | 45 ++++++++++---- .../ROOT/pages/api/vectordbs/pinecone.adoc | 2 +- .../ROOT/pages/api/vectordbs/weaviate.adoc | 53 +++++++++++++---- 25 files changed, 823 insertions(+), 139 deletions(-) diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/anthropic-chat.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/anthropic-chat.adoc index 66024221d..cb4a77948 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/anthropic-chat.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/anthropic-chat.adoc @@ -10,14 +10,42 @@ Spring AI provides dedicated xref:api/chat/bedrock-converse.adoc[Amazon Bedrock == Prerequisites -You will need to create an API key on Anthropic portal. -Create an account at https://console.anthropic.com/dashboard[Anthropic API dashboard] and generate the api key on the https://console.anthropic.com/settings/keys[Get API Keys] page. -The Spring AI project defines a configuration property named `spring.ai.anthropic.api-key` that you should set to the value of the `API Key` obtained from anthropic.com. -Exporting an environment variable is one way to set that configuration property: +You will need to create an API key on the Anthropic portal. -[source,shell] +Create an account at https://console.anthropic.com/dashboard[Anthropic API dashboard] and generate the API key on the https://console.anthropic.com/settings/keys[Get API Keys] page. + +The Spring AI project defines a configuration property named `spring.ai.anthropic.api-key` that you should set to the value of the `API Key` obtained from anthropic.com. + +You can set this configuration property in your `application.properties` file: + +[source,properties] ---- -export SPRING_AI_ANTHROPIC_API_KEY= +spring.ai.anthropic.api-key= +---- + +For enhanced security when handling sensitive information like API keys, you can use Spring Expression Language (SpEL) to reference a custom environment variable: + +[source,yaml] +---- +# In application.yml +spring: + ai: + anthropic: + api-key: ${ANTHROPIC_API_KEY} +---- + +[source,bash] +---- +# In your environment or .env file +export ANTHROPIC_API_KEY= +---- + +You can also set this configuration programmatically in your application code: + +[source,java] +---- +// Retrieve API key from a secure source or environment variable +String apiKey = System.getenv("ANTHROPIC_API_KEY"); ---- === Add Repositories and BOM diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/azure-openai-chat.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/azure-openai-chat.adoc index 84202df53..139b0d2f3 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/azure-openai-chat.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/azure-openai-chat.adoc @@ -14,15 +14,35 @@ To access models using an API key, obtain your Azure OpenAI `endpoint` and `api- Spring AI defines two configuration properties: -1. `spring.ai.azure.openai.api-key`: Set this to the value the `API Key` obtained from Azure. +1. `spring.ai.azure.openai.api-key`: Set this to the value of the `API Key` obtained from Azure. 2. `spring.ai.azure.openai.endpoint`: Set this to the endpoint URL obtained when provisioning your model in Azure. -You can set these configuration properties by exporting environment variables: +You can set these configuration properties in your `application.properties` or `application.yml` file: -[source,shell] +[source,properties] ---- -export SPRING_AI_AZURE_OPENAI_API_KEY= -export SPRING_AI_AZURE_OPENAI_ENDPOINT= +spring.ai.azure.openai.api-key= +spring.ai.azure.openai.endpoint= +---- + +For enhanced security when handling sensitive information like API keys, you can use Spring Expression Language (SpEL) to reference custom environment variables: + +[source,yaml] +---- +# In application.yml +spring: + ai: + azure: + openai: + api-key: ${AZURE_OPENAI_API_KEY} + endpoint: ${AZURE_OPENAI_ENDPOINT} +---- + +[source,bash] +---- +# In your environment or .env file +export AZURE_OPENAI_API_KEY= +export AZURE_OPENAI_ENDPOINT= ---- === OpenAI Key @@ -31,9 +51,34 @@ To authenticate with the OpenAI service (not Azure), provide an OpenAI API key. When using this approach, set the `spring.ai.azure.openai.chat.options.deployment-name` property to the name of the https://platform.openai.com/docs/models[OpenAI model] you wish to use. -[source,shell] +In your application configuration: + +[source,properties] ---- -export SPRING_AI_AZURE_OPENAI_OPENAI_API_KEY= +spring.ai.azure.openai.openai-api-key= +spring.ai.azure.openai.chat.options.deployment-name= +---- + +Using environment variables with SpEL: + +[source,yaml] +---- +# In application.yml +spring: + ai: + azure: + openai: + openai-api-key: ${AZURE_OPENAI_API_KEY} + chat: + options: + deployment-name: ${AZURE_OPENAI_MODEL_NAME} +---- + +[source,bash] +---- +# In your environment or .env file +export AZURE_OPENAI_API_KEY= +export AZURE_OPENAI_MODEL_NAME= ---- === Microsoft Entra ID diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/deepseek-chat.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/deepseek-chat.adoc index c07e3e947..4f5d7e22d 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/deepseek-chat.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/deepseek-chat.adoc @@ -5,13 +5,41 @@ Spring AI supports the various AI language models from DeepSeek. You can interac == Prerequisites You will need to create an API key with DeepSeek to access DeepSeek language models. -Create an account at https://platform.deepseek.com/sign_up[DeepSeek registration page] and generate a token on the https://platform.deepseek.com/api_keys[API Keys page]. -The Spring AI project defines a configuration property named `spring.ai.deepseek.api-key` that you should set to the value of the `API Key` obtained from the https://platform.deepseek.com/api_keys[API Keys page]. -Exporting an environment variable is one way to set this configuration property: -[source,shell] +Create an account at https://platform.deepseek.com/sign_up[DeepSeek registration page] and generate a token on the https://platform.deepseek.com/api_keys[API Keys page]. + +The Spring AI project defines a configuration property named `spring.ai.deepseek.api-key` that you should set to the value of the `API Key` obtained from the API Keys page. + +You can set this configuration property in your `application.properties` file: + +[source,properties] ---- -export SPRING_AI_DEEPSEEK_API_KEY= +spring.ai.deepseek.api-key= +---- + +For enhanced security when handling sensitive information like API keys, you can use Spring Expression Language (SpEL) to reference a custom environment variable: + +[source,yaml] +---- +# In application.yml +spring: + ai: + deepseek: + api-key: ${DEEPSEEK_API_KEY} +---- + +[source,bash] +---- +# In your environment or .env file +export DEEPSEEK_API_KEY= +---- + +You can also set this configuration programmatically in your application code: + +[source,java] +---- +// Retrieve API key from a secure source or environment variable +String apiKey = System.getenv("DEEPSEEK_API_KEY"); ---- === Add Repositories and BOM diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/groq-chat.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/groq-chat.adoc index f9752af14..ab1d63b1d 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/groq-chat.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/groq-chat.adoc @@ -18,21 +18,55 @@ for examples of using Groq with Spring AI. == Prerequisites -* Create an API Key. -Please visit https://console.groq.com/keys[here] to create an API Key. +* **Create an API Key**: +Visit https://console.groq.com/keys[here] to create an API Key. 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 groq.com. -* Set the Groq URL. + +* **Set the Groq URL**: You have to set the `spring.ai.openai.base-url` property to `https://api.groq.com/openai`. -* Select a https://console.groq.com/docs/models[Groq Model]. -Use the `spring.ai.openai.chat.options.model=` property to set the Model. -Exporting an environment variable is one way to set that configuration property: +* **Select a Groq Model**: +Use the `spring.ai.openai.chat.model=` property to select from the available https://console.groq.com/docs/models[Groq Models]. -[source,shell] +You can set these configuration properties in your `application.properties` file: + +[source,properties] ---- -export SPRING_AI_OPENAI_API_KEY= -export SPRING_AI_OPENAI_BASE_URL=https://api.groq.com/openai -export SPRING_AI_OPENAI_CHAT_MODEL=llama3-70b-8192 +spring.ai.openai.api-key= +spring.ai.openai.base-url=https://api.groq.com/openai +spring.ai.openai.chat.model=llama3-70b-8192 +---- + +For enhanced security when handling sensitive information like API keys, you can use Spring Expression Language (SpEL) to reference custom environment variables: + +[source,yaml] +---- +# In application.yml +spring: + ai: + openai: + api-key: ${GROQ_API_KEY} + base-url: ${GROQ_BASE_URL} + chat: + model: ${GROQ_MODEL} +---- + +[source,bash] +---- +# In your environment or .env file +export GROQ_API_KEY= +export GROQ_BASE_URL=https://api.groq.com/openai +export GROQ_MODEL=llama3-70b-8192 +---- + +You can also set these configurations programmatically in your application code: + +[source,java] +---- +// Retrieve configuration from secure sources or environment variables +String apiKey = System.getenv("GROQ_API_KEY"); +String baseUrl = System.getenv("GROQ_BASE_URL"); +String model = System.getenv("GROQ_MODEL"); ---- === Add Repositories and BOM diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/huggingface.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/huggingface.adoc index 7faedbb4a..11c7ccf8f 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/huggingface.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/huggingface.adoc @@ -10,15 +10,49 @@ TIP: For a complete and up-to-date list of supported models and architectures, s You will need to create an Inference Endpoint on Hugging Face and create an API token to access the endpoint. Further details can be found link:https://huggingface.co/docs/inference-endpoints/index[here]. -The Spring AI project defines a configuration property named `spring.ai.huggingface.chat.api-key` that you should set to the value of the API token obtained from Hugging Face. -There is also a configuration property named `spring.ai.huggingface.chat.url` that you should set to the inference endpoint URL obtained when provisioning your model in Hugging Face. -You can find this on the Inference Endpoint's UI link:https://ui.endpoints.huggingface.co/[here]. -Exporting environment variables is one way to set these configuration properties: -[source,shell] +The Spring AI project defines two configuration properties: + +1. `spring.ai.huggingface.chat.api-key`: Set this to the value of the API token obtained from Hugging Face. +2. `spring.ai.huggingface.chat.url`: Set this to the inference endpoint URL obtained when provisioning your model in Hugging Face. + +You can find your inference endpoint URL on the Inference Endpoint's UI link:https://ui.endpoints.huggingface.co/[here]. + +You can set these configuration properties in your `application.properties` file: + +[source,properties] ---- -export SPRING_AI_HUGGINGFACE_CHAT_API_KEY= -export SPRING_AI_HUGGINGFACE_CHAT_URL= +spring.ai.huggingface.chat.api-key= +spring.ai.huggingface.chat.url= +---- + +For enhanced security when handling sensitive information like API keys, you can use Spring Expression Language (SpEL) to reference custom environment variables: + +[source,yaml] +---- +# In application.yml +spring: + ai: + huggingface: + chat: + api-key: ${HUGGINGFACE_API_KEY} + url: ${HUGGINGFACE_ENDPOINT_URL} +---- + +[source,bash] +---- +# In your environment or .env file +export HUGGINGFACE_API_KEY= +export HUGGINGFACE_ENDPOINT_URL= +---- + +You can also set these configurations programmatically in your application code: + +[source,java] +---- +// Retrieve API key and endpoint URL from secure sources or environment variables +String apiKey = System.getenv("HUGGINGFACE_API_KEY"); +String endpointUrl = System.getenv("HUGGINGFACE_ENDPOINT_URL"); ---- === Add Repositories and BOM diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/minimax-chat.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/minimax-chat.adoc index f7215d9cf..1b9f17292 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/minimax-chat.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/minimax-chat.adoc @@ -7,12 +7,39 @@ Spring AI supports the various AI language models from MiniMax. You can interact You will need to create an API with MiniMax to access MiniMax language models. Create an account at https://www.minimaxi.com/login[MiniMax registration page] and generate the token on the https://www.minimaxi.com/user-center/basic-information/interface-key[API Keys page]. -The Spring AI project defines a configuration property named `spring.ai.minimax.api-key` that you should set to the value of the `API Key` obtained from https://www.minimaxi.com/user-center/basic-information/interface-key[API Keys page]. -Exporting an environment variable is one way to set that configuration property: -[source,shell] +The Spring AI project defines a configuration property named `spring.ai.minimax.api-key` that you should set to the value of the `API Key` obtained from the API Keys page. + +You can set this configuration property in your `application.properties` file: + +[source,properties] ---- -export SPRING_AI_MINIMAX_API_KEY= +spring.ai.minimax.api-key= +---- + +For enhanced security when handling sensitive information like API keys, you can use Spring Expression Language (SpEL) to reference an environment variable: + +[source,yaml] +---- +# In application.yml +spring: + ai: + minimax: + api-key: ${MINIMAX_API_KEY} +---- + +[source,bash] +---- +# In your environment or .env file +export MINIMAX_API_KEY= +---- + +You can also set this configuration programmatically in your application code: + +[source,java] +---- +// Retrieve API key from a secure source or environment variable +String apiKey = System.getenv("MINIMAX_API_KEY"); ---- === Add Repositories and BOM @@ -298,4 +325,4 @@ Flux streamResponse = chatModel.stream(new Prompt(this.messages, t ==== MiniMaxApi Samples * The link:https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-minimax/src/test/java/org/springframework/ai/minimax/api/MiniMaxApiIT.java[MiniMaxApiIT.java] test provides some general examples how to use the lightweight library. -* The link:https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-minimax/src/test/java/org/springframework/ai/minimax/api/MiniMaxApiToolFunctionCallIT.java[MiniMaxApiToolFunctionCallIT.java] test shows how to use the low-level API to call tool functions.> \ No newline at end of file +* The link:https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-minimax/src/test/java/org/springframework/ai/minimax/api/MiniMaxApiToolFunctionCallIT.java[MiniMaxApiToolFunctionCallIT.java] test shows how to use the low-level API to call tool functions.> diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/mistralai-chat.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/mistralai-chat.adoc index 8d589e220..14ae3217a 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/mistralai-chat.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/mistralai-chat.adoc @@ -8,13 +8,41 @@ Check the xref:_openai_api_compatibility[OpenAI API compatibility] section to le == Prerequisites You will need to create an API with Mistral AI to access Mistral AI language models. -Create an account at https://auth.mistral.ai/ui/registration[Mistral AI registration page] and generate the token on the https://console.mistral.ai/api-keys/[API Keys page]. -The Spring AI project defines a configuration property named `spring.ai.mistralai.api-key` that you should set to the value of the `API Key` obtained from console.mistral.ai. -Exporting an environment variable is one way to set that configuration property: -[source,shell] +Create an account at https://auth.mistral.ai/ui/registration[Mistral AI registration page] and generate the token on the https://console.mistral.ai/api-keys/[API Keys page]. + +The Spring AI project defines a configuration property named `spring.ai.mistralai.api-key` that you should set to the value of the `API Key` obtained from console.mistral.ai. + +You can set this configuration property in your `application.properties` file: + +[source,properties] ---- -export SPRING_AI_MISTRALAI_API_KEY= +spring.ai.mistralai.api-key= +---- + +For enhanced security when handling sensitive information like API keys, you can use Spring Expression Language (SpEL) to reference a custom environment variable: + +[source,yaml] +---- +# In application.yml +spring: + ai: + mistralai: + api-key: ${MISTRALAI_API_KEY} +---- + +[source,bash] +---- +# In your environment or .env file +export MISTRALAI_API_KEY= +---- + +You can also set this configuration programmatically in your application code: + +[source,java] +---- +// Retrieve API key from a secure source or environment variable +String apiKey = System.getenv("MISTRALAI_API_KEY"); ---- === Add Repositories and BOM diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/openai-chat.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/openai-chat.adoc index 4496b697f..67b28f4e8 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/openai-chat.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/openai-chat.adoc @@ -5,13 +5,41 @@ Spring AI supports the various AI language models from OpenAI, the company behin == Prerequisites You will need to create an API with OpenAI to access ChatGPT models. -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]. -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] +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]. + +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. + +You can set this configuration property in your `application.properties` file: + +[source,properties] ---- -export SPRING_AI_OPENAI_API_KEY= +spring.ai.openai.api-key= +---- + +For enhanced security when handling sensitive information like API keys, you can use Spring Expression Language (SpEL) to reference a custom environment variable: + +[source,yaml] +---- +# In application.yml +spring: + ai: + openai: + api-key: ${OPENAI_API_KEY} +---- + +[source,bash] +---- +# In your environment or .env file +export OPENAI_API_KEY= +---- + +You can also set this configuration programmatically in your application code: + +[source,java] +---- +// Retrieve API key from a secure source or environment variable +String apiKey = System.getenv("OPENAI_API_KEY"); ---- === Add Repositories and BOM diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/perplexity-chat.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/perplexity-chat.adoc index d3e12827e..c330292be 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/perplexity-chat.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/perplexity-chat.adoc @@ -17,24 +17,63 @@ Check the https://github.com/spring-projects/spring-ai/blob/main/models/spring-a == Prerequisites * **Create an API Key**: -Visit https://docs.perplexity.ai/guides/getting-started[here] to create an API Key. Configure it using the `spring.ai.openai.api-key` property in your Spring AI project. +Visit https://docs.perplexity.ai/guides/getting-started[here] to create an API Key. +Configure it using the `spring.ai.openai.api-key` property in your Spring AI project. * **Set the Perplexity Base URL**: Set the `spring.ai.openai.base-url` property to `https://api.perplexity.ai`. * **Select a Perplexity Model**: -Use the `spring.ai.openai.chat.model=` property to specify the model. Refer to https://docs.perplexity.ai/guides/model-cards[Supported Models] for available options. +Use the `spring.ai.openai.chat.model=` property to specify the model. +Refer to https://docs.perplexity.ai/guides/model-cards[Supported Models] for available options. * **Set the chat completions path**: -Set the `spring.ai.openai.chat.completions-path` to `/chat/completions` . Refer to https://docs.perplexity.ai/api-reference/chat-completions[chat completions api] for more details. +Set the `spring.ai.openai.chat.completions-path` to `/chat/completions`. +Refer to https://docs.perplexity.ai/api-reference/chat-completions[chat completions api] for more details. -Example environment variables configuration: +You can set these configuration properties in your `application.properties` file: -[source,shell] +[source,properties] ---- -export SPRING_AI_OPENAI_API_KEY= -export SPRING_AI_OPENAI_BASE_URL=https://api.perplexity.ai -export SPRING_AI_OPENAI_CHAT_MODEL=llama-3.1-sonar-small-128k-online +spring.ai.openai.api-key= +spring.ai.openai.base-url=https://api.perplexity.ai +spring.ai.openai.chat.model=llama-3.1-sonar-small-128k-online +spring.ai.openai.chat.completions-path=/chat/completions +---- + +For enhanced security when handling sensitive information like API keys, you can use Spring Expression Language (SpEL) to reference custom environment variables: + +[source,yaml] +---- +# In application.yml +spring: + ai: + openai: + api-key: ${PERPLEXITY_API_KEY} + base-url: ${PERPLEXITY_BASE_URL} + chat: + model: ${PERPLEXITY_MODEL} + completions-path: ${PERPLEXITY_COMPLETIONS_PATH} +---- + +[source,bash] +---- +# In your environment or .env file +export PERPLEXITY_API_KEY= +export PERPLEXITY_BASE_URL=https://api.perplexity.ai +export PERPLEXITY_MODEL=llama-3.1-sonar-small-128k-online +export PERPLEXITY_COMPLETIONS_PATH=/chat/completions +---- + +You can also set these configurations programmatically in your application code: + +[source,java] +---- +// Retrieve configuration from secure sources or environment variables +String apiKey = System.getenv("PERPLEXITY_API_KEY"); +String baseUrl = System.getenv("PERPLEXITY_BASE_URL"); +String model = System.getenv("PERPLEXITY_MODEL"); +String completionsPath = System.getenv("PERPLEXITY_COMPLETIONS_PATH"); ---- === Add Repositories and BOM diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/zhipuai-chat.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/zhipuai-chat.adoc index 3c9dcf7b8..dc4d9be2a 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/zhipuai-chat.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/zhipuai-chat.adoc @@ -7,12 +7,39 @@ Spring AI supports the various AI language models from ZhiPu AI. You can interac You will need to create an API with ZhiPuAI to access ZhiPu AI language models. Create an account at https://open.bigmodel.cn/login[ZhiPu AI registration page] and generate the token on the https://open.bigmodel.cn/usercenter/apikeys[API Keys page]. -The Spring AI project defines a configuration property named `spring.ai.zhipuai.api-key` that you should set to the value of the `API Key` obtained from https://open.bigmodel.cn/usercenter/apikeys[API Keys page]. -Exporting an environment variable is one way to set that configuration property: -[source,shell] +The Spring AI project defines a configuration property named `spring.ai.zhipuai.api-key` that you should set to the value of the `API Key` obtained from the API Keys page. + +You can set this configuration property in your `application.properties` file: + +[source,properties] ---- -export SPRING_AI_ZHIPU_AI_API_KEY= +spring.ai.zhipuai.api-key= +---- + +For enhanced security when handling sensitive information like API keys, you can use Spring Expression Language (SpEL) to reference a custom environment variable: + +[source,yaml] +---- +# In application.yml +spring: + ai: + zhipuai: + api-key: ${ZHIPUAI_API_KEY} +---- + +[source,bash] +---- +# In your environment or .env file +export ZHIPUAI_API_KEY= +---- + +You can also set this configuration programmatically in your application code: + +[source,java] +---- +// Retrieve API key from a secure source or environment variable +String apiKey = System.getenv("ZHIPUAI_API_KEY"); ---- === Add Repositories and BOM @@ -265,4 +292,4 @@ Flux streamResponse = this.zhiPuAiApi.chatCompletionStream( Follow the https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-zhipuai/src/main/java/org/springframework/ai/zhipuai/api/ZhiPuAiApi.java[ZhiPuAiApi.java]'s JavaDoc for further information. ==== ZhiPuAiApi Samples -* The link:https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-zhipuai/src/test/java/org/springframework/ai/zhipuai/api/ZhiPuAiApiIT.java[ZhiPuAiApiIT.java] test provides some general examples how to use the lightweight library. \ No newline at end of file +* The link:https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-zhipuai/src/test/java/org/springframework/ai/zhipuai/api/ZhiPuAiApiIT.java[ZhiPuAiApiIT.java] test provides some general examples how to use the lightweight library. diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/azure-openai-embeddings.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/azure-openai-embeddings.adoc index 3bdfd5262..034282e29 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/azure-openai-embeddings.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/azure-openai-embeddings.adoc @@ -20,30 +20,73 @@ Obtain your Azure OpenAI `endpoint` and `api-key` from the Azure OpenAI Service Spring AI defines two configuration properties: - 1. `spring.ai.azure.openai.api-key`: Set this to the value of the `API Key` obtained from Azure. 2. `spring.ai.azure.openai.endpoint`: Set this to the endpoint URL obtained when provisioning your model in Azure. -You can set these configuration properties by exporting environment variables: +You can set these configuration properties in your `application.properties` or `application.yml` file: -[source,shell] +[source,properties] ---- -export SPRING_AI_AZURE_OPENAI_API_KEY= -export SPRING_AI_AZURE_OPENAI_ENDPOINT= +spring.ai.azure.openai.api-key= +spring.ai.azure.openai.endpoint= ---- +If you prefer to use environment variables for sensitive information like API keys, you can use Spring Expression Language (SpEL) in your configuration: + +[source,yaml] +---- +# In application.yml +spring: + ai: + azure: + openai: + api-key: ${AZURE_OPENAI_API_KEY} + endpoint: ${AZURE_OPENAI_ENDPOINT} +---- + +[source,bash] +---- +# In your environment or .env file +export AZURE_OPENAI_API_KEY= +export AZURE_OPENAI_ENDPOINT= +---- === OpenAI Key -To authenticate with the OpenAI service (not Azure), provide an OpenAI API key. This will automatically set the endpoint to https://api.openai.com/v1. +To authenticate with the OpenAI service (not Azure), provide an OpenAI API key. +This will automatically set the endpoint to https://api.openai.com/v1. When using this approach, set the `spring.ai.azure.openai.chat.options.deployment-name` property to the name of the https://platform.openai.com/docs/models[OpenAI model] you wish to use. -[source,shell] +In your application configuration: + +[source,properties] ---- -export SPRING_AI_AZURE_OPENAI_OPENAI_API_KEY= +spring.ai.azure.openai.openai-api-key= +spring.ai.azure.openai.chat.options.deployment-name= ---- +Using environment variables with SpEL: + +[source,yaml] +---- +# In application.yml +spring: + ai: + azure: + openai: + openai-api-key: ${AZURE_OPENAI_API_KEY} + chat: + options: + deployment-name: ${OPENAI_MODEL_NAME} +---- + +[source,bash] +---- +# In your environment or .env file +export AZURE_OPENAI_API_KEY= +export OPENAI_MODEL_NAME= +---- === Microsoft Entra ID For keyless authentication using Microsoft Entra ID (formerly Azure Active Directory), set _only_ the `spring.ai.azure.openai.endpoint` configuration property and _not_ the api-key property mentioned above. diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/bedrock-cohere-embedding.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/bedrock-cohere-embedding.adoc index d7e3791b4..6b67b31c7 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/bedrock-cohere-embedding.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/bedrock-cohere-embedding.adoc @@ -47,13 +47,36 @@ TIP: Refer to the xref:getting-started.adoc#dependency-management[Dependency Man === Enable Cohere Embedding Support -By default the Cohere model is disabled. -To enable it set the `spring.ai.model.embedding` property to `bedrock-cohere`. -Exporting environment variable is one way to set this configuration property: +By default, the Cohere embedding model is disabled. +To enable it, set the `spring.ai.model.embedding` property to `bedrock-cohere` in your application configuration: + +[source,properties] +---- +spring.ai.model.embedding=bedrock-cohere +---- + +Alternatively, you can use Spring Expression Language (SpEL) to reference an environment variable: + +[source,yaml] +---- +# In application.yml +spring: + ai: + model: + embedding: ${AI_MODEL_EMBEDDING} +---- + +[source,bash] +---- +# In your environment or .env file +export AI_MODEL_EMBEDDING=bedrock-cohere +---- + +You can also set this property using Java system properties when starting your application: [source,shell] ---- -export SPRING_AI_MODEL_EMBEDDING=bedrock-cohere +java -Dspring.ai.model.embedding=bedrock-cohere -jar your-application.jar ---- === Embedding Properties diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/bedrock-titan-embedding.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/bedrock-titan-embedding.adoc index e350c5afe..2cce947c3 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/bedrock-titan-embedding.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/bedrock-titan-embedding.adoc @@ -54,13 +54,36 @@ TIP: Refer to the xref:getting-started.adoc#dependency-management[Dependency Man === Enable Titan Embedding Support -By default the Titan embedding model is disabled. -To enable it set the `spring.ai.model.embedding` property to `bedrock-titan`. -Exporting environment variable is one way to set this configuration property: +By default, the Titan embedding model is disabled. +To enable it, set the `spring.ai.model.embedding` property to `bedrock-titan` in your application configuration: + +[source,properties] +---- +spring.ai.model.embedding=bedrock-titan +---- + +Alternatively, you can use Spring Expression Language (SpEL) to reference an environment variable: + +[source,yaml] +---- +# In application.yml +spring: + ai: + model: + embedding: ${AI_MODEL_EMBEDDING} +---- + +[source,bash] +---- +# In your environment or .env file +export AI_MODEL_EMBEDDING=bedrock-titan +---- + +You can also set this property using Java system properties when starting your application: [source,shell] ---- -export SPRING_AI_MODEL_EMBEDDING=bedrock-titan +java -Dspring.ai.model.embedding=bedrock-titan -jar your-application.jar ---- === Embedding Properties @@ -236,4 +259,4 @@ TitanEmbeddingRequest request = TitanEmbeddingRequest.builder() .build(); TitanEmbeddingResponse response = this.titanEmbedApi.embedding(this.request); ----- \ No newline at end of file +---- diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/minimax-embeddings.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/minimax-embeddings.adoc index 0bfb59e63..67f968008 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/minimax-embeddings.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/minimax-embeddings.adoc @@ -7,12 +7,39 @@ Spring AI supports the various AI language models from MiniMax. You can interact You will need to create an API with MiniMax to access MiniMax language models. Create an account at https://www.minimaxi.com/login[MiniMax registration page] and generate the token on the https://www.minimaxi.com/user-center/basic-information/interface-key[API Keys page]. -The Spring AI project defines a configuration property named `spring.ai.minimax.api-key` that you should set to the value of the `API Key` obtained from https://www.minimaxi.com/user-center/basic-information/interface-key[API Keys page]. -Exporting an environment variable is one way to set that configuration property: -[source,shell] +The Spring AI project defines a configuration property named `spring.ai.minimax.api-key` that you should set to the value of the `API Key` obtained from the API Keys page. + +You can set this configuration property in your `application.properties` file: + +[source,properties] ---- -export SPRING_AI_MINIMAX_API_KEY= +spring.ai.minimax.api-key= +---- + +For enhanced security when handling sensitive information like API keys, you can use Spring Expression Language (SpEL) to reference an environment variable: + +[source,yaml] +---- +# In application.yml +spring: + ai: + minimax: + api-key: ${MINIMAX_API_KEY} +---- + +[source,bash] +---- +# In your environment or .env file +export MINIMAX_API_KEY= +---- + +You can also set this configuration programmatically in your application code: + +[source,java] +---- +// Retrieve API key from a secure source or environment variable +String apiKey = System.getenv("MINIMAX_API_KEY"); ---- === Add Repositories and BOM diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/mistralai-embeddings.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/mistralai-embeddings.adoc index b40c7bf93..743d982b5 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/mistralai-embeddings.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/mistralai-embeddings.adoc @@ -8,12 +8,39 @@ Embeddings are vectorial representations of text that capture the semantic meani You will need to create an API with MistralAI to access MistralAI embeddings models. Create an account at https://auth.mistral.ai/ui/registration[MistralAI registration page] and generate the token on the https://console.mistral.ai/api-keys/[API Keys page]. -The Spring AI project defines a configuration property named `spring.ai.mistralai.api-key` that you should set to the value of the `API Key` obtained from console.mistral.ai. -Exporting an environment variable is one way to set that configuration property: -[source,shell] +The Spring AI project defines a configuration property named `spring.ai.mistralai.api-key` that you should set to the value of the `API Key` obtained from console.mistral.ai. + +You can set this configuration property in your `application.properties` file: + +[source,properties] ---- -export SPRING_AI_MISTRALAI_API_KEY= +spring.ai.mistralai.api-key= +---- + +For enhanced security when handling sensitive information like API keys, you can use Spring Expression Language (SpEL) to reference an environment variable: + +[source,yaml] +---- +# In application.yml +spring: + ai: + mistralai: + api-key: ${MISTRALAI_API_KEY} +---- + +[source,bash] +---- +# In your environment or .env file +export MISTRALAI_API_KEY= +---- + +You can also set this configuration programmatically in your application code: + +[source,java] +---- +// Retrieve API key from a secure source or environment variable +String apiKey = System.getenv("MISTRALAI_API_KEY"); ---- === Add Repositories and BOM 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 b79407cb7..edd4b9971 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 @@ -9,12 +9,39 @@ An embedding is a vector (list) of floating point numbers. The distance between You will need to create an API with OpenAI to access OpenAI embeddings models. 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]. -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] +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. + +You can set this configuration property in your `application.properties` file: + +[source,properties] ---- -export SPRING_AI_OPENAI_API_KEY= +spring.ai.openai.api-key= +---- + +For enhanced security when handling sensitive information like API keys, you can use Spring Expression Language (SpEL) to reference an environment variable: + +[source,yaml] +---- +# In application.yml +spring: + ai: + openai: + api-key: ${OPENAI_API_KEY} +---- + +[source,bash] +---- +# In your environment or .env file +export OPENAI_API_KEY= +---- + +You can also set this configuration programmatically in your application code: + +[source,java] +---- +// Retrieve API key from a secure source or environment variable +String apiKey = System.getenv("OPENAI_API_KEY"); ---- === Add Repositories and BOM diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/zhipuai-embeddings.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/zhipuai-embeddings.adoc index a064d7d42..6b343a940 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/zhipuai-embeddings.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/zhipuai-embeddings.adoc @@ -9,12 +9,39 @@ An embedding is a vector (list) of floating point numbers. The distance between You will need to create an API with ZhiPuAI to access ZhiPu AI language models. Create an account at https://open.bigmodel.cn/login[ZhiPu AI registration page] and generate the token on the https://open.bigmodel.cn/usercenter/apikeys[API Keys page]. -The Spring AI project defines a configuration property named `spring.ai.zhipu.api-key` that you should set to the value of the `API Key` obtained from https://open.bigmodel.cn/usercenter/apikeys[API Keys page]. -Exporting an environment variable is one way to set that configuration property: -[source,shell] +The Spring AI project defines a configuration property named `spring.ai.zhipu.api-key` that you should set to the value of the `API Key` obtained from the API Keys page. + +You can set this configuration property in your `application.properties` file: + +[source,properties] ---- -export SPRING_AI_ZHIPU_AI_API_KEY= +spring.ai.zhipu.api-key= +---- + +For enhanced security when handling sensitive information like API keys, you can use Spring Expression Language (SpEL) to reference an environment variable: + +[source,yaml] +---- +# In application.yml +spring: + ai: + zhipu: + api-key: ${ZHIPU_API_KEY} +---- + +[source,bash] +---- +# In your environment or .env file +export ZHIPU_API_KEY= +---- + +You can also set this configuration programmatically in your application code: + +[source,java] +---- +// Retrieve API key from a secure source or environment variable +String apiKey = System.getenv("ZHIPU_API_KEY"); ---- === Add Repositories and BOM diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/image/azure-openai-image.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/image/azure-openai-image.adoc index 1dac1aa2e..cefeae8c5 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/image/azure-openai-image.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/image/azure-openai-image.adoc @@ -6,14 +6,47 @@ Spring AI supports DALL-E, the Image generation model from Azure OpenAI. == Prerequisites Obtain your Azure OpenAI `endpoint` and `api-key` from the Azure OpenAI Service section on the link:https://portal.azure.com[Azure Portal]. -Spring AI defines a configuration property named `spring.ai.azure.openai.api-key` that you should set to the value of the `API Key` obtained from Azure. -There is also a configuration property named `spring.ai.azure.openai.endpoint` that you should set to the endpoint URL obtained when provisioning your model in Azure. -Exporting environment variables is one way to set these configuration properties: -[source,shell] +Spring AI defines two configuration properties: + +1. `spring.ai.azure.openai.api-key`: Set this to the value of the `API Key` obtained from Azure. +2. `spring.ai.azure.openai.endpoint`: Set this to the endpoint URL obtained when provisioning your model in Azure. + +You can set these configuration properties in your `application.properties` file: + +[source,properties] ---- -export SPRING_AI_AZURE_OPENAI_API_KEY= -export SPRING_AI_AZURE_OPENAI_ENDPOINT= +spring.ai.azure.openai.api-key= +spring.ai.azure.openai.endpoint= +---- + +For enhanced security when handling sensitive information like API keys, you can use Spring Expression Language (SpEL) to reference custom environment variables: + +[source,yaml] +---- +# In application.yml +spring: + ai: + azure: + openai: + api-key: ${AZURE_OPENAI_API_KEY} + endpoint: ${AZURE_OPENAI_ENDPOINT} +---- + +[source,bash] +---- +# In your environment or .env file +export AZURE_OPENAI_API_KEY= +export AZURE_OPENAI_ENDPOINT= +---- + +You can also set these configurations programmatically in your application code: + +[source,java] +---- +// Retrieve API key and endpoint from secure sources or environment variables +String apiKey = System.getenv("AZURE_OPENAI_API_KEY"); +String endpoint = System.getenv("AZURE_OPENAI_ENDPOINT"); ---- === Deployment Name diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/image/openai-image.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/image/openai-image.adoc index 182b0eaa3..3d541d2d7 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/image/openai-image.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/image/openai-image.adoc @@ -6,13 +6,41 @@ Spring AI supports DALL-E, the Image generation model from OpenAI. == Prerequisites You will need to create an API key with OpenAI to access ChatGPT models. -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]. -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] +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]. + +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. + +You can set this configuration property in your `application.properties` file: + +[source,properties] ---- -export SPRING_AI_OPENAI_API_KEY= +spring.ai.openai.api-key= +---- + +For enhanced security when handling sensitive information like API keys, you can use Spring Expression Language (SpEL) to reference a custom environment variable: + +[source,yaml] +---- +# In application.yml +spring: + ai: + openai: + api-key: ${OPENAI_API_KEY} +---- + +[source,bash] +---- +# In your environment or .env file +export OPENAI_API_KEY= +---- + +You can also set this configuration programmatically in your application code: + +[source,java] +---- +// Retrieve API key from a secure source or environment variable +String apiKey = System.getenv("OPENAI_API_KEY"); ---- == Auto-configuration diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/image/stabilityai-image.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/image/stabilityai-image.adoc index 5f31ffb1e..977ed357f 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/image/stabilityai-image.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/image/stabilityai-image.adoc @@ -4,14 +4,40 @@ Spring AI supports Stability AI's https://platform.stability.ai/docs/api-referen == Prerequisites -You will need to create an API key with Stability AI to access their AI models, follow their https://platform.stability.ai/docs/getting-started/authentication[Getting Started documentation]. +You will need to create an API key with Stability AI to access their AI models. Follow their https://platform.stability.ai/docs/getting-started/authentication[Getting Started documentation] to obtain your API key. The Spring AI project defines a configuration property named `spring.ai.stabilityai.api-key` that you should set to the value of the `API Key` obtained from Stability AI. -Exporting an environment variable is one way to set that configuration property. -[source,shell] +You can set this configuration property in your `application.properties` file: + +[source,properties] ---- -export SPRING_AI_STABILITYAI_API_KEY= +spring.ai.stabilityai.api-key= +---- + +For enhanced security when handling sensitive information like API keys, you can use Spring Expression Language (SpEL) to reference a custom environment variable: + +[source,yaml] +---- +# In application.yml +spring: + ai: + stabilityai: + api-key: ${STABILITYAI_API_KEY} +---- + +[source,bash] +---- +# In your environment or .env file +export STABILITYAI_API_KEY= +---- + +You can also set this configuration programmatically in your application code: + +[source,java] +---- +// Retrieve API key from a secure source or environment variable +String apiKey = System.getenv("STABILITYAI_API_KEY"); ---- == Auto-configuration diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/image/zhipuai-image.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/image/zhipuai-image.adoc index 5f16404d2..cb0e638cf 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/image/zhipuai-image.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/image/zhipuai-image.adoc @@ -8,13 +8,41 @@ Spring AI supports CogView, the Image generation model from ZhiPuAI. You will need to create an API with ZhiPuAI to access ZhiPu AI language models. Create an account at https://open.bigmodel.cn/login[ZhiPu AI registration page] and generate the token on the https://open.bigmodel.cn/usercenter/apikeys[API Keys page]. -The Spring AI project defines a configuration property named `spring.ai.zhipuai.api-key` that you should set to the value of the `API Key` obtained from https://open.bigmodel.cn/usercenter/apikeys[API Keys page]. -Exporting an environment variable is one way to set that configuration property: -[source,shell] +The Spring AI project defines a configuration property named `spring.ai.zhipuai.api-key` that you should set to the value of the `API Key` obtained from the API Keys page. + +You can set this configuration property in your `application.properties` file: + +[source,properties] ---- -export SPRING_AI_ZHIPU_AI_API_KEY= +spring.ai.zhipuai.api-key= ---- + +For enhanced security when handling sensitive information like API keys, you can use Spring Expression Language (SpEL) to reference a custom environment variable: + +[source,yaml] +---- +# In application.yml +spring: + ai: + zhipuai: + api-key: ${ZHIPUAI_API_KEY} +---- + +[source,bash] +---- +# In your environment or .env file +export ZHIPUAI_API_KEY= +---- + +You can also set this configuration programmatically in your application code: + +[source,java] +---- +// Retrieve API key from a secure source or environment variable +String apiKey = System.getenv("ZHIPUAI_API_KEY"); +---- + === Add Repositories and BOM Spring AI artifacts are published in Maven Central and Spring Snapshot repositories. diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/chroma.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/chroma.adoc index 1b9a5543a..e682aaae5 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/chroma.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/chroma.adoc @@ -62,7 +62,7 @@ Here is an example of the needed bean: @Bean public EmbeddingModel embeddingModel() { // Can be any other EmbeddingModel implementation. - return new OpenAiEmbeddingModel(new OpenAiApi(System.getenv("SPRING_AI_OPENAI_API_KEY"))); + return new OpenAiEmbeddingModel(OpenAiApi.builder().apiKey(System.getenv("OPENAI_API_KEY")).build()); } ---- diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/couchbase.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/couchbase.adoc index c3724e060..f828caecf 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/couchbase.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/couchbase.adoc @@ -81,9 +81,9 @@ List results = vectorStore.similaritySearch(SearchRequest.query("Sprin === Configuration Properties To connect to Couchbase and use the `CouchbaseSearchVectorStore`, you need to provide access details for your instance. -A simple configuration can either be provided via Spring Boot's `application.properties`, +Configuration can be provided via Spring Boot's `application.properties`: -[application,properties] +[source,properties] ---- spring.ai.openai.api-key= spring.couchbase.connection-string= @@ -91,19 +91,44 @@ spring.couchbase.username= spring.couchbase.password= ---- -environment variables, +If you prefer to use environment variables for sensitive information like passwords or API keys, you have multiple options: + +==== Option 1: Using Spring Expression Language (SpEL) + +You can use custom environment variable names and reference them in your application configuration using SpEL: + +[source,yaml] +---- +# In application.yml +spring: + ai: + openai: + api-key: ${OPENAI_API_KEY} + couchbase: + connection-string: ${COUCHBASE_CONN_STRING} + username: ${COUCHBASE_USER} + password: ${COUCHBASE_PASSWORD} +---- [source,bash] ---- -export SPRING_COUCHBASE_CONNECTION_STRINGS= -export SPRING_COUCHBASE_USERNAME= -export SPRING_COUCHBASE_PASSWORD= -# API key if needed, e.g. OpenAI -export SPRING_AI_OPENAI_API_KEY= +# In your environment or .env file +export OPENAI_API_KEY= +export COUCHBASE_CONN_STRING= +export COUCHBASE_USER= +export COUCHBASE_PASSWORD= ---- -or can be a mix of those. -For example, if you want to store your password as an environment variable but keep the rest in the plain `application.yml` file. +==== Option 2: Accessing Environment Variables Programmatically + +Alternatively, you can access environment variables in your Java code: + +[source,java] +---- +String apiKey = System.getenv("OPENAI_API_KEY"); +---- + +This approach gives you flexibility in naming your environment variables while keeping sensitive information out of your application configuration files. NOTE: If you choose to create a shell script for ease in future work, be sure to run it prior to starting your application by "sourcing" the file, i.e. `source .sh`. diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/pinecone.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/pinecone.adoc index f659e31d3..97536d3b0 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/pinecone.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/pinecone.adoc @@ -64,7 +64,7 @@ Here is an example of the needed bean: @Bean public EmbeddingModel embeddingModel() { // Can be any other EmbeddingModel implementation. - return new OpenAiEmbeddingModel(new OpenAiApi(System.getenv("SPRING_AI_OPENAI_API_KEY"))); + return new OpenAiEmbeddingModel(new OpenAiApi(System.getenv("OPENAI_API_KEY"))); } ---- diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/weaviate.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/weaviate.adoc index bfcde1f5c..2c6011e70 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/weaviate.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/weaviate.adoc @@ -44,7 +44,7 @@ TIP: Refer to the xref:getting-started.adoc#dependency-management[Dependency Man == Configuration To connect to Weaviate and use the `WeaviateVectorStore`, you need to provide access details for your instance. -A simple configuration can either be provided via Spring Boot's _application.properties_, +Configuration can be provided via Spring Boot's _application.properties_: [source,properties] ---- @@ -55,20 +55,46 @@ spring.ai.vectorstore.weaviate.api-key= spring.ai.openai.api-key= ---- -environment variables, +If you prefer to use environment variables for sensitive information like API keys, you have multiple options: + +=== Option 1: Using Spring Expression Language (SpEL) + +You can use custom environment variable names and reference them in your application configuration: + +[source,yaml] +---- +# In application.yml +spring: + ai: + vectorstore: + weaviate: + host: ${WEAVIATE_HOST} + scheme: ${WEAVIATE_SCHEME} + api-key: ${WEAVIATE_API_KEY} + openai: + api-key: ${OPENAI_API_KEY} +---- [source,bash] ---- -export SPRING_AI_VECTORSTORE_WEAVIATE_HOST= -export SPRING_AI_VECTORSTORE_WEAVIATE_SCHEME= -export SPRING_AI_VECTORSTORE_WEAVIATE_API_KEY= -# API key if needed, e.g. OpenAI -export SPRING_AI_OPENAI_API_KEY= +# In your environment or .env file +export WEAVIATE_HOST= +export WEAVIATE_SCHEME= +export WEAVIATE_API_KEY= +export OPENAI_API_KEY= ---- -or can be a mix of those. +=== Option 2: Accessing Environment Variables Programmatically -NOTE: If you choose to create a shell script for ease in future work, be sure to run it prior to starting your application by "sourcing" the file, i.e. `source .sh`. +Alternatively, you can access environment variables in your Java code: + +[source,java] +---- +String weaviateApiKey = System.getenv("WEAVIATE_API_KEY"); +String openAiApiKey = System.getenv("OPENAI_API_KEY"); +---- + +NOTE: If you choose to create a shell script to manage your environment variables, be sure to run it prior to starting your application by "sourcing" the file, i.e. `source .sh`. == Auto-configuration @@ -100,14 +126,17 @@ TIP: Refer to the xref:getting-started.adoc#artifact-repositories[Artifact Repos Additionally, you will need a configured `EmbeddingModel` bean. Refer to the xref:api/embeddings.adoc#available-implementations[EmbeddingModel] section for more information. -Here is an example of the needed bean: +Here is an example of the required bean: [source,java] ---- @Bean public EmbeddingModel embeddingModel() { - // Can be any other Embeddingmodel implementation. - return new OpenAiEmbeddingModel(new OpenAiApi(System.getenv("SPRING_AI_OPENAI_API_KEY"))); + // Retrieve API key from a secure source or environment variable + String apiKey = System.getenv("OPENAI_API_KEY"); + + // Can be any other EmbeddingModel implementation + return new OpenAiEmbeddingModel(OpenAiApi.builder().apiKey(apiKey).build()); } ----