`$rerank`

Importante

O $rerank estágio de agregação está na visualização privada. O recurso e a documentação correspondente podem mudar a qualquer momento durante o período de Pré-visualização. Portanto, não recomendamos usar esse recurso em ambientes de produção. Para saber mais, consulte Recursos de visualização.

$rerank: O estágio reordena os $rerank documentos de entrada usando os modelos de reclassificação da Voyage AI e retorna os mesmos documentos classificados por relevância para a query. O $rerank estágio pode aparecer em qualquer lugar em um pipeline de agregação . Recomendamos que você use $rerank após um $vectorSearch $searchestágio,, $rankFusion $scoreFusion ou.

Sintaxe

Um estágio de pipeline do $rerank tem a seguinte sintaxe:

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

Campos

O estágio $rerank recebe um documento com os seguintes campos:

Campo	Tipo	necessidade	Descrição
`query`	Objeto	Obrigatório	Query a ser usada para reclassificação.
`query.` `text`	String	Obrigatório	Texto da query a ser usado para reclassificação. Por exemplo, você pode especificar: O que você está procurando Quais campos de um documento são mais relevantes Informações complementares para esclarecer queries ambíguas
`path`	String ou Array de Strings	Obrigatório	Caminho para os campos a serem usados na reclassificação. Se `$rerank` for um estágio intermediário, especifique um campo a partir dos resultados do estágio anterior. NOTA: a `$rerank` query falhará se os campos especificados em `path` não existirem. Use um `$match` estágio anterior para filtrar documentos com campos ausentes ou use para definir campos `$set` ausentes `""` como.
`numDocsToRerank`	Int	Obrigatório	Número máximo de documentos a serem enviados à IA do Voyage para reclassificação e retorno nos resultados. Os documentos são selecionados com base na ordem dos documento definida para o pipeline. O valor máximo deve ser menor ou igual a `1000`.
`model`	Objeto	Obrigatório	Modelo de IA Voyage a ser usado para reclassificar os documentos. O valor pode ser um dos seguintes: `rerank-2.5` - Reclassificação generalista otimizada para qualidade com suporte a instruções e multilíngue. `rerank-2.5-lite` - Reclassificação generalista otimizada para latência e qualidade com acompanhamento de instruções e suporte multilíngue. `rerank-2` - Modelo legado. `rerank-2-lite` - Modelo legado.

Exemplo

O exemplo a seguir demonstra como usar o $rerank estágio para reordenar documentos na sample_mflix.embedded_movies coleção com base em um modelo de reclassificação do Voyage AI. A query usa $rerank após o estágio para reordenar documentos usando $match o rerank-2.5 modelo de reclassificação. No seguinte pipeline de agregação ,:

$match O estágio filtra os documentos para incluir somente documentos que tenham um campo plot do tipo string.
$sort O estágio classifica os documentos em ordem decrescente do campo released para garantir a ordem determinística.
$rerank o estágio reordena os documentos para corresponder à query usando o modelo de reclassificação rerank-2.5.
$addFields estágio adiciona um campo chamado rerankScore aos documentos.

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
  }
]

Considerações

Antes de usar $rerank, considere a compatibilidade, as limitações, o comportamento e as permissões para usar $rerank.

Compatibilidade

O $rerank estágio está disponível somente no MongoDB Atlas executando o MongoDB 8.3 ou posterior.

Antes de $rerank usar, você deve ativar a reclassificação nativa por Project Settings meio. Para saber mais, consulte Habilitar ou desabilitar a reclassificação nativa de um projeto.

Limitações

Você não pode usar o estágio $rerank:

Nos $rankFusion $scoreFusion pipelines de entrada ou .
Em uma definição de visualização.

Comportamento

$rerank pode aparecer em qualquer lugar no pipeline. No entanto, recomendamos usar $rerank após um estágio como $search ou,$vectorSearch que já retorna documentos relevantes em ordem de classificação.

$rerank reclassifica e retorna os primeiros numDocsToRerank documentos que são passados para o estágio. Se $rerank for o primeiro estágio, ou se os estágios anteriores não retornarem resultados classificados deterministicamente, os documentos usados para $rerank poderão mudar entre as queries.

