Workers バインディング

Workers は、新しいアプリケーションを作ったり、既存のものを拡張したりできるサーバーレス実行環境です。Workers バインディング を使い、Cloudflare Worker から AI Search インスタンスを検索し、チャットします。

AI Search を Workers で使うには、AI Search バインディングを作成する必要があります。バインディングは Wrangler 設定 を更新して作成します。AI Search には次の 2 種類のバインディングがあります。

• 名前空間バインディング: ai_search_namespaces
• インスタンスバインディング: ai_search

名前空間 内のすべてのインスタンスにアクセスします。実行時にインスタンスの取得、作成、一覧、削除ができます。

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "compatibility_date": "2026-03-27",
  "ai_search_namespaces": [
    {
      "binding": "AI_SEARCH",
      "namespace": "my-namespace"
    }
  ]
}

compatibility_date = "2026-03-27"

[[ai_search_namespaces]]
binding = "AI_SEARCH"
namespace = "my-namespace"

default 名前空間内の 1 つのインスタンスへ直接バインドします。デプロイ時に使うインスタンスが決まっている場合に使います。

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "compatibility_date": "2026-03-27",
  "ai_search": [
    {
      "binding": "MY_SEARCH",
      "instance_name": "my-instance"
    }
  ]
}

compatibility_date = "2026-03-27"

[[ai_search]]
binding = "MY_SEARCH"
instance_name = "my-instance"

次のメソッドは、ai_search_namespaces バインディングと ai_search バインディングの両方で使えます。名前空間バインディングでは、get() が返すハンドルでメソッドを呼びます。インスタンスバインディングでは、バインディングに直接メソッドを呼びます（例: env.MY_SEARCH.search()）。

以下の例は、名前空間バインディングを使います。

インデックス済みデータソースから、関連するコンテンツチャンクを検索します。ソース参照付きのスコア付きチャンクを返します。

const instance = env.AI_SEARCH.get("my-instance");

const results = await instance.search({
	messages: [{ role: "user", content: "What is Cloudflare?" }],
});

messages array 必須

会話を表すメッセージオブジェクトの配列です。各メッセージには role と content フィールドがあります。

• role string 必須

  • メッセージ送信者のロールです。有効な値は system、developer、user、assistant、tool です。

• content string 必須

  • メッセージの内容です。

query string 任意

単純なテキストクエリ文字列です。messages の代替です。query または messages のどちらか一方を指定し、両方は指定しないでください。

ai_search_options object 任意

検索操作の設定です。

• retrieval object 任意

  • retrieval_type string 任意

    • 実行する取得の種類です。有効な値は vector、keyword、hybrid です。デフォルトは hybrid です。

  • match_threshold number 任意

    • 結果を一致とみなすために必要な最小マッチスコアです。0 から 1 の間である必要があります。デフォルトは 0.4 です。

  • max_num_results integer 任意

    • 返す結果の最大件数です。1 から 50 の間である必要があります。デフォルトは 10 です。

  • filters object 任意

    • メタデータに基づいて検索結果を絞り込みます。比較フィルター（eq、ne、gt、gte、lt、lte）と複合フィルター（and、or）に対応します。詳細は メタデータフィルタリング を参照してください。

  • context_expansion integer 任意

    • 追加の文脈として含める周囲のチャンク数です。0 から 3 の間である必要があります。デフォルトは 0 です。

  • fusion_method string 任意

    • ハイブリッド取得で、ベクトルスコアとキーワードスコアを結合する方法です。有効な値は rrf（Reciprocal Rank Fusion）、max（最大スコアを採用）です。デフォルトはインスタンスレベルの設定です。

  • keyword_match_mode string 任意

    • キーワード（BM25）照合で候補ドキュメントを選ぶ方法です。and はすべての語の一致が必要です。or はいずれかの語の一致で足ります。デフォルトは and です。

  • boost_by array 任意

    • メタデータフィールドで結果をブーストします。最大 3 件です。各項目には次があります。
      • field string 必須 - ブーストに使うメタデータフィールド名です（例: timestamp）。最大 64 文字です。
      • direction string 任意 - ブーストの方向です。有効な値は asc、desc、exists、not_exists です。数値フィールドのデフォルトは asc、テキストフィールドのデフォルトは exists です。

  • metadata_only boolean 任意

    • 各チャンクについて、テキスト本文なしでメタデータだけを返します。

  • return_on_failure boolean 任意

    • 一部の処理ステップが失敗した場合に部分結果を返すかどうかです。デフォルトは true です。

