类class io.agentscope.extensions.model.openai 2.x

Builder

public static class Builder

源码Source io/agentscope/extensions/model/openai/OpenAIChatModel.java:219–503

配置 API Key、模型名、端点、格式化器、流式开关与上下文窗口。位于 io.agentscope.extensions.model.openai 包。核心成员包括 apiKey、modelName、stream、generateOptions、baseUrl、endpointPath。

Builder for OpenAIChatModel.

The built model internally wraps the configuration so that calls without explicit options use the builder-provided values.

方法摘要Method Summary

方法Method	说明Description
`public` `Builder apiKey(String apiKey)`	设置 OpenAI API Key。 Sets the API key for OpenAI authentication.
`public` `Builder modelName(String modelName)`	设置模型名称。 Sets the model name to use.
`public` `Builder stream(boolean stream)`	设置是否启用流式输出。 Sets whether streaming should be enabled.
`public` `Builder generateOptions(GenerateOptions options)`	设置该配置项。 Sets the default generation options.
`public` `Builder baseUrl(String baseUrl)`	设置兼容端点的基础 URL。 Sets a custom base URL for OpenAI API.
`public` `Builder endpointPath(String endpointPath)`	设置自定义端点路径用于 API 请求。 Sets a custom endpoint path for the API request.
`public` `Builder formatter(Formatter<OpenAIMessage, OpenAIResponse, OpenAIRequest> formatter)`	设置请求与响应格式化器。 Sets the message formatter to use.
`public` `Builder httpTransport(HttpTransport httpTransport)`	设置HTTP 传输层到使用。 Sets the HTTP transport to use.
`public` `Builder proxy(ProxyConfig proxyConfig)`	设置代理。 Sets the proxy configuration for HTTP traffic.
`public` `Builder contextWindowSize(int contextWindowSize)`	设置上下文窗口大小。 Performs the context window size operation.
`public` `Builder nativeStructuredOutput(boolean nativeStructuredOutput)`	设置原生结构化输出。 Sets whether this model supports native structured output via `response_format`.
`public` `Builder nativeStructuredOutputWithTools(boolean nativeStructuredOutputWithTools)`	设置原生结构化输出使用工具。 Sets whether this model correctly handles native structured output (`response_format`) alongside tool calling.
`public` `OpenAIChatModel build()`	构建 OpenAIChatModel。 Builds the OpenAIChatModel instance.

方法详情Method Detail

apiKey

public Builder apiKey(String apiKey)

设置API 键。

Sets the API key for OpenAI authentication.

参数Parameters

名称Name	类型Type	说明Description
`apiKey`	String	API 密钥。the API key

返回Returns Builder

返回当前实例，以支持链式调用。this builder instance

源码Source io/agentscope/extensions/model/openai/OpenAIChatModel.java:239–242

modelName

public Builder modelName(String modelName)

设置模型名称到使用。

Sets the model name to use.

参数Parameters

名称Name	类型Type	说明Description
`modelName`	String	模型名称（类型 `String`）。the model name (e.g., "gpt-4", "gpt-3.5-turbo")

返回Returns Builder

返回当前实例，以支持链式调用。this builder instance

源码Source io/agentscope/extensions/model/openai/OpenAIChatModel.java:250–253

stream

public Builder stream(boolean stream)

设置流。

Sets whether streaming should be enabled.

参数Parameters

名称Name	类型Type	说明Description
`stream`	boolean	流（类型 `boolean`）。true to enable streaming, false for non-streaming

返回Returns Builder

返回当前实例，以支持链式调用。this builder instance

源码Source io/agentscope/extensions/model/openai/OpenAIChatModel.java:261–264

generateOptions

public Builder generateOptions(GenerateOptions options)

设置该配置项。

Sets the default generation options.

参数Parameters

名称Name	类型Type	说明Description
`options`	GenerateOptions	选项（类型 `GenerateOptions`）。the default options to use (null for defaults)

返回Returns Builder

返回当前实例，以支持链式调用。this builder instance

源码Source io/agentscope/extensions/model/openai/OpenAIChatModel.java:272–275

baseUrl

public Builder baseUrl(String baseUrl)

设置自定义基类 URL 用于 OpenAI API。

Sets a custom base URL for OpenAI API.

参数Parameters

