INTEGRITY Документация

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

привязка Workers

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

Настройка привязки

Чтобы использовать AI Search с Workers, нужно создать привязку AI Search. Привязки создаются путём обновления Конфигурация Wrangler. 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"
Поле Тип Обязательный Описание
binding string Да Имя переменной, доступной в env. Например, "AI_SEARCH" делает его доступным как env.AI_SEARCH.
namespace string Да пространство имён к которому нужно привязаться. Пространство имён default пространство имён создаётся автоматически для каждого аккаунта. Если пространство имён не существует, Wrangler создаёт его при развёртывании.
remote boolean Нет Установите значение true для локальной разработки с wrangler dev.

Привязка экземпляра

Подключайтесь напрямую к одному экземпляру в 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"
Поле Тип Обязательный Описание
binding string Да Имя переменной, доступной в env. Например, "MY_SEARCH" делает его доступным как env.MY_SEARCH.
instance_name string Да Имя инстанса AI Search. На момент развертывания должно существовать в пространстве имен по умолчанию.
remote boolean Нет Установите значение true для локальной разработки с wrangler dev.

Методы экземпляра

Следующие методы доступны как в ai_search_namespaces и ai_search привязки. При использовании привязки пространства имён вызывайте методы на дескрипторе, который возвращает get(). При использовании привязки к экземпляру вызывайте методы прямо на привязке (например, env.MY_SEARCH.search()).

В примерах ниже используется привязка пространства имён.

Ищите релевантные чанки контента в вашем проиндексированном источнике данных. Возвращает оценённые чанки со ссылками на источник.

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

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

Параметры

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

Массив объектов сообщений, представляющих переписку. У каждого сообщения есть role и content поле.

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

Простая строка текстового запроса. Альтернатива messages. Укажите либо query или messages, а не оба сразу.

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

Параметры конфигурации для операции поиска.

Ответ

Ответ содержит следующие поля:

Поле Тип Описание
search_query string Запрос, использованный для поиска. Он может быть переписан, если включено переписывание запроса.
chunks array Массив подходящих чанков контента.
chunks[].id string Уникальный идентификатор чанка.
chunks[].type string Тип содержимого, обычно text.
chunks[].score число Общая оценка совпадения в диапазоне от 0 до 1.
chunks[].text string Текстовое содержимое чанка.
chunks[].item объект Информация об исходном элементе.
chunks[].item.key string Путь к файлу или URL исходного документа.
chunks[].item.timestamp число Время Unix последнего изменения элемента.
chunks[].item.metadata объект Пользовательские метаданные, связанные с исходным элементом.
chunks[].scoring_details объект Разбивка того, как был оценён чанк.
chunks[].scoring_details.vector_score число Оценка семантического сходства (от 0 до 1).
chunks[].scoring_details.keyword_score число Показатель соответствия по ключевым словам (BM25). Указывается при использовании гибридного поиска или поиска по ключевым словам.
chunks[].scoring_details.keyword_rank число Позиция в рейтинге по ключевым словам.
chunks[].scoring_details.vector_rank число Позиция в векторном ранжировании.
chunks[].scoring_details.reranking_score число Оценка реранкинга (от 0 до 1). Присутствует, если реранкинг включён.
chunks[].scoring_details.fusion_method string Используемый метод слияния (rrf или max). Присутствует при использовании гибридного поиска.

chatCompletions()

Генерируйте chat completions, используя свой экземпляр AI Search в качестве контекста. Этот метод находит релевантный контент и использует его для генерации ответа.

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

const response = await instance.chatCompletions({
	messages: [
		{ role: "system", content: "You are a helpful documentation assistant." },
		{ role: "user", content: "What is Cloudflare?" },
	],
	model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
	ai_search_options: {
		retrieval: {
			max_num_results: 5,
		},
		query_rewrite: {
			enabled: true,
		},
	},
});

Потоковая передача ответов

Задайте stream: true и таким образом получать ответы в виде Server-Sent Events (SSE) по мере их генерации:

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

const stream = await instance.chatCompletions({
	messages: [{ role: "user", content: "What is Cloudflare?" }],
	stream: true,
});

return new Response(stream, {
	headers: {
		"content-type": "text/event-stream",
		"cache-control": "no-cache",
	},
});

Когда stream включён, метод возвращает ReadableStream событий SSE. Каждое событие содержит объект JSON с choices[0].delta.content для добавочного текста. Поток завершается data: [DONE] событие.

Параметры

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

Массив объектов сообщений, представляющих переписку. У каждого сообщения есть role и content поле.

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

Модель генерации текста, используемая для формирования ответов. По умолчанию используется модель генерации, настроенная в параметрах экземпляра AI Search. Список поддерживаемых моделей см. в Поддерживаемые модели.

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

