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

REST API

最后更新 查看 MarkdownAgent 设置

使用 AI Search REST API,可通过 HTTP 查询你的 AI Search 实例。

认证

所有请求都需要具有 AI Search:Edit 和 AI Search:Run 权限的 API token。

  1. 在 Cloudflare 仪表板中,前往 My Profile(我的个人资料) > API Tokens(API 令牌)。

    前往 API Tokens(API 令牌) ↗
  2. 选择 Create Token(创建令牌)。

  3. 选择 Create Custom Token(创建自定义令牌)。

  4. 输入 Token name(令牌名称),例如 AI Search Manager。

  5. 在 Permissions(权限) 下,添加两项权限:

    • Account > AI Search:Edit
    • Account > AI Search:Run
  6. 选择 Continue to summary(继续查看摘要),然后选择 Create Token(创建令牌)。

  7. 复制并保存 token 值。这就是你的 API_TOKEN。

在所有请求的 Authorization header 中包含该 token:

Authorization: Bearer <API_TOKEN>

搜索与 chat

AI Search 提供两个用于查询实例的 API。二者均使用与 OpenAI 兼容的 messages 格式。

  • Search(搜索) 返回相关内容分块(chunks)。当你希望自行处理生成或直接展示结果时使用。
  • 聊天补全(Chat completions) 在一次调用中检索内容并生成响应。

API 路径

搜索与聊天 API 限定在 namespace 范围内:

路径 说明
/accounts/{account_id}/ai-search/namespaces/{namespace}/instances/{id}/ 针对 namespace 内的特定实例操作

每个账户都有一个 default namespace。除非你创建了自定义 namespace,否则请使用 default。完整规范请参阅 Namespace API 参考。

搜索特定实例。search 端点也接受 query 字符串参数。完整规范请参阅 Search API 参考。

curl -X POST "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/namespaces/default/instances/<INSTANCE_NAME>/search" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "content": "What is Cloudflare?",
        "role": "user"
      }
    ]
  }'

聊天补全

从特定实例生成响应。完整规范请参阅 聊天补全 API 参考。

curl -X POST "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/namespaces/default/instances/<INSTANCE_NAME>/chat/completions" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "content": "What is Cloudflare?",
        "role": "user"
      }
    ]
  }'

图像查询

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

curl -X POST "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/namespaces/default/instances/<INSTANCE_NAME>/search" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -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。仅文本嵌入模型会先为图像生成说明,再进行嵌入。

流式传输

将 stream 设为 true,以 Server-Sent Events(SSE)形式接收响应。检索到的 chunks 会先作为 chunks 事件发送,随后是流式响应。

event: chunks
data: [{"id":"chunk-001","type":"text","score":0.85,"text":"...","item":{"key":"about-cloudflare.md","timestamp":1775925540000},"scoring_details":{"vector_score":0.85}}]

data: {"id":"id-1776072781845","created":1776072781,"model":"@cf/meta/llama-3.3-70b-instruct-fp8-fast","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":" document"}}]}

data: {"id":"id-1776072781845","created":1776072781,"model":"@cf/meta/llama-3.3-70b-instruct-fp8-fast","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":" you provided doesn"}}]}

data: {"id":"id-1776072781845","created":1776072781,"model":"@cf/meta/llama-3.3-70b-instruct-fp8-fast","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"'t contain"}}]}

data: {"id":"id-1776072781845","created":1776072781,"model":"@cf/meta/llama-3.3-70b-instruct-fp8-fast","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":" information"}}]}

data: [DONE]

跨实例搜索与 chat

search 与 chat completions API 也可在 namespace 级别使用。其工作方式与实例端点相同,但需传入 instance_ids 数组以指定要查询的实例。响应中的每个 chunk 都包含 instance_id 字段,标识其来源实例。完整规范请参阅 Namespace API 参考。

curl -X POST "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/namespaces/<NAMESPACE>/search" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What is Cloudflare?"
      }
    ],
    "ai_search_options": {
      "instance_ids": ["product-docs", "customer-abc123"]
    }
  }'

这篇文档对您有帮助吗?