跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

Namespace 公共端点

最后更新 查看 MarkdownAgent 设置

namespace 可以暴露自己的公共端点。随后单个 URL 会在该 namespace 中的多个实例之间搜索并合并结果。当一次搜索体验覆盖分布在多个实例中的内容(例如文档、博客和支持门户)时,请使用它。

namespace 端点提供与实例端点相同的路径,并接受相同设置,包括 自定义域名 和 Cloudflare Access。请参阅 公共端点设置。本页介绍仅适用于 namespace 的内容。

启用 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。

禁用 namespace 公共端点

将 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 绑定管理它们。

这篇文档对您有帮助吗?