名称Name	类型Type	说明Description
`baseUrl`	String	基类 URL（类型 `String`）。the base URL (null for default)

返回Returns Builder

返回当前实例，以支持链式调用。this builder instance

源码Source io/agentscope/extensions/model/openai/OpenAIChatModel.java:283–286

endpointPath

public Builder endpointPath(String endpointPath)

设置自定义端点路径用于 API 请求。

Sets a custom endpoint path for the API request.

参数Parameters

名称Name	类型Type	说明Description
`endpointPath`	String	端点路径（类型 `String`）。the endpoint path (e.g., "/v1/chat/completions")

返回Returns Builder

返回当前实例，以支持链式调用。this builder instance

源码Source io/agentscope/extensions/model/openai/OpenAIChatModel.java:298–301

formatter

public Builder formatter(Formatter<OpenAIMessage, OpenAIResponse, OpenAIRequest> formatter)

设置消息格式化器到使用。

Sets the message formatter to use.

参数Parameters

名称Name	类型Type	说明Description
`formatter`	Formatter<OpenAIMessage, OpenAIResponse, OpenAIRequest>	格式化器（类型 `Formatter`）。the formatter (null for default OpenAI formatter)

返回Returns Builder

返回当前实例，以支持链式调用。this builder instance

源码Source io/agentscope/extensions/model/openai/OpenAIChatModel.java:318–322

httpTransport

public Builder httpTransport(HttpTransport httpTransport)

设置HTTP 传输层到使用。

Sets the HTTP transport to use.

参数Parameters

名称Name	类型Type	说明Description
`httpTransport`	HttpTransport	HTTP 传输层（类型 `HttpTransport`）。the HTTP transport (null for default from factory)

返回Returns Builder

返回当前实例，以支持链式调用。this builder instance

源码Source io/agentscope/extensions/model/openai/OpenAIChatModel.java:345–348

proxy

public Builder proxy(ProxyConfig proxyConfig)

设置代理。

Sets the proxy configuration for HTTP traffic.

参数Parameters

名称Name	类型Type	说明Description
`proxyConfig`	ProxyConfig	代理配置（类型 `ProxyConfig`）。the proxy configuration (see `ProxyConfig`)

返回Returns Builder

返回当前实例，以支持链式调用。this builder instance

源码Source io/agentscope/extensions/model/openai/OpenAIChatModel.java:375–378

contextWindowSize

public Builder contextWindowSize(int contextWindowSize)

设置该配置项。

Performs the context window size operation.

参数Parameters

名称Name	类型Type	说明Description
`contextWindowSize`	int	上下文 Window 大小（类型 `int`）。The context window size.

返回Returns Builder

返回当前实例，以支持链式调用。Returns the current instance for chaining.

源码Source io/agentscope/extensions/model/openai/OpenAIChatModel.java:380–383

nativeStructuredOutput

public Builder nativeStructuredOutput(boolean nativeStructuredOutput)

设置原生结构化输出。

Sets whether this model supports native structured output via response_format.

参数Parameters

名称Name	类型Type	说明Description
`nativeStructuredOutput`	boolean	原生结构化输出（类型 `boolean`）。false to disable native structured output

返回Returns Builder

返回当前实例，以支持链式调用。this builder instance

源码Source io/agentscope/extensions/model/openai/OpenAIChatModel.java:397–400

nativeStructuredOutputWithTools

public Builder nativeStructuredOutputWithTools(boolean nativeStructuredOutputWithTools)

设置原生结构化输出使用工具。

Sets whether this model correctly handles native structured output (response_format) alongside tool calling.

参数Parameters

名称Name	类型Type	说明Description
`nativeStructuredOutputWithTools`	boolean	原生结构化输出使用工具（类型 `boolean`）。false to use fallback when tools are present

返回Returns Builder

返回当前实例，以支持链式调用。this builder instance

源码Source io/agentscope/extensions/model/openai/OpenAIChatModel.java:414–417

build

public OpenAIChatModel build()

构建OpenAIChatModel 实例。

Builds the OpenAIChatModel instance.

返回Returns OpenAIChatModel

返回OpenAIChatModel。configured OpenAIChatModel instance

抛出Throws

IllegalArgumentException 当if modelName是不设置时抛出 `IllegalArgumentException`。if modelName is not set

源码Source io/agentscope/extensions/model/openai/OpenAIChatModel.java:425–467