Возвращает поток результатов по мере их генерации. Если включено, возвращает Response объект с читаемым потоком. По умолчанию используется false.

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

Параметры конфигурации для операции поиска и генерации.

Ответ (без потоковой передачи)

Поле Тип Описание
id string Уникальный идентификатор completion.
object string Всегда chat.completion.
created число Время Unix создания completion.
model string Модель, используемая для генерации ответа.
choices array Массив вариантов ответа.
choices[].message.role string Всегда assistant.
choices[].message.content string Текст сгенерированного ответа.
choices[].finish_reason string Почему модель прекратила генерацию. Обычно stop.
usage.prompt_tokens число Количество токенов в промпте.
usage.completion_tokens число Количество токенов в сгенерированном ответе.
usage.total_tokens число Всего использовано токенов.
chunks array Исходные чанки, использованные в качестве контекста. Тот же формат, что и у ответ поиска.

Ответ (потоковый)

Когда stream: true, метод возвращает ReadableStream Server-Sent Events. Полученные фрагменты сначала отправляются как chunks событие, за которым следует потоковый ответ.

event: chunks
data: [{"id":"chunk-001","type":"text","score":0.85,"text":"...","item":{"key":"about-cloudflare.md","timestamp":1775925540000},"scoring_details":{"vector_score":0.85}}]

data: {"id":"id-1776072781845","created":1776072781,"model":"@cf/meta/llama-3.3-70b-instruct-fp8-fast","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":" document"}}]}

data: {"id":"id-1776072781845","created":1776072781,"model":"@cf/meta/llama-3.3-70b-instruct-fp8-fast","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":" you provided doesn"}}]}

data: {"id":"id-1776072781845","created":1776072781,"model":"@cf/meta/llama-3.3-70b-instruct-fp8-fast","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"'t contain"}}]}

data: {"id":"id-1776072781845","created":1776072781,"model":"@cf/meta/llama-3.3-70b-instruct-fp8-fast","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":" information"}}]}

data: [DONE]

Методы пространства имён

Следующие методы доступны только при использовании ai_search_namespaces привязка. Выполняйте поиск и общайтесь сразу с несколькими экземплярами в одном вызове, используя напрямую дескриптор пространства имён (env.AI_SEARCH).

search()

Передайте instance_ids в ai_search_options чтобы указать, какие инстансы запрашивать. Результаты объединяются и ранжируются, и каждый чанк содержит поле instance_id поле, указывающее, из какого экземпляра он получен.

const results = await env.AI_SEARCH.search({
	messages: [{ role: "user", content: "What is Cloudflare?" }],
	ai_search_options: {
		instance_ids: ["product-docs", "customer-abc123"],
	},
});

Параметры

Так же, как и поиск на уровне экземпляра, с одним дополнительным обязательным полем:

Параметр Тип Обязательный Описание
ai_search_options объект Да Требуется для поиска на уровне пространства имён.
ai_search_options.instance_ids array Да Идентификаторы экземпляров для поиска. Минимум 1, максимум 10.

Ответ

Так же, как и поиск на уровне экземпляра, с дополнительными полями:

Поле Тип Описание
chunks[].instance_id string Экземпляр, из которого получен этот чанк.
errors array Ошибки на уровне отдельных экземпляров, если какие-либо из них завершились сбоем. Каждый объект содержит instance_id и message.

chatCompletions()

Генерируйте chat completions с контекстом, извлечённым сразу из нескольких экземпляров.

const response = await env.AI_SEARCH.chatCompletions({
	messages: [{ role: "user", content: "What is Cloudflare?" }],
	ai_search_options: {
		instance_ids: ["product-docs", "customer-abc123"],
	},
});

Потоковая передача поддерживается с stream: true.

Параметры

Так же, как и Chat Completions на уровне экземпляра, с одним дополнительным обязательным полем:

Параметр Тип Обязательный Описание
ai_search_options объект Да Требуется для chat completions на уровне пространства имён.
ai_search_options.instance_ids array Да Идентификаторы экземпляров для поиска. Минимум 1, максимум 10.

Ответ

Так же, как и Chat Completions на уровне экземпляра, с дополнительными полями у каждого чанка:

Поле Тип Описание
chunks[].instance_id string Экземпляр, из которого получен этот чанк.
errors array Ошибки на уровне отдельных экземпляров, если какие-либо из них завершились сбоем. Каждый объект содержит instance_id и message.

Локальная разработка

Локальная разработка поддерживается за счёт проксирования запросов к вашему развёрнутому экземпляру AI Search. Добавьте remote: true в конфигурацию привязок, чтобы включить локальную разработку с wrangler dev.

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