diff --git a/src/components/AiSearchIndexingDiagram.astro b/src/components/AiSearchIndexingDiagram.astro new file mode 100644 index 00000000000..1104446eaf1 --- /dev/null +++ b/src/components/AiSearchIndexingDiagram.astro @@ -0,0 +1,893 @@ +--- +import { Icon as AstroIcon } from "astro-icon/components"; + +interface Props { + autoPlay?: boolean; + loop?: boolean; + keyword?: boolean; +} + +const { autoPlay = true, loop = true, keyword = true } = Astro.props; +--- + +
+ +
+ + + + Your content + e.g. PDF, image + + + +
+ +
+ source + + + + + +
+ + + Data source + Optional + + + + R2 bucket + + + + + Data source · Browser Run + Optional + + + + Website + + +
+ + + + + + + AI Search · R2 + + + Built-in storage + + + +
+
+ + +
+ + + + Workers AI · toMarkdown() + + + Parsing + + + +
+ + + + AI Search + + + Chunking + + + + { + keyword ? ( + <> + {/* Line into the "index & store" scope */} +
+ +
+ index & store + + {/* Split: chunks fan out to two parallel lanes */} + + +
+
+ + + AI Gateway / Workers AI + Optional + + + + Embedding + + +
+ + + AI Search · Vectorize + Optional + + + + Vector index + + +
+ +
+ + + AI Search + Optional + + + + Keyword tokenizer + + +
+ + + AI Search + Optional + + + + Inverted index + + +
+
+
+ + ) : ( + <> +
+ + AI Gateway / Workers AI + + + Embedding + + +
+ + AI Search · Vectorize + + + Vector index + + + + ) + } +
+ +
+ + + + diff --git a/src/components/AiSearchNamespacesDiagram.astro b/src/components/AiSearchNamespacesDiagram.astro new file mode 100644 index 00000000000..d4168c80af3 --- /dev/null +++ b/src/components/AiSearchNamespacesDiagram.astro @@ -0,0 +1,727 @@ +--- +import { Icon as AstroIcon } from "astro-icon/components"; + +interface Props { + autoPlay?: boolean; + loop?: boolean; +} + +const { autoPlay = true, loop = true } = Astro.props; +--- + +
+ +
+ +
+ + + Tenant A + + + + Tenant B + + + + Tenant C + +
+ + + + + + + env.AI_SEARCH.get(id) + + + Worker + + + + +
+ +
+ namespace: tenants + + + + + +
+ + AI Search instance + + + tenant-a + + + + AI Search instance + + + tenant-b + + + + AI Search instance + + + tenant-c + + +
+
+
+ +
+ + + + diff --git a/src/components/AiSearchOverviewDiagram.astro b/src/components/AiSearchOverviewDiagram.astro new file mode 100644 index 00000000000..5e35bb1867a --- /dev/null +++ b/src/components/AiSearchOverviewDiagram.astro @@ -0,0 +1,478 @@ +--- +import { Icon as AstroIcon } from "astro-icon/components"; + +interface Props { + autoPlay?: boolean; + loop?: boolean; +} + +const { autoPlay = true, loop = true } = Astro.props; +--- + +
+ +
+ + + + Upload or connect + + +
+ + +
+ AI Search +
+ + + Storage + + + + AI models + + + + Index + +
+
+ +
+ + + + + Search + +
+ +
+ + + + diff --git a/src/components/AiSearchQueryingDiagram.astro b/src/components/AiSearchQueryingDiagram.astro new file mode 100644 index 00000000000..349d1e3dd88 --- /dev/null +++ b/src/components/AiSearchQueryingDiagram.astro @@ -0,0 +1,853 @@ +--- +import { Icon as AstroIcon } from "astro-icon/components"; + +interface Props { + autoPlay?: boolean; + loop?: boolean; +} + +const { autoPlay = true, loop = true } = Astro.props; +--- + +
+ +
+ +
+ + Your query +
+ +
+ + + + + AI Gateway / Workers AI + Optional + + + + Query rewriting + + + + +
+ +
+ hybrid search + + + + + +
+ +
+ + + AI Gateway / Workers AI + Optional + + + + Query embedding + + +
+ + + AI Search · Vectorize + Optional + + + + Vector retrieval + + +
+ + +
+ + + AI Search + Optional + + + + Query tokenization + + +
+ + + AI Search · BM25 + Optional + + + + Keyword retrieval + + +
+
+ + + + + + + + AI Search + Optional + + + + Fusion + + + +
+
+ + +
+ + + + + AI Gateway / Workers AI + Optional + + + + Reranking + + + +
+ + + + AI Search · R2 + + + Chunk content retrieval + + + +
+ + + + + Search result + + + +
+ + + + AI Gateway / Workers AI + Optional + + + + Response generation + + + +
+ + + + + Chat Completions result + +
+ +
+ + + + diff --git a/src/components/index.ts b/src/components/index.ts index 97540562967..e4793d39c51 100644 --- a/src/components/index.ts +++ b/src/components/index.ts @@ -5,6 +5,10 @@ export { Icon as StarlightIcon } from "@astrojs/starlight/components"; export { Icon as AstroIcon } from "astro-icon/components"; // Custom components export { default as AnchorHeading } from "./AnchorHeading.astro"; +export { default as AiSearchIndexingDiagram } from "./AiSearchIndexingDiagram.astro"; +export { default as AiSearchNamespacesDiagram } from "./AiSearchNamespacesDiagram.astro"; +export { default as AiSearchOverviewDiagram } from "./AiSearchOverviewDiagram.astro"; +export { default as AiSearchQueryingDiagram } from "./AiSearchQueryingDiagram.astro"; export { default as AnimatedWorkflowDiagram } from "./AnimatedWorkflowDiagram.astro"; export { default as AgentsPlatformDiagram } from "./AgentsPlatformDiagram.astro"; export { default as APIRequest } from "./APIRequest.astro"; diff --git a/src/components/landing/BuildFromScratch.astro b/src/components/landing/BuildFromScratch.astro index 364136d4a4a..2a5d2371b7c 100644 --- a/src/components/landing/BuildFromScratch.astro +++ b/src/components/landing/BuildFromScratch.astro @@ -45,6 +45,7 @@ const primitives = [ tags: [ { label: "Workers AI", href: "/workers-ai/" }, { label: "AI Gateway", href: "/ai-gateway/" }, + { label: "AI Search", href: "/ai-search/" }, { label: "Agents", href: "/agents/" }, { label: "Vectorize", href: "/vectorize/" }, { label: "Browser Run", href: "/browser-run/" }, diff --git a/src/content/docs/ai-search/concepts/how-ai-search-works.mdx b/src/content/docs/ai-search/concepts/how-ai-search-works.mdx index 30abef41272..69a3d70ffb0 100644 --- a/src/content/docs/ai-search/concepts/how-ai-search-works.mdx +++ b/src/content/docs/ai-search/concepts/how-ai-search-works.mdx @@ -8,6 +8,8 @@ products: - ai-search --- +import { AiSearchIndexingDiagram, AiSearchQueryingDiagram } from "~/components"; + AI Search is a managed search service. Connect a website, an R2 bucket, or upload your own documents, and AI Search indexes your content for natural language queries. AI Search consists of two core processes: @@ -19,12 +21,12 @@ AI Search consists of two core processes: Indexing begins automatically when you connect a data source or upload files through the [Items API](/ai-search/api/items/workers-binding/). -![Indexing](~/assets/images/ai-search/indexing.png) + Here is what happens during indexing: 1. **Data ingestion:** AI Search reads from your connected data source or receives files uploaded through the [Items API](/ai-search/api/items/workers-binding/). -2. **Markdown conversion:** AI Search uses [Workers AI's Markdown Conversion](/workers-ai/features/markdown-conversion/) to convert [supported data types](/ai-search/configuration/data-source/) into structured Markdown. This ensures consistency across diverse file types. For images, Workers AI is used to perform object detection followed by vision-to-language transformation to convert images into Markdown text. +2. **Markdown conversion:** AI Search uses [Workers AI's Markdown Conversion](/workers-ai/features/markdown-conversion/) to convert [supported data types](/ai-search/configuration/data-source/) into structured Markdown. This ensures consistency across diverse file types. For images, Workers AI is used to perform object detection followed by vision-to-language transformation to convert images into Markdown text. Refer to [how images are converted](/workers-ai/features/markdown-conversion/how-it-works/#images) for details. 3. **Chunking:** The extracted text is [chunked](/ai-search/configuration/indexing/chunking/) into smaller pieces to improve retrieval granularity. 4. **Embedding:** Each chunk is embedded using Workers AI's embedding model to transform the content into vectors. 5. **Keyword indexing:** When keyword search is enabled, each chunk is also indexed for BM25 keyword matching. @@ -36,7 +38,7 @@ For instances with a connected data source, AI Search regularly checks for updat Once indexing is complete, AI Search is ready to respond to end-user queries in real time. -![Querying](~/assets/images/ai-search/querying.png) + Here is how the querying pipeline works: @@ -49,3 +51,17 @@ Here is how the querying pipeline works: 7. **Reranking (optional):** A cross-encoder model re-scores results by evaluating the query and document together. Refer to [Reranking](/ai-search/configuration/retrieval/reranking/) for details. 8. **Content retrieval:** The most relevant chunks and their source content are returned. If you are using the Search endpoint, the content is returned at this point. 9. **Response generation:** If you are using the Chat Completions endpoint, a text-generation model generates a response using the retrieved content. Refer to [System prompt](/ai-search/configuration/retrieval/system-prompt/) for details. + +## When to use AI Search vs. Vectorize + +AI Search is built on [Vectorize](/vectorize/) and adds the rest of the search pipeline around it. Use Vectorize when you want to manage vectors yourself, and AI Search when you want managed search over your content. + +| Capability | AI Search | Vectorize | +| ----------------------- | ---------------------------------------------------------- | ------------------------------------------------ | +| What it is | Managed, end-to-end search over your content | A vector database you build on | +| You give it | Files, or a connected data source | Vectors you generate yourself | +| Chunking and embeddings | Handled for you | You generate and insert them | +| Indexing | Automatic, with continuous sync | You upsert and manage vectors | +| Retrieval | Vector and keyword (hybrid), reranking, metadata filtering | Vector similarity search with metadata filtering | +| Generated answers | Optional, built in | Not included | +| Best when | You want to add search or RAG quickly | You need full control of the retrieval pipeline | diff --git a/src/content/docs/ai-search/concepts/namespaces.mdx b/src/content/docs/ai-search/concepts/namespaces.mdx index 48e3e14628f..6d8d098c713 100644 --- a/src/content/docs/ai-search/concepts/namespaces.mdx +++ b/src/content/docs/ai-search/concepts/namespaces.mdx @@ -8,10 +8,20 @@ products: - ai-search --- -import { WranglerConfig } from "~/components"; +import { AiSearchNamespacesDiagram, WranglerConfig } from "~/components"; Every AI Search instance belongs to a **namespace**. A namespace is a logical grouping of instances within your account. + + +## Why use namespaces + +Common reasons to use namespaces include: + +- **Domain separation**: Separate instances by product area, for example `blog`, `support`, and `docs`. +- **Tenant isolation**: Assign each tenant their own namespace so that instance names do not collide across tenants. +- **Agent isolation**: Give each agent its own namespace for independent context management. + ## Requirements The namespace binding requires the following minimum package versions for TypeScript types and local development support. @@ -86,12 +96,6 @@ namespace = "support" -### Common reasons to use multiple namespaces - -- **Domain separation**: Separate instances by product area, for example `blog`, `support`, and `docs`. -- **Tenant isolation**: Assign each tenant their own namespace so that instance names do not collide across tenants. -- **Agent isolation**: Give each agent its own namespace for independent context management. - ## Namespaces and instance uniqueness An instance name must be unique within a namespace. This means you can have an instance named `docs` in both the `blog` and `support` namespaces without conflict. diff --git a/src/content/docs/ai-search/configuration/index.mdx b/src/content/docs/ai-search/configuration/index.mdx index a67bd862bca..11266015ddd 100644 --- a/src/content/docs/ai-search/configuration/index.mdx +++ b/src/content/docs/ai-search/configuration/index.mdx @@ -53,3 +53,4 @@ You can customize how your AI Search instance indexes your data, retrieves resul | [Generation model](/ai-search/configuration/models/) | yes | Model used to generate the final response | | [Query rewriting model](/ai-search/configuration/models/) | yes | Model used for query rewriting | | [Reranking model](/ai-search/configuration/models/) | yes | Model used to reorder results by semantic relevance | +| [AI Gateway](/ai-search/configuration/models/ai-gateway/) | yes | Observe and control the model calls AI Search makes | diff --git a/src/content/docs/ai-search/configuration/models/ai-gateway.mdx b/src/content/docs/ai-search/configuration/models/ai-gateway.mdx new file mode 100644 index 00000000000..bad1c8c73f1 --- /dev/null +++ b/src/content/docs/ai-search/configuration/models/ai-gateway.mdx @@ -0,0 +1,43 @@ +--- +pcx_content_type: concept +title: AI Gateway +description: Observe and control the AI models your AI Search instance uses through the connected AI Gateway. +sidebar: + order: 3 +products: + - ai-search +--- + +Every AI Search instance is connected to a Cloudflare [AI Gateway](/ai-gateway/). The model calls that AI Search makes for embedding, query rewriting, reranking, and response generation run through this gateway. By configuring the connected gateway, you can observe and control those model calls. + +To choose or change which gateway your instance uses, see [Models](/ai-search/configuration/models/). + +## Observe your model calls + +AI Gateway records the model requests that run through it, so you can see what your instance is doing. + +- **[Analytics](/ai-gateway/observability/analytics/):** Track the number of requests, tokens used, cost, latency, and errors across your model calls. +- **[Logs](/ai-gateway/observability/logging/):** Inspect individual requests and responses, including the effective [system prompt](/ai-search/configuration/retrieval/system-prompt/), rewritten queries, and generated answers. + +## Use models from other providers + +By default, AI Search uses [Workers AI](/workers-ai/) models. To use models from other providers, such as OpenAI or Anthropic, add your provider keys to AI Gateway and select those models in AI Search. + +1. Add your provider keys with [Bring Your Own Keys](/ai-gateway/configuration/bring-your-own-keys/). +2. Connect the gateway and select the models in your AI Search settings. For details, see [Models](/ai-search/configuration/models/). + +## Guard against unsafe content + +Use AI Gateway [Guardrails](/ai-gateway/features/guardrails/) to screen the prompts and responses that flow through your instance and block content that is unsafe or inappropriate. To detect and handle sensitive information, such as personal or financial data, use [Data Loss Prevention (DLP)](/ai-gateway/features/dlp/). + +## Improve resilience + +Configure [request retries and model fallbacks](/ai-gateway/configuration/fallbacks/) so that a model call can automatically retry or fall back to another model when a provider returns an error. + +## Caching and rate limiting + +Some AI Gateway features act on every request that passes through the gateway. Because your AI Search instance shares this gateway for its internal model calls, a few features can interfere with indexing and querying. + +Do not turn on [AI Gateway caching](/ai-gateway/features/caching/) for the gateway connected to your AI Search instance. This matters most for embedding requests. AI Search relies on fresh embeddings to build its vector index and to match each query against it, so serving cached embeddings can store or return incorrect vectors and quietly degrade the accuracy of your search results. To cache search results, use AI Search's own [Similarity cache](/ai-search/configuration/retrieval/cache/) instead. + +Similarly, avoid setting [rate limiting](/ai-gateway/features/rate-limiting/) on this gateway. Rate limits apply to AI Search's own model calls, including the many embedding requests made while indexing, and can interrupt indexing and querying. diff --git a/src/content/docs/ai-search/index.mdx b/src/content/docs/ai-search/index.mdx index e9d7f3e8964..1d0a1a35762 100644 --- a/src/content/docs/ai-search/index.mdx +++ b/src/content/docs/ai-search/index.mdx @@ -15,6 +15,7 @@ products: --- import { + AiSearchOverviewDiagram, CardGrid, Description, LinkTitleCard, @@ -32,6 +33,8 @@ import { AI Search lets you add search to any application or agent without having to build an entire retrieval infrastructure. Create an instance, give it your data, and search it with natural language. + + You can use AI Search for: - Documentation and knowledge base search diff --git a/src/nimbus/components/landing/BuildFromScratch.astro b/src/nimbus/components/landing/BuildFromScratch.astro index f8353ec3b28..28e05a15c38 100644 --- a/src/nimbus/components/landing/BuildFromScratch.astro +++ b/src/nimbus/components/landing/BuildFromScratch.astro @@ -44,6 +44,7 @@ const primitives = [ tags: [ { label: "Workers AI", href: "/workers-ai/" }, { label: "AI Gateway", href: "/ai-gateway/" }, + { label: "AI Search", href: "/ai-search/" }, { label: "Agents", href: "/agents/" }, { label: "Vectorize", href: "/vectorize/" }, { label: "Browser Run", href: "/browser-run/" },