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

привязка Workers

Workers предоставляет бессерверную среду выполнения, в которой можно создавать новые приложения или дополнять существующие. Используйте привязка Workers для создания, получения списка, обновления и удаления инстансов AI Search из Cloudflare Worker. Вы также можете проверять конфигурацию инстанса и отслеживать ход индексирования.

Чтобы использовать AI Search с Workers, нужно создать привязку AI Search. Привязки создаются путём обновления Конфигурация Wrangler. AI Search предоставляет два типа привязок:

• Привязка пространства имён: 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 пространство имён. Используйте этот вариант, когда вы уже знаете нужный экземпляр на момент развёртывания.

{
  "$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

Создаёт новый экземпляр и возвращает на него дескриптор. Можно создавать экземпляры на основе источника данных или пустые экземпляры для использования с 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);

Создайте экземпляр веб-краулера:

Автоматически сканируйте и индексируйте сайт, которым вы владеете. Дополнительные варианты настройки см. в Источник данных «Сайт».

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

Создайте экземпляр на основе R2:

Индексация документов, хранящихся в R2 bucket. Дополнительные варианты настройки см. в Источник данных R2.

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

id string обязательно

Уникальный идентификатор экземпляра AI Search. Должен содержать от 1 до 64 символов и соответствовать шаблону ^[a-z0-9_]+(?:-[a-z0-9_]+)*$.

type string необязательно

Тип источника данных. Допустимые значения: r2, web-crawler. Обязательно при создании экземпляра с источником данных. Пропустите при создании пустого экземпляра для использования с API элементов.

source string необязательно

Расположение источника данных. Для r2 типа это имя бакета R2. Для web-crawler типа это домен веб-сайта. Требуется, если type указан.

source_params object необязательно

Дополнительные параметры источника данных.

• prefix string необязательно
  • Для источников R2 ограничивает индексирование объектами с этим префиксом ключа.
• r2_jurisdiction string необязательно
  • Юрисдикция для бакета R2, например eu.
• include_items array необязательно
  • Glob-шаблоны для путей, которые нужно включить в индексирование. Например: ["/blog/**", "/docs/**/*.html"].
• exclude_items array необязательно
  • Glob-шаблоны для путей, которые нужно исключить из индексирования. Например: ["/admin/**", "/private/**"].
• web_crawler object необязательно
  • Конфигурация источников для веб-краулера.
  • parse_type string необязательно
    • Как обнаруживаются страницы. Допустимые значения: sitemap (считывает файлы XML sitemap), discover (начинается с исходного URL-адреса и по умолчанию использует как файлы sitemap, так и ссылки, найденные на просканированных страницах). Значение по умолчанию: sitemap. См. Parse types.
  • parse_options object необязательно
    • include_headers object необязательно
      • Пользовательские заголовки HTTP, которые нужно добавлять при обходе.
    • include_images boolean необязательно
      • Включать ли изображения в индекс.
    • specific_sitemaps array необязательно
      • Конкретные URL-адреса sitemap для сканирования. Например: ["https://example.com/sitemap.xml"]. Допустимо только если parse_type это sitemap.
    • use_browser_rendering boolean необязательно
      • Используйте Browser Run (ранее Browser Rendering) для обхода страниц, отрисованных на JavaScript.
  • discover_options object необязательно
    • Настройки сканирования, которые применяются, когда parse_type это discover.
    • source string необязательно
      • Где краулер ищет потенциальные URL-адреса. Допустимые значения: all, sitemaps, links. По умолчанию используется all.
    • limit number необязательно
      • Максимальное количество страниц для сканирования. Допустимые значения: 1 к 100000. По умолчанию используется 100000.
    • depth number необязательно
      • Максимальное количество переходов по ссылкам от исходного URL. Допустимые значения: 1 к 100000. По умолчанию используется 5.
    • max_age number необязательно
      • Как долго, в секундах, краулер использует кешированное содержимое страницы, прежде чем заново загрузить его с origin-сервера. Допустимые значения: 0 к 604800. По умолчанию используется 86400.
    • include_external_links boolean необязательно
      • Переходить ли по ссылкам, ведущим на другие домены. По умолчанию: false.
    • include_subdomains boolean необязательно
      • Переходить ли по ссылкам, ведущим на поддомены исходного URL. По умолчанию: false.
  • store_options object необязательно
    • storage_type string необязательно
      • Тип хранилища. Допустимое значение: r2.
    • storage_id string необязательно
      • ID бакета хранилища.
    • r2_jurisdiction string необязательно
      • Юрисдикция для бакета хранилища.

