Workers binding

Workers は、新しいアプリケーションの作成や既存アプリの拡張ができるサーバーレス実行環境です。Workers binding を使い、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 バインディングを使う場合のみ使えます。名前空間ハンドル（env.AI_SEARCH）は、名前空間 内のインスタンスを操作するメソッドを公開します。

特定インスタンスへのハンドルを返します。これは 同期 で、ネットワーク呼び出しはしません。インスタンスは search() や info() などのメソッドを呼んだときに遅延解決されます。

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

名前空間内の全インスタンスを返します。

const { result, result_info } = await env.AI_SEARCH.list();

for (const instance of result) {
	console.log(`${instance.id} (${instance.type}) - ${instance.status}`);
}
// result_info.total_count contains the total number of instances

新しいインスタンスを作成し、そのハンドルを返します。データソース付きのインスタンスを作るか、Items API 向けの空インスタンスを作れます。

ファイルアップロード用の空インスタンスを作成する:

AI Search インスタンスには 組み込みストレージ があり、ドキュメントを直接アップロードできます。

const instance = await env.AI_SEARCH.create({
	id: "knowledge-base",
});

// Upload documents using the Items API
await instance.items.upload("guide.pdf", pdfArrayBuffer);

web-crawler インスタンスを作成する:

所有する Web サイトを自動でクロールし、インデックスします。設定オプションの詳細は Web サイトデータソース を参照してください。

const instance = await env.AI_SEARCH.create({
	id: "my-docs",
	type: "web-crawler",
	source: "developers.cloudflare.com",
});

R2 バックエンドのインスタンスを作成する:

R2 バケットに保存したドキュメントをインデックスします。設定オプションの詳細は R2 データソース を参照してください。

const instance = await env.AI_SEARCH.create({
	id: "internal-docs",
	type: "r2",
	source: "my-docs-bucket",
});

id string required

AI Search インスタンスの一意の識別子です。1〜64 文字で、パターン ^[a-z0-9_]+(?:-[a-z0-9_]+)*$ に一致する必要があります。

type string optional

データソースの種類です。有効な値は r2、web-crawler です。データソース付きでインスタンスを作成する場合は必須です。Items API 向けの空のインスタンスを作成する場合は省略します。

source string optional

データソースの場所です。r2 の場合は R2 バケット名です。web-crawler の場合はウェブサイトのドメインです。type を指定した場合は必須です。

source_params object optional

データソースの追加パラメーターです。

• prefix string optional
  • R2 ソースでは、このキープレフィックスを持つオブジェクトだけをインデックスします。
• r2_jurisdiction string optional
  • R2 バケットの管轄です。例: eu。
• include_items array optional
  • インデックスに含めるパスの Glob パターンです。例: ["/blog/**", "/docs/**/*.html"]。
• exclude_items array optional
  • インデックスから除外するパスの Glob パターンです。例: ["/admin/**", "/private/**"]。
• web_crawler object optional
  • Web クローラーソースの設定です。
  • parse_type string optional
    • ページの検出方法です。有効な値は sitemap（XML サイトマップを読む）、discover（ソース URL から開始し、デフォルトではサイトマップとクロールしたページ上のリンクの両方を使う）です。デフォルトは sitemap です。パースタイプ を参照してください。
  • parse_options object optional
    • include_headers object optional
      • クロール時に含めるカスタム HTTP ヘッダーです。
    • include_images boolean optional
      • インデックスに画像を含めるかどうかです。
    • specific_sitemaps array optional
      • クロールする特定のサイトマップ URL です。例: ["https://example.com/sitemap.xml"]。parse_type が sitemap の場合にだけ有効です。
    • use_browser_rendering boolean optional
      • JavaScript で描画されるページをクロールするために、Browser Run（旧称 Browser Rendering）を使います。
  • discover_options object optional
    • parse_type が discover のときに適用されるクロール設定です。
    • source string optional
      • クローラーが候補 URL を探す場所です。有効な値は all、sitemaps、links です。デフォルトは all です。
    • limit number optional
      • クロールするページの最大数です。有効な値は 1 から 100000 です。デフォルトは 100000 です。
    • depth number optional
      • ソース URL からたどるリンクの最大ホップ数です。有効な値は 1 から 100000 です。デフォルトは 5 です。
    • max_age number optional
      • クローラーがキャッシュ済みページ内容を再利用してから、オリジンへ再取得するまでの秒数です。有効な値は 0 から 604800 です。デフォルトは 86400 です。
    • include_external_links boolean optional
      • ほかのドメインを指すリンクをたどるかどうかです。デフォルトは false です。
    • include_subdomains boolean optional
      • ソース URL のサブドメインを指すリンクをたどるかどうかです。デフォルトは false です。
  • store_options object optional
    • storage_type string optional
      • ストレージの種類です。有効な値は r2 です。
    • storage_id string optional
      • ストレージバケットの ID です。
    • r2_jurisdiction string optional
      • ストレージバケットの管轄です。

