程序包 io.agentscope.core.model

类 GenerateOptions

java.lang.Object
io.agentscope.core.model.GenerateOptions
public class GenerateOptions extends Object
Immutable generation options for LLM models. Use the builder pattern to construct instances.

This class holds both per-request generation parameters (temperature, maxTokens, etc.) and connection-level configuration (apiKey, baseUrl, modelName, stream).

  • 方法详细资料

    • getApiKey

      public String getApiKey()
      Gets the API key for authentication.

      This is the API key used to authenticate with the LLM provider. When null, the model's default API key will be used (if configured).

      返回:
      the API key, or null if not set

    • getBaseUrl

      public String getBaseUrl()
      Gets the base URL for the API endpoint.

      This is the base URL of the LLM provider's API. When null, the model's default base URL will be used (if configured).

      返回:
      the base URL, or null if not set

    • getEndpointPath

      public String getEndpointPath()
      Gets the endpoint path for the API request.

      This is the API endpoint path (e.g., "/v1/chat/completions"). When null, the model's default endpoint path will be used.

      This allows customization for OpenAI-compatible APIs that use different endpoint paths than the standard OpenAI API.

      返回:
      the endpoint path, or null if not set

    • getModelName

      public String getModelName()
      Gets the model name to use for generation.

      This specifies which model to use (e.g., "gpt-4", "gpt-3.5-turbo"). When null, the model's default model name will be used (if configured).

      返回:
      the model name, or null if not set

    • getStream

      public Boolean getStream()
      Gets whether streaming mode is enabled.

      When true, responses will be streamed as they are generated. When false, the full response will be returned when complete. When null, the model's default streaming mode will be used (if configured).

      返回:
      true for streaming, false for non-streaming, null if not set

    • getTemperature

      public Double getTemperature()
      Gets the temperature for text generation.

      Higher values (e.g., 0.8) make output more random, while lower values (e.g., 0.2) make it more focused and deterministic.

      返回:
      the temperature value between 0 and 2, or null if not set

    • getTopP

      public Double getTopP()
      Gets the top-p (nucleus sampling) parameter.

      Controls diversity via nucleus sampling: considers the smallest set of tokens whose cumulative probability exceeds the top_p value.

      返回:
      the top-p value between 0 and 1, or null if not set

    • getMaxTokens

      public Integer getMaxTokens()
      Gets the maximum number of tokens to generate.
      返回:
      the maximum tokens limit, or null if not set

    • getMaxCompletionTokens

      public Integer getMaxCompletionTokens()
      Gets the maximum number of completion tokens to generate.

      This is an alternative to getMaxTokens() for OpenAI-compatible APIs that support max_completion_tokens. Some providers/models treat max_tokens and max_completion_tokens as mutually exclusive; this SDK does not enforce exclusivity and will forward exactly what the caller sets.

      返回:
      the maximum completion tokens limit, or null if not set

    • getFrequencyPenalty

      public Double getFrequencyPenalty()
      Gets the frequency penalty.

      Reduces repetition by penalizing tokens based on their frequency in the text so far. Higher values decrease repetition more strongly.

      返回:
      the frequency penalty between -2 and 2, or null if not set

    • getPresencePenalty

      public Double getPresencePenalty()
      Gets the presence penalty.

      Reduces repetition by penalizing tokens that have already appeared in the text. Higher values decrease repetition more strongly.

      返回:
      the presence penalty between -2 and 2, or null if not set

    • getThinkingBudget

      public Integer getThinkingBudget()
      Gets the maximum number of tokens for reasoning/thinking content.

      This parameter is specific to models that support thinking mode (e.g., DashScope). When set, it enables the model to show its reasoning process before generating the final answer.

      返回:
      the thinking budget in tokens, or null if not set

    • getReasoningEffort

      public String getReasoningEffort()
      Gets the reasoning effort level for o1 models.

      This parameter controls how much effort the model spends on reasoning. Valid values are "low", "medium", and "high".

      返回:
      the reasoning effort level, or null if not set

    • getExecutionConfig

      public ExecutionConfig getExecutionConfig()
      Gets the execution configuration for timeout and retry behavior.

      When set, the model will apply timeout and retry logic according to the configured execution config (timeout duration, max attempts, backoff, error filtering).

      返回:
      the execution configuration, or null if not configured

    • getToolChoice

      public ToolChoice getToolChoice()
      Gets the tool choice configuration for controlling how the model uses tools.

      When set, this controls whether the model can call tools, must call tools, or must call a specific tool. When null, the default behavior (auto) is used.

      返回:
      the tool choice configuration, or null if not set (defaults to auto)
      另请参阅:

    • getTopK

      public Integer getTopK()
      Gets the top-k sampling parameter.

      Limits the model to only consider the top K most probable tokens at each step. Lower values make output more focused, higher values allow more diversity.

      返回:
      the top-k value, or null if not set

    • getSeed

      public Long getSeed()
      Gets the random seed for deterministic generation.

      When set, the model will attempt to generate the same output for the same input and seed value, enabling reproducible results.

      返回:
      the seed value, or null if not set

    • getCacheControl

      public Boolean getCacheControl()
      Gets whether cache control is enabled for prompt caching.

      When true, the formatter will automatically add cache_control: {"type": "ephemeral"} to system messages and the last message in the request. This enables prompt caching on supported providers (e.g., Anthropic, DashScope, OpenAI-compatible APIs) to reduce latency and cost.

      Users can also manually mark individual messages for caching via MessageMetadataKeys.CACHE_CONTROL metadata. Manually marked messages take priority over the automatic strategy.

      返回:
      true if cache control is enabled, false or null if not set

    • getAdditionalHeaders

      public Map<String,String> getAdditionalHeaders()
      Gets the additional HTTP headers to include in API requests.

      These headers will be merged with the default headers when making API calls. Useful for passing custom authentication, tracing, or provider-specific headers.

      返回:
      an unmodifiable map of additional headers, empty if none set

    • getAdditionalBodyParams

      public Map<String,Object> getAdditionalBodyParams()
      Gets the additional parameters to include in the request body.

      These parameters will be merged into the API request body, allowing provider-specific options not covered by the standard fields.

      返回:
      an unmodifiable map of additional body parameters, empty if none set

    • getAdditionalQueryParams

      public Map<String,String> getAdditionalQueryParams()
      Gets the additional query parameters to include in API requests.

      These parameters will be appended to the API request URL as query string.

      返回:
      an unmodifiable map of additional query parameters, empty if none set

    • builder

      public static GenerateOptions.Builder builder()
      Creates a new builder for GenerateOptions.
      返回:
      a new Builder instance

    • mergeOptions

      public static GenerateOptions mergeOptions(GenerateOptions primary, GenerateOptions fallback)
      Merges two GenerateOptions instances, with primary options taking precedence.

      This method performs parameter-by-parameter merging: for each parameter, if the primary value is non-null, it is used; otherwise, the fallback value is used. This allows proper layering of options from different sources (e.g., per-request options over default options).

      Merge Behavior:

      • Primitive fields (temperature, topP, etc.): primary != null ? primary : fallback
      • Map fields (additionalHeaders, etc.): merges both maps, with primary values overriding fallback
      • If primary is null, returns fallback directly
      • If fallback is null, returns primary directly

      Example: 

      
 ExecutionConfig defaultExecConfig = ExecutionConfig.builder()
     .timeout(Duration.ofMinutes(5))
     .maxAttempts(3)
     .build();

 GenerateOptions defaults = GenerateOptions.builder()
     .temperature(0.7)
     .executionConfig(defaultExecConfig)
     .build();

 ExecutionConfig customExecConfig = ExecutionConfig.builder()
     .timeout(Duration.ofSeconds(30))
     .build();

 GenerateOptions perRequest = GenerateOptions.builder()
     .executionConfig(customExecConfig)
     .build();

 // Result: temperature=0.7, executionConfig with timeout=30s and maxAttempts=3
 GenerateOptions merged = GenerateOptions.mergeOptions(perRequest, defaults);
      参数:
      primary - the primary options (higher priority)
      fallback - the fallback options (lower priority)
      返回:
      merged options, or null if both are null