OpenAI Web Search

ResponsesまたはChatからWebを検索し、出典の引用を処理します。

OpenAI Web Searchを使用すると、対応モデルが回答前にWebを検索し、テキスト、検索呼び出し、出典の引用をレスポンスに含めることができます。ニュース、天気、製品更新など、鮮度が重要な質問に適しています。

データが独自のデータベースや業務サービスにある場合は、内部データを公開Web検索に渡さず、Tool Callingで制御されたツールを定義してください。

モデルとエンドポイントを先に確認してください

プロトコルにWeb Searchフィールドが存在しても、現在のアカウントのすべてのモデルが検索に対応するとは限りません。モデルマーケットプレイスでモデルとプロトコルを確認してから、対応するAPI Referenceを参照してください。

ResponsesまたはChatを選択する

エンドポイント	有効化方法	結果の位置
Responses	`tools`にWeb Search Toolを追加	`web_search_call`とMessage Output Item
Chat Completions	`web_search_options`を使用	Assistant Messageと`annotations`

Responsesは検索呼び出し、回答、出典を分けて扱うアプリケーションに適しています。Chatはすでにメッセージ構造を使用しているプロジェクトに適しています。

ResponsesでWebを検索する

curl 'https://api.agtcloud.cn/v1/responses' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your-api-key' \
  --data '{
    "model": "MODEL_ID",
    "tools": [
      {
        "type": "web_search_preview",
        "search_context_size": "medium"
      }
    ],
    "input": "今日注目すべきテクノロジーニュースを教えてください。"
  }'

モデルは質問に応じて検索するかどうかを判断する場合があります。検索が行われると、レスポンスのoutputには通常、検索呼び出し項目とテキストメッセージ項目の両方が含まれます。完全なToolタイプはResponses Referenceを参照してください。

Chat Completionsを使用する

curl 'https://api.agtcloud.cn/v1/chat/completions' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your-api-key' \
  --data '{
    "model": "MODEL_ID",
    "messages": [
      {
        "role": "user",
        "content": "今日注目すべきテクノロジーニュースを教えてください。"
      }
    ],
    "web_search_options": {
      "search_context_size": "medium"
    }
  }'

Chatレスポンスの本文はchoices[].message.contentにあり、構造化された引用はレスポンスで提供される場合にchoices[].message.annotationsにあります。完全なフィールドはChat Completions Referenceを参照してください。

回答と引用を読み取る

{
  "output": [
    {
      "type": "web_search_call",
      "id": "ws_example",
      "status": "completed"
    },
    {
      "type": "message",
      "content": [
        {
          "type": "output_text",
          "text": "検索結果によると……",
          "annotations": [
            {
              "type": "url_citation",
              "url": "https://example.com/article",
              "title": "出典タイトル"
            }
          ]
        }
      ]
    }
  ]
}

回答テキストだけを保存しないでください。URL、タイトル、引用とテキスト位置の関連を保持し、画面にクリック可能な出典を表示して、外部リンクには安全な新規タブ属性を使用します。

検索範囲を制限する

モデルとエンドポイントが対応する場合、次の検索オプションを設定できます。

ドメイン範囲：許可されたサイトだけを検索し、医療、法規制、企業知識などの情報源を限定します。
ユーザーの位置：国、都市、地域、タイムゾーンを指定し、ローカライズされた結果を得やすくします。
検索コンテキストの規模：応答品質、遅延、使用量のバランスに応じて範囲を選択します。
出典一覧：Responsesでは、本文で最終的に引用された出典だけでなく、検索中に参照した出典を返せる場合があります。

これらのフィールドはResponsesとChatで位置が異なります。具体的な名前と制限は対応するReferenceを確認してください。

失敗とフォールバック

状況	処理方法
検索が実行されない	質問にリアルタイム情報が必要かを判断し、モデルの検索対応を確認する
回答はあるが引用がない	出典を捏造せず、表示できる引用が返されなかったことを示す
検索が失敗	レスポンスエラーに応じて再試行、検索なしの回答、または後で再試行する案内を選択する
出典が矛盾	複数の出典と更新日時を表示し、重要な相違をモデルに隠させない
出典にアクセスできない	タイトルと元のURLを保持し、現在ページを開けないことを示す

外部Webページには誤情報やモデルを狙った悪意ある指示が含まれる場合があります。検索結果であるだけで自動的に信頼せず、検索内容にアプリケーション権限を迂回させたり、高リスクのツールを実行させたりしないでください。

公開前の確認

モデルとプロトコルがWeb Searchに明確に対応している。
回答、検索呼び出し、引用、出典一覧を個別に解析する。
引用がない場合に偽のリンクを生成しない。
ドメインと位置情報は業務上必要な場合だけ送信する。
外部コンテンツがTool Callingの権限と確認手順を迂回しない。
検索失敗、タイムアウト、結果なしに明確なフォールバックがある。

リクエストに失敗した場合はエラーとトラブルシューティングを、プロトコルを切り替える前はプロトコルの選択を参照してください。