$rerank retorna um erro se qualquer um dos campos especificados em path não estiver presente em um ou mais documentos de entrada. Para mitigar isso, use o estágio para definir campos ausentes em uma string $set vazia.

Query

O campo query.text determina como o modelo de reclassificação pontua cada documento. O reclassificador calcula uma pontuação de relevância entre o texto da query e o conteúdo de cada documento no path especificado. Para a maioria dos casos de uso, $rerank.query.text deve ser igual ou semelhante à query do estágio $search ou $vectorSearch anterior.

Métricas

As seguintes métricas estão disponíveis para monitorar o uso do $rerank:

`$rerank` Taxa de status da query

A métrica da taxa de sucesso da query $rerank rastreia a porcentagem de queries $rerank concluídas com êxito. Você pode visualizar essa métrica na aba Metrics do seu cluster na UI do Atlas . Use essa métrica para identificar falhas nas queries $rerank, como erros de limite de taxa ou problemas de conectividade com o Voyage AI.

`$rerank` Taxa de uso do token

A métrica de uso de token $rerank acompanha o número total de tokens que as queries $rerank consomem. Você pode visualizar essa métrica na aba Metrics do seu cluster na UI do Atlas . Use essa métrica para monitorar o consumo de tokens e correlacionar o uso com o faturamento.

Pontuação

Use a score variável com a expressão para recuperar a pontuação de cada documento nos resultados $meta do $rerank estágio.

Exemplo: adicionar pontuação de reclassificação ao pipeline

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

O estágio $rerank substitui o valor de $meta: "score" por uma nova pontuação. Para preservar o valor de um estágio anterior como $$rankFusion, você pode projeto as pontuações em campos nomeados antes do estágio $rerank.

Exemplo: Preservar pontuação do estágio anterior

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

Cobrança

O MongoDB usa um modelo de preços pago conforme o uso e cobra pelo uso com base no número total de tokens processados. A seguinte fórmula calcula o total:

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