index_method object optional

インスタンスで有効にするインデックス方法を設定します。ベクトル（セマンティック）検索、キーワード検索、またはその両方を使えるかどうかを決めます。少なくとも 1 つを true にする必要があります。

• vector boolean optional
  • ベクトルベースのセマンティック検索を有効にします。デフォルトは true です。
• keyword boolean optional
  • キーワード検索を有効にします。デフォルトは false です。

ハイブリッド検索にするには、両方を true にします。

fusion_method string optional

ハイブリッド検索で、ベクトルスコアとキーワードスコアをどう組み合わせるかを制御します。有効な値は rrf（Reciprocal Rank Fusion）、max（最大スコアを使う）です。デフォルトは rrf です。

indexing_options object optional

コンテンツのインデックス方法の設定です。

• keyword_tokenizer string optional
  • キーワード検索のインデックスに使うトークナイザーです。有効な値は porter（ステミングベース）、trigram（文字 n-gram）です。デフォルトは porter です。

retrieval_options object optional

インスタンスのデフォルト取得設定です。これらのデフォルトは、リクエストごとに ai_search_options で上書きできます。

• keyword_match_mode string optional
  • キーワード（BM25）照合で候補ドキュメントを選ぶ方法を制御します。and はすべての語の一致が必要です。or はいずれかの語の一致で足ります。デフォルトは and です。
• boost_by array optional
  • すべての検索クエリに適用するデフォルトのブーストフィールドです。最大 3 件です。各項目は次の構成です。
    • field string required - ブースト対象のメタデータフィールド名です。最大 64 文字です。
    • direction string optional - ブーストの方向です。有効な値は asc、desc、exists、not_exists です。

sync_interval number optional

データソースの自動同期の間隔（秒）です。有効な値は 3600、7200、14400、21600、43200、86400 です。デフォルトは 21600（6 時間）です。

token_id string optional

このインスタンスで使う サービス API トークン の UUID です。AI Search インスタンスを一度も作成したことがない場合にだけ必須です。サービストークンの作成と登録は API スタートガイド を参照してください。

ai_gateway_id string optional

ログと分析のためにリクエストを通す AI Gateway ID です。

embedding_model string optional

コンテンツをベクトル化するときに使う埋め込みモデルです。

ai_search_model string optional

応答の生成に使うテキスト生成モデルです。

rewrite_query boolean optional

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

rewrite_model string optional

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

reranking boolean optional

取得結果を意味的な関連性で並べ替えるリランキングを有効にします。デフォルトは false です。

reranking_model string optional

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

chunk_size number optional

ドキュメント分割時のチャンクサイズです。最小値は 64 です。

chunk_overlap number optional

チャンク間のオーバーラップです。最小値は 0 です。

max_num_results number optional

返す結果のデフォルト最大件数です。最小値は 1 です。

score_threshold number optional

結果のデフォルト最小スコアしきい値です。最小値は 0 です。

cache boolean optional

応答キャッシュを有効にします。デフォルトは true です。

cache_threshold string optional

キャッシュの一致しきい値です。有効な値は super_strict_match、close_enough、flexible_friend、anything_goes です。デフォルトは close_enough です。

cache_ttl number optional

キャッシュエントリの TTL（秒）です。有効な値は 600、1800、3600、7200、21600、43200、86400、172800、259200、518400 です。デフォルトは 172800 です。

custom_metadata array optional

ドキュメントから抽出してインデックスするカスタムメタデータフィールドです。

• field_name string required
  • メタデータフィールドの名前です。
• data_type string required
  • フィールドのデータ型です。有効な値は text、number、boolean、datetime です。

enable boolean optional

インスタンスを有効にするかどうかです。デフォルトは true です。

search()、info()、stats()、items.upload() などのメソッドをすぐ呼べる AiSearchInstance ハンドルを返します。インスタンス設定を得るには、ハンドルの info() を呼びます。

インスタンスと、そのインデックス済みコンテンツを完全に削除します。この操作は元に戻せません。

await env.AI_SEARCH.delete("old-docs");

void を返します。インスタンスが存在しない場合はエラーを投げます。

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

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

インスタンス設定を部分更新します。渡したフィールドだけが変更されます。

const updated = await env.AI_SEARCH.get("my-instance").update({
	ai_search_model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
	reranking: true,
});

作成パラメーター の部分版を受け付けます。含めたフィールドだけが更新されます。

更新後のインスタンス設定を返します。形は info() と同じです。

インスタンスの現在の設定とメタデータを返します。

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

インスタンスの現在のインデックス進捗を返します。インスタンス作成後やファイルアップロード後に完了をポーリングするときに使います。

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

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

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