Skip to content

非公式 / UnofficialCloudflare, Inc. 非提携。アカウント情報は入力しないでください。Not affiliated with Cloudflare, Inc. Do not enter Cloudflare credentials here.Official docsこのサイトについてプライバシー

Workers binding の移行

最終更新 Markdown で表示Agent セットアップ

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(従来) を参照してください。

役に立ちましたか?