`$rerank`

重要

$rerank聚合阶段处于私有预览阶段。在预览期间，功能和相应的文档可能随时更改。因此，我们不建议在生产环境中使用此功能。要学习；了解详情，请参阅预览功能。

$rerank: $rerank阶段使用 Voyage AI 的重新排名模型对输入文档重新排序，并返回按与查询的相关性排序的相同文档。$rerank 阶段可以出现在聚合管道中的任何位置。我们建议您在$rerank $vectorSearch、$search 、$rankFusion 或$scoreFusion 阶段之后使用。

语法

$rerank管道阶段采用以下语法：

{
  "$rerank": {
    "query": {
      "text": "<query-text>"
    },
    "path": "<text-field-name>",
    "numDocsToRerank": <number-of-documents-to-rerank>,
    "model": "<reranker-model>"
  }
}

字段

$rerank 阶段采用包含以下字段的文档：

字段	类型	必要性	说明
`query`	对象	必需	用于重新排名的查询。
`query.` `text`	字符串	必需	用于重新排名的查询文本。示例，您可以指定：您正在搜索的内容文档的哪些字段最相关用于澄清歧义查询的补充信息
`path`	字符串或字符串数组	必需	用于重新排名的字段的路径。如果 `$rerank` 是中间阶段，请指定前一阶段结果中的字段。注意：如果 `$rerankpath`中指定的字段不存在，则查询将失败。使用先前的`$match` 阶段过滤掉缺少字段的文档，或使用`$set` 将缺失字段设立为`""` 。
`numDocsToRerank`	Int	必需	发送到 Voyage AI进行重新排名并在结果中返回的最大文档数。根据管道定义的文档顺序选择文档。最大值必须小于或等于 `1000`。
`model`	对象	必需	用于对文档重新排名的 Voyage AI模型。值可以是以下之一： `rerank-2.5` - 通过指令跟踪和多语言支持对质量进行了优化的 Generalist reranker。 `rerank-2.5-lite` - 通过指令跟踪和多语言支持，针对延迟和质量优化了 Generalist reranker。 `rerank-2` — 旧版模型。 `rerank-2-lite` — 旧版模型。

例子

以下示例演示了如何使用$rerank sample_mflix.embedded_movies阶段根据 Voyage AI重排序器模型对集合中的文档重新排序。查询在$rerank $match阶段之后使用，以使用rerank-2.5 重新排序器模型对文档重新排序。在以下聚合管道中：

$match 阶段筛选文档，以仅包含具有字符串类型的 plot字段的文档。
$sort 阶段按 released字段的降序对文档进行排序，以确保确定性的排序。
$rerank 阶段使用 rerank-2.5 重排序器模型对文档重新排序以匹配查询。
$addFields 阶段将名为 rerankScore 的字段添加到文档中。

1 db.embedded_movies.aggregate([
2   {
3     "$match": {
4       "plot": { "$exists": true, "$type": "string" }
5     }
6   },
7   {
8     "$sort": { "released": -1 }
9   },
10   {
11     "$rerank": {
12       "model": "rerank-2.5",
13       "query": {
14         "text": "a group of heroes band together to stop a powerful enemy and save the world"
15       },
16       "numDocsToRerank": 100,
17       "path": ["title", "plot"]
18     }
19   },
20   {
21     "$addFields": {
22       "rerankScore": { "$meta": "score" }
23     }
24   },
25   { "$limit": 10 },
26   {
27     "$project": {
28       "_id": 0,
29       "title": 1,
30       "plot": 1,
31       "rerankScore": 1
32     }
33   }
34 ])

[
  {
    plot: 'No treason, no surrender.',
    title: 'Ti mene nosis',
    rerankScore: 0.5986876487731934
  },
  {
    plot: 'The life of the greatest karate master of a generation.',
    title: 'The Real Miyagi',
    rerankScore: 0.5986876487731934
  },
  {
    plot: 'A shy genius is employed by his former university to design robot software.',
    title: 'Eva',
    rerankScore: 0.5986876487731934
  },
  {
    plot: 'The owners of a failing security company start robbing houses to boost business.',
    title: 'Armed Response',
    rerankScore: 0.5986876487731934
  },
  {
    plot: 'A live telecast of the beloved J. M. Barrie story.',
    title: 'Peter Pan Live!',
    rerankScore: 0.5986876487731934
  },
  {
    plot: "A French police magistrate spends years trying to take down one of the country's most powerful drug rings.",
    title: 'The Connection',
    rerankScore: 0.5986876487731934
  },
  {
    plot: 'A documentary that follows undercover activists trying to stave off a man-made mass extinction.',
    title: 'Racing Extinction',
    rerankScore: 0.5986876487731934
  },
  {
    plot: 'An ex-hitman comes out of retirement to track down the gangsters that took everything from him.',
    title: 'John Wick',
    rerankScore: 0.5986876487731934
  },
  {
    plot: 'A former hit-man for a drug cartel becomes a vigilante to pay for his sins and find redemption.',
    title: 'Redeemer',
    rerankScore: 0.5986876487731934
  },
  {
    plot: 'Charles Ingvar Jènsson gathers three criminals to take vengeance upon the people who killed his uncle.',
    title: 'The Master Plan',
    rerankScore: 0.5986876487731934
  }
]