• query_rewrite object 任意

  • enabled boolean 任意

    • クエリを書き換えて取得精度を上げます。デフォルトは false です。

  • model string 任意

    • クエリ書き換えに使うモデルです。

  • rewrite_prompt string 任意

    • クエリ書き換えを案内するカスタムプロンプトです。

• reranking object 任意

  • enabled boolean 任意

    • リランキングモデルを使い、取得結果を意味的な関連度で並べ替えます。デフォルトは false です。

  • model string 任意

    • 使うリランキングモデルです。有効な値は @cf/baai/bge-reranker-base です。

  • match_threshold number 任意

    • リランキング後の結果の最小スコアです。0 から 1 の間である必要があります。デフォルトは 0.4 です。

• cache object 任意

  • enabled boolean 任意

    • このリクエストについて、インスタンスレベルのキャッシュ設定を上書きします。

  • cache_threshold string 任意

    • キャッシュヒットの類似度しきい値です。有効な値は super_strict_match、close_enough、flexible_friend、anything_goes です。

レスポンスには次のフィールドが含まれます。

AI Search インスタンスをコンテキストとしてチャット補完を生成します。このメソッドは関連コンテンツを取得し、それを使って応答を生成します。

const instance = env.AI_SEARCH.get("my-instance");

const response = await instance.chatCompletions({
	messages: [
		{ role: "system", content: "You are a helpful documentation assistant." },
		{ role: "user", content: "What is Cloudflare?" },
	],
	model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
	ai_search_options: {
		retrieval: {
			max_num_results: 5,
		},
		query_rewrite: {
			enabled: true,
		},
	},
});

stream: true を設定すると、生成に合わせて Server-Sent Events（SSE）として応答を受け取れます。

const instance = env.AI_SEARCH.get("my-instance");

const stream = await instance.chatCompletions({
	messages: [{ role: "user", content: "What is Cloudflare?" }],
	stream: true,
});

return new Response(stream, {
	headers: {
		"content-type": "text/event-stream",
		"cache-control": "no-cache",
	},
});

stream を有効にすると、メソッドは SSE イベントの ReadableStream を返します。各イベントには、増分テキスト用の choices[0].delta.content を含む JSON オブジェクトがあります。ストリームは data: [DONE] イベントで終わります。

messages array 必須

会話を表すメッセージオブジェクトの配列です。各メッセージには role と content フィールドがあります。

• role string 必須

  • メッセージ送信者のロールです。有効な値は system、developer、user、assistant、tool です。

• content string 必須

  • メッセージの内容です。

model string 任意

応答の生成に使うテキスト生成モデルです。デフォルトは、AI Search インスタンス設定で構成した生成モデルです。対応モデルの一覧は 対応モデル を参照してください。

stream boolean 任意

生成された結果をストリームで返します。有効にすると、読み取り可能なストリーム付きの Response オブジェクトを返します。デフォルトは false です。

ai_search_options object 任意

検索と生成の設定オプションです。

• retrieval object 任意

  • retrieval_type string 任意

    • 実行する取得の種類です。有効な値は vector、keyword、hybrid です。デフォルトは hybrid です。

  • match_threshold number 任意

    • 結果を一致とみなすための最小マッチスコアです。0 から 1 のあいだである必要があります。デフォルトは 0.4 です。

  • max_num_results integer 任意

    • 返す結果の最大数です。1 から 50 のあいだである必要があります。デフォルトは 10 です。

  • filters object 任意

    • メタデータに基づいて検索結果を絞り込みます。比較フィルター（eq、ne、gt、gte、lt、lte）と複合フィルター（and、or）に対応します。詳細は メタデータフィルタリング を参照してください。

  • context_expansion integer 任意

    • 追加のコンテキストとして含める周囲のチャンク数です。0 から 3 のあいだである必要があります。デフォルトは 0 です。

  • fusion_method string 任意

    • ハイブリッド取得で、ベクトルスコアとキーワードスコアをどう結合するかを制御します。有効な値は rrf（Reciprocal Rank Fusion）、max（最大スコアを採用）です。デフォルトはインスタンスレベルの設定です。

  • keyword_match_mode string 任意

    • キーワード（BM25）マッチングが候補ドキュメントを選ぶ方法を制御します。and はすべての語句の一致が必要です。or はいずれかの語句の一致で足ります。デフォルトは and です。

  • boost_by array 任意

    • メタデータフィールドで結果をブーストします。最大 3 件です。各項目には次があります。
      • field string 必須 - ブーストに使うメタデータフィールド名です（例: timestamp）。最大 64 文字です。
      • direction string 任意 - ブーストの方向です。有効な値は asc、desc、exists、not_exists です。数値フィールドのデフォルトは asc、テキストフィールドのデフォルトは exists です。

  • metadata_only boolean 任意

    • 各チャンクについて、テキスト本文なしでメタデータだけを返します。

  • return_on_failure boolean 任意

    • 一部の処理ステップが失敗した場合に、部分的な結果を返すかどうかです。デフォルトは true です。

