GPT-5 の機能・ベストプラクティスまとめ

OpenAI の GPT-5 の機能やベストプラクティスがまとまった以下のドキュメントのまとめです。

サンプルコードは、公式ドキュメントは OpenAI でやってるのでこちらは AzureOpenAI でやっています。
(Azure でも OpenAI を使って接続できるようになってはいる昨今ですが)

概要
GPT-5 の API の新機能
- Minimal reasoning effort
- verbosity
Custom tools
Migration guidance
- 他の model から GPT-5 へのマイグレーション
- Chat Completions API から Responses API へのマイグレーション
Prompting guidance
- GPT-5 は reasoning model である

概要

GPT-5は、これまでのモデルの中で最もインテリジェントなモデルであり特に以下の分野で高い能力を持つように訓練されている。

コード生成、バグ修正、リファクタリング
指示への追従
長文コンテキストとツール呼び出し

より速いレスポンスを必要な場合

デフォルトでは、GPT-5はプロンプトに応答する前に、中程度の長さの chain of thought を生成します。より速く、より低遅延の応答を得るには、low reasoning effort と low text verbosity を使用します。

この動作は、GPT-4.1のような非推論モデルの挙動により近いものになります（ただし、完全に一致するわけではない）。GPT-5 はGPT-4.1よりもインテリジェントな応答を生成すると期待されていますが、速度と最大コンテキスト長が最も重要である場合は、代わりにGPT-4.1の使用を検討してもよいでしょう。

コーディングやエージェントのタスクでの利用

GPT-5は複雑なタスクの推論に優れています。コーディングや複数ステップの計画のような複雑なタスクには、"high reasoning effort" を使用してください。

これらの設定は、o3で取り組んでいたタスクを置き換える際に使用してください。ほとんどの状況において、GPT-5はo3やo4-miniよりも優れた結果を出すと期待しています。

モデルの選択

gpt-5は、最も複雑なタスクに適したモデルであり、広範な世界知識を必要とします。より小型のminiモデルとnanoモデルは、汎用的な世界知識を一部犠牲にする代わりに、低コストと低遅延を実現します。小規模なモデルは、より明確に定義されたタスクにおいて、より優れたパフォーマンスを発揮する傾向があります。

ユースケースに最適なモデルを選択する際は、以下のトレードオフを考慮してください。

CAREIANT	BEST FOR
gpt-5	複雑な推論、広範な世界知識、そしてコードを多用する、または複数ステップにわたるエージェントタスク
gpt-5-mini	コストを最適化した推論とチャット。速度、コスト、機能のバランスが取れている
gpt-5-nano	高スループットタスク、特に単純な指示の追従や分類

GPT-5のシステムカードは、APIとは異なる名前を使用しています。以下の表を使用して、両者をマッピングします。

System card name	API alias
gpt-5-thinking	gpt-5
gpt-5-thinking-mini	gpt-5-mini
gpt-5-thinking-nano	gpt-5-nano
gpt-5-main	gpt-5-chat-latest
gpt-5-main-mini	[not available via API]

GPT-5 の API の新機能

Minimal reasoning effort

reasoning.effortパラメーターは、モデルが応答を生成する前にどのくらいの推論トークンを生成するかの制御です。

o3のような以前の推論モデルは、low、medium、highのみをサポートしていました。lowは速度と少ないトークンを優先し、highはより徹底した推論を優先します。

新しいminimal設定は、可能な限り速い「Time-to-first-token」（最初のトークンまでの時間）が必要な場合に、ごくわずかな推論トークンを生成します。モデルが必要なときに数トークンを生成できる場合、全く生成しない場合よりも優れたパフォーマンスを示すことがよくあります。デフォルトはmediumです。

minimal設定は、コーディングや指示の追従シナリオにおいて、与えられた指示に厳密に従うため、特に優れたパフォーマンスを発揮します。ただし、より積極的に行動させるためには、プロンプトによる指示が必要な場合があります。

minimalな努力であってもモデルの推論品質を向上させるには、回答する前に「考える」またはステップを概説するように促すと良いでしょう。

# 今回の利用では新しい v1 endpoint 使ってないです。
aif_client = AsyncAzureOpenAI(
    api_key=os.environ["AIF_API_KEY"],
    azure_endpoint=os.environ["AIF_ENDPOINT"],
    api_version="2025-04-01-preview"
)

Responses API と chat completions api での reasoning effort の指定のコードサンプル。

「"夏に関するジョークを言ってください。"」という content を与えた場合、結果はこんな感じでした。

