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

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 vytváření, výpisu, aktualizaci a mazání instancí AI Search z Cloudflare Workeru. Můžete také kontrolovat konfiguraci instance a sledovat průběh indexování.

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"

Následující metody jsou k dispozici pouze při použití ai_search_namespaces vazba. Handle jmenného prostoru (env.AI_SEARCH) zpřístupňuje metody pro práci s instancemi v rámci namespace.

Vrátí handle na konkrétní instanci. Toto je synchronní a neprovádí síťové volání. Instance se líně inicializuje až ve chvíli, kdy zavoláte metody jako search() nebo info().

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

Vrátí všechny instance v jmenném prostoru.

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

Vytvoří novou instanci a vrátí na ni odkaz. Můžete vytvořit instance podporované zdrojem dat, nebo vytvořit prázdné instance pro použití s Items API.

Vytvořte prázdnou instanci pro nahrávání souborů:

Instance AI Search obsahují vestavěné úložiště kde můžete dokumenty nahrávat přímo.

const instance = await env.AI_SEARCH.create({
	id: "knowledge-base",
});

// Upload documents using the Items API
await instance.items.upload("guide.pdf", pdfArrayBuffer);

Vytvořte instanci webového prohledávače:

Automaticky procházejte a indexujte web, který vlastníte. Další možnosti konfigurace najdete v Datový zdroj typu web.

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

Vytvořte instanci podporovanou R2:

Indexujte dokumenty uložené v R2 bucket. Další možnosti konfigurace najdete v Zdroj dat R2.

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

id string povinné

Jedinečný identifikátor instance AI Search. Musí mít 1 až 64 znaků a odpovídat vzoru ^[a-z0-9_]+(?:-[a-z0-9_]+)*$.

type string volitelné

Typ zdroje dat. Platné hodnoty: r2, web-crawler. Povinné při vytváření instance se zdrojem dat. Vynechte při vytváření prázdné instance určené k použití s Items API.

source string volitelné

Umístění zdroje dat. Pro r2 typu je to název R2 bucketu. Pro web-crawler typu je to doména webu. Vyžadováno, pokud type je zadáno.

source_params object volitelné

Další parametry zdroje dat.

• prefix string volitelné
  • U zdrojů R2 omezuje indexování na objekty s touto předponou klíče.
• r2_jurisdiction string volitelné
  • Jurisdikce pro bucket R2, například eu.
• include_items array volitelné
  • Glob patterns pro cesty, které se mají zahrnout do indexování. Například: ["/blog/**", "/docs/**/*.html"].
• exclude_items array volitelné
  • Glob patterns pro cesty, které se mají vyloučit z indexování. Například: ["/admin/**", "/private/**"].
• web_crawler object volitelné
  • Konfigurace zdrojů pro procházení webu.
  • parse_type string volitelné
    • Jak se vyhledávají stránky. Platné hodnoty: sitemap (načítá soubory XML sitemap), discover (začíná na zdrojové URL adrese a ve výchozím nastavení používá jak soubory sitemap, tak odkazy nalezené na procházených stránkách). Výchozí hodnota: sitemap. Viz Parse types.
  • parse_options object volitelné
    • include_headers object volitelné
      • Vlastní hlavičky HTTP, které se mají zahrnout při procházení.
    • include_images boolean volitelné
      • Zda zahrnout obrázky do indexu.
    • specific_sitemaps array volitelné
      • Konkrétní adresy URL sitemap k procházení. Například: ["https://example.com/sitemap.xml"]. Platí jen v případě, že parse_type je sitemap.
    • use_browser_rendering boolean volitelné
      • Použijte Browser Run (dříve Browser Rendering) k procházení stránek vykreslených pomocí JavaScriptu.
  • discover_options object volitelné
    • Nastavení procházení, která se použijí, když parse_type je discover.
    • source string volitelné
      • Kde crawler hledá kandidátní adresy URL. Platné hodnoty: all, sitemaps, links. Výchozí hodnota je all.
    • limit number volitelné
      • Maximální počet stránek k procházení. Platné hodnoty: 1 na 100000. Výchozí hodnota je 100000.
    • depth number volitelné
      • Maximální počet odkazových skoků, které se mají sledovat od zdrojové URL adresy. Platné hodnoty: 1 na 100000. Výchozí hodnota je 5.
    • max_age number volitelné
      • Jak dlouho, v sekundách, crawler znovu používá obsah stránky uložený v mezipaměti, než ho znovu načte z origin serveru. Platné hodnoty: 0 na 604800. Výchozí hodnota je 86400.
    • include_external_links boolean volitelné
      • Zda sledovat odkazy vedoucí na jiné domény. Výchozí hodnota je false.
    • include_subdomains boolean volitelné
      • Zda sledovat odkazy vedoucí na subdomény zdrojové adresy URL. Výchozí hodnota je false.
  • store_options object volitelné
    • storage_type string volitelné
      • Typ úložiště. Platná hodnota: r2.
    • storage_id string volitelné
      • ID úložného bucketu.
    • r2_jurisdiction string volitelné
      • Jurisdikce pro úložný bucket.

index_method object volitelné

Určuje, které metody indexování jsou pro instanci povoleny. Rozhoduje o tom, zda je k dispozici vektorové (sémantické) vyhledávání, vyhledávání podle klíčových slov, nebo obojí. Alespoň jedna musí být true.

• vector boolean volitelné
  • Povolte sémantické vyhledávání založené na vektorech. Výchozí hodnota je true.