• query_rewrite object 任意

  • enabled boolean 任意

    • 取得精度を上げるためにクエリを書き換えます。デフォルトは false です。

  • model string 任意

    • クエリ書き換えに使うモデルです。

  • rewrite_prompt string 任意

    • クエリ書き換えを案内するカスタムプロンプトです。

• reranking object 任意

  • enabled boolean 任意

    • リランキングモデルを使い、意味的な関連度に基づいて取得結果を並べ替えます。デフォルトは false です。

  • model string 任意

    • 使うリランキングモデルです。有効な値は @cf/baai/bge-reranker-base です。

  • match_threshold number 任意

    • リランキング後の結果の最小スコアです。0 から 1 のあいだである必要があります。デフォルトは 0.4 です。

• cache object 任意

  • enabled boolean 任意

    • このリクエストについて、インスタンスレベルのキャッシュ設定を上書きします。

  • cache_threshold string 任意

    • キャッシュヒットの類似度しきい値です。有効な値は super_strict_match、close_enough、flexible_friend、anything_goes です。

stream: true のとき、メソッドは Server-Sent Events の ReadableStream を返します。取得したチャンクは最初に chunks イベントとして送られ、そのあとにストリームされた応答が続きます。

event: chunks
data: [{"id":"chunk-001","type":"text","score":0.85,"text":"...","item":{"key":"about-cloudflare.md","timestamp":1775925540000},"scoring_details":{"vector_score":0.85}}]

data: {"id":"id-1776072781845","created":1776072781,"model":"@cf/meta/llama-3.3-70b-instruct-fp8-fast","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":" document"}}]}

data: {"id":"id-1776072781845","created":1776072781,"model":"@cf/meta/llama-3.3-70b-instruct-fp8-fast","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":" you provided doesn"}}]}

data: {"id":"id-1776072781845","created":1776072781,"model":"@cf/meta/llama-3.3-70b-instruct-fp8-fast","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"'t contain"}}]}

data: {"id":"id-1776072781845","created":1776072781,"model":"@cf/meta/llama-3.3-70b-instruct-fp8-fast","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":" information"}}]}

data: [DONE]

次のメソッドは、ai_search_namespaces バインディングを使うときだけ利用できます。名前空間ハンドル（env.AI_SEARCH）を直接使い、1 回の呼び出しで複数インスタンスを横断して検索およびチャットします。

ai_search_options に instance_ids を渡し、クエリするインスタンスを指定します。結果はマージされて順位付けされます。各チャンクには、どのインスタンス由来かを示す instance_id フィールドが含まれます。

const results = await env.AI_SEARCH.search({
	messages: [{ role: "user", content: "What is Cloudflare?" }],
	ai_search_options: {
		instance_ids: ["product-docs", "customer-abc123"],
	},
});

インスタンスレベルの検索 と同じです。次の必須フィールドが 1 つ追加されます。

インスタンスレベルの検索 と同じです。次のフィールドが追加されます。

複数インスタンスから取得したコンテキストを使い、チャット補完を生成します。

const response = await env.AI_SEARCH.chatCompletions({
	messages: [{ role: "user", content: "What is Cloudflare?" }],
	ai_search_options: {
		instance_ids: ["product-docs", "customer-abc123"],
	},
});

stream: true でストリーミングにも対応します。

インスタンスレベルのチャット補完 と同じです。次の必須フィールドが 1 つ追加されます。

インスタンスレベルのチャット補完 と同じです。各チャンクに次のフィールドが追加されます。

ローカル開発は、デプロイ済みの AI Search インスタンスへリクエストをプロキシすることで対応しています。wrangler dev でローカル開発するには、バインディング設定に remote: true を追加します。

// wrangler.jsonc
{
	"ai_search": [
		{
			"binding": "MY_SEARCH",
			"instance_name": "my-instance",
			"remote": true,
		},
	],
}