Chat Completions → Responses

Chat Completions messages と choices を使用して会話を整理します。 Responses input、Input Item、および output を使用して、入力、ツール呼び出し、および結果を表現します。移行するときは、エンドポイントを置き換えるだけでなく、入力構造、応答解析、ツール呼び出しループ、ストリーミング ステート マシンも調整する必要があります。

移行が必要か判断する

Responses への移行に適したケース:

• 新しいプロジェクトでは、統合された型付きInput ItemとOutput Itemを使用する必要があります。
• previous_response_id はステータス機能の複数ラウンドを待機する必要があります。
• Responses がサポートする組み込みツールが必要です。
• アプリケーションは、Itemタイプに応じてテキスト、ツール呼び出し、その他の出力を処理します。

Chat Completions を引き続き使用できるケース:

• 既存のアプリケーションは、messages、choices、および Chat Delta に安定的に依存します。
• 対象モデルまたは必要なツールは Chat Completions のみをサポートします。
• 現在、ツール、複数ラウンド、ストリーミングに対する回帰テストの範囲が十分ではありません。
• 移行の利点は、応答の解析と状態管理の変革コストをカバーするには十分ではありません。

主な変更点

最小リクエストのBefore / After

{
  "model": "MODEL_ID",
  "messages": [
    {
      "role": "system",
      "content": "回答は簡潔かつ正確である必要があります。"
    },
    {
      "role": "user",
      "content": "一言で紹介してくださいAGTCloud。"
    }
  ]
}

OpenAI SDK を使用する場合、クライアントの Base URL は https://api.agtcloud.cn/v1 のままです。メソッドが client.chat.completions.create(...) から client.responses.create(...) に変更されました。完全な Python および TypeScript の初期化メソッドについては、OpenAI SDK を参照してください。

レスポンスの読み取り処理を移行する

Chat Completions 通常、ヘルパー メッセージは最初の Choice から読み取られます。

choices[0].message.content

Responses はソートされた output[] を返します。メッセージ、関数呼び出し、検索呼び出し、またはその他の項目が含まれる場合もあります。 output_text の SDK は、集約されたテキストを読み取るために使用できますが、処理ツールまたはその他の出力が必要な場合は、完全な output を走査する必要があります。

response.output_text
response.output[]

マルチターンの状態を移行する

previous_response_id を使用する場合、前のラウンドの instructions は自動的に継承されません。各ラウンドでは、アプリケーションのニーズに基づいて命令を再構成する必要があります。

同じ履歴を同時に完全に再生し、移行後に previous_response_id 経由で再度参照しないでください。そうしないと、重複したコンテキストが作成される可能性があります。

Function Calling を移行する

ツール定義

Chat Completions 関数定義を tools[].function に配置します。

{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "市内の天気を確認する",
    "parameters": {
      "type": "object",
      "properties": {
        "city": { "type": "string" }
      },
      "required": ["city"]
    }
  }
}

Responses 関数情報を Function Tool オブジェクトに直接配置します。

{
  "type": "function",
  "name": "get_weather",
  "description": "市内の天気を確認する",
  "parameters": {
    "type": "object",
    "properties": {
      "city": { "type": "string" }
    },
    "required": ["city"]
  }
}

結果を返す

• チャット: assistant.tool_calls[] からの呼び出しを読み取り、tool_call_id を使用してツール メッセージを追加します。
• Responses: output[] から function_call を読み取り、function_call_output を送信します。call_id は元の呼び出しと一致している必要があります。

使用されるプロトコルに関係なく、関数はアプリケーションによって実行されます。未検証のパラメータを直接実行しないでください。また、ツール例外を通常の結果として偽装しないでください。

Streaming を移行する

Chat Completions 各チャンクの増分を choices[].delta ずつ返します。通常は [DONE] で終わります。

Responses 名前付きイベントを使用します。例:

• response.created。
• response.output_item.added。
• response.content_part.added。
• response.output_text.delta。
• response.output_text.done。
• response.completed。

移行中は、元の「テキストのみを結合する」ロジックをイベント ディスパッチャに変更する必要があります。最初にイベント タイプに従って処理し、次に output_index、content_index、item_id およびその他の識別子に従って対応するステータスを更新します。

Structured Outputs を移行する

Chat Completionsの出力形式の設定を response_format に配置します。 Responsesでは対応する設定を text.format に配置します。移行時には両方を対応させて変更してください。

1. リクエストフィールドの位置。
2. JSON スキーマのパッケージ化構造。
3. SDK の解析補助メソッド。
4. 拒否、不完全な応答、およびスキーマ検証の失敗の処理。

詳細なフィールドについては、Chat Completions および OpenAI Responses を参照してください。

Web Search を移行する

2 つのプロトコルの検索エントリは異なります。

• Chat Completions web_search_options を使用して、検索をサポートするモデルを選択するよう求めます。
• Responses tools でサポートされている Web Search ツールを有効にし、項目と参照の検索呼び出しを返す場合があります。

ドメイン フィルタリング、ソース リスト、ユーザーの場所、リアルタイム インターネット アクセスなどの設定は、選択したプロトコルとモデルによって異なります。完全な例については、OpenAI Web Search を参照してください。

Usage、エラー、キャンセル

モニタリングおよびアカウンティング読み取りロジックを移行する場合は、少なくとも以下を調整してください。

HTTP ステータス コード、エラー オブジェクト、リクエスト ID も保持します。 SDK 例外テキストをキャプチャするだけではありません。アプリケーション ログでは、認証の失敗、非表示のモデル、スロットル、サービス エラー、接続の中断を区別できる必要があります。

段階的に移行する

回帰確認とロールバックのチェックリスト

• 通常のテキスト、空の出力、拒否、不完全、および失敗ステータス。
• 単一ツール、複数ツール、ツールの失敗、パラメータ検証の失敗。
• previous_response_id によるステートレスな履歴再生。
• 通常の完了、中断、繰り返されるイベントのストリーミング。
• Structured Output の検証に失敗しました。
• 使用状況、エラー情報、リクエスト ID、タイムアウト、レート制限。
• 対象モデルが特定の Responses 機能をサポートしていない場合は、Chat Completions に戻すことができます。

本番環境に切り替わるまで、チャットと Responses 用に別々の設定と制御可能なスイッチを保持します。業務指標、ログ、エラー処理が安定していることを確認したら、古い解析処理をクリーンアップします。

次のステップ

• OpenAI SDK を使用して Python または TypeScript クライアントを構成します。
• テキストとダイアログ を表示して、Responses の毎日の呼び出しプロセスを理解します。
• OpenAI Responses 内の完全なフィールドと応答を確認します。
• 呼び出しエラーが発生した場合は、エラーとトラブルシューティング を確認してください。