추론(Thinking)

Classic/VPC 환경에서 이용 가능합니다.

복잡한 문제 해결 능력을 갖춘 HCX-007 추론 모델을 이용할 수 있는 v3 Chat Completions에 대해 설명합니다.

요청

요청 형식을 설명합니다. 요청 형식은 다음과 같습니다.

요청 헤더

요청 헤더에 대한 설명은 다음과 같습니다.

요청 경로 파라미터

요청 경로 파라미터에 대한 설명은 다음과 같습니다.

요청 바디

요청 바디에 대한 설명은 다음과 같습니다.

messages

messages에 대한 설명은 다음과 같습니다.

content

content에 대한 설명은 다음과 같습니다.

요청 예시

요청 예시는 다음과 같습니다.

curl --location --request POST 'https://clovastudio.stream.ntruss.com/v3/chat-completions/HCX-007' \
--header 'Authorization: Bearer {CLOVA Studio API Key}' \
--header 'X-NCP-CLOVASTUDIO-REQUEST-ID: {Request ID}' \
--header 'Content-Type: application/json' \
--header 'Accept: text/event-stream' \
--data '{
    "messages": [
      {
        "role": "system",
        "content": "- 고도로 체계적인 분석가이자 논리 기반 문제 해결의 전문가입니다."
      },
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "n개의 원소를 가진 집합이 있을 때, 이 집합에서 만들 수 있는 모든 부분집합의 개수가 2의 n제곱과 같다는 것을 설명하라."
          }
        ]
      }
    ],
    "thinking": {
        "effort": "low"
        },
    "topP": 0.8,
    "topK": 0,
    "maxCompletionTokens": 5120,
    "temperature": 0.5,
    "repetitionPenalty": 1.1
  }'

응답

응답 형식을 설명합니다.

응답 헤더

응답 헤더에 대한 설명은 다음과 같습니다.

응답 바디

응답 바디에 대한 설명은 다음과 같습니다.

aiFilter

aiFilter에 대한 설명은 다음과 같습니다.

응답 예시

응답 예시는 다음과 같습니다.

성공

호출이 성공한 경우의 응답 예시는 다음과 같습니다.

