REST API 迁移

AutoRAG API 端点是 AI Search 的旧版 REST API。它们将继续可用，但所有新功能和改进仅通过新的 AI Search API 端点提供。

端点变更

旧版 AutoRAG API 端点位于 /autorag/rags/ 下，已被 /ai-search/instances/ 下的新端点取代。

描述	新端点	参考
Chat completions	`/ai-search/instances/{name}/chat/completions`	API 参考
Search	`/ai-search/instances/{name}/search`	API 参考

新 API 还包含旧版 API 中不可用的实例管理、items 和 namespace 级搜索端点。有关旧版端点，请参阅 AutoRAG API 参考。

API token 权限

旧版 AutoRAG 端点使用 AutoRAG API token 权限。新的 AI Search 端点改为需要 AI Search 权限，因此请更新你用于调用 API 的 token 权限。我们建议使用账户 API token，其归账户而非单个用户所有，并添加位于 AI & Machine Learning（AI 与机器学习） > AI Search 下的 AI Search 权限。

创建新 token

在 Cloudflare 仪表板中，前往 Manage Account（管理账户） > API Tokens（API 令牌）。
选择 Create Token（创建令牌），然后开始自定义 token。
输入 token 名称。
添加权限策略，选择 AI & Machine Learning（AI 与机器学习） > AI Search，然后选择所需的访问级别。AI Search 提供 Read（读取）、Run（运行） 和 Edit（编辑） 访问。
（可选）设置客户端 IP 地址过滤和 token 过期时间。
创建 token 并复制其值。

编辑现有 token

在 Cloudflare 仪表板中，前往 Manage Account（管理账户） > API Tokens（API 令牌）。
选择要更新的 token。
添加或更新权限策略，以包含 AI & Machine Learning（AI 与机器学习） > AI Search 及所需访问级别，然后保存。

完整的 token 创建流程请参阅创建 API token。

聊天补全

如何从 AutoRAG /ai-search 端点迁移到新的 /chat/completions 端点：

之前（AutoRAG API）：

curl -X POST "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/autorag/rags/<INSTANCE_NAME>/ai-search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -d '{
    "query": "What is Cloudflare?"
  }'

之后（AI Search API）：

新 API 使用 messages 数组格式。

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

Search

如何从 AutoRAG /search 端点迁移到新的 /search 端点：

之前（AutoRAG API）：

curl -X POST "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/autorag/rags/<INSTANCE_NAME>/search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -d '{
    "query": "What is Cloudflare?"
  }'

之后（AI Search API）：

新 API 使用 messages 数组格式。也支持 query 字符串格式。

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

流式行为变更

在旧版 AutoRAG API 中，当 stream 设为 true 时，你只会收到流式响应，而不包含检索到的内容块。

在新的 AI Search API 中，流式响应包含内容块。检索到的内容块会先作为 chunks 事件发送，随后是流式响应数据。这样你可以立即显示源内容块，同时将生成的响应流式传输给用户。

过滤器格式

新的 AI Search REST API 使用类似 Vectorize 的元数据过滤方式，与 AutoRAG API 格式不同。过滤器现在嵌套在请求体的 ai_search_options.retrieval.filters 下。有关旧格式的完整文档，请参阅元数据过滤器格式（旧版）。

运算符映射

过滤器运算符已重命名为使用 $ 前缀：

AutoRAG API	AI Search API
`eq`	`$eq`（或隐式）
`ne`	`$ne`
`gt`	`$gt`
`gte`	`$gte`
`lt`	`$lt`
`lte`	`$lte`
	`$in`（新增）
	`$nin`（新增）

示例

简单过滤器

使用隐式相等按单个元数据字段过滤：

之前（AutoRAG API）：

{
	"filters": {
		"type": "eq",
		"key": "folder",
		"value": "customer-a/"
	}
}

之后（AI Search API）：

{
	"ai_search_options": {
		"retrieval": {
			"filters": { "folder": "customer-a/" }
		}
	}
}

复合过滤器（AND）

组合多个条件，全部必须匹配：

之前（AutoRAG API）：

{
	"filters": {
		"type": "and",
		"filters": [
			{ "type": "eq", "key": "folder", "value": "customer-a/" },
			{ "type": "gte", "key": "timestamp", "value": "1735689600000" }
		]
	}
}

之后（AI Search API）：

{
	"ai_search_options": {
		"retrieval": {
			"filters": {
				"folder": "customer-a/",
				"timestamp": { "$gte": 1735689600 }
			}
		}
	}
}