Add promptCacheKey and safetyIdentifier support, document extraBody and reasoningContent

- Add promptCacheKey and safetyIdentifier fields to OpenAiChatOptions
- Add integration and unit tests for new fields
- Document extraBody parameter for OpenAI-compatible servers
- Document reasoningContent field for reasoning models
- Update configuration documentation

Signed-off-by: SenreySong <25841017+SenreySong@users.noreply.github.com>
Signed-off-by: Mark Pollack <mark.pollack@broadcom.com>

Author: markpollack

models/spring-ai-openai/src/main/java/org/springframework/ai/openai/OpenAiChatOptions.java

@@ -237,6 +237,20 @@ public class OpenAiChatOptions implements ToolCallingChatOptions {
 	 */
 	private @JsonProperty("service_tier") String serviceTier;
 
+	/**
+	 * A cache key used by OpenAI to optimize cache hit rates for similar requests.
+	 * Improves latency and reduces costs. Replaces the deprecated {@code user} field for caching purposes.
+	 * <a href="https://platform.openai.com/docs/guides/prompt-caching">Learn more</a>.
+	 */
+	private @JsonProperty("prompt_cache_key") String promptCacheKey;
+
+	/**
+	 * A stable identifier to help OpenAI detect users violating usage policies.
+	 * Should be a hashed value (e.g., hashed username or email). Replaces the deprecated {@code user} field for safety tracking.
+	 * <a href="https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers">Learn more</a>.
+	 */
+	private @JsonProperty("safety_identifier") String safetyIdentifier;
+
 	/**
 	 * Collection of {@link ToolCallback}s to be used for tool calling in the chat completion requests.
 	 */
@@ -264,6 +278,20 @@ public class OpenAiChatOptions implements ToolCallingChatOptions {
 	@JsonIgnore
 	private Map<String, Object> toolContext = new HashMap<>();
 
+	/**
+	 * Additional parameters to pass to OpenAI-compatible servers. Accepts any key-value pairs
+	 * that will be included at the top level of the JSON request. Intended for use with
+	 * vLLM, Ollama, and other OpenAI-compatible servers that support parameters beyond the
+	 * standard OpenAI API (e.g., {@code top_k}, {@code repetition_penalty}). The official
+	 * OpenAI API ignores unknown parameters.
+	 * <p>
+	 * Example:
+	 * <pre>{@code
+	 * OpenAiChatOptions.builder()
+	 *     .extraBody(Map.of("top_k", 50, "repetition_penalty", 1.1))
+	 *     .build()
+	 * }</pre>
+	 */
 	private @JsonProperty("extra_body") Map<String, Object> extraBody;
 
 	// @formatter:on
@@ -308,6 +336,8 @@ public static OpenAiChatOptions fromOptions(OpenAiChatOptions fromOptions) {
 			.webSearchOptions(fromOptions.getWebSearchOptions())
 			.verbosity(fromOptions.getVerbosity())
 			.serviceTier(fromOptions.getServiceTier())
+			.promptCacheKey(fromOptions.getPromptCacheKey())
+			.safetyIdentifier(fromOptions.getSafetyIdentifier())
 			.extraBody(fromOptions.getExtraBody())
 			.build();
 	}
@@ -629,6 +659,22 @@ public void setServiceTier(String serviceTier) {
 		this.serviceTier = serviceTier;
 	}
 
+	public String getPromptCacheKey() {
+		return this.promptCacheKey;
+	}
+
+	public void setPromptCacheKey(String promptCacheKey) {
+		this.promptCacheKey = promptCacheKey;
+	}
+
+	public String getSafetyIdentifier() {
+		return this.safetyIdentifier;
+	}
+
+	public void setSafetyIdentifier(String safetyIdentifier) {
+		this.safetyIdentifier = safetyIdentifier;
+	}
+
 	@Override
 	public OpenAiChatOptions copy() {
 		return OpenAiChatOptions.fromOptions(this);
@@ -641,8 +687,8 @@ public int hashCode() {
 				this.streamOptions, this.seed, this.stop, this.temperature, this.topP, this.tools, this.toolChoice,
 				this.user, this.parallelToolCalls, this.toolCallbacks, this.toolNames, this.httpHeaders,
 				this.internalToolExecutionEnabled, this.toolContext, this.outputModalities, this.outputAudio,
-				this.store, this.metadata, this.reasoningEffort, this.webSearchOptions, this.serviceTier,
-				this.extraBody);
+				this.store, this.metadata, this.reasoningEffort, this.webSearchOptions, this.verbosity,
+				this.serviceTier, this.promptCacheKey, this.safetyIdentifier, this.extraBody);
 	}
 
 	@Override
@@ -678,6 +724,8 @@ public boolean equals(Object o) {
 				&& Objects.equals(this.webSearchOptions, other.webSearchOptions)
 				&& Objects.equals(this.verbosity, other.verbosity)
 				&& Objects.equals(this.serviceTier, other.serviceTier)
+				&& Objects.equals(this.promptCacheKey, other.promptCacheKey)
+				&& Objects.equals(this.safetyIdentifier, other.safetyIdentifier)
 				&& Objects.equals(this.extraBody, other.extraBody);
 	}
 
@@ -946,6 +994,16 @@ public Builder serviceTier(OpenAiApi.ServiceTier serviceTier) {
 			return this;
 		}
 
+		public Builder promptCacheKey(String promptCacheKey) {
+			this.options.promptCacheKey = promptCacheKey;
+			return this;
+		}
+
+		public Builder safetyIdentifier(String safetyIdentifier) {
+			this.options.safetyIdentifier = safetyIdentifier;
+			return this;
+		}
+
 		public Builder extraBody(Map<String, Object> extraBody) {
 			this.options.extraBody = extraBody;
 			return this;

models/spring-ai-openai/src/main/java/org/springframework/ai/openai/api/OpenAiApi.java

@@ -1131,6 +1131,8 @@ public record ChatCompletionRequest(// @formatter:off
 			@JsonProperty("reasoning_effort") String reasoningEffort,
 			@JsonProperty("web_search_options") WebSearchOptions webSearchOptions,
 			@JsonProperty("verbosity") String verbosity,
+			@JsonProperty("prompt_cache_key") String promptCacheKey,
+			@JsonProperty("safety_identifier") String safetyIdentifier,
 			Map<String, Object> extraBody) {
 
 		/**
@@ -1143,7 +1145,7 @@ public record ChatCompletionRequest(// @formatter:off
 		public ChatCompletionRequest(List<ChatCompletionMessage> messages, String model, Double temperature) {
 			this(messages, model, null, null, null, null, null, null, null, null, null, null, null, null, null,
 					null, null, null, false, null, temperature, null,
-					null, null, null, null, null, null, null, null);
+					null, null, null, null, null, null, null, null, null, null);
 		}
 
 		/**
@@ -1157,7 +1159,7 @@ public ChatCompletionRequest(List<ChatCompletionMessage> messages, String model,
 			this(messages, model, null, null, null, null, null, null,
 					null, null, null, List.of(OutputModality.AUDIO, OutputModality.TEXT), audio, null, null,
 					null, null, null, stream, null, null, null,
-					null, null, null, null, null, null, null, null);
+					null, null, null, null, null, null, null, null, null, null);
 		}
 
 		/**
@@ -1172,7 +1174,7 @@ public ChatCompletionRequest(List<ChatCompletionMessage> messages, String model,
 		public ChatCompletionRequest(List<ChatCompletionMessage> messages, String model, Double temperature, boolean stream) {
 			this(messages, model, null, null, null, null, null, null, null, null, null,
 					null, null, null, null, null, null, null, stream, null, temperature, null,
-					null, null, null, null, null, null, null, null);
+					null, null, null, null, null, null, null, null, null, null);
 		}
 
 		/**
@@ -1188,7 +1190,7 @@ public ChatCompletionRequest(List<ChatCompletionMessage> messages, String model,
 				List<FunctionTool> tools, Object toolChoice) {
 			this(messages, model, null, null, null, null, null, null, null, null, null,
 					null, null, null, null, null, null, null, false, null, 0.8, null,
-					tools, toolChoice, null, null, null, null, null, null);
+					tools, toolChoice, null, null, null, null, null, null, null, null);
 		}
 
 		/**
@@ -1201,7 +1203,7 @@ public ChatCompletionRequest(List<ChatCompletionMessage> messages, String model,
 		public ChatCompletionRequest(List<ChatCompletionMessage> messages, Boolean stream) {
 			this(messages, null, null, null, null, null, null, null, null, null, null, null, null, null,
 				null, null, null, null, stream, null, null, null, null, null, null, null, null, null,
-				null, null);
+				null, null, null, null);
 		}
 
 		/**
@@ -1214,7 +1216,8 @@ public ChatCompletionRequest streamOptions(StreamOptions streamOptions) {
 			return new ChatCompletionRequest(this.messages, this.model, this.store, this.metadata, this.frequencyPenalty, this.logitBias, this.logprobs,
 					this.topLogprobs, this.maxTokens, this.maxCompletionTokens, this.n, this.outputModalities, this.audioParameters, this.presencePenalty,
 					this.responseFormat, this.seed, this.serviceTier, this.stop, this.stream, streamOptions, this.temperature, this.topP,
-					this.tools, this.toolChoice, this.parallelToolCalls, this.user, this.reasoningEffort, this.webSearchOptions, this.verbosity, this.extraBody);
+					this.tools, this.toolChoice, this.parallelToolCalls, this.user, this.reasoningEffort, this.webSearchOptions, this.verbosity,
+					this.promptCacheKey, this.safetyIdentifier, this.extraBody);
 		}
 
 		/**

models/spring-ai-openai/src/test/java/org/springframework/ai/openai/OpenAiChatOptionsTests.java

@@ -84,18 +84,20 @@ void testBuilderWithAllFields() {
 			.httpHeaders(Map.of("header1", "value1"))
 			.toolContext(toolContext)
 			.serviceTier(ServiceTier.PRIORITY)
+			.promptCacheKey("test-cache-key")
+			.safetyIdentifier("test-safety-id")
 			.build();
 
 		assertThat(options)
 			.extracting("model", "frequencyPenalty", "logitBias", "logprobs", "topLogprobs", "maxTokens",
 					"maxCompletionTokens", "n", "outputModalities", "outputAudio", "presencePenalty", "responseFormat",
 					"streamOptions", "seed", "stop", "temperature", "topP", "tools", "toolChoice", "user",
 					"parallelToolCalls", "store", "metadata", "reasoningEffort", "internalToolExecutionEnabled",
-					"httpHeaders", "toolContext", "serviceTier")
+					"httpHeaders", "toolContext", "serviceTier", "promptCacheKey", "safetyIdentifier")
 			.containsExactly("test-model", 0.5, logitBias, true, 5, null, 50, 2, outputModalities, outputAudio, 0.8,
 					responseFormat, streamOptions, 12345, stopSequences, 0.7, 0.9, tools, toolChoice, "test-user", true,
 					false, metadata, "medium", false, Map.of("header1", "value1"), toolContext,
-					ServiceTier.PRIORITY.getValue());
+					ServiceTier.PRIORITY.getValue(), "test-cache-key", "test-safety-id");
 
 		assertThat(options.getStreamUsage()).isTrue();
 		assertThat(options.getStreamOptions()).isEqualTo(StreamOptions.INCLUDE_USAGE);
@@ -144,6 +146,8 @@ void testCopy() {
 			.internalToolExecutionEnabled(true)
 			.httpHeaders(Map.of("header1", "value1"))
 			.serviceTier(ServiceTier.DEFAULT)
+			.promptCacheKey("copy-test-cache")
+			.safetyIdentifier("copy-test-safety")
 			.build();
 
 		OpenAiChatOptions copiedOptions = originalOptions.copy();

models/spring-ai-openai/src/test/java/org/springframework/ai/openai/api/ExtraBodySerializationTest.java

@@ -42,7 +42,7 @@ void testExtraBodySerializationFlattensToTopLevel() throws Exception {
 		ChatCompletionRequest request = new ChatCompletionRequest(List.of(), // messages
 				"gpt-4", // model
 				null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, false,
-				null, null, null, null, null, null, null, null, null, null,
+				null, null, null, null, null, null, null, null, null, null, null, null,
 				Map.of("top_k", 50, "repetition_penalty", 1.1) // extraBody
 		);
 
@@ -71,8 +71,8 @@ void testExtraBodyWithEmptyMap() throws Exception {
 		ChatCompletionRequest request = new ChatCompletionRequest(List.of(), // messages
 				"gpt-4", // model
 				null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, false,
-				null, null, null, null, null, null, null, null, null, null, Map.of() // empty
-																						// extraBody
+				null, null, null, null, null, null, null, null, null, null, null, null, Map.of() // empty
+		// extraBody
 		);
 
 		// Act
@@ -93,9 +93,9 @@ void testExtraBodyNullSerialization() throws Exception {
 		ChatCompletionRequest request = new ChatCompletionRequest(List.of(), // messages
 				"gpt-4", // model
 				null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, false,
-				null, null, null, null, null, null, null, null, null, null, null // extraBody
-																					// =
-																					// null
+				null, null, null, null, null, null, null, null, null, null, null, null, null // extraBody
+		// =
+		// null
 		);
 
 		// Act

models/spring-ai-openai/src/test/java/org/springframework/ai/openai/api/OpenAiApiIT.java

@@ -81,7 +81,7 @@ void validateReasoningTokens() {
 				ChatCompletionMessage.Role.USER);
 		ChatCompletionRequest request = new ChatCompletionRequest(List.of(userMessage), "gpt-5", null, null, null, null,
 				null, null, null, null, null, null, null, null, null, null, null, null, false, null, null, null, null,
-				null, null, null, "high", null, null, null);
+				null, null, null, "high", null, null, null, null, null);
 		ResponseEntity<ChatCompletion> response = this.openAiApi.chatCompletionEntity(request);
 
 		assertThat(response).isNotNull();
@@ -185,7 +185,7 @@ void chatCompletionEntityWithNewModelsAndLowVerbosity(OpenAiApi.ChatModel modelN
 
 		ChatCompletionRequest request = new ChatCompletionRequest(List.of(chatCompletionMessage), // messages
 				modelName.getValue(), null, null, null, null, null, null, null, null, null, null, null, null, null,
-				null, null, null, false, null, 1.0, null, null, null, null, null, null, null, "low", null);
+				null, null, null, false, null, 1.0, null, null, null, null, null, null, null, "low", null, null, null);
 
 		ResponseEntity<ChatCompletion> response = this.openAiApi.chatCompletionEntity(request);
 
@@ -232,7 +232,7 @@ void chatCompletionEntityWithServiceTier(OpenAiApi.ServiceTier serviceTier) {
 		ChatCompletionRequest request = new ChatCompletionRequest(List.of(chatCompletionMessage), // messages
 				OpenAiApi.ChatModel.GPT_4_O.value, null, null, null, null, null, null, null, null, null, null, null,
 				null, null, null, serviceTier.getValue(), null, false, null, 1.0, null, null, null, null, null, null,
-				null, null, null);
+				null, null, null, null, null);
 
 		ResponseEntity<ChatCompletion> response = this.openAiApi.chatCompletionEntity(request);
 

models/spring-ai-openai/src/test/java/org/springframework/ai/openai/chat/OpenAiChatModelIT.java

@@ -816,6 +816,19 @@ void testReasoningEffortParameter() {
 		}
 	}
 
+	@Test
+	void shouldSendPromptCacheKeyAndSafetyIdentifier() {
+		OpenAiChatOptions options = OpenAiChatOptions.builder()
+			.promptCacheKey("test-cache-" + System.currentTimeMillis())
+			.safetyIdentifier("hashed-user-123")
+			.build();
+
+		ChatResponse response = this.openAiChatModel.call(new Prompt("Tell me a joke about Spring", options));
+
+		assertThat(response).isNotNull();
+		assertThat(response.getResults()).isNotEmpty();
+	}
+
 	record ActorsFilmsRecord(String actor, List<String> movies) {
 
 	}

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

@@ -515,6 +515,9 @@ Although this is optional for JSON Schema, it's recommended for the structured r
 Ollama is OpenAI API-compatible and you can use the xref:api/chat/openai-chat.adoc[Spring AI OpenAI] client to talk to Ollama and use tools.
 For this, you need to configure the OpenAI base URL to your Ollama instance: `spring.ai.openai.chat.base-url=http://localhost:11434` and select one of the provided Ollama models: `spring.ai.openai.chat.options.model=mistral`.
 
+TIP: When using the OpenAI client with Ollama, you can pass Ollama-specific parameters (like `top_k`, `repeat_penalty`, `num_predict`) using the xref:api/chat/openai-chat.adoc#openai-compatible-servers[`extraBody` option].
+This allows you to leverage Ollama's full capabilities while using the OpenAI client.
+
 image::spring-ai-ollama-over-openai.jpg[Ollama OpenAI API compatibility, 800, 600, align="center"]
 
 Check the link:https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-openai/src/test/java/org/springframework/ai/openai/chat/proxy/OllamaWithOpenAiChatModelIT.java[OllamaWithOpenAiChatModelIT.java] tests for examples of using Ollama over Spring AI OpenAI.