INTEGRITY Dokumentace

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

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 vyhledávání a chatování s instancemi AI Search z Cloudflare Workeru.

Nakonfigurujte binding

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

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"
Pole Typ Povinné Popis
binding string Ano Název proměnné dostupné na env. Například "AI_SEARCH" jej zpřístupňuje jako env.AI_SEARCH.
namespace string Ano namespace ke kterému se má vytvořit vazba. Namespace default namespace se automaticky vytvoří pro každý účet. Pokud namespace neexistuje, Wrangler jej při nasazení vytvoří.
remote boolean Ne Nastavte na true pro lokální vývoj s wrangler dev.

Vazba instance

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"
Pole Typ Povinné Popis
binding string Ano Název proměnné dostupné na env. Například "MY_SEARCH" jej zpřístupňuje jako env.MY_SEARCH.
instance_name string Ano Název instance AI Search. Musí existovat ve výchozím namespace v době nasazení.
remote boolean Ne Nastavte na true pro lokální vývoj s wrangler dev.

Metody instance

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.search()).

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

Vyhledejte relevantní chunky obsahu ve svém indexovaném zdroji dat. Vrátí ohodnocené chunky se zdrojovými odkazy.

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

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

Parametry

messages array povinné

Pole objektů zpráv reprezentujících konverzaci. Každá zpráva má role a content .

query string volitelné

Jednoduchý textový řetězec dotazu. Alternativa k messages. Zadejte buď query nebo messages, ne obojí.

ai_search_options object volitelné

Možnosti konfigurace operace vyhledávání.

Odpověď

Odpověď obsahuje následující položky:

Pole Typ Popis
search_query string Dotaz použitý pro vyhledávání, který může být přepsaný, pokud je povoleno přepisování dotazu.
chunks array Pole odpovídajících částí obsahu.
chunks[].id string Jedinečný identifikátor části obsahu.
chunks[].type string Typ obsahu, obvykle text.
chunks[].score number Celkové skóre shody mezi 0 a 1.
chunks[].text string Textový obsah dané části.
chunks[].item objekt Informace o zdrojové položce.
chunks[].item.key string Cesta k souboru nebo URL adresa zdrojového dokumentu.
chunks[].item.timestamp number Časové razítko Unix poslední úpravy položky.
chunks[].item.metadata objekt Vlastní metadata přiřazená ke zdrojové položce.
chunks[].scoring_details objekt Rozpis toho, jak bylo vypočítáno skóre dané části obsahu.
chunks[].scoring_details.vector_score number Skóre sémantické podobnosti (0 až 1).
chunks[].scoring_details.keyword_score number Skóre shody klíčových slov (BM25). Je přítomno při použití hybridního nebo klíčového vyhledávání.
chunks[].scoring_details.keyword_rank number Pozice v pořadí podle klíčových slov.
chunks[].scoring_details.vector_rank number Pořadí podle vektorového vyhledávání.
chunks[].scoring_details.reranking_score number Skóre rerankingu (0 až 1). Přítomno, pokud je povolený reranking.
chunks[].scoring_details.fusion_method string Použitá metoda fúze (rrf nebo max). Přítomno při použití hybridního vyhledávání.

chatCompletions()

Generujte chat completions s vaší instancí AI Search jako kontextem. Tato metoda načte relevantní obsah a použije ho k vygenerování odpovědi.

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

Streamování odpovědí

Nastavte stream: true a přijímat tak odpovědi jako Server-Sent Events (SSE) v okamžiku jejich generování:

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

Když stream je povoleno, metoda vrací ReadableStream SSE událostí. Každá událost obsahuje objekt JSON s choices[0].delta.content pro přírůstkový text. Stream končí data: [DONE] událost.

Parametry

messages array povinné

Pole objektů zpráv reprezentujících konverzaci. Každá zpráva má role a content .

model string volitelné

Model pro generování textu použitý ke generování odpovědí. Výchozí hodnota odpovídá generačnímu modelu nakonfigurovanému v nastavení instance AI Search. Seznam podporovaných modelů najdete v Podporované modely.

stream boolean volitelné

Vrátí proud výsledků, jakmile jsou vygenerovány. Pokud je povoleno, vrátí Response objekt s čitelným streamem. Výchozí hodnota je false.

ai_search_options object volitelné

Možnosti konfigurace operace vyhledávání a generování.

Odpověď (bez streamování)

Pole Typ Popis
id string Jedinečný identifikátor dokončení.
object string Vždy chat.completion.
created number Časové razítko Unix vytvoření dokončení.
model string Model použitý k vygenerování odpovědi.
choices array Pole možností dokončení.
choices[].message.role string Vždy assistant.
choices[].message.content string Text vygenerované odpovědi.
choices[].finish_reason string Důvod, proč model přestal generovat. Obvykle stop.
usage.prompt_tokens number Počet tokenů v promptu.
usage.completion_tokens number Počet tokenů ve vygenerované odpovědi.
usage.total_tokens number Celkový počet použitých tokenů.
chunks array Zdrojové části obsahu použité jako kontext. Stejný formát jako odpověď vyhledávání.

Odpověď (streamovaná)

Když stream: true, metoda vrátí ReadableStream Server-Sent Events. Získané chunky se odesílají nejprve jako chunks událost, po které následuje streamovaná odpověď.

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]

Metody jmenného prostoru

Následující metody jsou k dispozici pouze při použití ai_search_namespaces vazba. Prohledávejte a chatujte napříč více instancemi v jediném volání přímo pomocí handle jmenného prostoru (env.AI_SEARCH).

search()

Předejte instance_ids v ai_search_options a určit tak, které instance se mají dotazovat. Výsledky se sloučí a seřadí a každý chunk obsahuje pole instance_id je pole, které určuje, ze které instance pochází.

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

Parametry

Stejné jako vyhledávání na úrovni instance, s jedním dalším povinným polem:

Parametr Typ Povinné Popis
ai_search_options objekt Ano Vyžadováno pro vyhledávání na úrovni jmenného prostoru.
ai_search_options.instance_ids array Ano ID instancí, ve kterých se má vyhledávat. Minimálně 1, maximálně 10.

Odpověď

Stejné jako vyhledávání na úrovni instance, s dalšími poli:

Pole Typ Popis
chunks[].instance_id string Instance, ze které tato část obsahu pochází.
errors array Chyby jednotlivých instancí, pokud některé z instancí selhaly. Každý objekt obsahuje instance_id a message.

chatCompletions()

Generujte chat completions s kontextem načteným z více instancí.

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

Streamování je podporováno s stream: true.

Parametry

Stejné jako chat completions na úrovni instance, s jedním dalším povinným polem:

Parametr Typ Povinné Popis
ai_search_options objekt Ano Vyžadováno pro chat completions na úrovni jmenného prostoru.
ai_search_options.instance_ids array Ano ID instancí, ve kterých se má vyhledávat. Minimálně 1, maximálně 10.

Odpověď

Stejné jako chat completions na úrovni instance, s dalšími poli u každé části obsahu:

Pole Typ Popis
chunks[].instance_id string Instance, ze které tato část obsahu pochází.
errors array Chyby jednotlivých instancí, pokud některé z instancí selhaly. Každý objekt obsahuje instance_id a message.

Lokální vývoj

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,
		},
	],
}