相关性提升

提升（boosting）可让你使搜索结果偏向具有特定元数据特征的文档。例如，你可以提升较新的文档、优先展示高优先级页面，或降低草稿的优先级。提升会在不取代语义相关性的情况下重新排序结果。

提升在初始检索步骤之后、重排序（reranking）（若已启用）之前应用：

1. 搜索：AI Search 使用向量搜索、关键词搜索或两者检索最多 50 个候选分块。
2. 提升：使用你在 boost_by 中指定的元数据字段对每个候选重新打分。提升会叠加到原始检索分数上。
3. 重排序：若启用了重排序，提升后的结果会由重排序模型再次排序。
4. 返回：返回前 max_num_results 个结果。

提升可以改变候选集内的结果顺序，但无法提升初始搜索步骤未检索到的分块。

你可以按内置的 timestamp 字段，或按自定义元数据 schema 中定义的任意字段进行提升。

方向控制字段值如何影响每个结果的排名：

如果省略 direction，AI Search 会根据字段类型应用默认值：

对 text 或 boolean 字段使用 asc 或 desc 会返回错误。

在创建或更新实例时，将 boost_by 指定为最多 3 个对象的数组。每个对象必须引用唯一字段。

const instance = await env.AI_SEARCH.create({
	id: "my-instance",
	retrieval_options: {
		boost_by: [
			{ field: "timestamp", direction: "desc" },
			{ field: "priority", direction: "desc" },
		],
	},
});

要移除提升，在更新实例时将 boost_by 设为空数组。

你可以使用 ai_search_options.retrieval 在单个请求上覆盖 boost_by。按请求的值会完全替换实例级默认值。

const instance = env.AI_SEARCH.get("my-instance");

const results = await instance.search({
	messages: [{ role: "user", content: "What is Cloudflare?" }],
	ai_search_options: {
		retrieval: {
			boost_by: [{ field: "timestamp", direction: "desc" }],
		},
	},
});

要为单个请求禁用提升，传入空数组：

const results = await instance.search({
	messages: [{ role: "user", content: "What is Cloudflare?" }],
	ai_search_options: {
		retrieval: {
			boost_by: [],
		},
	},
});

以下是一些使用相关性提升的常见方式：

• 每个请求最多 3 个提升字段。
• 字段名必须匹配自定义元数据 schema 中的字段或内置 timestamp 字段。
• text 与 boolean 字段仅支持 exists 与 not_exists 方向。
• 单个请求中的提升字段必须唯一。
• 提升会对初始搜索的候选集重新排序。它无法展示未被检索到的文档。