--- title: "추론(Thinking)" slug: "clovastudio-chatcompletionsv3-thinking" updated: 2026-09-17T09:15:56Z published: 2026-09-17T09:15:56Z canonical: "api.ncloud-docs.com/clovastudio-chatcompletionsv3-thinking" --- > ## Documentation Index > Fetch the complete documentation index at: https://api.ncloud-docs.com/llms.txt > Use this file to discover all available pages before exploring further. # 추론(Thinking)

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

복잡한 문제 해결 능력을 갖춘 HCX-007 추론 모델을 이용할 수 있는 v3 Chat Completions에 대해 설명합니다. ## 요청 요청 형식을 설명합니다. 요청 형식은 다음과 같습니다. | 메서드 | URI | | --- | --- | | POST | /v3/chat-completions/{modelName} | ### 요청 헤더 CLOVA Studio API에서 공통으로 사용하는 헤더에 대한 정보는 [CLOVA Studio 요청 헤더](/docs/ai-naver-clovastudio-summary#요청헤더)를 참조해 주십시오. ### 요청 경로 파라미터 요청 경로 파라미터에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `modelName` | Enum | Required | 모델 이름 | :::(Info) (참고) HCX-007 추론 모델은 Chat Completions v3 API에서만 사용할 수 있으며, 이미지 입력과 튜닝 학습은 지원하지 않습니다. ::: ### 요청 바디 요청 바디에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `messages` | Array | Required | [대화 메시지](#messages) | | `thinking` | Object | Optional | 추론 모델 설정 정보 | | `thinking.effort` | Enum | Optional | 추론 여부 및 사고 과정 깊이 설정 | | `topP` | Double | Optional | 생성 토큰 후보군을 누적 확률을 기반으로 샘플링 | | `topK` | Integer | Optional | 생성 토큰 후보군에서 확률이 높은 K개를 후보로 지정하여 샘플링 | | `maxCompletionTokens` | Integer | Optional | 최대 생성 토큰 수 (추론 내용을 포함한 대화 메시지 길이) | | `temperature` | Double | Optional | 생성 토큰에 대한 다양성 정도(설정값이 높을수록 다양한 문장 생성) | | `repetitionPenalty` | Double | Optional | 같은 토큰을 생성하는 것에 대한 패널티 정도| | `seed` | Integer | Optional | 모델 반복 실행 시 결괏값의 일관성 수준 조정 | | `includeAiFilters` | Boolean | Optional | AI 필터(생성된 결괏값에 대해 욕설, 비하/차별/혐오, 성희롱/음란 등 카테고리별로 해당하는 정도) 결과 표시 여부 | #### `messages` `messages`에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `role` | Enum | Required | 대화 메시지 역할| | `content` | String \| Array | Required | 대화 메시지 내용 | #### `content` `content`에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `type` | Enum | Required | 대화 메시지 내용의 형식 | | `text` | String | Conditional | 대화 메시지 내용 | :::(Info) (참고) 일부 필드 입력 시 다음 내용을 확인해 주십시오. * `role`: `system`인 [대화 메시지](#messages)는 요청당 1개만 포함할 수 있습니다. * `role`: `assistant`인 [대화 메시지](#응답바디) 입력 시 `message.thinkingContent`는 요청에 포함할 수 없습니다. * 추론과 Function calling 또는 Structured Outputs를 동시에 요청할 수 없습니다. * 추론 사용 시 Chat Completions V3의 `stop`은 사용할 수 없습니다. * HCX-007 * 입력 토큰과 출력 토큰의 합은 128000 토큰을 초과할 수 없습니다. * 입력 토큰은 최대 128000 토큰까지 가능합니다. * 모델에 요청할 출력 토큰(`maxCompletionTokens`)은 최대 32768 토큰까지 설정 가능합니다. ::: ### 요청 예시 요청 예시는 다음과 같습니다. ```shell 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 }' ``` ## 응답 응답 형식을 설명합니다. ### 응답 헤더 응답 헤더에 대한 설명은 다음과 같습니다. | 헤더 | 필수 여부 | 설명 | | --- | --- | --- | | `Content-Type` | - | 응답 데이터의 형식 | ### 응답 바디 응답 바디에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `status` | Object | - | [응답 상태](/docs/ai-naver-clovastudio-summary#응답) 참조 | | `result` | Object | - | 응답 결과 | | `result.message` | Object | - | 대화 메시지 | | `result.message.role` | Enum | - | 대화 메시지 역할 | | `result.message.content` | String | - | 대화 메시지 내용 | | `result.message.thinkingContent` | String | - | 대화 메시지 중 추론 내용 | | `result.finishReason` | String | - | 토큰 생성 중단 이유(일반적으로 마지막 이벤트에 전달) | | `result.created` | Integer | - | 응답 날짜 | | `result.seed` | Integer | - | 입력 seed 값(0 입력 또는 미입력 시 랜덤 값 반환) | | `result.usage` | Object | - | 토큰 사용량 | | `result.usage.completionTokens` | Integer | - | 생성 토큰 수 | | `result.usage.promptTokens` | Integer | - | 입력(프롬프트) 토큰 수 | | `result.usage.totalTokens` | Integer | - | 전체 토큰 수 | | `result.usage.completionTokensDetails` | Object | - | 생성 토큰 수 관련 추가 정보| | `result.usage.completionTokensDetails.thinkingTokens` | Integer | - | 추론 토큰 수 | | `result.aiFilter` | Array | - | AI 필터 결과: [aiFilter](#aiFilter) | #### `aiFilter` `aiFilter`에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `groupName` | String | - | AI 필터 카테고리 | | `name` | String | - | AI 필터 세부 카테고리 | | `score` | String | - | AI 필터 점수 | | `result` | String | - | AI 필터 정상 작동 여부 | :::(Info) (참고) AI Filter는 최대 500자까지 분석할 수 있습니다. 단, 분석 대상 텍스트에 비정상적인 형식, 이모티콘, 특수 문자 등이 많은 경우, 정상적으로 분석되지 않을 수 있습니다. ::: ### 응답 예시 응답 예시는 다음과 같습니다. #### 성공 호출이 성공한 경우의 응답 예시는 다음과 같습니다. ```json { "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)](/docs/clovastudio-troubleshoot-c4xx) * [서버 공통 오류 문제(5xx)](/docs/clovastudio-troubleshoot-c5xx) ## 응답 스트림 생성되는 토큰을 하나씩 출력하도록 토큰 스트리밍을 사용할 수 있습니다. 토큰 스트리밍 형식을 설명합니다. ### 응답 바디 응답 바디에 대한 설명은 다음과 같습니다. #### StreamingChatCompletionsTokenEvent `StreamingChatCompletionsTokenEvent`에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `message` | Object | - | 대화 메시지 | | `message.role` | Enum | - | 대화 메시지 역할 | | `message.content` | String | - | 대화 메시지 내용 | | `message.thinkingContent` | String | - | 대화 메시지 중 추론 내용 | | `finishReason` | String | - | 토큰 생성 중단 이유 (일반적으로 마지막 이벤트에 전달, 그 외 null) | | `created` | Integer | - | 응답 시간 타임스탬프 | | `seed` | Integer | - | 입력 seed 값 (0 입력 또는 미입력 시 랜덤 값 반환) | | `usage` | Object | - | 토큰 사용량 (일반적으로 마지막 이벤트에 전달, 그 외 null) | #### StreamingChatCompletionsResultEvent `StreamingChatCompletionsResultEvent`에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `message` | Object | - | 대화 메시지 | | `message.role` | Enum | - | 대화 메시지 역할 | | `message.content` | String | - | 대화 메시지 내용 | | `message.thinkingContent` | String | - | 대화 메시지 중 추론 내용 | | `finishReason` | String | - | 토큰 생성 중단 이유 | | `created` | Integer | - | 응답 시간 타임스탬프 | | `seed` | Integer | - | 입력 seed 값 (0 입력 또는 미입력 시 랜덤 값 반환) | | `usage` | Object | - | 토큰 사용량 | | `usage.completionTokens` | Integer | - | 생성 토큰 수 | | `usage.promptTokens` | Integer | - | 입력(프롬프트) 토큰 수 | | `usage.totalTokens` | Integer | - | 전체 토큰 수 | | `usage.completionTokensDetails` | Object | - | 생성 토큰 수 관련 추가 정보| | `usage.completionTokensDetails.thinkingTokens` | Integer | - | 추론 토큰 수 | | `aiFilter` | Array | - | AI 필터 결과: [aiFilter](#aiFilter) | #### ErrorEvent `ErrorEvent`에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `status` | Object | - | [응답 상태](/docs/ai-naver-clovastudio-summary#응답) 참조 | | `status.code` | Object | - | 응답 상태 코드 | | `status.message` | Object | - | 응답 상태 메시지 | #### SignalEvent `SignalEvent`에 대한 설명은 다음과 같습니다. | 필드 | 타입 | 필수 여부 | 설명 | | --- | --- | --- | --- | | `data` | String | - | 전달할 시그널 데이터 정보 | ### 응답 예시 응답 예시는 다음과 같습니다. #### 성공 호출이 성공한 경우의 응답 예시는 다음과 같습니다. ```python 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)](/docs/clovastudio-troubleshoot-c4xx) * [서버 공통 오류 문제(5xx)](/docs/clovastudio-troubleshoot-c5xx) ## 권장 사항 CLOVA Studio 추론 모델은 최종 답변을 바로 생성하지 않고, 사용자 질의를 분석하고 필요한 논리적 사고 과정을 거쳐 추론 내용(토큰)을 생성한 뒤 이를 바탕으로 최종 답변을 생성합니다. 권장 사항에서는 최적화된 최종 답변 생성을 위해 추론 모델을 효과적으로 활용하는 방법을 설명합니다. ### 추론 여부 및 길이 설정 CLOVA Studio 추론 모델은 사용자가 직접 추론 여부와 길이를 설정할 수 있도록 학습되어 있습니다. 다음 설정 방법을 참고하여 요청 종류에 맞게 추론 여부 및 길이를 설정해 주십시오. * 추론 여부와 추론의 사고 과정 깊이 * `thinking.effort`를 통해 설정합니다. 설정값에 따라 최대 생성 요청 토큰 수의 기본값이 다음과 같이 적용됩니다. | `thinking.effort` 설정값 | `maxCompletionTokens` 기본값 | 설명 | | --- | --- | --- | | `none` | 512 | 추론 사용 안 함 | | `low` | 5120 | 짧은 길이의 추론 (기본값) | | `medium` | 10240 | 중간 길이의 추론 | | `high` | 20480 | 긴 길이의 추론 | * 추론 길이(최대 생성 토큰 수) * `maxCompletionTokens`를 통해 설정합니다. 추론 내용과 최종 답변 토큰 수를 전부 포함합니다. * 추론에서는 `maxTokens`가 아닌 `maxCompletionTokens`를 사용합니다. * 값을 직접 설정할 수 있지만, 설정값이 충분히 크지 않은 경우에 모델이 추론 과정 중 해당 길이에 도달하게 되면 최종 답변을 생성하지 못할 수 있습니다. 따라서 기본값을 준수하거나 여러 번 시도를 통해 적절한 길이를 찾아 설정해 주십시오. :::(Info) (참고) 상대적으로 긴 출력값을 생성하려면 일정 시간이 소요될 수 있으므로 스트림 출력 설정을 권장합니다. ::: ### 추론 내용 확인 추론을 사용한 API 요청 시 응답 결과에는 추론 내용과 최종 답변이 각각 구성되어 출력됩니다. 추론 내용 및 토큰 수는 다음과 같이 확인할 수 있습니다. * 추론 모델이 최종 답변을 위해 생성한 생각 과정을 담은 추론 내용은 응답 바디의 `message.thinkingContent`에서 확인할 수 있습니다. * 추론 내용의 토큰 수는 응답 바디의 `usage.completionTokensDetails.thinkingTokens`에서 확인할 수 있습니다. :::(Warning) (주의) 추론 내용은 좀 더 나은 최종 답변을 얻기 위한 과정으로 시스템 프롬프트를 비롯한 모델에 전달된 컨텍스트 일부가 포함될 수 있습니다. 따라서 추론 내용은 개발 목적으로만 활용하는 것을 권장하며, 별도의 후처리 없이 사용자에게 제공하는 것은 지양해 주십시오. ::: ### 멀티 턴 대화 시 입력 처리 멀티 턴 대화를 이어가려고 하는 경우, CLOVA Studio 추론 모델의 추론 내용(`message.thinkingContent`)은 제외하고 최종 답변인 모델 응답(`message.content`)만 다음 턴 입력에 포함해야 합니다. 다음 그림을 참고해 주십시오. ![CLOVA Studio_thinking_multiturn.png](https://cdn.document360.io/da0368a0-4444-4862-a528-42f78876f9e6/Images/Documentation/CLOVA%20Studio_thinking_multiturn.png?sv=2026-02-06&spr=https&st=2026-10-12T07%3A00%3A29Z&se=2026-10-12T08%3A00%3A29Z&sr=c&sp=r&sig=ALIZ%2BZhd2%2BrDl5Ade28U68TBzGZ16VVCaZQBVmQPiZ8%3D){height="" width="70%"}