LLM 参数

本页提供关于 Koog 智能体框架中 LLM 参数的详细信息。LLM 参数允许您控制和定制语言模型的行为。

概述

LLM 参数是配置选项，可让您微调语言模型生成响应的方式。这些参数控制响应随机性、长度、格式和工具使用等方面。通过调整这些参数，您可以为不同用例优化模型行为，从创意内容生成到确定性结构化输出。

在 Koog 中，LLMParams 类整合了 LLM 参数，并为配置语言模型行为提供了一致的接口。您可以通过以下方式使用 LLM 参数：

• 创建提示时：

KotlinJava

val prompt = prompt(
    id = "dev-assistant",
    params = LLMParams(
        temperature = 0.7,
        maxTokens = 500
    )
) {
    // 添加系统消息以设置上下文
    system("You are a helpful assistant.")

    // 添加用户消息
    user("Tell me about Kotlin")
}

Prompt prompt = Prompt.builder("dev-assistant")
    .withParams(new LLMParams(
        0.7,         // temperature
        500,         // maxTokens
        1,           // numberOfChoices
        null,        // speculation
        null,        // schema
        LLMParams.ToolChoice.Auto.INSTANCE, // toolChoice
        null,        // user
        null         // additionalProperties
    ))
    .system("You are a helpful assistant.")
    .user("Tell me about Kotlin")
    .build();

有关提示创建的更多信息，请参阅提示。

• 创建子图时：

KotlinJava

val processQuery by subgraphWithTask<String, String>(
    tools = listOf(searchTool, calculatorTool, weatherTool),
    llmModel = OpenAIModels.Chat.GPT4o,
    llmParams = LLMParams(
        temperature = 0.7,
        maxTokens = 500
    ),
    runMode = ToolCalls.SEQUENTIAL,
    assistantResponseRepeatMax = 3,
) { userQuery ->
    """
    You are a helpful assistant that can answer questions about various topics.
    Please help with the following query:
    $userQuery
    """
}

有关 Koog 中现有子图类型的更多信息，请参阅预定义子图。要了解如何创建和实现自己的子图，请参阅自定义子图。

• 在 LLM 写入会话中更新提示时：

=== "Kotlin"

llm.writeSession {
    changeLLMParams(
        LLMParams(
            temperature = 0.7,
            maxTokens = 500
        )
    )
}

Java

有关会话的更多信息，请参阅LLM 会话与手动历史记录管理。

LLM 参数参考

下表提供了 LLMParams 类中包含且由 Koog 开箱即用的所有 LLM 提供商支持的 LLM 参数参考。 有关特定于某些提供商的参数列表，请参阅提供商特定参数。| 参数 | 类型 | 描述 | |-----------------------|--------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | temperature | Double | 控制输出结果的随机性。较高的值（如 0.7–1.0）会产生更多样化和创造性的响应，而较低的值会产生更确定性和聚焦的响应。 | | maxTokens | Integer | 响应中生成的最大令牌数。用于控制响应长度。 | | numberOfChoices | Integer | 生成的备选响应数量。必须大于 0。 | | speculation | String | 影响模型行为的推测性配置字符串，旨在提升结果速度和准确性。仅特定模型支持，但可能显著提升速度和准确性。 | | schema | Schema | 定义模型响应格式的结构，支持结构化输出，如 JSON。更多信息请参阅 Schema。 | | toolChoice | ToolChoice | 控制语言模型的工具调用行为。更多信息请参阅 Tool choice。 | | user | String | 发起请求的用户标识符，可用于追踪目的。 | | additionalProperties | Map<String, JsonElement> | 可用于存储特定模型提供商自定义参数的附加属性。 |

各参数的默认值列表，请参阅相应的 LLM 提供商文档：

• OpenAI Chat
• OpenAI Responses
• Google
• Anthropic
• Mistral
• DeepSeek
• OpenRouter
• 阿里巴巴 (DashScope)

Schema

Schema 接口定义了模型响应格式的结构。 Koog 支持 JSON 模式，如下文各节所述。

JSON 模式JSON 模式允许您向语言模型请求结构化的 JSON 数据。Koog 支持以下两种类型的 JSON 模式：

1) 基础 JSON 模式 (LLMParams.Schema.JSON.Basic)：用于基础的 JSON 处理能力。此格式主要关注嵌套数据定义，不包含高级的 JSON 模式功能。

KotlinJavaKotlin

