LLM 파라미터

이 페이지는 Koog 에이전틱 프레임워크(agentic framework)의 LLM 파라미터에 대한 세부 정보를 제공합니다. LLM 파라미터를 사용하면 언어 모델의 동작을 제어하고 커스터마이징할 수 있습니다.

개요

LLM 파라미터는 언어 모델이 응답을 생성하는 방식을 미세 조정할 수 있는 구성 옵션입니다. 이러한 파라미터는 응답의 무작위성, 길이, 형식 및 도구 사용과 같은 측면을 제어합니다. 파라미터를 조정하여 창의적인 콘텐츠 생성부터 결정론적인(deterministic) 구조화된 출력(structured outputs)까지, 다양한 유스케이스에 맞춰 모델 동작을 최적화할 수 있습니다.

Koog에서 LLMParams 클래스는 LLM 파라미터를 통합하며 언어 모델 동작 구성을 위한 일관된 인터페이스를 제공합니다. LLM 파라미터는 다음과 같은 방법으로 사용할 수 있습니다:

프롬프트를 생성할 때:

KotlinJava

kotlin

val prompt = prompt(
    id = "dev-assistant",
    params = LLMParams(
        temperature = 0.7,
        maxTokens = 500
    )
) {
    // 컨텍스트 설정을 위해 시스템 메시지 추가
    system("You are a helpful assistant.")

    // 사용자 메시지 추가
    user("Tell me about Kotlin")
}

java

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();

프롬프트 생성에 대한 자세한 내용은 프롬프트(Prompts)를 참고하세요.

서브그래프(subgraph)를 생성할 때:

KotlinJava

kotlin

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

java

Koog에서 제공하는 기존 서브그래프 유형에 대한 자세한 내용은 사전 정의된 서브그래프(Predefined subgraphs)를 참고하세요. 직접 서브그래프를 생성하고 구현하는 방법을 알아보려면 커스텀 서브그래프(Custom subgraphs)를 참고하세요.

LLM 쓰기 세션(write session)에서 프롬프트를 업데이트할 때:

KotlinJava

kotlin

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

java

세션에 대한 자세한 내용은 LLM 세션 및 수동 히스토리 관리를 참고하세요.

LLM 파라미터 레퍼런스

다음 표는 LLMParams 클래스에 포함되어 있으며 Koog에서 기본적으로 제공하는 모든 LLM 제공자가 지원하는 LLM 파라미터 레퍼런스를 제공합니다. 특정 제공자 전용 파라미터 목록은 제공자 전용 파라미터를 참고하세요.

파라미터	타입	설명
`temperature`	Double	출력의 무작위성을 제어합니다. 0.7–1.0과 같이 높은 값은 더 다양하고 창의적인 응답을 생성하며, 낮은 값은 더 결정론적(deterministic)이고 집중된 응답을 생성합니다.
`maxTokens`	Integer	응답에서 생성할 최대 토큰 수입니다. 응답 길이를 제어하는 데 유용합니다.
`numberOfChoices`	Integer	생성할 대체 응답의 수입니다. 0보다 커야 합니다.
`speculation`	String	결과의 속도와 정확성을 향상시키기 위해 설계된, 모델 동작에 영향을 미치는 추측성(speculative) 구성 문자열입니다. 특정 모델에서만 지원되지만 속도와 정확성을 크게 향상시킬 수 있습니다.
`schema`	Schema	모델의 응답 형식 구조를 정의하여 JSON과 같은 구조화된 출력을 가능하게 합니다. 자세한 내용은 스키마(Schema)를 참고하세요.
`toolChoice`	ToolChoice	언어 모델의 도구 호출 동작을 제어합니다. 자세한 내용은 도구 선택(Tool choice)을 참고하세요.
`user`	String	요청을 수행하는 사용자의 식별자로, 추적 목적으로 사용할 수 있습니다.
`additionalProperties`	Map<String, JsonElement>	특정 모델 제공자 전용의 커스텀 파라미터를 저장하는 데 사용할 수 있는 추가 속성입니다.

각 파라미터의 기본값 목록은 해당 LLM 제공자 문서를 참고하세요:

스키마 (Schema)

Schema 인터페이스는 모델의 응답 형식 구조를 정의합니다. Koog는 아래 섹션에 설명된 대로 JSON 스키마를 지원합니다.

JSON 스키마

