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

公共端点

最后更新 查看 MarkdownAgent 设置

AI Search 公共端点允许你在无需认证的情况下暴露 AI Search 能力。这样你可以将 AI Search 集成到面向公众的应用中,或与外部用户共享。

有关可使用公共端点嵌入到网站上的预构建搜索与聊天组件,请参阅 UI snippets。

前提条件

为你的 AI Search 实例启用公共端点:

  1. 在 Cloudflare 仪表板中前往 AI Search。 前往 AI Search ↗
  2. 选择你的 AI Search 实例。
  3. 前往 Settings(设置) > Public Endpoint(公共端点)。
  4. 打开 Enable Public Endpoint(启用公共端点)。
  5. 复制公共端点 URL。

有关速率限制与 CORS 等配置选项,请参阅 公共端点配置。

端点主机名

你可以在单个实例或整个 namespace 上启用公共端点。namespace 端点提供相同的三条路径,并会在该 namespace 中你允许的实例之间搜索,然后合并结果。

启用端点时,Cloudflare 会生成主机名:

主机名 说明
<PUBLIC_ENDPOINT_ID>.search.ai.cloudflare.com 服务于单个实例。
ns-<NAMESPACE_ENDPOINT_ID>.search.ai.cloudflare.com 服务于 namespace,并在多个实例之间搜索。

两种端点的请求与响应格式相同。本页示例使用实例主机名。

使用自有域名

你可以用自己拥有的主机名提供相同的端点,例如 search.example.com,而不使用生成的主机名:

https://search.example.com/search
https://search.example.com/chat/completions
https://search.example.com/mcp

该主机名必须属于同一 Cloudflare 账户中的 zone。要附加自定义域名:

  1. 在 Cloudflare 仪表板中前往 AI Search。 前往 AI Search ↗
  2. 选择你的实例或 namespace。
  3. 前往 Public Endpoints(公共端点) 并启用公共端点。自定义域名需要已启用的公共端点。
  4. 前往 Custom Domains(自定义域名) 并附加你的主机名。

自定义域名会通过你自己的 zone 路由请求,因此你还可以在端点前放置 Cloudflare Access,要求调用方先通过身份验证再到达 AI Search。Access 只保护自定义主机名,因此请同时将 default_domain_enabled 设为 false。否则默认的 <PUBLIC_ENDPOINT_ID>.search.ai.cloudflare.com 主机名会继续响应未经身份验证的请求。

要通过 API 附加域名,请参阅 自定义域名。

聊天补全

/chat/completions 端点会搜索你的数据源,并使用模型与检索到的上下文生成响应。它使用与 REST API 相同的 OpenAI 兼容格式。

curl https://<PUBLIC_ENDPOINT_ID>.search.ai.cloudflare.com/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "content": "How do I configure AI Search?",
        "role": "user"
      }
    ]
  }'

完整选项列表请参阅 Chat Completions API 参考。

搜索

/search 端点会从你的数据源返回相关分块,而不生成响应。它使用与 REST API 相同的格式。

curl https://<PUBLIC_ENDPOINT_ID>.search.ai.cloudflare.com/search \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "content": "How do I configure AI Search?",
        "role": "user"
      }
    ]
  }'

完整选项列表请参阅 Search API 参考。

图像查询

将 messages[].content 设为包含 image_url 部分的数组。URL 必须使用 HTTPS,或内联的 data:image/<subtype>;base64,... URI。

curl https://<PUBLIC_ENDPOINT_ID>.search.ai.cloudflare.com/search \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{
      "role": "user",
      "content": [{
        "type": "image_url",
        "image_url": { "url": "https://example.com/product.png" }
      }]
    }]
  }'

响应中的 query_kind 为 image。仅包含图像的响应会省略 search_query。添加 text 部分可构成多模态查询。原生图像嵌入需要 @cf/qwen/qwen3-vl-embedding-2b 或 google-ai-studio/gemini-embedding-2。仅文本嵌入模型会先为图像生成说明,再进行嵌入。

后续步骤

  • UI snippets - 向网站添加预构建的搜索与聊天组件。
  • MCP - 使用 Model Context Protocol 连接 AI 智能体。
  • 公共端点配置 - 配置速率限制、CORS 与安全设置。
  • 自定义域名 - 用你拥有的主机名提供这些端点。
  • Cloudflare Access - 要求调用方先通过身份验证再访问这些端点。

这篇文档对您有帮助吗?