reasoning effort 指定なし場合 (=reasoning effort: medium) の場合は 500 - 1500トークンくらい (振れ幅が結構ある...)
minimal だと 200-250トークンくらい。

async def run_responses_api(content: str):
    response = await aif_client.responses.create(
        model="gpt-5",
        input=content,
        reasoning={
            "effort": "minimal"
        },
    )
    print(response.model_dump_json(indent=2))

async def run_completions_api(content: str):
    response = await aif_client.chat.completions.create(
        model="gpt-5",
        messages=[
            {"role": "user", "content": content}
        ],
        reasoning_effort = "minimal" # minimal, low, medium, or high
    )
    print(response.model_dump_json(indent=2))

verbosity

Verbosity は、モデルが生成する出力トークンの数を決定します。トークン数を減らすことで全体の応答時間が短縮されます。モデルの推論アプローチ自体はほぼ同じですが、より簡潔に回答する方法を見つけるため、ユースケースによっては回答の品質が向上する場合もあれば、低下する場合もあります。

以下に、詳細度の両極端なシナリオをいくつかご紹介します。

High Verbosity
- ドキュメントの徹底的な説明や、広範囲にわたるコードのリファクタリングをモデルに行わせる必要がある場合に使用します。
Low Verbosity
- SQLクエリのような、簡潔な回答やシンプルなコード生成を求める状況に最適です。

GPT-5より前のモデルは、デフォルトで verbosity を medium に設定していました。GPT-5では、このオプションを high、medium、low のいずれかに設定できるようになりました。コードを生成する際、verbosityのレベルが medium と high の場合は、インラインの説明が付いたより長くより構造化されたコードが生成されますが、lowの場合は、コメントが最小限の、より短く、より簡潔なコードが生成されます。

VerbosityをAPIでlowに設定した後でも、プロンプトを通じて出力を調整することは可能です。verbosityパラメータはシステムプロンプトのレベルで一般的なトークンの範囲を定義しますが、実際の出力はその範囲内で開発者やユーザーのプロンプトによって柔軟に変化します。

Custom tools

GPT-5では、新しい機能「カスタムツール」を導入しています。これにより、モデルは任意の生テキストをツールコールの入力として送信できますが、必要に応じて出力を制約することも可能です。

Freeform inputs

type: customでツールを定義すると、モデルは構造化されたJSONに限定されず、プレーンテキスト入力をツールに直接送信できるようになります。モデルは、コード、SQLクエリ、シェルコマンド、設定ファイル、長文の散文など、あらゆる未加工のテキストをツールに直接送信できます。

{
    "type": "custom",
    "name": "code_exec",
    "description": "Executes arbitrary python code",
}

Constraining outputs (出力の制約)

GPT-5はカスタムツール向けに文脈自由文法 (CFG) をサポートしており、Lark 文法を提供することで、出力を特定の構文やDSLに制約できます。CFG（例：SQLやDSL文法）を添付すると、アシスタントのテキストがその文法に確実に一致するようになります。

これにより、正確で制約されたツール呼び出しや構造化された応答が可能になり、GPT-5の関数呼び出しで厳密な構文やドメイン固有の形式を直接強制できるため、複雑なドメインや制約のあるドメインでの制御と信頼性が向上します。

Custom tools のベストプラクティス

簡潔で明確なツール説明を記述する。モデルはあなたの記述に基づいて何を送信するかを決定します。ツールを常に呼び出すようにしたい場合は、その旨を明確に記述してください。
サーバー側で出力を検証する。自由形式の文字列は強力ですが、インジェクションや安全でないコマンドに対する保護策が必要です。

Allowed tools

tool_choice パラメーター内の allowed_tools パラメーターを使用すると、N個のツール定義を渡しながら、そのうちのM個（M < N）にモデルを制限できます。すべてのツール定義を tools にリストし、次に allowed_tools ブロックを使用してサブセットの名前を指定し、モードを auto（モデルはそれらのいずれかを選択できる）または required（モデルはいずれか1つを呼び出す必要がある）に指定します。

項目	STANDARD TOOLS	ALLOWED TOOLS
Model's universe	tools にリストされているすべてのツール	tool_choice 内の tools のサブセットのみ
ツール呼び出し	モデルは任意のツールを呼び出す場合と呼び出さない場合がある	モデルは選択されたツールに制限される（または呼び出す必要がある
目的	利用可能な機能を宣言する	実際に使用される機能を制約する

  "tool_choice": {
    "type": "allowed_tools",
    "mode": "auto",
    "tools": [
      { "type": "function", "name": "get_weather" },
      { "type": "mcp", "server_label": "deepwiki" },
      { "type": "image_generation" }
    ]
  }
}'

