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

привязка Workers

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

Чтобы использовать 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"

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

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

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

Загружает документ для индексирования. Возвращает ответ немедленно. Документ ставится в очередь на обработку.

// Upload from a string
await instance.items.upload(
	"faq.md",
	"# FAQ\n\nQ: How do I reset my password?\nA: Go to Settings > Security...",
);

// Upload from an ArrayBuffer
const pdfResponse = await fetch("https://example.com/guide.pdf");
const pdfBuffer = await pdfResponse.arrayBuffer();
await instance.items.upload("guide.pdf", pdfBuffer);

// Upload from a ReadableStream
await instance.items.upload("doc.txt", request.body);

Подключите пользовательские метаданные к документу для фильтрации в поисковых запросах. Пользовательские поля метаданных нужно сначала определить на уровне инстанса с помощью update() метод, либо в момент создания.

await instance.items.upload("guide.pdf", pdfBuffer, {
	metadata: {
		category: "onboarding",
		language: "en",
		version: "2.0",
	},
});

Загружает документ и опрашивает его статус, пока обработка не завершится или не истечёт время ожидания. Используйте этот метод, если нужно искать по документу сразу после загрузки.

// Wait for a specific document to finish indexing before searching
const item = await instance.items.uploadAndPoll(
	"handbook.txt",
	handbookContent,
);
console.log(`handbook.txt status: ${item.status}`); // "completed"

// Now search across all uploaded documents
const results = await instance.search({
	messages: [{ role: "user", content: "password reset policy" }],
});

Так же, как и items.upload(), с дополнительными параметрами опроса:

Возвращает полный объект элемента после завершения опроса:

Возвращает постраничный список элементов экземпляра.

const { result, result_info } = await instance.items.list();

for (const item of result) {
	console.log(`${item.key} (${item.status})`);
}
// result_info.total_count contains the total number of items

Удаляет элемент и его индексированные чанки.

await instance.items.delete("item-id-123");

Возвращает void. Возвращает ошибку, если элемент не существует.

Возвращает дескриптор конкретного элемента для получения его статуса или скачивания исходного файла.

Возвращает статус и метаданные конкретного элемента.

const itemInfo = await instance.items.get("item-id-123").info();

Скачивает исходный файл для элемента.

const file = await instance.items.get("item-id-123").download();
// file.body is a ReadableStream