Workers binding

import { Render, MetaInfo, Type } from "~/components";

Workers provides a serverless execution environment that allows you to create new applications or augment existing ones. Use a Workers binding to search and chat with your AI Search instances from a Cloudflare Worker.

Configure the binding

Instance methods

The following methods are available on both the ai_search_namespaces and ai_search bindings. With the namespace binding, call methods on the handle returned by get(). With the instance binding, call methods directly on the binding (for example, env.MY_SEARCH.search()).

The examples below use the namespace binding.

search()

Search for relevant content chunks from your indexed data source. Returns scored chunks with source references.

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

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

Parameters

The Workers binding accepts string values for messages[].content. To send image or file content parts, use the REST API or a public endpoint.

Response

chatCompletions()

Generate chat completions using your AI Search instance as context. This method retrieves relevant content and uses it to generate a response.

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 responses

Set stream: true to receive responses as Server-Sent Events (SSE) as they are generated:

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

When stream is enabled, the method returns a ReadableStream of SSE events. Each event contains a JSON object with choices[0].delta.content for incremental text. The stream ends with a data: [DONE] event.

Parameters

Response (non-streaming)

Response (streaming)

When stream: true, the method returns a ReadableStream of Server-Sent Events. The retrieved chunks are sent first as a chunks event, followed by the streamed response.

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]

Namespace methods

The following methods are only available when using the ai_search_namespaces binding. Search and chat across multiple instances in a single call using the namespace handle directly (env.AI_SEARCH).

search()

Pass instance_ids in ai_search_options to specify which instances to query. Results are merged and ranked, and each chunk includes an instance_id field identifying which instance it came from.

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

Parameters

Same as instance-level search, with one additional required field:

Response

Same as instance-level search, with additional fields:

chatCompletions()

Generate chat completions using context retrieved from multiple instances.

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

Streaming is supported with stream: true.

Parameters

Same as instance-level chat completions, with one additional required field:

Response

Same as instance-level chat completions, with additional fields on each chunk:

Local development

Local development is supported by proxying requests to your deployed AI Search instance. Add remote: true to your binding configuration to enable local development with wrangler dev.

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