JSON 스키마를 사용하면 언어 모델로부터 구조화된 JSON 데이터를 요청할 수 있습니다. Koog는 다음과 같은 두 가지 유형의 JSON 스키마를 지원합니다:

기본 JSON 스키마 (LLMParams.Schema.JSON.Basic): 기본적인 JSON 처리 기능에 사용됩니다. 이 형식은 고급 JSON Schema 기능 없이 주로 중첩된 데이터 정의에 중점을 둡니다.

KotlinJava

kotlin

// 기본 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")))
        ))
    )
)

java

// 기본 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
);

표준 JSON 스키마 (LLMParams.Schema.JSON.Standard): json-schema.org에 따른 표준 JSON 스키마를 나타냅니다. 이 형식은 공식 JSON Schema 사양의 적절한 하위 집합입니다. 모든 LLM 제공자가 전체 JSON 스키마를 지원하는 것은 아니므로 제공자마다 세부 사양이 다를 수 있음에 유의하세요.

KotlinJava

kotlin

// 표준 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
);

도구 선택 (Tool choice)

ToolChoice 클래스는 언어 모델이 도구를 사용하는 방식을 제어합니다. 다음과 같은 옵션을 제공합니다:

LLMParams.ToolChoice.Named: 언어 모델이 지정된 도구를 호출합니다. 호출할 도구의 이름을 나타내는 name 문자열 인자를 받습니다.
LLMParams.ToolChoice.All: 언어 모델이 모든 도구를 호출합니다.
LLMParams.ToolChoice.None: 언어 모델이 도구를 호출하지 않고 텍스트만 생성합니다.
LLMParams.ToolChoice.Auto: 언어 모델이 도구 호출 여부와 호출할 도구를 자동으로 결정합니다.
LLMParams.ToolChoice.Required: 언어 모델이 최소 하나 이상의 도구를 호출합니다.

다음은 특정 도구를 호출하기 위해 LLMParams.ToolChoice.Named 클래스를 사용하는 예시입니다:

KotlinJava

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 Chat Completions API 전용 파라미터.
OpenAIResponsesParams: OpenAI Responses API 전용 파라미터.
GoogleParams: Google 모델 전용 파라미터.
AnthropicParams: Anthropic 모델 전용 파라미터.
MistralAIParams: Mistral 모델 전용 파라미터.
DeepSeekParams: DeepSeek 모델 전용 파라미터.
OpenRouterParams: OpenRouter 모델 전용 파라미터.
DashscopeParams: Alibaba 모델 전용 파라미터.
OllamaParams: Ollama 모델 전용 파라미터.

Koog의 제공자 전용 파라미터에 대한 전체 레퍼런스는 다음과 같습니다:

OpenAI ChatOpenAI ResponsesGoogleAnthropicMistralDeepSeekOpenRouterAlibaba (DashScope)Ollama

