← Přehled / ai-search / api / items

Workers binding

Workers poskytuje bezserverové prostředí pro spouštění kódu, ve kterém můžete vytvářet nové aplikace nebo rozšiřovat ty stávající. Použijte Workers binding k nahrávání, výpisu a správě dokumentů ve vašich instancích AI Search z Cloudflare Workeru. K Items API přistupujte prostřednictvím items vlastnost na handle instance.

Chcete-li používat AI Search s Workers, musíte vytvořit vazbu AI Search. Vazby vytváříte úpravou svého Konfigurace Wrangleru. AI Search nabízí dva typy bindingů:

• Vazba jmenného prostoru: ai_search_namespaces
• Vazba instance: ai_search

Přístup ke všem instancím v rámci namespace. Instance můžete za běhu získávat, vytvářet, vypisovat a mazat.

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

Navažte přímou vazbu na jedinou instanci v default jmenný prostor. Použijte to v případě, že víte, kterou instanci potřebujete už v době nasazení.

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

Metody Items API jsou dostupné jak u ai_search_namespaces a ai_search vazby. U vazby jmenného prostoru volejte metody na handle vráceném get(). S vazbou instance volejte metody přímo na vazbě (například env.MY_SEARCH.items.upload()).

Níže uvedené příklady používají vazbu jmenného prostoru.

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

Nahraje dokument k indexaci. Vrátí odpověď okamžitě. Dokument se zařadí do fronty ke zpracování.

// 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);

Připojte vlastní metadata k dokumentu, aby ho bylo možné filtrovat ve vyhledávacích dotazech. Vlastní pole metadat je nutné nejprve definovat na instanci pomocí update() metoda, nebo v okamžiku vytvoření.

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

Nahraje dokument a čeká na dokončení zpracování, nebo dokud není dosaženo časového limitu. Použijte tuto možnost, pokud potřebujete dokument prohledat ihned po nahrání.

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

Stejné jako items.upload(), s dalšími možnostmi dotazování:

Po dokončení dotazování vrátí úplný objekt položky:

Vrátí stránkovaný seznam položek v instanci.

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

Odstraní položku a její indexované části obsahu.

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

Vrátí void. Vyvolá chybu, pokud položka neexistuje.

Vrátí handle na konkrétní položku pro načtení jejího stavu nebo stažení původního souboru.

Vrátí stav a metadata konkrétní položky.

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

Stáhne původní zdrojový soubor položky.

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