命名空间 · Cloudflare AI Search docs

每个 AI Search 实例都属于一个 命名空间。命名空间是账户内实例的逻辑分组。

Tenant A Tenant B Tenant C

env.AI_SEARCH.get(id)Worker

namespace: tenants

AI Search instancetenant-a AI Search instancetenant-b AI Search instancetenant-c

为何使用命名空间

使用命名空间的常见原因包括：

域隔离：按产品领域分离实例，例如 blog、support 与 docs。
租户隔离：为每个租户分配独立命名空间，避免实例名称在租户之间冲突。
智能体隔离：为每个智能体分配独立命名空间，以便独立管理上下文。

有关按租户隔离搜索的分步指南，请参阅多租户。

要求

命名空间绑定（binding）需要以下最低包版本，以支持 TypeScript 类型与本地开发。

包	最低版本
`@cloudflare/workers-types`	`4.20260304.0`
`wrangler`	`4.68.1`

命名空间如何工作

当你在 Wrangler 配置中添加 ai_search_namespaces 绑定（binding）时，需要指定该绑定可访问的命名空间。该绑定授予对该命名空间内所有实例的完全访问权限。你可以在运行时获取、列出、创建与删除实例。

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "ai_search_namespaces": [
    {
      "binding": "AI_SEARCH",
      "namespace": "my-namespace"
    }
  ]
}

[[ai_search_namespaces]]
binding = "AI_SEARCH"
namespace = "my-namespace"

在运行时，env.AI_SEARCH 是命名空间句柄。使用 env.AI_SEARCH.get("my-instance") 获取特定实例的句柄：

const instance = env.AI_SEARCH.get("my-instance");
const results = await instance.search({
	messages: [{ role: "user", content: "How does caching work?" }],
});

get() 方法是同步的，不会发起网络调用。实例会在你调用 search() 或 chatCompletions() 等方法时延迟解析。

默认命名空间

每个账户都会自动创建 default 命名空间。如果不需要多个命名空间，请对所有实例使用 default。

你也可以使用 ai_search 绑定（binding）直接绑定到默认命名空间中的特定实例。这会将每个条目绑定到单个已有实例，而无需调用 get()。

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "ai_search": [
    {
      "binding": "PROD_SEARCH",
      "instance_name": "production"
    },
    {
      "binding": "STAGING_SEARCH",
      "instance_name": "staging"
    }
  ]
}

[[ai_search]]
binding = "PROD_SEARCH"
instance_name = "production"

[[ai_search]]
binding = "STAGING_SEARCH"
instance_name = "staging"

ai_search 绑定（binding）提供相同的实例方法（search()、chatCompletions()、info()、stats()、items），但不支持 list()、create() 或 delete() 等命名空间级操作。

多个命名空间

你可以在同一个 Worker 中声明多个命名空间绑定（binding）。每个绑定映射到不同的命名空间，并对其实例提供隔离访问。

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "ai_search_namespaces": [
    {
      "binding": "BLOG_SEARCH",
      "namespace": "blog"
    },
    {
      "binding": "SUPPORT_SEARCH",
      "namespace": "support"
    }
  ]
}

[[ai_search_namespaces]]
binding = "BLOG_SEARCH"
namespace = "blog"

[[ai_search_namespaces]]
binding = "SUPPORT_SEARCH"
namespace = "support"

命名空间与实例唯一性

实例名称必须在命名空间内唯一。这意味着你可以在 blog 与 support 命名空间中都有一个名为 docs 的实例，而不会冲突。