파라미터	타입	설명
`audio`	OpenAIAudioConfig	오디오 지원 모델을 사용할 때의 오디오 출력 구성입니다. 자세한 내용은 OpenAIAudioConfig API 문서를 참조하세요.
`frequencyPenalty`	Double	빈번하게 나타나는 토큰에 페널티를 부여하여 반복을 줄입니다. `frequencyPenalty` 값이 높을수록 표현의 변화가 많아지고 반복이 줄어듭니다. -2.0에서 2.0 사이의 값을 가집니다.
`logprobs`	Boolean	`true`인 경우, 출력 토큰에 대한 로그 확률(log-probabilities)을 포함합니다.
`parallelToolCalls`	Boolean	`true`인 경우, 여러 도구 호출을 병렬로 실행할 수 있습니다. 특히 에이전트 전략 이외의 커스텀 노드나 LLM 상호작용에 적용됩니다.
`presencePenalty`	Double	모델이 이미 출력에 포함된 토큰을 다시 사용하는 것을 방지합니다. 값이 높을수록 새로운 토큰과 주제의 도입을 장려합니다. -2.0에서 2.0 사이의 값을 가집니다.
`promptCacheKey`	String	프롬프트 캐싱을 위한 고유한 캐시 키입니다. OpenAI는 이를 사용하여 유사한 요청에 대한 응답을 캐시합니다.
`reasoningEffort`	ReasoningEffort	모델이 사용할 추론 노력(reasoning effort) 수준을 지정합니다. 자세한 내용 및 사용 가능한 값은 ReasoningEffort API 문서를 참조하세요.
`safetyIdentifier`	String	OpenAI 정책을 위반하는 사용자를 감지하는 데 사용될 수 있는 고유하고 안정적인 사용자 식별자입니다.
`serviceTier`	ServiceTier	비용보다 성능을 우선시하거나 그 반대로 설정할 수 있는 OpenAI 처리 티어 선택입니다. 자세한 내용은 ServiceTier API 문서를 참조하세요.
`stop`	List<String>	모델이 해당 문자열 중 하나라도 만나면 콘텐츠 생성을 중단해야 함을 알리는 문자열 리스트입니다. 예를 들어, 두 개의 줄바꿈이 발생할 때 생성을 중단하게 하려면 중단 시퀀스를 `stop = listOf("/n/n")`와 같이 지정합니다.
`store`	Boolean	`true`인 경우, 제공자가 나중에 회수할 수 있도록 출력을 저장할 수 있습니다.
`topLogprobs`	Integer	각 위치에서 가장 가능성이 높은 상위 토큰의 개수입니다. 0–20 사이의 값을 가집니다. `logprobs` 파라미터가 `true`로 설정되어야 합니다.
`topP`	Double	핵심 샘플링(nucleus sampling)이라고도 합니다. 확률 값의 합이 지정된 `topP` 값에 도달할 때까지 가장 높은 확률 값을 가진 토큰들을 추가하여 다음 토큰의 하위 집합을 생성합니다. 0.0보다 크고 1.0보다 작거나 같은 값을 가집니다.
`webSearchOptions`	OpenAIWebSearchOptions	웹 검색 도구 사용을 구성합니다(지원되는 경우). 자세한 내용은 OpenAIWebSearchOptions API 문서를 참조하세요.