// 使用基础 JSON 模式创建参数
val jsonParams = LLMParams(
    temperature = 0.2,
    schema = LLMParams.Schema.JSON.Basic(
        name = "PersonInfo",
        schema = JsonObject(mapOf(
            "type" to JsonPrimitive("object"),
            "properties" to JsonObject(
                mapOf(
                    "name" to JsonObject(mapOf("type" to JsonPrimitive("string"))),
                    "age" to JsonObject(mapOf("type" to JsonPrimitive("number"))),
                    "skills" to JsonObject(
                        mapOf(
                            "type" to JsonPrimitive("array"),
                            "items" to JsonObject(mapOf("type" to JsonPrimitive("string")))
                        )
                    )
                )
            ),
            "additionalProperties" to JsonPrimitive(false),
            "required" to JsonArray(listOf(JsonPrimitive("name"), JsonPrimitive("age"), JsonPrimitive("skills")))
        ))
    )
)

// 使用基础 JSON 模式创建参数
LLMParams jsonParams = new LLMParams(
    0.2,         // temperature
    null,        // maxTokens
    1,           // numberOfChoices
    null,        // speculation
    new LLMParams.Schema.JSON.Basic(
        "PersonInfo",
        new JsonObject(Map.of(
            "type", new JsonPrimitive("object"),
            "properties", new JsonObject(Map.of(
                "name", new JsonObject(Map.of("type", new JsonPrimitive("string"))),
                "age", new JsonObject(Map.of("type", new JsonPrimitive("number"))),
                "skills", new JsonObject(Map.of(
                    "type", new JsonPrimitive("array"),
                    "items", new JsonObject(Map.of("type", new JsonPrimitive("string")))
                ))
            )),
            "additionalProperties", new JsonPrimitive(false),
            "required", new JsonArray(List.of(
                new JsonPrimitive("name"),
                new JsonPrimitive("age"),
                new JsonPrimitive("skills")
            ))
        ))
    ),
    LLMParams.ToolChoice.Auto.INSTANCE, // toolChoice
    null,        // user
    null         // additionalProperties
);

2) 标准 JSON 架构 (LLMParams.Schema.JSON.Standard)：表示符合 json-schema.org 的标准 JSON 架构。此格式是官方 JSON 架构规范的一个真子集。请注意，不同 LLM 提供商的实现风格可能有所不同，因为它们并非全部支持完整的 JSON 架构。

// 使用标准 JSON 架构创建参数
val standardJsonParams = LLMParams(
    temperature = 0.2,
    schema = LLMParams.Schema.JSON.Standard(
        name = "ProductCatalog",
        schema = JsonObject(mapOf(
            "type" to JsonPrimitive("object"),
            "properties" to JsonObject(mapOf(
                "products" to JsonObject(mapOf(
                    "type" to JsonPrimitive("array"),
                    "items" to JsonObject(mapOf(
                        "type" to JsonPrimitive("object"),
                        "properties" to JsonObject(mapOf(
                            "id" to JsonObject(mapOf("type" to JsonPrimitive("string"))),
                            "name" to JsonObject(mapOf("type" to JsonPrimitive("string"))),
                            "price" to JsonObject(mapOf("type" to JsonPrimitive("number"))),
                            "description" to JsonObject(mapOf("type" to JsonPrimitive("string")))
                        )),
                        "additionalProperties" to JsonPrimitive(false),
                        "required" to JsonArray(listOf(JsonPrimitive("id"), JsonPrimitive("name"), JsonPrimitive("price"), JsonPrimitive("description")))
                    ))
                ))
            )),
            "additionalProperties" to JsonPrimitive(false),
            "required" to JsonArray(listOf(JsonPrimitive("products")))
        ))
    )
)

=== "Java"

// 使用标准的 JSON 模式创建参数
LLMParams standardJsonParams = new LLMParams(
    0.2,         // temperature
    null,        // maxTokens
    1,           // numberOfChoices
    null,        // speculation
    new LLMParams.Schema.JSON.Standard(
        "ProductCatalog",
        new JsonObject(Map.of(
            "type", new JsonPrimitive("object"),
            "properties", new JsonObject(Map.of(
                "products", new JsonObject(Map.of(
                    "type", new JsonPrimitive("array"),
                    "items", new JsonObject(Map.of(
                        "type", new JsonPrimitive("object"),
                        "properties", new JsonObject(Map.of(
                            "id", new JsonObject(Map.of("type", new JsonPrimitive("string"))),
                            "name", new JsonObject(Map.of("type", new JsonPrimitive("string"))),
                            "price", new JsonObject(Map.of("type", new JsonPrimitive("number"))),
                            "description", new JsonObject(Map.of("type", new JsonPrimitive("string")))
                        )),
                        "additionalProperties", new JsonPrimitive(false),
                        "required", new JsonArray(List.of(
                            new JsonPrimitive("id"),
                            new JsonPrimitive("name"),
                            new JsonPrimitive("price"),
                            new JsonPrimitive("description")
                        ))
                    ))
                ))
            )),
            "additionalProperties", new JsonPrimitive(false),
            "required", new JsonArray(List.of(new JsonPrimitive("products")))
        ))
    ),
    LLMParams.ToolChoice.Auto.INSTANCE, // toolChoice
    null,        // user
    null         // additionalProperties
);