Preambles

Preamble は、GPT-5がツールや関数を呼び出す前に生成する、ユーザーに見える簡潔な説明です。その目的や計画（例：「なぜこのツールを呼び出しているのか」）を概説します。これらは、思考プロセス（chain-of-thought）の後に、実際のツール呼び出しの前に表示され、モデルの推論を透過的に示し、デバッグの容易さ、ユーザーの信頼、およびきめ細かな操作性を向上させます。

各ツール呼び出しの前にGPT-5が「思考を声に出す」ことで、推論のオーバーヘッドを増大させることなく、ツール呼び出しの精度（およびタスク全体の成功）を高めます。前文を有効にするには、システムまたは開発者向けの指示を追加します。例えば、「ツールを呼び出す前に、なぜそれを呼び出すのかを説明してください」と記述します。これにより、GPT-5は指定された各ツール呼び出しの前に簡潔な理由を付加します。モデルは、ツール呼び出しの間に複数のメッセージを出力することも可能で、これにより、特に最小限の推論やレイテンシが重要なユースケースにおいて、インタラクション体験を向上させることができます。

前文の使用方法の詳細については、GPT-5 prompt cookbookを参照してください。

Migration guidance

GPT-5は思考の連鎖（CoT）をターン間で受け渡せる Responses API と併用することで最高のパフォーマンスを発揮します。現在お使いのモデルやAPIから移行するには、以下をお読みください。

他の model から GPT-5 へのマイグレーション

Responses APIが前ターンの CoT をモデルに渡せるため、GPT-5では知能が向上しています。これにより、生成される推論トークンが減少し、キャッシュヒット率が高まり、レイテンシが短縮されます。詳細については、Responses の利点に関する詳細ガイドを参照してください。

古い OpenAI のモデルからGPT-5へ移行する際は、まず推論レベルとプロンプティング戦略を試すことから始めてください。私たちのテストに基づくと、プロンプトオプティマイザ（ベストプラクティスに基づいてプロンプトをGPT-5用に自動更新するもの）を使用し、このモデル固有のガイダンスに従うことを推奨します。

旧モデル	マイグレーションガイド
o3	GPT-5 の medium または high 推論は優れた代替品です。まず medium 推論から始めてプロンプトを調整し、期待する結果が得られない場合は high に上げてください。
gpt-4.1	GPT-5 の minimal または low 推論は強力な代替手段です。まず minimal から始めてプロンプトを調整し、より良いパフォーマンスが必要な場合は low に上げてくさい。
o4-mini または gpt-4.1-mini	GPT-5-mini とプロンプトチューニングの組み合わせは優れた代替品です。
gpt-4.1-nano	GPT-5-nano とプロンプトチューニングの組み合わせは優れた代替品です。

Chat Completions API から Responses API へのマイグレーション

GPT-5のために Chat Completions から Responses API に移行する最大の理由であり、主な違いは、ターン間で思考の連鎖（CoT）を受け渡すサポートがあることです。APIの完全な比較を参照してください。

CoTの受け渡しは Responses API にのみ存在し、これにより知能の向上、生成される推論トークンの削減、キャッシュヒット率の向上、そして低レイテンシが実現しています。フォーマットは異なりますが、ほとんどの他のパラメータは同等です。

Prompting guidance

私たちは、コーディング、フロントエンドエンジニアリング、そしてエージェントタスクのためのツール呼び出しに優れるよう、GPT-5を特別に設計しました。また、プロンプトオプティマイザ を使用してGPT-5のプロンプトを反復的に改善することを推奨します。

GPT-5 は reasoning model である

GPT-5のような推論モデルは、問題を段階的に分解し、その推論を符号化する内部的な思考の連鎖を生成します。パフォーマンスを最大化するには、これらの推論項目をモデルに返すことで、再推論を回避し、モデルのトレーニング分布にインタラクションを近づけることができます。複数ターンの会話では、previous_response_id を渡すことで、以前の推論項目が自動的に利用可能になります。これは、ツールを使用する場合、特に例えば関数呼び出しに追加の往復が必要な場合に重要です。これらのケースでは、previous_response_id と一緒に含めるか、input に直接追加してください。

推論モデルとその活用方法の詳細については、OpenAI の*推論ガイド*でご確認ください。

BEACHSIDE BLOG

Azure と GitHub と C# が好きなエンジニアの個人メモ ( ･ㅂ･)و ̑̑