Considerations

在使用 $rerank 之前，请考虑使用 $rerank 的兼容性、限制、行为和权限。

兼容性

$rerank阶段仅在运行MongoDB 或更高版本的MongoDB8.3 Atlas上可用。

在使用$rerank 之前，您必须通过Project Settings 启用原生重新排名。要学习；了解更多信息，请参阅启用或禁用项目的原生重排名。

限制

您不能使用 $rerank 阶段：

在$rankFusion 或$scoreFusion 输入管道中。
在视图定义上。

行为

$rerank可以出现在管道中的任何位置。但是，我们建议在已按排序顺序返回相关文档的$rerank $search或等阶段之后使用$vectorSearch 。

$rerank 重新排序并返回传递到此阶段的前 numDocsToRerank 个文档。如果 $rerank 是第一阶段，或者先前的阶段未返回确定性排序的结果，则用于 $rerank 的文档可能会在查询之间发生变化。

$rerank 如果path 中指定的任何字段不存在于一个或多个输入文档中，则会返回错误信息。为缓解此问题，请使用$set 阶段将缺失字段设立为空字符串。

查询

query.text字段确定重排序模型如何对每个文档进行评分。重排序器会在指定的 path 处计算查询文本与每个文档的内容之间的相关性分数。对于大多数使用案例，$rerank.query.text 应与前面的 $search 或 $vectorSearch 阶段的查询相同或相似。

衡量标准

以下指标可用于监控$rerank 的使用情况：

`$rerank` 查询状态率

$rerank查询成功率指标跟踪成功完成的 $rerank 查询的百分比。您可以在Atlas用户用户界面中集群的 Metrics标签页页上查看此指标。使用此指标来识别 $rerank 查询中的故障，例如速率限制错误或 Voyage AI的连接问题。

`$rerank` 令牌使用率

$rerank 令牌使用量指标跟踪 $rerank 查询消耗的令牌总数。您可以在Atlas用户用户界面中集群的 Metrics标签页页上查看此指标。使用此指标监控令牌消耗并将使用量与计费关联起来。

评分

使用score 变量和$meta 表达式检索$rerank 阶段结果中每个文档的分数。

示例：将重新排名分数添加到管道

{
  "$addFields": {
    "rerankScore": { "$meta": "score" }
  }
}

$rerank 阶段将 $meta: "score" 的值替换为新分数。要保留 $$rankFusion 等前一阶段的值，您可以在 $rerank 阶段之前将分数项目到命名字段中。

示例：保留前一阶段的分数

{
  "$addFields": {
    "originalRankFusionScore": { "$meta": "score" }
  }
},
{
  "$rerank": {
    ...
  }
},
{
  "$addFields": {
    "rerankScore": { "$meta": "score" }
  }
}

帐单

MongoDB采用即用即付的定价模式，并根据已处理的令牌总数收取使用费。以下公式计算总数：