工具选择

ToolChoice 类控制语言模型如何使用工具。它提供以下选项：

• LLMParams.ToolChoice.Named：语言模型调用指定的工具。接受一个 name 字符串参数，该参数表示要调用的工具名称。
• LLMParams.ToolChoice.All：语言模型调用所有工具。
• LLMParams.ToolChoice.None：语言模型不调用工具，仅生成文本。
• LLMParams.ToolChoice.Auto：语言模型自动决定是否调用工具以及调用哪个工具。
• LLMParams.ToolChoice.Required：语言模型至少调用一个工具。

以下是使用 LLMParams.ToolChoice.Named 类调用特定工具的示例：

Kotlin

val specificToolParams = LLMParams(
    toolChoice = LLMParams.ToolChoice.Named(name = "calculator")
)

=== "Java"

LLMParams specificToolParams = new LLMParams(
    null,        // temperature
    null,        // maxTokens
    1,           // numberOfChoices
    null,        // speculation
    null,        // schema
    new LLMParams.ToolChoice.Named("calculator"), // toolChoice
    null,        // user
    null         // additionalProperties
);

供应商特定参数

Koog 支持部分 LLM 供应商的特定参数。这些参数扩展了基础 LLMParams 类，并增加了供应商特定的功能。以下类包含按供应商特定的参数：

• OpenAIChatParams：特定于 OpenAI 聊天补全 API 的参数。
• OpenAIResponsesParams：特定于 OpenAI 响应 API 的参数。
• GoogleParams：特定于 Google 模型的参数。
• AnthropicParams：特定于 Anthropic 模型的参数。
• MistralAIParams：特定于 Mistral 模型的参数。
• DeepSeekParams：特定于 DeepSeek 模型的参数。
• OpenRouterParams：特定于 OpenRouter 模型的参数。
• DashscopeParams：特定于阿里巴巴模型的参数。

以下是 Koog 中供应商特定参数的完整参考：

OpenAI 聊天OpenAI 响应Google

参数	类型	说明
audio	OpenAIAudioConfig	使用支持音频的模型时的音频输出配置。更多信息，请参阅 OpenAIAudioConfig 的 API 文档。
frequencyPenalty	Double	对频繁出现的标记进行惩罚以减少重复。较高的 frequencyPenalty 值会导致措辞变化更大并减少重复。取值范围为 -2.0 到 2.0。
logprobs	Boolean	如果设置为 true，则包含输出标记的对数概率。
parallelToolCalls	Boolean	如果设置为 true，则可以并行运行多个工具调用。特别适用于自定义节点或代理策略之外的 LLM 交互。
presencePenalty	Double	防止模型重用已包含在输出中的标记。较高的值鼓励引入新标记和新主题。取值范围为 -2.0 到 2.0。
promptCacheKey	String	用于提示缓存的稳定缓存键。OpenAI 使用它来缓存类似请求的响应。
reasoningEffort	ReasoningEffort	指定模型将使用的推理努力级别。更多信息和可用值，请参阅 ReasoningEffort 的 API 文档。
safetyIdentifier	String	稳定且唯一的用户标识符，可用于检测违反 OpenAI 政策的用户。
serviceTier	ServiceTier	OpenAI 处理层级选择，允许您在性能与成本之间进行优先权衡。更多信息，请参阅 ServiceTier 的 API 文档。
stop	List<String>	指示模型在遇到其中任何一个字符串时应停止生成内容的字符串。例如，要使模型在生成两个换行符时停止生成内容，可将停止序列指定为 stop = listOf("/n/n")。
store	Boolean	如果设置为 true，提供商可能会存储输出以供后续检索。
topLogprobs	Integer	每个位置最可能的前 N 个标记数量。取值范围为 0–20。需要将 logprobs 参数设置为 true。
topP	Double	也称为核采样。通过将概率值最高的标记添加到子集中，直到其概率总和达到指定的 topP 值，从而创建下一个标记的子集。取值范围大于 0.0 且小于等于 1.0。

