メインコンテンツへスキップ
phaseo:web_search を追加すると、最新の情報や出典のある情報が必要なときにモデルが Web を検索できるようになります。モデルがクエリを書き、1 回のリクエストで複数回検索できます。Phaseo は URL、タイトル、スニペット、ハイライト、必要に応じてページ本文を返し、モデルはそれに基づいた回答を書きます。
同じツール定義は、/v1/responses と /v1/messages の tools でも使えます。

パラメーター

モデルが送信する内容

各呼び出しには query が含まれます。モデルは max_results、engine、search_context_size、ドメインリスト、include_text、include_highlights、max_characters、および次のローカライズ用ヒントも送信できます。 モデルが送信した値は、その呼び出しに限りツールの既定値を上書きします。max_results は引き続き max_total_results の残りで制限され、それを使い切ると以降の呼び出しは max_total_results_reached を返します。

エンジンの選択

管理エンジンが有効になっていない場合、呼び出しはモデルに search_not_configured を返します。 /v1/chat/completions または /v1/responses で engine: "native" を指定すると、リクエストは Web 検索を自前で実行するプロバイダーにのみ送られます。そのモデルを提供するプロバイダーがない場合、Phaseo は代わりに既定エンジンを実行し、管理検索として課金します。 これらのエンドポイントで Web 検索を自前で実行するプロバイダーは、OpenAI、/v1/responses の Azure OpenAI デプロイ、xAI、そして deepseek/deepseek-v4.1-flash-1017 の DeepSeek です。DeepSeek が自前で検索するのは、Web 検索がリクエストの唯一のツールで、ドメインリストやユーザーの位置情報がなく、JSON 出力も、ツールを強制する tool_choice もない場合に限られます。DeepSeek の API はドメインリスト、位置情報、JSON 出力を受け付けず、リクエストに他のツールがあると Web 検索をオフにし、検索を強制することもできないためです。このモデルへのそれ以外のリクエストでは、代わりに Phaseo の検索が使われ、独自のツールと併用できます。推論を有効にすると、DeepSeek は複数のステップでページを開いて読む、より深い検索を実行します。 OpenAI 独自の { "type": "web_search" } ツールを送った場合も、engine: "native" と同じように動作します。native はツール定義でのみ指定してください。プロバイダーのツールはリクエスト送信前に選ぶ必要があるため、モデルが呼び出しで native を指定すると、その呼び出しは unsupported_search_engine を返します。

ドメインで絞り込む

回答を決まった情報源から得る必要がある場合は allowed_domains を、それ以外は制限のない検索から特定のサイトだけを外したい場合は excluded_domains を使います。
リストの扱いはエンジンによって異なります。
  • Perplexity はどちらか一方のリストのみを受け付け、両方は指定できません。ドメインは最大 20 件です。除外ドメインは Perplexity の拒否リスト形式で送られます。
  • Firecrawl はどちらか一方のリストのみを受け付け、両方は指定できません。
  • TinyFish は両方を受け付け、クエリ内の site: と -site: 演算子に変換します。
  • DeepSeek は両方を受け付け、site: と -site: 演算子に変換します。クエリは 128 文字までに制限されているため、演算子の分の余地を確保するためにクエリが短縮されます。ドメインリストだけで上限を超える場合、呼び出しは search_query_too_long を返します。

ツールが返す内容

エンジン、クエリ、results 配列を含む JSON の結果です。各結果には title、url、snippet または highlights があり、ページ本文を要求してエンジンがそれを提供する場合は text も含まれます。

使用量と料金

検索ごとに usage.server_tool_use に加算されます。
モデルの料金カードで server_tool_web_search_requests と server_tool_web_search_extra_results の料金を設定していない場合、Phaseo は管理型検索 1 回につき $0.007、最初の 10 件を超える結果 1 件につき $0.001 を課金します。失敗した検索は課金されず、TinyFish Search は公開プランで無料のため、engine: "tinyfish" では検索料金は加算されません。有料エンジンでの検索には、モデルが無料でもクレジットが必要です。ネイティブ検索は、プロバイダーの公開価格で native_web_search_requests として課金されます。たとえば OpenAI と Anthropic では 1,000 回の検索につき $10、DeepSeek では 1,000 回につき $0.75 で、DeepSeek では結果を返した検索のみが対象です。DeepSeek は、リンク読み取りツールで URL を読み込む各ページ取得も 1,000 回につき $0.75 で、native_web_fetch_requests として課金します。推論を有効にすると、DeepSeek の 1 回の回答で 12 回以上検索することがあり、読み込んだ結果は入力トークンに加算されます。
最終更新日 2026年11月16日