Workers binding の移行

env.AI.autorag() バインディングは、AI Search の従来 API です。引き続き動作しますが、新しい機能と改善は新しい AI Search バインディングでのみ使えます。

変更点

従来バインディングと新しいバインディングの主な違いは次のとおりです。

	従来	新
Wrangler 設定	`ai` バインディング	`ai_search` または `ai_search_namespaces` バインディング
アクセス方法	`env.AI.autorag("name")`	`env.MY_INSTANCE` または `env.AI_SEARCH.get("name")`
検索形式	`query` 文字列	`messages` 配列または `query` 文字列
応答形式	`data` 配列	`chunks` 配列

AI Search のバインディング

AI Search は 2 つの新しいバインディングを提供します。

インスタンスバインディング（ai_search） は、1 つのインスタンスへ直接バインドします。env.AI.autorag() からのいちばん簡単な移行経路です。

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

名前空間バインディング（ai_search_namespaces） は、名前空間内の全インスタンスへアクセスできます。動的なインスタンス管理、インスタンス横断検索、Items API が必要な場合に使います。

// wrangler.jsonc
{
	"ai_search_namespaces": [
		{
			"binding": "AI_SEARCH",
			"namespace": "default",
		},
	],
}

違いの詳細は名前空間を参照してください。

要件

新しいバインディングには、TypeScript の型とローカル開発のサポートのため、次の最小パッケージバージョンが必要です。

パッケージ	最小バージョン
`@cloudflare/workers-types`	`4.20260304.0`
`wrangler`	`4.68.1`

ステップ 1: Wrangler 設定を更新する

既存のインスタンスはデフォルト名前空間にあります。簡単なアップグレードにはインスタンスバインディングを使います。名前空間バインディングは AI Search のバインディングを参照してください。

変更前:

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "ai": {
    "binding": "AI"
  }
}

[ai]
binding = "AI"

変更後:

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

compatibility_date = "2026-03-27"

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

ステップ 2: 型定義を更新する

Env インターフェースを、新しいバインディング型に更新します。

変更前:

export interface Env {
	AI: Ai;
}

変更後:

export interface Env {
	MY_INSTANCE: AiSearchInstance;
}

ステップ 3: 検索呼び出しを更新する

env.AI.autorag() の呼び出しを、新しいバインディングに置き換えます。

変更前:

const result = await env.AI.autorag("my-instance").search({
	query: "What is Cloudflare?",
});

変更後:

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

ステップ 4: 応答の処理を更新する

応答の形は data 配列から chunks 配列に変わりました。

フィールド対応

旧フィールド	新フィールド
`data[]`	`chunks[]`
`data[].file_id`	`chunks[].id`
`data[].filename`	`chunks[].item.key`
`data[].score`	`chunks[].score`
`data[].content[].text`	`chunks[].text`
`data[].attributes.modified_date`	`chunks[].item.timestamp`

ストリーミング動作の変更

従来バインディングでは、env.AI.autorag().aiSearch({ stream: true }) のストリーミングは、取得したチャンクなしでストリーム応答だけを返していました。

新しいバインディングは、取得したチャンクを先に chunks イベントとして送り、そのあとストリーム応答を送ります。生成応答をストリーミングしながら、ソースチャンクをすぐに表示できます。

フィルター形式の変更

新しいバインディングは、Vectorize 形式のメタデータフィルターを使います。フィルターは ai_search_options.retrieval.filters の中に渡します。

旧形式	新形式
`eq`	`$eq`（または暗黙）
`ne`	`$ne`
`gt`	`$gt`
`gte`	`$gte`
`lt`	`$lt`
`lte`	`$lte`
	`$in`（新規）
	`$nin`（新規）

例

単純なフィルター

暗黙の等価で、1 つのメタデータフィールドで絞り込みます。

変更前:

const result = await env.AI.autorag("my-instance").search({
	query: "What is Cloudflare?",
	filters: {
		type: "eq",
		key: "folder",
		value: "customer-a/",
	},
});

変更後:

const result = await env.MY_INSTANCE.search({
	messages: [{ role: "user", content: "What is Cloudflare?" }],
	ai_search_options: {
		retrieval: {
			filters: { folder: "customer-a/" },
		},
	},
});

複合フィルター（AND）

すべての条件に一致するよう、複数条件を組み合わせます。

変更前:

const result = await env.AI.autorag("my-instance").search({
	query: "What is Cloudflare?",
	filters: {
		type: "and",
		filters: [
			{ type: "eq", key: "folder", value: "customer-a/" },
			{ type: "gte", key: "timestamp", value: "1735689600000" },
		],
	},
});

変更後:

const result = await env.MY_INSTANCE.search({
	messages: [{ role: "user", content: "What is Cloudflare?" }],
	ai_search_options: {
		retrieval: {
			filters: {
				folder: "customer-a/",
				timestamp: { $gte: 1735689600 },
			},
		},
	},
});

後方互換性

env.AI.autorag() バインディングは、期限なく動き続けます。すぐに移行する必要はありません。

従来 API のリファレンスは Workers binding（従来）を参照してください。