参数	类型	说明
background	Boolean	在后台运行响应。
include	List<OpenAIInclude>	要在模型响应中包含的额外数据，例如网络搜索工具调用的来源或文件搜索工具调用的搜索结果。详细的参考信息，请参阅 Koog API 参考中的 OpenAIInclude。要了解有关 include 参数的更多信息，请参阅 OpenAI 的文档。
logprobs	Boolean	如果设置为 true，则包含输出标记的对数概率。
maxToolCalls	Integer	此响应中允许的内置工具调用的最大总数。取值需大于或等于 0。
parallelToolCalls	Boolean	如果设置为 true，则可以并行运行多个工具调用。特别适用于自定义节点或代理策略之外的 LLM 交互。
promptCacheKey	String	用于提示缓存的稳定缓存键。OpenAI 使用它来缓存类似请求的响应。
reasoning	ReasoningConfig	适用于具备推理能力模型的推理配置。更多信息，请参阅 ReasoningConfig 的 API 文档。
safetyIdentifier	String	稳定且唯一的用户标识符，可用于检测违反 OpenAI 政策的用户。
serviceTier	ServiceTier	OpenAI 处理层级选择，允许您在性能与成本之间进行优先权衡。更多信息，请参阅 ServiceTier 的 API 文档。
store	Boolean	如果设置为 true，提供商可能会存储输出以供后续检索。
topLogprobs	Integer	每个位置最可能的前 N 个标记数量。取值范围为 0–20。需要将 logprobs 参数设置为 true。
topP	Double	也称为核采样。通过将概率值最高的标记添加到子集中，直到其概率总和达到指定的 topP 值，从而创建下一个标记的子集。取值范围大于 0.0 且小于等于 1.0。
truncation	Truncation	当接近上下文窗口时的截断策略。更多信息，请参阅 Truncation 的 API 文档。

参数	类型	说明
thinkingConfig	GoogleThinkingConfig	控制模型是否应暴露其思维链以及可为其花费多少令牌。更多信息，请参阅 API 参考中的 GoogleThinkingConfig。
topK	Integer	生成输出时考虑的最高概率令牌数量。取值需大于或等于 0（具体提供方可能有最低值要求）。
topP	Double	也称为核采样。通过将概率值最高的标记添加到子集中，直到其概率总和达到指定的 topP 值，从而创建下一个标记的子集。取值范围大于 0.0 且小于等于 1.0。

=== "Anthropic"--8<-- llm-parameters-snippets.md:heading llm-parameters-snippets.md:container llm-parameters-snippets.md:mcpServers llm-parameters-snippets.md:serviceTier llm-parameters-snippets.md:stopSequences llm-parameters-snippets.md:thinking llm-parameters-snippets.md:topK llm-parameters-snippets.md:topP

llm-parameters-snippets.md:heading
llm-parameters-snippets.md:frequencyPenalty
llm-parameters-snippets.md:parallelToolCalls
llm-parameters-snippets.md:presencePenalty
llm-parameters-snippets.md:promptMode
llm-parameters-snippets.md:randomSeed
llm-parameters-snippets.md:safePrompt
llm-parameters-snippets.md:stop
llm-parameters-snippets.md:topP


llm-parameters-snippets.md:heading
llm-parameters-snippets.md:frequencyPenalty
llm-parameters-snippets.md:logprobs
llm-parameters-snippets.md:presencePenalty
llm-parameters-snippets.md:stop
llm-parameters-snippets.md:topLogprobs
llm-parameters-snippets.md:topP


llm-parameters-snippets.md:heading
llm-parameters-snippets.md:frequencyPenalty
llm-parameters-snippets.md:logprobs
llm-parameters-snippets.md:minP
llm-parameters-snippets.md:models
llm-parameters-snippets.md:presencePenalty
llm-parameters-snippets.md:provider
llm-parameters-snippets.md:repetitionPenalty
llm-parameters-snippets.md:route
llm-parameters-snippets.md:stop
llm-parameters-snippets.md:topA
llm-parameters-snippets.md:topK
llm-parameters-snippets.md:topLogprobs
llm-parameters-snippets.md:topP
llm-parameters-snippets.md:transforms


llm-parameters-snippets.md:heading
llm-parameters-snippets.md:enableSearch
llm-parameters-snippets.md:enableThinking
llm-parameters-snippets.md:frequencyPenalty
llm-parameters-snippets.md:logprobs
llm-parameters-snippets.md:parallelToolCalls
llm-parameters-snippets.md:presencePenalty
llm-parameters-snippets.md:stop
llm-parameters-snippets.md:topLogprobs
llm-parameters-snippets.md:topP

abbreviations.md