← Обзор / ai-search / api / migration

Миграция привязки Workers

env.AI.autorag() привязка это устаревший API для AI Search. Он продолжит работать, но все новые функции и улучшения доступны только через новые привязки AI Search.

Вот краткий обзор ключевых различий между устаревшими и новыми привязками:

AI Search предоставляет две новые привязки:

Привязка экземпляра (ai_search) привязывается напрямую к одному экземпляру. Это самый простой способ перехода с 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 и поддержки локальной разработки.

Существующие экземпляры находятся в пространстве имён по умолчанию. Для простого перехода используйте привязку экземпляра. Об использовании привязки пространства имён см. в Привязки 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"

Обновите Env интерфейс, чтобы использовать новый тип привязки.

До:

export interface Env {
	AI: Ai;
}

После:

export interface Env {
	MY_INSTANCE: AiSearchInstance;
}

Замените 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?" }],
});

Форма ответа изменилась с data массив в chunks массив.

В устаревшей привязке потоковая передача с env.AI.autorag().aiSearch({ stream: true }) возвращала только потоковый ответ без полученных фрагментов.

Новая привязка сначала отправляет полученные чанки в виде chunks событие, за которым следует потоковый ответ. Это позволяет сразу показывать исходные чанки, одновременно транслируя сгенерированный ответ.

Новая привязка использует фильтрацию метаданных в стиле Vectorize. Теперь фильтры передаются внутри ai_search_options.retrieval.filters.

Фильтрация по одному полю метаданных с неявным равенством:

До:

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/" },
		},
	},
});

Объедините несколько условий, все из которых должны выполняться:

До:

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 (устаревшая).