index_method object необязательно

Определяет, какие методы индексирования включены для экземпляра. Указывает, доступен ли векторный (семантический) поиск, поиск по ключевым словам или оба варианта. Хотя бы один должен быть true.

• vector boolean необязательно
  • Включите векторный семантический поиск. По умолчанию: true.
• keyword boolean необязательно
  • Включите поиск по ключевым словам. По умолчанию: false.

Задайте для обоих значение true для гибридного поиска.

fusion_method string необязательно

Определяет, как объединяются оценки векторного и ключевого поиска при использовании гибридного поиска. Допустимые значения: rrf (Reciprocal Rank Fusion), max (используется максимальное значение оценки). Значение по умолчанию: rrf.

indexing_options object необязательно

Конфигурация способа индексирования контента.

• keyword_tokenizer string необязательно
  • Токенизатор, используемый для индексирования при поиске по ключевым словам. Допустимые значения: porter (на основе стемминга), trigram (символьная n-грамма). Значение по умолчанию: porter.

retrieval_options object необязательно

Конфигурация поиска по умолчанию для экземпляра. Эти значения по умолчанию можно переопределить на уровне запроса с помощью ai_search_options.

• keyword_match_mode string необязательно
  • Определяет, как сопоставление по ключевым словам (BM25) выбирает документы-кандидаты. and требует совпадения всех терминов. or требует совпадения хотя бы одного термина. Значение по умолчанию: and.
• boost_by array необязательно
  • Поля усиления по умолчанию, применяемые ко всем поисковым запросам. Максимум 3 элемента. Каждый элемент содержит:
    • field string обязательно - Имя поля метаданных, по которому выполняется усиление. Максимум 64 символа.
    • direction string необязательно - Направление усиления (boost). Допустимые значения: asc, desc, exists, not_exists.

sync_interval number необязательно

Интервал в секундах между автоматическими синхронизациями источника данных. Допустимые значения: 3600, 7200, 14400, 21600, 43200, 86400. По умолчанию используется 21600 (6 часов).

token_id string необязательно

UUID токен API службы для использования в этом экземпляре. Требуется только если вы ещё не создавали ни одного экземпляра AI Search. См. Руководство по началу работы с API о том, как создать и зарегистрировать токен службы.

ai_gateway_id string необязательно

ID AI Gateway для маршрутизации запросов в целях логирования и аналитики.

embedding_model string необязательно

Embedding-модель, используемая для векторизации контента.

ai_search_model string необязательно

Модель генерации текста, используемая для формирования ответов.

rewrite_query boolean необязательно

Включите переписывание запроса для повышения точности поиска. По умолчанию: false.

rewrite_model string необязательно

Модель, используемая для переписывания запроса.

reranking boolean необязательно

Включите реранкинг, чтобы переупорядочивать найденные результаты по семантической релевантности. По умолчанию: false.

reranking_model string необязательно

Модель реранкинга. Допустимое значение: @cf/baai/bge-reranker-base.

chunk_size number необязательно

Размер чанков при разбиении документов. Минимальное значение: 64.

chunk_overlap number необязательно

Перекрытие между чанками. Минимальное значение: 0.

max_num_results number необязательно

Максимальное количество возвращаемых результатов по умолчанию. Минимальное значение: 1.

score_threshold number необязательно

Минимальный порог показателя соответствия для результатов по умолчанию. Минимальное значение: 0.

cache boolean необязательно

Включите кеширование ответов. По умолчанию: true.

cache_threshold string необязательно

Порог совпадения кэша. Допустимые значения: super_strict_match, close_enough, flexible_friend, anything_goes. По умолчанию используется close_enough.

cache_ttl number необязательно

TTL записи кэша в секундах. Допустимые значения: 600, 1800, 3600, 7200, 21600, 43200, 86400, 172800, 259200, а также 518400. По умолчанию используется 172800.

custom_metadata array необязательно

Поля пользовательских метаданных, которые нужно извлекать и индексировать из документов.

• field_name string обязательно
  • Имя поля метаданных.
• data_type string обязательно
  • Тип данных поля. Допустимые значения: text, number, boolean, datetime.

enable boolean необязательно

Включён ли экземпляр. По умолчанию: true.

Возвращает AiSearchInstance дескриптор, который сразу готов к использованию для вызова таких методов, как search(), info(), stats(), а также items.upload(). Вызовите 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,
		},
	],
}