• keyword boolean volitelné
  • Povolte vyhledávání založené na klíčových slovech. Výchozí hodnota je false.

Nastavte obě na true pro hybridní vyhledávání.

fusion_method string volitelné

Určuje, jak se při hybridním vyhledávání kombinuje vektorové skóre se skóre klíčových slov. Platné hodnoty: rrf (Reciprocal Rank Fusion), max (použije se nejvyšší skóre). Výchozí hodnota: rrf.

indexing_options object volitelné

Konfigurace způsobu indexování obsahu.

• keyword_tokenizer string volitelné
  • Tokenizér použitý pro indexování klíčového vyhledávání. Platné hodnoty: porter (založený na stemmingu), trigram (znakový n-gram). Výchozí hodnota: porter.

retrieval_options object volitelné

Výchozí konfigurace načítání pro instanci. Tyto výchozí hodnoty lze pro jednotlivé požadavky přepsat pomocí ai_search_options.

• keyword_match_mode string volitelné
  • Určuje, jak porovnávání podle klíčových slov (BM25) vybírá kandidátní dokumenty. and vyžaduje shodu všech výrazů. or vyžaduje shodu alespoň jednoho výrazu. Výchozí hodnota je and.
• boost_by array volitelné
  • Výchozí posilovací položky použité na všechny dotazy vyhledávání. Maximálně 3 položky. Každá položka obsahuje:
    • field string povinné - Název pole metadat, podle kterého se má posílení provést. Maximálně 64 znaků.
    • direction string volitelné - Směr posílení (boost). Platné hodnoty: asc, desc, exists, not_exists.

sync_interval number volitelné

Počet sekund mezi automatickými synchronizacemi zdroje dat. Platné hodnoty: 3600, 7200, 14400, 21600, 43200, 86400. Výchozí hodnota je 21600 (6 hodin).

token_id string volitelné

UUID servisní token API k použití pro tuto instanci. Vyžadováno pouze v případě, že jste dosud nevytvořili žádnou instanci AI Search. Viz Úvodní příručka k API o tom, jak vytvořit a zaregistrovat token služby.

ai_gateway_id string volitelné

ID AI Gateway, přes které se směrují požadavky pro protokolování a analýzu.

embedding_model string volitelné

Embedding model, který se má použít k vektorizaci obsahu.

ai_search_model string volitelné

Model pro generování textu, který se má použít ke generování odpovědí.

rewrite_query boolean volitelné

Povolte přepisování dotazu, abyste zlepšili přesnost vyhledávání. Výchozí hodnota je false.

rewrite_model string volitelné

Model, který se má použít pro přepis dotazu.

reranking boolean volitelné

Povolte reranking, aby se načtené výsledky přeřadily podle sémantické relevance. Výchozí hodnota je false.

reranking_model string volitelné

Model rerankingu, který se má použít. Platná hodnota: @cf/baai/bge-reranker-base.

chunk_size number volitelné

Velikost částí obsahu při rozdělování dokumentů. Minimální hodnota: 64.

chunk_overlap number volitelné

Překryv mezi částmi obsahu. Minimální hodnota: 0.

max_num_results number volitelné

Výchozí maximální počet vracených výsledků. Minimální hodnota: 1.

score_threshold number volitelné

Výchozí minimální prahová hodnota skóre pro výsledky. Minimální hodnota: 0.

cache boolean volitelné

Povolte ukládání odpovědí do mezipaměti. Výchozí hodnota je true.

cache_threshold string volitelné

Práh shody mezipaměti. Platné hodnoty: super_strict_match, close_enough, flexible_friend, anything_goes. Výchozí hodnota je close_enough.

cache_ttl number volitelné

TTL položky mezipaměti v sekundách. Platné hodnoty jsou 600, 1800, 3600, 7200, 21600, 43200, 86400, 172800, 259200, a 518400. Výchozí hodnota je 172800.

custom_metadata array volitelné

Položky vlastních metadat, které se mají extrahovat a indexovat z dokumentů.

• field_name string povinné
  • Název pole metadat.
• data_type string povinné
  • Datový typ pole. Platné hodnoty: text, number, boolean, datetime.

enable boolean volitelné

Zda je instance povolena. Výchozí hodnota je true.

Vrátí AiSearchInstance handle, který lze ihned použít k volání metod, jako je search(), info(), stats(), a items.upload(). Zavolejte info() na handle, čímž získáte konfiguraci instance.

Trvale odstraní instanci a veškerý její indexovaný obsah. Tuto akci nelze vrátit zpět.

await env.AI_SEARCH.delete("old-docs");

Vrátí void. Vyvolá chybu, pokud instance neexistuje.

Následující metody jsou k dispozici u obou 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.info()).

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

Částečně aktualizuje konfiguraci instance. Upraví se pouze pole, která zadáte.

const updated = await env.AI_SEARCH.get("my-instance").update({
	ai_search_model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
	reranking: true,
});

Přijímá částečnou verzi parametry pro vytvoření. Aktualizují se jen pole, která uvedete.

Vrátí aktualizovanou konfiguraci instance. Má stejný tvar jako info().

Vrátí aktuální konfiguraci a metadata instance.

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

Vrátí aktuální průběh indexování instance. Použijte to k dotazování na dokončení po vytvoření instance nebo nahrání souborů.

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

Lokální vývoj je podporován přeposíláním požadavků na vaši nasazenou instanci AI Search. Přidejte remote: true do konfigurace vazby, a povolíte tak lokální vývoj s wrangler dev.

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