블로그 | 모하지?

원문: Koog Documentation — llm-parameters 이 글은 Koog 공식 문서의 llm-parameters 페이지를 한국어로 옮긴 번역본입니다. 문서 구조와 링크 의미를 유지하되, MkDocs 전용 UI 문법은 블로그에서 읽기 좋도록 정리했습니다.

LLM 매개변수

이 페이지에서는 Koog 에이전트 프레임워크의 LLM 매개변수에 대한 세부정보를 제공합니다. LLM 매개변수를 사용하면 언어 모델의 동작을 사용자 정의합니다.

개요

LLM 매개변수는 언어 모델이 응답을 생성하는 방법을 미세 조정할 수 있는 구성 옵션입니다. 이 매개변수 응답 무작위성, 길이, 형식 및 도구 사용과 같은 측면을 제어합니다. 매개변수를 조정하여 최적화합니다. 창의적인 콘텐츠 생성부터 결정론적 구조화된 출력까지 다양한 사용 사례에 대한 모델 동작을 제공합니다.

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

프롬프트를 생성할 때:

코틀린

1val prompt = prompt(2    id = "dev-assistant",3    params = LLMParams(4        temperature = 0.7,5        maxTokens = 5006    )7) {8    // Add a system message to set the context9    system("You are a helpful assistant.")1011    // Add a user message12    user("Tell me about Kotlin")13}

자바

1Prompt prompt = Prompt.builder("dev-assistant")2    .withParams(new LLMParams(3        0.7,         // temperature4        500,         // maxTokens5        1,           // numberOfChoices6        null,        // speculation7        null,        // schema8        LLMParams.ToolChoice.Auto.INSTANCE, // toolChoice9        null,        // user10        null         // additionalProperties11    ))12    .system("You are a helpful assistant.")13    .user("Tell me about Kotlin")14    .build();

프롬프트 생성에 대한 자세한 내용은 Prompts을 참조하세요.

하위 그래프를 생성할 때:

코틀린

1val processQuery by subgraphWithTask<String, String>(2    tools = listOf(searchTool, calculatorTool, weatherTool),3    llmModel = OpenAIModels.Chat.GPT4o,4    llmParams = LLMParams(5        temperature = 0.7,6        maxTokens = 5007    ),8    runMode = ToolCalls.SEQUENTIAL,9    assistantResponseRepeatMax = 3,10) { userQuery ->11    """12    You are a helpful assistant that can answer questions about various topics.13    Please help with the following query:14    $userQuery15    """16}

자바

Koog의 기존 하위 그래프 유형에 대한 자세한 내용은 Predefined subgraphs을 참조하세요. 자신만의 것을 만들고 구현하는 방법을 배우려면 하위 그래프는 Custom subgraphs을 참조하세요.

LLM 쓰기 세션에서 프롬프트를 업데이트하는 경우:

코틀린

1llm.writeSession {2    changeLLMParams(3        LLMParams(4            temperature = 0.7,5            maxTokens = 5006        )7    )8}

자바

세션에 대한 자세한 내용은 LLM sessions and manual history management을 참조하세요.

매개변수	유형	설명
`temperature`	더블	출력의 무작위성을 제어합니다. 0.7~1.0과 같이 값이 높을수록 더욱 다양하고 창의적인 반응이 생성되고, 값이 낮을수록 더욱 결정적이고 집중된 반응이 생성됩니다.
`maxTokens`	정수	응답에서 생성할 최대 토큰 수입니다. 응답 길이를 제어하는 데 유용합니다.
`numberOfChoices`	정수	생성할 대체 응답 수입니다. 0보다 커야 합니다.
`speculation`	끈	결과 속도와 정확성을 향상시키도록 설계된 모델 동작에 영향을 미치는 추측적 구성 문자열입니다. 특정 모델에서만 지원되지만 속도와 정확성이 크게 향상될 수 있습니다.
`schema`	개요	모델의 응답 형식에 대한 구조를 정의하여 JSON과 같은 구조화된 출력을 활성화합니다. 자세한 내용은 Schema을 참조하세요.
`toolChoice`	도구 선택	언어 모델의 도구 호출 동작을 제어합니다. 자세한 내용은 Tool choice을 참조하세요.
`user`	끈	추적 목적으로 사용될 수 있는 요청을 수행하는 사용자의 식별자입니다.
`additionalProperties`	맵<문자열, JsonElement>	특정 모델 제공자에 특정한 사용자 정의 매개변수를 저장하는 데 사용할 수 있는 추가 속성입니다.

개요

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

JSON 스키마

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

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

코틀린

1// Create parameters with a basic JSON schema2val jsonParams = LLMParams(3    temperature = 0.2,4    schema = LLMParams.Schema.JSON.Basic(5        name = "PersonInfo",6        schema = JsonObject(mapOf(7            "type" to JsonPrimitive("object"),8            "properties" to JsonObject(9                mapOf(10                    "name" to JsonObject(mapOf("type" to JsonPrimitive("string"))),11                    "age" to JsonObject(mapOf("type" to JsonPrimitive("number"))),12                    "skills" to JsonObject(13                        mapOf(14                            "type" to JsonPrimitive("array"),15                            "items" to JsonObject(mapOf("type" to JsonPrimitive("string")))16                        )17                    )18                )19            ),20            "additionalProperties" to JsonPrimitive(false),21            "required" to JsonArray(listOf(JsonPrimitive("name"), JsonPrimitive("age"), JsonPrimitive("skills")))22        ))23    )24)

자바

1// Create parameters with a basic JSON schema2LLMParams jsonParams = new LLMParams(3    0.2,         // temperature4    null,        // maxTokens5    1,           // numberOfChoices6    null,        // speculation7    new LLMParams.Schema.JSON.Basic(8        "PersonInfo",9        new JsonObject(Map.of(10            "type", new JsonPrimitive("object"),11            "properties", new JsonObject(Map.of(12                "name", new JsonObject(Map.of("type", new JsonPrimitive("string"))),13                "age", new JsonObject(Map.of("type", new JsonPrimitive("number"))),14                "skills", new JsonObject(Map.of(15                    "type", new JsonPrimitive("array"),16                    "items", new JsonObject(Map.of("type", new JsonPrimitive("string")))17                ))18            )),19            "additionalProperties", new JsonPrimitive(false),20            "required", new JsonArray(List.of(21                new JsonPrimitive("name"),22                new JsonPrimitive("age"),23                new JsonPrimitive("skills")24            ))25        ))26    ),27    LLMParams.ToolChoice.Auto.INSTANCE, // toolChoice28    null,        // user29    null         // additionalProperties30);

표준 JSON 스키마 (LLMParams.Schema.JSON.Standard): 표준 JSON 스키마를 나타냅니다. json-schema.org으로. 이 형식은 공식 JSON 스키마의 적절한 하위 집합입니다. 사양. 모든 LLM 제공업체가 전체 기능을 지원하는 것은 아니기 때문에 LLM 제공업체마다 특징이 다를 수 있습니다. JSON 스키마.

코틀린

1// Create parameters with a standard JSON schema2val standardJsonParams = LLMParams(3    temperature = 0.2,4    schema = LLMParams.Schema.JSON.Standard(5        name = "ProductCatalog",6        schema = JsonObject(mapOf(7            "type" to JsonPrimitive("object"),8            "properties" to JsonObject(mapOf(9                "products" to JsonObject(mapOf(10                    "type" to JsonPrimitive("array"),11                    "items" to JsonObject(mapOf(12                        "type" to JsonPrimitive("object"),13                        "properties" to JsonObject(mapOf(14                            "id" to JsonObject(mapOf("type" to JsonPrimitive("string"))),15                            "name" to JsonObject(mapOf("type" to JsonPrimitive("string"))),16                            "price" to JsonObject(mapOf("type" to JsonPrimitive("number"))),17                            "description" to JsonObject(mapOf("type" to JsonPrimitive("string")))18                        )),19                        "additionalProperties" to JsonPrimitive(false),20                        "required" to JsonArray(listOf(JsonPrimitive("id"), JsonPrimitive("name"), JsonPrimitive("price"), JsonPrimitive("description")))21                    ))22                ))23            )),24            "additionalProperties" to JsonPrimitive(false),25            "required" to JsonArray(listOf(JsonPrimitive("products")))26        ))27    )28)

자바

1// Create parameters with a standard JSON schema2LLMParams standardJsonParams = new LLMParams(3    0.2,         // temperature4    null,        // maxTokens5    1,           // numberOfChoices6    null,        // speculation7    new LLMParams.Schema.JSON.Standard(8        "ProductCatalog",9        new JsonObject(Map.of(10            "type", new JsonPrimitive("object"),11            "properties", new JsonObject(Map.of(12                "products", new JsonObject(Map.of(13                    "type", new JsonPrimitive("array"),14                    "items", new JsonObject(Map.of(15                        "type", new JsonPrimitive("object"),16                        "properties", new JsonObject(Map.of(17                            "id", new JsonObject(Map.of("type", new JsonPrimitive("string"))),18                            "name", new JsonObject(Map.of("type", new JsonPrimitive("string"))),19                            "price", new JsonObject(Map.of("type", new JsonPrimitive("number"))),20                            "description", new JsonObject(Map.of("type", new JsonPrimitive("string")))21                        )),22                        "additionalProperties", new JsonPrimitive(false),23                        "required", new JsonArray(List.of(24                            new JsonPrimitive("id"),25                            new JsonPrimitive("name"),26                            new JsonPrimitive("price"),27                            new JsonPrimitive("description")28                        ))29                    ))30                ))31            )),32            "additionalProperties", new JsonPrimitive(false),33            "required", new JsonArray(List.of(new JsonPrimitive("products")))34        ))35    ),36    LLMParams.ToolChoice.Auto.INSTANCE, // toolChoice37    null,        // user38    null         // additionalProperties39);

도구 선택

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

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

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

코틀린

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

자바

1LLMParams specificToolParams = new LLMParams(2    null,        // temperature3    null,        // maxTokens4    1,           // numberOfChoices5    null,        // speculation6    null,        // schema7    new LLMParams.ToolChoice.Named("calculator"), // toolChoice8    null,        // user9    null         // additionalProperties10);

공급자별 매개변수

Koog는 일부 LLM 제공업체에 대해 제공업체별 매개변수를 지원합니다. 이러한 매개변수는 기본 LLMParams 클래스를 확장합니다. 공급자별 기능을 추가합니다. 다음 클래스에는 공급자별로 특정한 매개변수가 포함되어 있습니다.

OpenAIChatParams: OpenAI Chat Completions API 관련 매개변수입니다.
OpenAIResponsesParams: OpenAI 응답 API와 관련된 매개변수입니다.
GoogleParams: Google 모델과 관련된 매개변수입니다.
AnthropicParams: 인류 모델에 특정한 매개변수.
MistralAIParams: Mistral 모델에 특정한 매개변수입니다.
DeepSeekParams: DeepSeek 모델에 특정한 매개변수입니다.
OpenRouterParams: OpenRouter 모델에 특정한 매개변수입니다.
DashscopeParams: Alibaba 모델에만 해당되는 매개변수입니다.
OllamaParams: Ollama 모델에 특정한 매개변수입니다.

다음은 Koog의 공급자별 매개변수에 대한 전체 참조입니다.

--8<-- llm-parameters-snippets.md:제목 llm-매개변수-snippets.md:오디오 llm-parameters-snippets.md:주파수페널티 llm-parameters-snippets.md:logprobs llm-parameters-snippets.md:parallelToolCalls llm-parameters-snippets.md:존재 패널티 llm-parameters-snippets.md:promptCacheKey llm-parameters-snippets.md:추론노력 llm-parameters-snippets.md:안전 식별자 llm-parameters-snippets.md:serviceTier llm-매개변수-snippets.md:중지 llm-매개변수-snippets.md:저장 llm-parameters-snippets.md:topLogprobs llm-매개변수-snippets.md:topP llm-parameters-snippets.md:webSearch옵션 --8<--

OpenAI 응답

--8<-- llm-parameters-snippets.md:제목 llm-매개변수-snippets.md:배경 llm-매개변수-snippets.md:포함 llm-parameters-snippets.md:logprobs llm-parameters-snippets.md:maxToolCalls llm-parameters-snippets.md:parallelToolCalls llm-parameters-snippets.md:promptCacheKey llm-parameters-snippets.md:추론 llm-parameters-snippets.md:안전 식별자 llm-parameters-snippets.md:serviceTier llm-매개변수-snippets.md:저장 llm-parameters-snippets.md:topLogprobs llm-매개변수-snippets.md:topP llm-parameters-snippets.md:잘림 --8<--

구글

--8<-- llm-parameters-snippets.md:제목 llm-parameters-snippets.md:thinkingConfig llm-매개변수-snippets.md:topK llm-매개변수-snippets.md:topP --8<--

인류학

--8<-- llm-parameters-snippets.md:제목 llm-parameters-snippets.md:컨테이너 llm-parameters-snippets.md:mcpServers llm-parameters-snippets.md:serviceTier llm-parameters-snippets.md:stopSequences llm-parameters-snippets.md:생각 llm-매개변수-snippets.md:topK llm-매개변수-snippets.md:topP --8<--

미스트랄

--8<-- llm-parameters-snippets.md:제목 llm-parameters-snippets.md:주파수페널티 llm-parameters-snippets.md:parallelToolCalls llm-parameters-snippets.md:존재 패널티 llm-parameters-snippets.md:프롬프트 모드 llm-parameters-snippets.md:randomSeed llm-parameters-snippets.md:safePrompt llm-매개변수-snippets.md:중지 llm-매개변수-snippets.md:topP --8<--

딥시크

--8<-- llm-parameters-snippets.md:제목 llm-parameters-snippets.md:주파수페널티 llm-parameters-snippets.md:logprobs llm-parameters-snippets.md:존재 패널티 llm-매개변수-snippets.md:중지 llm-parameters-snippets.md:topLogprobs llm-매개변수-snippets.md:topP --8<--

오픈라우터

--8<-- llm-parameters-snippets.md:제목 llm-parameters-snippets.md:주파수페널티 llm-parameters-snippets.md:logprobs llm-매개변수-snippets.md:minP llm-parameters-snippets.md:모델 llm-parameters-snippets.md:존재 패널티 llm-매개변수-snippets.md:공급자 llm-parameters-snippets.md:반복페널티 llm-매개변수-snippets.md:경로 llm-매개변수-snippets.md:중지 llm-매개변수-snippets.md:topA llm-매개변수-snippets.md:topK llm-parameters-snippets.md:topLogprobs llm-매개변수-snippets.md:topP llm-parameters-snippets.md:변형 --8<--

알리바바(DashScope)

--8<-- llm-parameters-snippets.md:제목 llm-parameters-snippets.md:검색 활성화 llm-parameters-snippets.md:enableThinking llm-parameters-snippets.md:주파수페널티 llm-parameters-snippets.md:logprobs llm-parameters-snippets.md:parallelToolCalls llm-parameters-snippets.md:존재 패널티 llm-매개변수-snippets.md:중지 llm-parameters-snippets.md:topLogprobs llm-매개변수-snippets.md:topP --8<--

올라마

--8<-- llm-parameters-snippets.md:제목 llm-parameters-snippets.md:생각 --8<--

다음 예에서는 공급자별 OpenRouterParams 클래스를 사용하여 정의된 OpenRouter LLM 매개변수를 보여줍니다.

코틀린

1val openRouterParams = OpenRouterParams(2    temperature = 0.7,3    maxTokens = 500,4    frequencyPenalty = 0.5,5    presencePenalty = 0.5,6    topP = 0.9,7    topK = 40,8    repetitionPenalty = 1.1,9    models = listOf("anthropic/claude-3-opus", "anthropic/claude-3-sonnet"),10    transforms = listOf("middle-out")11)

자바

1OpenRouterParams openRouterParams = new OpenRouterParams(2    0.7,         // temperature3    500,         // maxTokens4    1,           // numberOfChoices5    null,        // speculation6    null,        // schema7    null,        // toolChoice8    null,        // user9    null,        // additionalProperties10    0.5,         // frequencyPenalty11    null,        // logprobs12    null,        // minP13    Arrays.asList("anthropic/claude-3-opus", "anthropic/claude-3-sonnet"), // models14    0.5,         // presencePenalty15    null,        // provider16    1.1,         // repetitionPenalty17    null,        // route18    null,        // stop19    null,        // topA20    40,          // topK21    null,        // topLogprobs22    0.9,         // topP23    Arrays.asList("middle-out") // transforms24);

사용 예

기본 사용법

코틀린

1// A basic set of parameters with limited length2val basicParams = LLMParams(3    temperature = 0.7,4    maxTokens = 150,5    toolChoice = LLMParams.ToolChoice.Auto6)

자바

1// A basic set of parameters with limited length2LLMParams basicParams = new LLMParams(3    0.7,         // temperature4    150,         // maxTokens5    1,           // numberOfChoices6    null,        // speculation7    null,        // schema8    LLMParams.ToolChoice.Auto.INSTANCE, // toolChoice9    null,        // user10    null         // additionalProperties11);

추론 제어

모델 추론을 제어하는 공급자별 매개변수를 통해 추론 제어를 구현합니다. OpenAI Chat API와 추론을 지원하는 모델을 사용하는 경우 reasoningEffort 매개변수를 사용하세요. 응답을 제공하기 전에 모델이 생성하는 추론 토큰 수를 제어하려면 다음을 수행하세요.

코틀린

1val openAIReasoningEffortParams = OpenAIChatParams(2    reasoningEffort = ReasoningEffort.MEDIUM3)

자바

1OpenAIChatParams openAIReasoningEffortParams = new OpenAIChatParams(2    null,        // temperature3    null,        // maxTokens4    1,           // numberOfChoices5    null,        // speculation6    null,        // schema7    null,        // toolChoice8    null,        // user9    null,        // additionalProperties10    null,        // audio11    null,        // frequencyPenalty12    null,        // logprobs13    null,        // parallelToolCalls14    null,        // presencePenalty15    null,        // promptCacheKey16    ReasoningEffort.MEDIUM, // reasoningEffort17    null,        // safetyIdentifier18    null,        // serviceTier19    null,        // stop20    null,        // store21    null,        // topLogprobs22    null,        // topP23    null         // webSearchOptions24);

또한 상태 비저장 모드에서 OpenAI Responses API를 사용하면 추론 항목의 암호화된 기록을 유지합니다. 대화가 진행될 때마다 이를 모델에 보냅니다. 암호화는 OpenAI 측에서 이루어지며 요청해야 합니다. 요청의 include 매개변수를 reasoning.encrypted_content로 설정하여 암호화된 추론 토큰. 그러면 다음 대화 차례에 암호화된 추론 토큰을 모델에 다시 전달할 수 있습니다.

코틀린

1val openAIStatelessReasoningParams = OpenAIResponsesParams(2    include = listOf(OpenAIInclude.REASONING_ENCRYPTED_CONTENT)3)

자바

1OpenAIResponsesParams openAIStatelessReasoningParams = new OpenAIResponsesParams(2    null,        // temperature3    null,        // maxTokens4    1,           // numberOfChoices5    null,        // speculation6    null,        // schema7    null,        // toolChoice8    null,        // user9    null,        // additionalProperties10    null,        // background11    Arrays.asList(OpenAIInclude.REASONING_ENCRYPTED_CONTENT), // include12    null,        // logprobs13    null,        // maxToolCalls14    null,        // parallelToolCalls15    null,        // promptCacheKey16    null,        // reasoning17    null,        // safetyIdentifier18    null,        // serviceTier19    null,        // store20    null,        // topLogprobs21    null,        // topP22    null         // truncation23);

맞춤 매개변수

제공업체에 따라 다르며 Koog에서 기본적으로 지원되지 않는 사용자 정의 매개변수를 추가하려면 다음을 사용하세요. additionalProperties 속성은 아래 예와 같습니다.

코틀린

1// Add custom parameters for specific model providers2val customParams = LLMParams(3    additionalProperties = additionalPropertiesOf(4        "top_p" to 0.95,5        "frequency_penalty" to 0.5,6        "presence_penalty" to 0.57    )8)

자바

1// Add custom parameters for specific model providers2LLMParams customParams = new LLMParams(3    null,        // temperature4    null,        // maxTokens5    1,           // numberOfChoices6    null,        // speculation7    null,        // schema8    null,        // toolChoice9    null,        // user10    AdditionalPropertiesKt.additionalPropertiesOf(11        "top_p", 0.95,12        "frequency_penalty", 0.5,13        "presence_penalty", 0.514    )15);

매개변수 설정 및 재정의

아래 코드 샘플은 주로 사용하려는 LLM 매개변수 세트를 정의하는 방법을 보여줍니다. 그런 다음 원래 세트의 값을 부분적으로 재정의하고 새 값을 추가하여 다른 세트를 만듭니다. 이를 통해 대부분의 요청에 공통적인 매개변수를 정의할 수 있을 뿐만 아니라 보다 구체적인 매개변수 조합을 추가할 수도 있습니다. 공통 매개변수를 반복할 필요 없이.

코틀린

1// Define default parameters2val defaultParams = LLMParams(3    temperature = 0.7,4    maxTokens = 150,5    toolChoice = LLMParams.ToolChoice.Auto6)78// Create parameters with some overrides, using defaults for the rest9val overrideParams = LLMParams(10    temperature = 0.2,11    numberOfChoices = 312).default(defaultParams)

자바

1// Define default parameters2LLMParams defaultParams = new LLMParams(3    0.7,         // temperature4    150,         // maxTokens5    1,           // numberOfChoices6    null,        // speculation7    null,        // schema8    LLMParams.ToolChoice.Auto.INSTANCE, // toolChoice9    null,        // user10    null         // additionalProperties11);1213// Create parameters with some overrides, using defaults for the rest14LLMParams overrideParams = new LLMParams(15    0.2,         // temperature16    null,        // maxTokens17    3,           // numberOfChoices18    null,        // speculation19    null,        // schema20    null,        // toolChoice21    null,        // user22    null         // additionalProperties23).applyDefaults(defaultParams);

결과 overrideParams 세트의 값은 다음과 같습니다.

코틀린

1val overrideParams = LLMParams(2    temperature = 0.2,3    maxTokens = 150,4    toolChoice = LLMParams.ToolChoice.Auto,5    numberOfChoices = 36)

자바

1LLMParams overrideParams = new LLMParams(2    0.2,         // temperature3    150,         // maxTokens4    3,           // numberOfChoices5    null,        // speculation6    null,        // schema7    LLMParams.ToolChoice.Auto.INSTANCE, // toolChoice8    null,        // user9    null         // additionalProperties10);