推論(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ⁿになることを説明しなさい。"
          }
        ]
      }
    ],
    "thinking": {
        "effort": "low"
        },
    "topP": 0.8,
    "topK": 0,
    "maxCompletionTokens": 5120,
    "temperature": 0.5,
    "repetitionPenalty": 1.1,
    "stop": []
  }'

レスポンス

レスポンス形式を説明します。

レスポンスヘッダ

レスポンスヘッダの説明は次の通りです。

レスポンスボディ

レスポンスボディの説明は次の通りです。

aiFilter

aiFilterの説明は次の通りです。

レスポンス例

レスポンスのサンプルコードは次の通りです。

成功

呼び出しに成功した場合のレスポンスのサンプルコードは次の通りです。

{
    "status": {
        "code": "20000",
        "message": "OK"
    },
    "result": {
        "message": {
            "role": "assistant",
            "content": "部分集合の数は、各要素を含めるか、含めないかという2つの選択で決まります。\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ⁿになるのかのことだった。これは組合せ論や2進法と関係があるんじゃないかな。\nまず、各要素に対して選択するか、選択しないかの2つの場合があると考えてみよう。例えば、要素が1つの場合、部分集合は空集合とそれ自体で合計2つ、つまり2^1=2つとなる。要素が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)

レスポンスストリーム

生成されるトークンを1つずつ出力するようにトークンストリーミングを使用できます。トークンストリーミング形式を説明します。

レスポンスボディ

レスポンスボディの説明は次の通りです。

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各要素は **\"含む\"または\"含まない\"** のどちらかを選択できるので、1つの要素につき2つの場合が発生します。 \n\n例えば: \n- 要素が1つの集合({a}) → ∅、{a} ( **2¹ = 2** )\n- 要素が2つの集合({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まず基本的な考え方から始めよう。各要素は、部分集合に含めるか、含めないか、2つの選択肢がある。例えば、要素が1つであれば、{}、{a}の2つの部分集合があるってわけだ。2^1=2で、ちょうど当てはまる。\n\n2個目の要素 bを追加すると、それぞれの既存の部分集合に bを入れるか入れないかを決めなければならない。元々{}と{a}のそれぞれに bを追加したり、追加しなかったりするから、合計4つになる。つまり2^2=4だね。このように拡張すると、各段階で前の場合の数に2を掛けることを繰り返されるから、最終的には2×2×...×2 (n回) = 2^nになるのだ。\n\nもう1つのアプローチとして、各要素に対する独立した選択を強調するものがある。各要素を含めるか含めないかが互いに影響しないから、組み合わせの掛け算の法則を適用できる。したがって、全体の場合の数は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)だけ次のターン入力に含める必要があります。次の図をご参照ください。