Modelo	Price per 1K tokens	Price per 1M tokens	Tokens grátis
`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

O estágio $rerank é cobrado separadamente de outras operações da Voyage AI em seu projeto Atlas . Você pode gerenciar pagamentos e cobrança por meio da interface de cobrança e pagamentos na interface do usuário do Atlas . Na interface do usuário do Atlas , você pode:

Acompanhe o uso do token na Usage página. Para saber mais, consulte Monitorar o uso de token.
Veja detalhamentos de custos por meio do Visualizador de custos.
Veja seus custos mensais atuais na Invoices página. Para saber mais,consulte Gerenciar faturas.

Níveis de uso e limites de taxa

O Atlas impõe limites de taxa ao número de solicitações que você pode fazer dentro de um período de tempo específico, medido em tokens por minuto (TPM) ou solicitações por minuto (RPM). Os limites de taxa seguem um sistema em camadas, com níveis mais altos oferecendo limites maiores.

Nível	Descrição
camada grátis	Nenhuma informação de pagamento necessária.
Nível 1	Informações de pagamento necessárias. Os limites de taxa são o dobro dos da camada grátis.

Modelo	Solicitações por minuto (RPM)	Tokens por minuto (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

Modelo	Solicitações por minuto (RPM)	Tokens por minuto (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

Monitore seu uso do token na Usage página na UI do Atlas . O uso é limitado por solicitações por minuto (RPM) e tokens por minuto (TPM) por cluster. Para saber mais, consulte Níveis de uso e limites de taxa.

A página Usage fornece várias visualizações para monitorar e analisar seu uso de token. Clique na guia Free Usage para visualizar os tokens gratuitos restantes por modelo para sua organização.

Na guia Usage Activity, o gráfico Total Usage exibe o total de tokens usados em seu projeto ao longo do tempo. Você pode filtrar dados de uso usando as seguintes opções:

Opção	Descrição
Usage Period	Visualize dados de uso para um intervalo de tempo específico.
Models	Filtre por modelos específicos da Voyage IA.

Para saber como monitorar o uso do token em um nível mais granular, consulte Monitorar o uso do token.

Política de recursos

Você pode configurar uma política de recursos no nível da organização para bloquear $rerank totalmente ou com exceções. Para fazer isso, adicione uma forbid regra, escrita em Cedar, que tenha como alvo a $rerank ação. Se você configurar esta política, novos projetos não poderão habilitar $rerank o. No entanto, isso não desabilita projetos já habilitados. Você deve desabilitar $rerank individualmente para projetos para os quais ele já está habilitado. Para desabilitar o $rerank para um projeto, consulte Habilitar ou desabilitar a reclassificação nativa para um projeto.

Você pode desabilitar $rerank com exceções usando a cláusula unless na regra forbid.

Exemplo: desativar $rerank com exceções

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

Para saber mais sobre como configurar a política de recursos, consulte Políticas de Recursos do Atlas .

Procedimentos

Você pode executar as seguintes tarefas na UI do Atlas :

Habilitar ou desabilitar a reclassificação de um projeto
Monitore o uso da reclassificação
Ver limites de taxa e uso
Definir uma política de recursos
Ver métricas

Habilitar ou desabilitar a reclassificação nativa para um projeto

Antes de usar o estágio $rerank, você deve ativar a reclassificação para seu projeto. Para ativar a reclassificação, você deve fazer o seguinte:

Navegue até a página de configurações do projeto .

Selecione a organização que contém seu projeto Organizations no menu da barra de navegação.
Selecione seu projeto no menu Projects na barra de navegação.
Clique em Settings na barra lateral.

Habilite ou desabilite a reclassificação.

Para habilitar a reclassificação, faça o seguinte:

Na guia Project Settings, defina a alternância de Native Reranking: $rerank in the Aggregation Pipeline para On.
Na janela Confirm Rerank Model Usage, marque a caixa de seleção para confirmar que você entende os custos associados ao uso do estágio $rerank e clique em Confirm.

Para desativar a reclassificação, faça o seguinte:

Na guia Project Settings, defina a alternância de Native Reranking: $rerank in the Aggregation Pipeline para Off.
Na janela de confirmação Disable Native Reranking, digite Disable e clique em Disable.
A desativação da reclassificação pode fazer com que a execução de queries que usam o estágio $rerank falhe.

Monitore o uso de token

Monitore seu uso do token na página Usage na UI do Atlas . Para visualizar o uso:

Navegue até a página Search & Vector Search.

Selecione a organização que contém seu projeto Organizations no menu da barra de navegação.
Selecione seu projeto no menu Projects na barra de navegação.
Na barra lateral, clique em Search & Vector Search sob o título Database.

Clique Usage em em Native Reranking na barra de navegação.

A Usage página fornece várias visualizações para monitorar e analisar seu uso de token. Para saber mais, consulte Uso de token.

Ver limites de taxa e uso

Navegue até a página Search & Vector Search.

Selecione a organização que contém seu projeto Organizations no menu da barra de navegação.
Selecione seu projeto no menu Projects na barra de navegação.
Na barra lateral, clique em Search & Vector Search sob o título Database.

Clique Rate Limits em em Native Reranking na barra de navegação.

A página Rate Limits fornece informações sobre os limites de taxa para seu projeto e orientação sobre como aumentar os limites de taxa.

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	])

Importante

Sintaxe

Campos

Exemplo

Considerações

Compatibilidade

Limitações

Comportamento

Query

Métricas

$rerank Taxa de status da query

$rerank Taxa de uso do token

Pontuação

Cobrança

Níveis de uso e limites de taxa

Token Usage

Política de recursos

Procedimentos

Habilitar ou desabilitar a reclassificação nativa para um projeto

Navegue até a página de configurações do projeto .

Habilite ou desabilite a reclassificação.

Monitore o uso de token

Navegue até a página Search & Vector Search.

Clique Usage em em Native Reranking na barra de navegação.

Ver limites de taxa e uso

Navegue até a página Search & Vector Search.

Clique Rate Limits em em Native Reranking na barra de navegação.

`$rerank` Taxa de status da query

`$rerank` Taxa de uso do token