名前空間

すべての AI Search インスタンスは 名前空間 に属します。名前空間は、アカウント内のインスタンスの論理的なグループです。

名前空間を使う一般的な理由は次のとおりです。

• ドメインの分離: 製品領域ごとにインスタンスを分けます。例: blog、support、docs。
• テナントの分離: テナントごとに名前空間を割り当て、テナント間でインスタンス名が衝突しないようにします。
• エージェントの分離: エージェントごとに名前空間を与え、コンテキストを独立して管理します。

テナントごとに検索を分離する手順は、マルチテナンシー を参照してください。

名前空間バインディングには、TypeScript 型とローカル開発のサポート向けに、次の最小パッケージバージョンが必要です。

Wrangler 設定に ai_search_namespaces バインディングを追加すると、そのバインディングがアクセスできる名前空間を指定します。バインディングはその名前空間内のすべてのインスタンスへの完全なアクセスを付与します。実行時にインスタンスの取得、一覧、作成、削除ができます。

{
  "$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 バインディングで直接バインドすることもできます。各エントリは既存の 1 つのインスタンスにバインドされ、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 バインディングは同じインスタンスメソッド（search()、chatCompletions()、info()、stats()、items）を提供しますが、list()、create()、delete() などの名前空間レベルの操作には対応しません。

同じ Worker で複数の名前空間バインディングを宣言できます。各バインディングは別の名前空間に対応し、そのインスタンスへの分離されたアクセスを提供します。

{
  "$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"

名前空間は、独自の公開 /search、/chat/completions、/mcp エンドポイントを公開できます。1 つの URL で、その名前空間内の選んだインスタンスを横断検索し、結果をマージします。

名前空間の公開エンドポイント を参照してください。

インスタンス名は名前空間内で一意である必要があります。つまり、blog と support の両方の名前空間に docs という名前のインスタンスを置いても衝突しません。