{
    "status": {
        "code": "20000",
        "message": "OK"
    },
    "result": {
        "message": {
            "role": "assistant",
            "content": "부분집합의 개수는 각 원소가 포함 또는 제외되는 두 가지 선택으로 결정됩니다.\n예를 들어, {a}의 부분집합은 ∅, {a} → 2개 (2¹)이며,
{a,b}는 ∅, {a}, {b}, {a,b} → 4개 (2²)입니다.\nn개 원소 집합에서는 각 원소마다 2가지 선택지(포함/제외)가 있으므로, 전체 경우의 수는 2 × 2 × ... × 2 (n번) = 2ⁿ이 됩니다.\n또는 이항정리로도 설명 가능합니다: 부분집합의 크기가 k인 경우의 수는 조합 **C(n,k)**이므로, 모든 k(0 ≤ k ≤ n)에 대해 합하면 ∑_{k=0}^n C(n,k) = (1+1)^n = 2ⁿ입니다.\n따라서 n개 원소의 부분집합 개수는 항상 2ⁿ입니다.",
            "thinkingContent": "오늘 사용자가 물어본 문제는 n개의 원소를 가진 집합에서 만들 수 있는 모든 부분집합의 개수가 왜 2의 n제곱인지 설명해달라는 거야. 이 주제는 조합론이나 이진법과 관련이 있지 않을까?\n먼저, 각 원소에 대해 선택하거나 선택하지 않는 두 가지 경우가 있다는 걸 생각해봐. 예를 들어 원소가 하나라면 부분집합은 공집합과 그 자체로 총 2개, 즉 2^1=2개가 되지. 원소가 둘일 때는 각각 포함되거나 안 되니까 2*2=4개, 2^2=4가 되고.\n일반화하면 각 원소마다 2가지 선택(포함/제외)이 가능하니까 전체 경우의 수는 2를 n번 곱한 것, 즉 2^n이 되는 거야. 이게 기본적인 조합적 사고 방식이지.\n혹은 부분집합의 크기가 k인 경우의 수를 생각하면 C(n,k)이고, 이를 k=0부터 n까지 더하면 (1+1)^n = 2^n이 된다는 이항정리도 떠올라. 그래서 모든 부분집합의 수는 2^n이라는 결론에 도달할 수 있어.\n사용자가 이 설명을 원했을 테니 간결하게 각 원소의 선택 여부로 접근하는 게 좋을 것 같아. 예시를 들어 설명하고, 일반화하는 과정을 짧게 요약해야겠어."
        },
        "finishReason": "stop",
        "created": 1753362971
        "seed": 1561390649,
        "usage": {
            "promptTokens": 58,
            "completionTokens": 631,
            "totalTokens": 689,
            "completionTokensDetails": {
                "thinkingTokens": 366
            }
}

실패

호출이 실패한 경우의 응답 예시는 다음과 같습니다.

• 클라이언트 공통 오류 문제(4xx)
• 서버 공통 오류 문제(5xx)

응답 스트림

생성되는 토큰을 하나씩 출력하도록 토큰 스트리밍을 사용할 수 있습니다. 토큰 스트리밍 형식을 설명합니다.

응답 바디

응답 바디에 대한 설명은 다음과 같습니다.

StreamingChatCompletionsTokenEvent

StreamingChatCompletionsTokenEvent에 대한 설명은 다음과 같습니다.

StreamingChatCompletionsResultEvent

StreamingChatCompletionsResultEvent에 대한 설명은 다음과 같습니다.

ErrorEvent

ErrorEvent에 대한 설명은 다음과 같습니다.

SignalEvent

SignalEvent에 대한 설명은 다음과 같습니다.

응답 예시

응답 예시는 다음과 같습니다.

성공

호출이 성공한 경우의 응답 예시는 다음과 같습니다.

id: aabdfe-dfgwr-edf-hpqwd-f3asd-g
event: token
data: {"message": {"role": "assistant", "thinkingContent": “오늘”},"finishReason": null, "created": 1744710905, "seed": 3284419119, "usage": null} 

...

id: aabdfe-dfgwr-edf-hpqwd-f2asd-g
event: token
data: {"message": {"role": "assistant", "content": “부분”},"finishReason": null, "created": 1744710905, "seed": 3284419119, "usage": null} 

...

id: aabdfe-dfgwr-edf-hpqwd-f1asd-g
event: result
data: {
    "message": {
        "role": "assistant",
        "content": "부분집합의 수는 각 원소의 **포함 여부**에 따라 결정됩니다.  \n각 원소는 **\"포함\" 또는 \"미포함\"** 중 하나를 선택할 수 있으므로, 한 원소당 2가지 경우가 생깁니다.  \n\n예를 들어:  \n- 원소가 하나인 집합({a}) → ∅, {a} (**2¹ = 2**)  \n- 원소가 둘인 집합({a, b}) → ∅, {a}, {b}, {a,b} (**2² = 4**)  \n\n확장하면, **n개 원소**는 각 단계마다 이전 결과(2ⁿ⁻¹)에 **2배**씩 증가합니다(**2ⁿ⁻¹ × 2 = 2ⁿ**).  \n즉, 모든 부분집합의 수는 **2ⁿ**으로 표현되며, 이는 각 원소의 독립적 선택 가능성을 반영한 것입니다.  \n\n공집합과 전체 집합 역시 자연스럽게 포함되므로, 공식 **2ⁿ**은 완전하고 일관된 결과를 제공합니다.",
        "thinkingContent": "오늘 사용자가 물어본 문제는 n개의 원소로 이루어진 집합의 부분집합의 수가 왜 2^n인지 설명해달라는 거야. 이걸 어떻게 쉽게 설명할 수 있을까? \n\n먼저 기본 개념부터 생각해보자. 각 원소는 부분집합에 포함되거나 포함되지 않거나 두 가지 선택지가 있지. 예를 들어 원소가 하나라면 {}, {a} 두 개의 부분집합이야. 여기서 2^1=2로 맞아떨어져.\n\n두 번째 원소 b를 추가하면 각각의 기존 부분집합에 대해 b를 넣을지 말지 결정해야 해. 원래 {}와 {a} 각각에 대해 b를 추가하거나 안 하니까 총 4개가 되겠지. 이건 2^2=4고. 이런 식으로 확장되면 n개일 때는 각 단계마다 이전 경우의 수에 2를 곱하는 게 반복되니까 결국 2×2×…×2 (n번) = 2^n이 되는 거야.\n\n또 다른 접근은 각 원소에 대한 독립적 선택을 강조하는 거야. 각 원소의 포함 여부가 서로 영향을 주지 않으므로 조합의 곱셈 법칙을 적용할 수 있어. 따라서 전체 경우의 수는 2 × 2 × … × 2 (n번) = 2^n으로 계산되는 거지.\n\n혹시 공집합이나 전체 집합도 포함된다는 걸 언급해야 할까? 예제를 통해 보여주면 더 명확해질 것 같아. 하지만 간결하게 설명하려면 핵심 아이디어인 각 원소의 선택 가능성만 강조해도 충분하지 않을까?\n\n마지막으로 수학적으로 엄밀히 증명하기 위해 귀납법을 사용할 수도 있지만, 사용자의 요청은 간단한 설명을 원하는 것 같으니 기본적인 논리를 중심으로 답변해야겠다. 이렇게 생각하면 될 것 같다!"
    },
    "finishReason": "stop",
    "created": 1753363313,
    "seed": 3219533885,
    "usage": {
        "promptTokens": 58,
        "completionTokens": 588,
        "totalTokens": 646,
        "completionTokensDetails": {
            "thinkingTokens": 361
        }
    }
}

실패

호출이 실패한 경우의 응답 예시는 다음과 같습니다.

• 클라이언트 공통 오류 문제(4xx)
• 서버 공통 오류 문제(5xx)

권장 사항

CLOVA Studio 추론 모델은 최종 답변을 바로 생성하지 않고, 사용자 질의를 분석하고 필요한 논리적 사고 과정을 거쳐 추론 내용(토큰)을 생성한 뒤 이를 바탕으로 최종 답변을 생성합니다. 권장 사항에서는 최적화된 최종 답변 생성을 위해 추론 모델을 효과적으로 활용하는 방법을 설명합니다.

추론 여부 및 길이 설정

CLOVA Studio 추론 모델은 사용자가 직접 추론 여부와 길이를 설정할 수 있도록 학습되어 있습니다. 다음 설정 방법을 참고하여 요청 종류에 맞게 추론 여부 및 길이를 설정해 주십시오.

• 추론 여부와 추론의 사고 과정 깊이
  • thinking.effort를 통해 설정합니다. 설정값에 따라 최대 생성 요청 토큰 수의 기본값이 다음과 같이 적용됩니다.

    thinking.effort 설정값	maxCompletionTokens 기본값	설명
    none	512	추론 사용 안 함
    low	5120	짧은 길이의 추론 (기본값)
    medium	10240	중간 길이의 추론
    high	20480	긴 길이의 추론

• 추론 길이(최대 생성 토큰 수)
  • maxCompletionTokens를 통해 설정합니다. 추론 내용과 최종 답변 토큰 수를 전부 포함합니다.
    • 추론에서는 maxTokens가 아닌 maxCompletionTokens를 사용합니다.
  • 값을 직접 설정할 수 있지만, 설정값이 충분히 크지 않은 경우에 모델이 추론 과정 중 해당 길이에 도달하게 되면 최종 답변을 생성하지 못할 수 있습니다. 따라서 기본값을 준수하거나 여러 번 시도를 통해 적절한 길이를 찾아 설정해 주십시오.

추론 내용 확인

추론을 사용한 API 요청 시 응답 결과에는 추론 내용과 최종 답변이 각각 구성되어 출력됩니다. 추론 내용 및 토큰 수는 다음과 같이 확인할 수 있습니다.

• 추론 모델이 최종 답변을 위해 생성한 생각 과정을 담은 추론 내용은 응답 바디의 message.thinkingContent에서 확인할 수 있습니다.
• 추론 내용의 토큰 수는 응답 바디의 usage.completionTokensDetails.thinkingTokens에서 확인할 수 있습니다.

멀티 턴 대화 시 입력 처리

멀티 턴 대화를 이어가려고 하는 경우, CLOVA Studio 추론 모델의 추론 내용(message.thinkingContent)은 제외하고 최종 답변인 모델 응답(message.content)만 다음 턴 입력에 포함해야 합니다. 다음 그림을 참고해 주십시오.