namespace 可以暴露自己的公共端点。随后单个 URL 会在该 namespace 中的多个实例之间搜索并合并结果。当一次搜索体验覆盖分布在多个实例中的内容(例如文档、博客和支持门户)时,请使用它。
namespace 端点提供与实例端点相同的路径,并接受相同设置,包括 自定义域名 和 Cloudflare Access。请参阅 公共端点设置。本页介绍仅适用于 namespace 的内容。
在 namespace 上设置 public_endpoint_params,并在 instances_allowed 中列出要暴露的实例。
curl -X PUT "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/namespaces/<NAMESPACE>" \
-H "Authorization: Bearer <API_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"public_endpoint_params": {
"enabled": true,
"instances_allowed": ["docs", "blog", "support"]
}
}'响应会返回生成的 public_endpoint_id。namespace 主机名带有 ns- 前缀:
https://ns-<NAMESPACE_ENDPOINT_ID>.search.ai.cloudflare.com/search启用 namespace 端点不会更改其中的实例端点。每个实例端点都单独启用和禁用。
instances_allowed 控制端点可以到达哪些实例。
- 每个条目都必须是该 namespace 中已有的实例。未知条目会返回错误
7097。 - 列表最多包含 10 个实例。
- 空列表表示没有任何内容可搜索。这是你首次启用端点时 namespace 的初始状态。
- 删除实例或将其移到另一个 namespace 会将其从允许列表中移除。
解析后没有可搜索实例的请求会返回带有错误 60013 的 404。无论实例不存在、不在允许列表中,还是允许列表为空,该响应都相同,因此调用方无法发现 namespace 包含哪些实例。
默认情况下,请求会搜索允许列表中的每个实例。要缩小单次请求范围,请在请求体中设置 ai_search_options.instance_ids。
curl https://ns-<NAMESPACE_ENDPOINT_ID>.search.ai.cloudflare.com/search \
--header "Content-Type: application/json" \
--data '{
"messages": [
{
"content": "How do I configure AI Search?",
"role": "user"
}
],
"ai_search_options": {
"instance_ids": ["docs", "support"]
}
}'每个值都必须在允许列表中。该字段的规则:
- 省略该字段或将其设为
null会搜索整个允许列表。 - 格式错误的值(例如空数组或非字符串条目)会返回带有错误
60012的400。 - 允许列表之外的值会返回带有错误
60013的404。
将 public_endpoint_params 设为 null。这会清除配置并停止提供流量,但会保留标识符,以便你再次启用端点时复用 URL。
curl -X PUT "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/namespaces/<NAMESPACE>" \
-H "Authorization: Bearer <API_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"public_endpoint_params": null
}'| 代码 | 消息 | HTTP 状态 | 原因 |
|---|---|---|---|
7097 |
instances_allowed_contains_unknown_instances |
400 | instances_allowed 中的条目不是此 namespace 中的实例。 |
7099 |
namespace_modified_concurrently_please_retry |
409 | 另一次更新同时更改了 namespace。请重试。 |
60012 |
invalid ai_search_options.instance_ids |
400 | instance_ids 值格式错误。 |
60013 |
ai_search_not_found |
404 | 没有可搜索的实例匹配该请求。 |
60014 |
path not supported for namespace-kind hash |
404 | 路径不是 /search、/chat/completions 或 /mcp。 |
60015 |
request body must be a JSON object |
400 | 请求体不是 JSON 对象。 |
Namespaces
将实例分组到 namespace 中,并通过 Workers 绑定管理它们。
跨多个实例搜索
从 Worker 或 REST API 查询多个实例。
自定义域名
用你拥有的主机名提供 namespace 公共端点。