推論モデルの労力（Reasoning Effort）の制御 (Chat Completions)

エンドポイントの説明

プロンプトが与えられると、モデルは1つまたは複数の予測される補完応答を返します（推論モデルの思考の労力（reasoning effort）の制御をサポートします）。

• 公式ドキュメントリファレンス：OpenAI Reasoning Guides
• エンドポイントのステータス：リリース済み (released)

リクエスト仕様

• HTTPメソッド：POST
• リクエストURL：https://api.codingplanx.ai/v1/chat/completions

リクエストヘッダー (Headers)

リクエストボディパラメータ (Body)

データフォーマット：application/json

リクエストサンプル

{
  "model": "o4-mini",
  "max_tokens": 500,
  "messages": [
    {
      "role": "user",
      "content": "こんにちは、量子コンピューティングの原理について詳しく説明してください。"
    }
  ],
  "temperature": 1.0,
  "stream": false,
  "reasoning_effort": "medium"
}

---

レスポンス仕様

レスポンスボディパラメータ

データフォーマット：application/json

レスポンスサンプル (HTTP 200 OK)

{
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "\r
\r
Hello there, how may I assist you today?"
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 9,
        "completion_tokens": 12,
        "total_tokens": 21
    }
}

---

FAQ（よくある質問）

1. reasoning_effort パラメータの役割は何ですか？

reasoning_effort は、高度な推論機能（Reasoning）を持つモデル（OpenAIのo1/o4シリーズなど）が、最終的な回答を出す前にどれだけの計算リソースと時間を費やして内部的な思考を行うかを制御するために使用します。通常、low、medium、high の3つのレベルをサポートします。high に設定すると、モデルはより深い論理的推論を行い、複雑な数学やプログラミングの問題解決に適していますが、それに応じて応答時間も増加します。

2. stream: true を有効にすると、標準のJSONレスポンスが受信されないのはなぜですか？

ストリーミング（stream: true）を有効にすると、APIはServer-Sent Events（SSE）プロトコルを使用してデータチャンク（Chunks）を継続的に返します。各チャンクは data: {...} の形式で送信され、すべてのコンテンツの送信が完了すると、data: [DONE] というメッセージが送信されます。開発者は、完全な応答を構築するために、1行ずつ読み取り、data: に続くJSON文字列を解析して結合する必要があります。

3. ドキュメントでは temperature と top_p のどちらか一方のみを変更することが推奨されていますが、なぜですか？

これら2つのパラメータは、モデルの出力内容のランダム性と多様性を制御するために使用されます。temperature はロジットをスケーリングすることで確率分布を変化させ、top_p（ヌクレアスサンプリング）は累積確率が低い語彙を切り捨てることで候補プールを制限します。これら2つのパラメータを同時に調整すると、モデルの動作が予測・制御しにくくなるため、ベストプラクティスは一方を固定（通常はデフォルトのまま）し、ランダム性の制御要件を満たすためにもう一方のみを調整することです。

4. finish_reason が "length" を返した場合、どういう意味ですか？

これは、モデルの応答が強制的に切り捨てられたことを意味します。原因は通常2つあります。1つ目は、生成されたトークン数がリクエストパラメータで設定された max_tokens の上限に達したこと。2つ目は、リクエストのプロンプト（Prompt）とモデルが生成した応答の合計トークン数が、該当モデルで許可されている最大コンテキストウィンドウ制限を超えたことです。この場合、過去の会話履歴を短くするか、max_tokens パラメータを増やすことをお勧めします。

5. モデルにJSON形式のデータを強制的に返させるにはどうすればよいですか？

リクエストボディに "response_format": {"type": "json_object"} を渡すことで、JSONモードを有効にできます。非常に重要：このモードを有効にすると同時に、messages（通常はsystemまたはuserプロンプト内）において、モデルにJSONを出力するように自然言語で明示的に指示する必要があります。そうしないと、モデルはトークン制限に達するまで空白文字を無限に生成する無限ループに陥る可能性があります。