total number of processed tokens = (# of query tokens * numDocsToRerank) + sum(# of tokens across all documents )

模型	Price per 1K tokens	Price per 1M tokens	免费令牌
`rerank-2.5`	$ 0.00005	$ 0.05	200,000,000
`rerank-2.5-lite`	$ 0.00002	$ 0.02	200,000,000
`rerank-2`	$ 0.00005	$ 0.05
`rerank-2-lite`	$ 0.00002	$ 0.02

$rerank 阶段与Atlas项目中的其他 Voyage AI操作分开收费。您可以通过Atlas 用户界面中的账单和付款界面管理付款和账单。在Atlas 用户界面中，您可以：

使用层级和速率限制

Atlas对您在特定时间范围内可以发出的请求数量实施速率限制，以每分钟令牌 (TPM) 或每分钟请求数 (RPM) 来衡量。速率限制采用分层系统，层级越高，限制越多。

层级	说明
免费层	无需付款信息。
1 层级	需要提供付款信息。速率限制是免费套餐的两倍。

模型	每分钟请求数 (RPM)	每分钟令牌数 (TPM)
`rerank-2.5`	2 , 000	2,000,000
`rerank-2.5-lite`	2 , 000	4,000,000
`rerank-2`	2 , 000	2,000,000
`rerank-2-lite`	2 , 000	4,000,000

模型	每分钟请求数 (RPM)	每分钟令牌数 (TPM)
`rerank-2.5`	4 , 000	4,000,000
`rerank-2.5-lite`	4 , 000	8,000,000
`rerank-2`	4 , 000	4,000,000
`rerank-2-lite`	4 , 000	8,000,000

Token Usage

Usage在Atlas 用户界面的页面监控令牌使用情况。使用量受到每个集群的每分钟请求数 (RPM) 和每分钟令牌数 (TPM) 的限制。要学习；了解更多信息，请参阅使用层级和速率限制。

Usage 页面提供了多个视图来监控和分析令牌使用情况。单击 Free Usage标签页可按型号查看组织的剩余免费令牌。

在 Usage Activity标签页中，Total Usage图表显示一段时间内整个项目使用的令牌总数。您可以使用以下选项过滤使用情况数据：

选项	说明
Usage Period	查看特定时间范围内的使用情况数据。
Models	按特定 Voyage AI模型进行筛选。

要学习；了解如何更精细地监控令牌使用情况，请参阅监控令牌使用情况。

资源策略

您可以在组织级别配置资源策略，以完全区块或例外情况下阻止$rerank 。为此，添加一条用forbid Cedar 编写的针对$rerank 动作的规则。如果配置此策略，新项目将无法启用$rerank 。但是，它不会禁用已启用的项目。对于已启用的项目，您必须单独禁用$rerank $rerank。要为项目禁用，请参阅为项目启用或禁用原生重排名。

您可以通过使用 forbid 规则中的 unless 子句来禁用 $rerank（例外情况）。

示例：禁用 $rerank，但有例外

forbid (principal, action == ResourcePolicy::Action::"$rerank", resource)
unless { <exception> };

要学习；了解有关设置资源策略的更多信息，请参阅Atlas资源策略。

步骤

您可以在Atlas用户界面中执行以下任务：

启用或禁用项目重新排名
监控重新排名使用情况
查看速率限制和使用情况
设置资源策略
查看指标

启用或禁用项目的原生重新排名

在使用 $rerank 阶段之前，您必须为项目启用重新排名。要启用重新排名，您必须执行以下操作：

导航到项目设置页面。

Organizations从导航栏的菜单中选择包含您的项目的组织。
从导航栏的 Projects（项目）菜单中选择项目。
单击侧边栏中的 Settings（支持）。

启用或禁用重新排名。

要启用重新排名，请执行以下操作：

在 Project Settings标签页中，将 Native Reranking: $rerank in the Aggregation Pipeline 开关设立为 On。
在 Confirm Rerank Model Usage窗口中，选中复选框以确认您了解与使用 $rerank 阶段相关的成本，然后单击 Confirm。

要禁用重新排名，请执行以下操作：

在 Project Settings标签页中，将 Native Reranking: $rerank in the Aggregation Pipeline 开关设立为 Off。
在 Disable Native Reranking 确认窗口中，键入 Disable 并单击 Disable。
禁用重新排名可能会导致使用 $rerank 阶段的查询运行失败。

监控令牌使用情况

在Atlas 用户界面的Usage 页面监控令牌使用情况。要查看使用情况：

导航至Search & Vector Search 页面。

Organizations从导航栏的菜单中选择包含您的项目的组织。
从导航栏的 Projects（项目）菜单中选择项目。
在侧边栏中，单击 Database 标题下的 Search & Vector Search。

UsageNative Reranking单击导航栏下的。

Usage页面提供了多个视图来监控和分析令牌使用情况。要学习；了解更多信息，请参阅令牌使用情况。

查看速率限制和使用情况

导航至Search & Vector Search 页面。

Organizations从导航栏的菜单中选择包含您的项目的组织。
从导航栏的 Projects（项目）菜单中选择项目。
在侧边栏中，单击 Database 标题下的 Search & Vector Search。

Rate LimitsNative Reranking单击导航栏下的。

Rate Limits 页面提供有关项目速率限制的信息以及如何提高速率限制的指导。

1	db.embedded_movies.aggregate([
2	{
3	"$match": {
4	"plot": { "$exists": true, "$type": "string" }
5	}
6	},
7	{
8	"$sort": { "released": -1 }
9	},
10	{
11	"$rerank": {
12	"model": "rerank-2.5",
13	"query": {
14	"text": "a group of heroes band together to stop a powerful enemy and save the world"
15	},
16	"numDocsToRerank": 100,
17	"path": ["title", "plot"]
18	}
19	},
20	{
21	"$addFields": {
22	"rerankScore": { "$meta": "score" }
23	}
24	},
25	{ "$limit": 10 },
26	{
27	"$project": {
28	"_id": 0,
29	"title": 1,
30	"plot": 1,
31	"rerankScore": 1
32	}
33	}
34	])

重要

语法

字段

例子

Considerations

兼容性

限制

行为

查询

衡量标准

$rerank 查询状态率

$rerank 令牌使用率

评分

帐单

使用层级和速率限制

Token Usage

资源策略

步骤

启用或禁用项目的原生重新排名

导航到项目设置页面。

启用或禁用重新排名。

监控令牌使用情况

导航至Search & Vector Search 页面。

UsageNative Reranking单击导航栏 下的 。

查看速率限制和使用情况

导航至Search & Vector Search 页面。

Rate LimitsNative Reranking单击导航栏 下的 。

`$rerank` 查询状态率

`$rerank` 令牌使用率

UsageNative Reranking单击导航栏下的。

Rate LimitsNative Reranking单击导航栏下的。