파라미터	타입	설명
`background`	Boolean	백그라운드에서 응답을 실행합니다.
`include`	List<OpenAIInclude>	웹 검색 도구 호출의 소스나 파일 검색 도구 호출의 검색 결과와 같이 모델 응답에 포함할 추가 데이터입니다. 자세한 참조 정보는 Koog API 참조의 OpenAIInclude를 확인하세요. `include` 파라미터에 대해 자세히 알아보려면 OpenAI 문서를 참조하세요.
`logprobs`	Boolean	`true`인 경우, 출력 토큰에 대한 로그 확률(log-probabilities)을 포함합니다.
`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	각 위치에서 가장 가능성이 높은 상위 토큰의 개수입니다. 0–20 사이의 값을 가집니다. `logprobs` 파라미터가 `true`로 설정되어야 합니다.
`topP`	Double	핵심 샘플링(nucleus sampling)이라고도 합니다. 확률 값의 합이 지정된 `topP` 값에 도달할 때까지 가장 높은 확률 값을 가진 토큰들을 추가하여 다음 토큰의 하위 집합을 생성합니다. 0.0보다 크고 1.0보다 작거나 같은 값을 가집니다.
`truncation`	Truncation	컨텍스트 윈도우에 근접했을 때의 자르기(truncation) 전략입니다. 자세한 내용은 Truncation API 문서를 참조하세요.

파라미터	타입	설명
`thinkingConfig`	GoogleThinkingConfig	모델이 사고 과정(chain-of-thought)을 노출할지 여부와 여기에 소비할 수 있는 최대 토큰 수를 제어합니다. 자세한 내용은 GoogleThinkingConfig API 참조를 확인하세요.
`topK`	Integer	출력을 생성할 때 고려할 상위 토큰의 개수입니다. 0보다 크거나 같은 값을 가집니다(제공자별 최소값이 적용될 수 있음).
`topP`	Double	핵심 샘플링(nucleus sampling)이라고도 합니다. 확률 값의 합이 지정된 `topP` 값에 도달할 때까지 가장 높은 확률 값을 가진 토큰들을 추가하여 다음 토큰의 하위 집합을 생성합니다. 0.0보다 크고 1.0보다 작거나 같은 값을 가집니다.

파라미터	타입	설명
`container`	String	요청 간 재사용을 위한 컨테이너 식별자입니다. 컨테이너는 Anthropic의 코드 실행 도구에서 안전하고 컨테이너화된 코드 실행 환경을 제공하는 데 사용됩니다. 이전 응답의 컨테이너 식별자를 제공하면 여러 요청에서 컨테이너를 재사용할 수 있으며, 이를 통해 요청 간에 생성된 파일을 보존할 수 있습니다. 자세한 내용은 Anthropic 문서의 Containers를 참조하세요.
`mcpServers`	List<AnthropicMCPServerURLDefinition>	요청에서 사용될 MCP 서버의 정의입니다. 최대 20개의 서버를 지원합니다. 자세한 내용은 AnthropicMCPServerURLDefinition API 참조를 확인하세요.
`serviceTier`	ServiceTier	비용보다 성능을 우선시하거나 그 반대로 설정할 수 있는 OpenAI 처리 티어 선택입니다. 자세한 내용은 ServiceTier API 문서를 참조하세요.
`stopSequences`	List<String>	모델이 콘텐츠 생성을 중단하게 만드는 커스텀 텍스트 시퀀스입니다. 일치하는 경우 응답의 `stop_reason` 값은 `stop_sequence`가 됩니다.
`thinking`	AnthropicThinking	Claude의 확장 사고(extended thinking) 활성화를 위한 구성입니다. 활성화되면 응답에 사고 콘텐츠 블록도 포함됩니다. 자세한 내용은 AnthropicThinking API 참조를 확인하세요.
`topK`	Integer	출력을 생성할 때 고려할 상위 토큰의 개수입니다. 0보다 크거나 같은 값을 가집니다(제공자별 최소값이 적용될 수 있음).
`topP`	Double	핵심 샘플링(nucleus sampling)이라고도 합니다. 확률 값의 합이 지정된 `topP` 값에 도달할 때까지 가장 높은 확률 값을 가진 토큰들을 추가하여 다음 토큰의 하위 집합을 생성합니다. 0.0보다 크고 1.0보다 작거나 같은 값을 가집니다.

파라미터	타입	설명
`frequencyPenalty`	Double	빈번하게 나타나는 토큰에 페널티를 부여하여 반복을 줄입니다. `frequencyPenalty` 값이 높을수록 표현의 변화가 많아지고 반복이 줄어듭니다. -2.0에서 2.0 사이의 값을 가집니다.
`parallelToolCalls`	Boolean	`true`인 경우, 여러 도구 호출을 병렬로 실행할 수 있습니다. 특히 에이전트 전략 이외의 커스텀 노드나 LLM 상호작용에 적용됩니다.
`presencePenalty`	Double	모델이 이미 출력에 포함된 토큰을 다시 사용하는 것을 방지합니다. 값이 높을수록 새로운 토큰과 주제의 도입을 장려합니다. -2.0에서 2.0 사이의 값을 가집니다.
`promptMode`	String	추론 모드와 시스템 프롬프트 없음 사이를 전환할 수 있게 합니다. `reasoning`으로 설정하면 추론 모델용 기본 시스템 프롬프트가 사용됩니다. 자세한 내용은 Mistral의 Reasoning 문서를 확인하세요.
`randomSeed`	Integer	무작위 샘플링에 사용할 시드(seed)입니다. 설정 시, 동일한 파라미터와 동일한 시드 값을 사용한 다른 호출은 결정론적인 결과를 생성합니다.
`safePrompt`	Boolean	모든 대화 전에 안전 프롬프트(safety prompt)를 주입할지 여부를 지정합니다. 안전 프롬프트는 가드레일을 적용하고 유해한 콘텐츠로부터 보호하는 데 사용됩니다. 자세한 내용은 Mistral의 Moderation & Guardarailing 문서를 확인하세요.
`stop`	List<String>	모델이 해당 문자열 중 하나라도 만나면 콘텐츠 생성을 중단해야 함을 알리는 문자열 리스트입니다. 예를 들어, 두 개의 줄바꿈이 발생할 때 생성을 중단하게 하려면 중단 시퀀스를 `stop = listOf("/n/n")`와 같이 지정합니다.
`topP`	Double	핵심 샘플링(nucleus sampling)이라고도 합니다. 확률 값의 합이 지정된 `topP` 값에 도달할 때까지 가장 높은 확률 값을 가진 토큰들을 추가하여 다음 토큰의 하위 집합을 생성합니다. 0.0보다 크고 1.0보다 작거나 같은 값을 가집니다.

파라미터	타입	설명
`frequencyPenalty`	Double	빈번하게 나타나는 토큰에 페널티를 부여하여 반복을 줄입니다. `frequencyPenalty` 값이 높을수록 표현의 변화가 많아지고 반복이 줄어듭니다. -2.0에서 2.0 사이의 값을 가집니다.
`logprobs`	Boolean	`true`인 경우, 출력 토큰에 대한 로그 확률(log-probabilities)을 포함합니다.
`presencePenalty`	Double	모델이 이미 출력에 포함된 토큰을 다시 사용하는 것을 방지합니다. 값이 높을수록 새로운 토큰과 주제의 도입을 장려합니다. -2.0에서 2.0 사이의 값을 가집니다.
`stop`	List<String>	모델이 해당 문자열 중 하나라도 만나면 콘텐츠 생성을 중단해야 함을 알리는 문자열 리스트입니다. 예를 들어, 두 개의 줄바꿈이 발생할 때 생성을 중단하게 하려면 중단 시퀀스를 `stop = listOf("/n/n")`와 같이 지정합니다.
`topLogprobs`	Integer	각 위치에서 가장 가능성이 높은 상위 토큰의 개수입니다. 0–20 사이의 값을 가집니다. `logprobs` 파라미터가 `true`로 설정되어야 합니다.
`topP`	Double	핵심 샘플링(nucleus sampling)이라고도 합니다. 확률 값의 합이 지정된 `topP` 값에 도달할 때까지 가장 높은 확률 값을 가진 토큰들을 추가하여 다음 토큰의 하위 집합을 생성합니다. 0.0보다 크고 1.0보다 작거나 같은 값을 가집니다.

파라미터	타입	설명
`frequencyPenalty`	Double	빈번하게 나타나는 토큰에 페널티를 부여하여 반복을 줄입니다. `frequencyPenalty` 값이 높을수록 표현의 변화가 많아지고 반복이 줄어듭니다. -2.0에서 2.0 사이의 값을 가집니다.
`logprobs`	Boolean	`true`인 경우, 출력 토큰에 대한 로그 확률(log-probabilities)을 포함합니다.
`minP`	Double	가장 가능성이 높은 토큰에 대한 상대적 확률이 정의된 `minP` 값 미만인 토큰을 필터링합니다. 0.0–0.1 범위의 값을 가집니다.
`models`	List<String>	요청에 허용되는 모델 리스트입니다.
`presencePenalty`	Double	모델이 이미 출력에 포함된 토큰을 다시 사용하는 것을 방지합니다. 값이 높을수록 새로운 토큰과 주제의 도입을 장려합니다. -2.0에서 2.0 사이의 값을 가집니다.
`provider`	ProviderPreferences	OpenRouter가 사용할 LLM 제공자를 선택하는 방식을 명시적으로 제어할 수 있는 다양한 파라미터를 포함합니다. 자세한 내용은 ProviderPreferences API 문서를 참조하세요.
`repetitionPenalty`	Double	토큰 반복에 페널티를 부여합니다. 이미 출력에 나타난 토큰의 다음 토큰 확률을 `repetitionPenalty` 값으로 나눕니다. `repetitionPenalty > 1`인 경우 해당 토큰이 다시 나타날 가능성이 낮아집니다. 0.0보다 크고 2.0보다 작거나 같은 값을 가집니다.
`route`	String	사용할 요청 라우팅 전략입니다.
`stop`	List<String>	모델이 해당 문자열 중 하나라도 만나면 콘텐츠 생성을 중단해야 함을 알리는 문자열 리스트입니다. 예를 들어, 두 개의 줄바꿈이 발생할 때 생성을 중단하게 하려면 중단 시퀀스를 `stop = listOf("/n/n")`와 같이 지정합니다.
`topA`	Double	모델의 확신도에 따라 샘플링 윈도우를 동적으로 조정합니다. 모델이 확신하는 경우(지배적인 고확률 다음 토큰이 있는 경우) 샘플링 윈도우를 소수의 상위 토큰으로 제한합니다. 확신도가 낮은 경우(확률이 비슷한 토큰이 많은 경우) 샘플링 윈도우에 더 많은 토큰을 유지합니다. 0.0–0.1(포함) 범위의 값을 가집니다. 값이 높을수록 동적 적응 폭이 커집니다.
`topK`	Integer	출력을 생성할 때 고려할 상위 토큰의 개수입니다. 0보다 크거나 같은 값을 가집니다(제공자별 최소값이 적용될 수 있음).
`topLogprobs`	Integer	각 위치에서 가장 가능성이 높은 상위 토큰의 개수입니다. 0–20 사이의 값을 가집니다. `logprobs` 파라미터가 `true`로 설정되어야 합니다.
`topP`	Double	핵심 샘플링(nucleus sampling)이라고도 합니다. 확률 값의 합이 지정된 `topP` 값에 도달할 때까지 가장 높은 확률 값을 가진 토큰들을 추가하여 다음 토큰의 하위 집합을 생성합니다. 0.0보다 크고 1.0보다 작거나 같은 값을 가집니다.
`transforms`	List<String>	컨텍스트 변환 리스트입니다. 컨텍스트가 모델의 토큰 제한을 초과할 때 변환되는 방식을 정의합니다. 기본 변환은 프롬프트의 중간부터 자르는 `middle-out`입니다. 변환을 사용하지 않으려면 빈 리스트를 사용하세요. 자세한 내용은 OpenRouter 문서의 Message Transforms를 참조하세요.

파라미터	타입	설명
`enableSearch`	Boolean	웹 검색 기능 활성화 여부를 지정합니다. 자세한 내용은 Alibaba의 Web search 문서를 확인하세요.
`enableThinking`	Boolean	하이브리드 사고 모델을 사용할 때 사고 모드(thinking mode) 활성화 여부를 지정합니다. 자세한 내용은 Alibaba의 Deep thinking 문서를 확인하세요.
`frequencyPenalty`	Double	빈번하게 나타나는 토큰에 페널티를 부여하여 반복을 줄입니다. `frequencyPenalty` 값이 높을수록 표현의 변화가 많아지고 반복이 줄어듭니다. -2.0에서 2.0 사이의 값을 가집니다.
`logprobs`	Boolean	`true`인 경우, 출력 토큰에 대한 로그 확률(log-probabilities)을 포함합니다.
`parallelToolCalls`	Boolean	`true`인 경우, 여러 도구 호출을 병렬로 실행할 수 있습니다. 특히 에이전트 전략 이외의 커스텀 노드나 LLM 상호작용에 적용됩니다.
`presencePenalty`	Double	모델이 이미 출력에 포함된 토큰을 다시 사용하는 것을 방지합니다. 값이 높을수록 새로운 토큰과 주제의 도입을 장려합니다. -2.0에서 2.0 사이의 값을 가집니다.
`stop`	List<String>	모델이 해당 문자열 중 하나라도 만나면 콘텐츠 생성을 중단해야 함을 알리는 문자열 리스트입니다. 예를 들어, 두 개의 줄바꿈이 발생할 때 생성을 중단하게 하려면 중단 시퀀스를 `stop = listOf("/n/n")`와 같이 지정합니다.
`topLogprobs`	Integer	각 위치에서 가장 가능성이 높은 상위 토큰의 개수입니다. 0–20 사이의 값을 가집니다. `logprobs` 파라미터가 `true`로 설정되어야 합니다.
`topP`	Double	핵심 샘플링(nucleus sampling)이라고도 합니다. 확률 값의 합이 지정된 `topP` 값에 도달할 때까지 가장 높은 확률 값을 가진 토큰들을 추가하여 다음 토큰의 하위 집합을 생성합니다. 0.0보다 크고 1.0보다 작거나 같은 값을 가집니다.

파라미터	타입	설명
`think`	Boolean	Ollama의 확장 사고(extended thinking) 활성화를 위한 구성입니다. 활성화되면 응답에 사고 콘텐츠 블록도 포함됩니다. 자세한 내용은 Ollama thinking API 참조를 확인하세요.

다음 예시는 제공자 전용 OpenRouterParams 클래스를 사용하여 정의된 OpenRouter LLM 파라미터를 보여줍니다:

KotlinJava

kotlin

val openRouterParams = OpenRouterParams(
    temperature = 0.7,
    maxTokens = 500,
    frequencyPenalty = 0.5,
    presencePenalty = 0.5,
    topP = 0.9,
    topK = 40,
    repetitionPenalty = 1.1,
    models = listOf("anthropic/claude-3-opus", "anthropic/claude-3-sonnet"),
    transforms = listOf("middle-out")
)

java

OpenRouterParams openRouterParams = new OpenRouterParams(
    0.7,         // temperature
    500,         // maxTokens
    1,           // numberOfChoices
    null,        // speculation
    null,        // schema
    null,        // toolChoice
    null,        // user
    null,        // additionalProperties
    0.5,         // frequencyPenalty
    null,        // logprobs
    null,        // minP
    Arrays.asList("anthropic/claude-3-opus", "anthropic/claude-3-sonnet"), // models
    0.5,         // presencePenalty
    null,        // provider
    1.1,         // repetitionPenalty
    null,        // route
    null,        // stop
    null,        // topA
    40,          // topK
    null,        // topLogprobs
    0.9,         // topP
    Arrays.asList("middle-out") // transforms
);

사용 예시

기본 사용법

KotlinJava

kotlin

// 길이가 제한된 기본 파라미터 세트
val basicParams = LLMParams(
    temperature = 0.7,
    maxTokens = 150,
    toolChoice = LLMParams.ToolChoice.Auto
)

java

// 길이가 제한된 기본 파라미터 세트
LLMParams basicParams = new LLMParams(
    0.7,         // temperature
    150,         // maxTokens
    1,           // numberOfChoices
    null,        // speculation
    null,        // schema
    LLMParams.ToolChoice.Auto.INSTANCE, // toolChoice
    null,        // user
    null         // additionalProperties
);

추론(Reasoning) 제어

모델의 추론을 제어하는 제공자 전용 파라미터를 통해 추론 제어를 구현합니다. OpenAI Chat API 및 추론을 지원하는 모델을 사용하는 경우, reasoningEffort 파라미터를 사용하여 모델이 응답을 제공하기 전에 생성할 추론 토큰의 양을 제어할 수 있습니다:

KotlinJava

kotlin

val openAIReasoningEffortParams = OpenAIChatParams(
    reasoningEffort = ReasoningEffort.MEDIUM
)

java

OpenAIChatParams openAIReasoningEffortParams = new OpenAIChatParams(
    null,        // temperature
    null,        // maxTokens
    1,           // numberOfChoices
    null,        // speculation
    null,        // schema
    null,        // toolChoice
    null,        // user
    null,        // additionalProperties
    null,        // audio
    null,        // frequencyPenalty
    null,        // logprobs
    null,        // parallelToolCalls
    null,        // presencePenalty
    null,        // promptCacheKey
    ReasoningEffort.MEDIUM, // reasoningEffort
    null,        // safetyIdentifier
    null,        // serviceTier
    null,        // stop
    null,        // store
    null,        // topLogprobs
    null,        // topP
    null         // webSearchOptions
);

또한, 상태 비저장(stateless) 모드에서 OpenAI Responses API를 사용하는 경우, 추론 항목의 암호화된 히스토리를 유지하고 매 대화 차례(conversation turn)마다 이를 모델에 전송합니다. 암호화는 OpenAI 측에서 수행되며, 요청 시 include 파라미터를 reasoning.encrypted_content로 설정하여 암호화된 추론 토큰을 요청해야 합니다. 그런 다음 다음 대화 차례에서 암호화된 추론 토큰을 모델에 다시 전달할 수 있습니다.

KotlinJava

kotlin

val openAIStatelessReasoningParams = OpenAIResponsesParams(
    include = listOf(OpenAIInclude.REASONING_ENCRYPTED_CONTENT)
)

java

OpenAIResponsesParams openAIStatelessReasoningParams = new OpenAIResponsesParams(
    null,        // temperature
    null,        // maxTokens
    1,           // numberOfChoices
    null,        // speculation
    null,        // schema
    null,        // toolChoice
    null,        // user
    null,        // additionalProperties
    null,        // background
    Arrays.asList(OpenAIInclude.REASONING_ENCRYPTED_CONTENT), // include
    null,        // logprobs
    null,        // maxToolCalls
    null,        // parallelToolCalls
    null,        // promptCacheKey
    null,        // reasoning
    null,        // safetyIdentifier
    null,        // serviceTier
    null,        // store
    null,        // topLogprobs
    null,        // topP
    null         // truncation
);

커스텀 파라미터

제공자 전용이거나 Koog에서 기본적으로 지원하지 않는 커스텀 파라미터를 추가하려면 아래 예시와 같이 additionalProperties 속성을 사용하세요.

KotlinJava

kotlin

// 특정 모델 제공자를 위한 커스텀 파라미터 추가
val customParams = LLMParams(
    additionalProperties = additionalPropertiesOf(
        "top_p" to 0.95,
        "frequency_penalty" to 0.5,
        "presence_penalty" to 0.5
    )
)

java

// 특정 모델 제공자를 위한 커스텀 파라미터 추가
LLMParams customParams = new LLMParams(
    null,        // temperature
    null,        // maxTokens
    1,           // numberOfChoices
    null,        // speculation
    null,        // schema
    null,        // toolChoice
    null,        // user
    AdditionalPropertiesKt.additionalPropertiesOf(
        "top_p", 0.95,
        "frequency_penalty", 0.5,
        "presence_penalty", 0.5
    )
);

파라미터 설정 및 재정의(Overriding)

아래 코드 샘플은 주로 사용할 LLM 파라미터 세트를 정의한 후, 원래 세트의 값을 일부 재정의하고 새 값을 추가하여 다른 세트를 생성하는 방법을 보여줍니다. 이를 통해 대부분의 요청에 공통적인 파라미터를 정의하고, 공통 파라미터를 반복할 필요 없이 더 구체적인 파라미터 조합을 추가할 수 있습니다.

KotlinJava

kotlin

// 기본 파라미터 정의
val defaultParams = LLMParams(
    temperature = 0.7,
    maxTokens = 150,
    toolChoice = LLMParams.ToolChoice.Auto
)

// 일부는 재정의하고 나머지는 기본값을 사용하는 파라미터 생성
val overrideParams = LLMParams(
    temperature = 0.2,
    numberOfChoices = 3
).default(defaultParams)

java

// 기본 파라미터 정의
LLMParams defaultParams = new LLMParams(
    0.7,         // temperature
    150,         // maxTokens
    1,           // numberOfChoices
    null,        // speculation
    null,        // schema
    LLMParams.ToolChoice.Auto.INSTANCE, // toolChoice
    null,        // user
    null         // additionalProperties
);

// 일부는 재정의하고 나머지는 기본값을 사용하는 파라미터 생성
LLMParams overrideParams = new LLMParams(
    0.2,         // temperature
    null,        // maxTokens
    3,           // numberOfChoices
    null,        // speculation
    null,        // schema
    null,        // toolChoice
    null,        // user
    null         // additionalProperties
).applyDefaults(defaultParams);

결과로 생성된 overrideParams 세트의 값은 다음과 동일합니다:

KotlinJava

kotlin

val overrideParams = LLMParams(
    temperature = 0.2,
    maxTokens = 150,
    toolChoice = LLMParams.ToolChoice.Auto,
    numberOfChoices = 3
)

java

LLMParams overrideParams = new LLMParams(
    0.2,         // temperature
    150,         // maxTokens
    3,           // numberOfChoices
    null,        // speculation
    null,        // schema
    LLMParams.ToolChoice.Auto.INSTANCE, // toolChoice
    null,        // user
    null         // additionalProperties
);

개요

에이전트

플래너 에이전트

프롬프트

프롬프트 만들기

프롬프트 실행

도구

기능

채팅 메모리

OpenTelemetry

A2A 프로토콜

서브그래프

LLM 파라미터

개요

LLM 파라미터 레퍼런스

스키마 (Schema)

JSON 스키마

도구 선택 (Tool choice)

제공자 전용 파라미터

사용 예시

기본 사용법

추론(Reasoning) 제어

커스텀 파라미터

파라미터 설정 및 재정의(Overriding)

플래너 에이전트

프롬프트 만들기

채팅 메모리

OpenTelemetry

LLM 파라미터 ​

개요 ​

LLM 파라미터 레퍼런스 ​

스키마 (Schema) ​

JSON 스키마 ​

도구 선택 (Tool choice) ​

제공자 전용 파라미터 ​

사용 예시 ​

기본 사용법 ​

추론(Reasoning) 제어 ​

커스텀 파라미터 ​

파라미터 설정 및 재정의(Overriding) ​

LLM 파라미터

개요

LLM 파라미터 레퍼런스

스키마 (Schema)

JSON 스키마

도구 선택 (Tool choice)

제공자 전용 파라미터

사용 예시

기본 사용법

추론(Reasoning) 제어

커스텀 파라미터

파라미터 설정 및 재정의(Overriding)