Como melhorar a relevância do resultado da pesquisa

A pesquisa pode recuperar registros úteis para uma consulta, mas uma pesquisa ampla ainda pode retornar resultados mais diretos do que um aplicativo pode usar, incluindo resultados que são apenas vagamente relacionados à pergunta.

O pós-processamento de pesquisa permite que um aplicativo controle o tamanho e o foco desse conjunto de resultados após a recuperação. Isso é especialmente útil quando os resultados da pesquisa são inseridos em um prompt de agente ou em um cartão de contexto com espaço limitado.

Este guia explica como configurar o comportamento pós-pesquisa para pesquisas regulares e recuperação de cartão de contexto. Use TopKMemorySearchConfig para retornar um número máximo fixo de resultados de pesquisa direta e, opcionalmente, reclassificá-los. Use PruningMemorySearchConfig para remover adicionalmente resultados menos relevantes com um LLM.

Observação: ao criar um cartão de contexto, a Memória do Agente Oracle pesquisa registros semelhantes à memória separadamente das mensagens no thread atual. Quando a nova classificação ou a poda é configurada, ela é aplicada separadamente a cada conjunto de resultados antes que os conjuntos sejam combinados. Os resultados combinados são limitados por max_relevant_results e pelo orçamento de token.

Quando o min_relevant_results_by_type é usado, cada tipo de registro solicitado é pesquisado separadamente. Reranking ou poda, quando configurado, também é aplicado separadamente aos resultados de cada pesquisa. Outra pesquisa em todos os tipos de registro semelhantes à memória pode usar qualquer slot de resultado restante. Por comparação, se a reclassificação ou a remoção estiver configurada para uma pesquisa regular que solicite vários record_types, ela será aplicada uma vez aos resultados da pesquisa combinada.

Neste guia, você irá:

configurar um número máximo fixo de resultados de pesquisa direta
usar reclassificação
usar poda baseada em LLM
usar orçamentos de token configurados e por chamada

Dica: Para configurar o pacote, consulte Conceitos Básicos da Memória do Agente. Se você precisar de um Oracle AI Database local para este exemplo, siga Executar o Oracle AI Database localmente.

Configurar Componentes de Pesquisa

Crie os componentes de modelo usados pela configuração de pesquisa. O reranker recebe a consulta e o texto do documento bruto, enquanto o pruner usa o LLM para remover resultados diretos menos relevantes.


import oracledb

from oracleagentmemory.core import (
    OracleAgentMemory,
    PruningEvaluationMode,
    PruningMemorySearchConfig,
    Reranker,
    SchemaPolicy,
    TopKMemorySearchConfig,
)
from oracleagentmemory.core.embedders.embedder import Embedder
from oracleagentmemory.core.llms.llm import Llm

embedder = Embedder(model="YOUR_EMBEDDING_MODEL")
search_llm = Llm(model="provider/search-llm-model")
reranker = Reranker(model="provider/reranker-model")
db_pool = oracledb.SessionPool(
    user="YOUR DB USER",
    password="YOUR DB PASSWORD",
    dsn="localhost:1521/...",
)
memory_store_id = "T_SEARCH_RESULTS"

Referência de API: Reranker

Llm

Usar um Limite de Resultados Diretos Fixo e Reranking

Informe TopKMemorySearchConfig ao criar o cliente ou o thread. A pesquisa primeiro recupera no máximo max_results resultados diretos. Em seguida, o reranker opcional recebe apenas esses resultados e altera sua ordem sem alterar sua identidade.

top_k_config = TopKMemorySearchConfig(
    max_results=5,
    reranker=reranker
)
memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=search_llm,
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    memory_store_id=memory_store_id,
    search_config=top_k_config,
)
user_id = "user_123"

Referência de API: TopKMemorySearchConfig

OracleAgentMemory

Usar Corte Baseado em LLM

Defina pruner_llm em OracleAgentMemory para ativar a remoção em todo o cliente com o modo de avaliação FAST padrão. Os novos threads herdam essa definição, enquanto os threads que já têm uma configuração de pesquisa armazenada a mantêm quando reabertos. Use PruningMemorySearchConfig quando a pesquisa inicial contiver muitos resultados menos relevantes e você precisar ajustar o comportamento de remoção. Ele mantém os resultados diretos classificados e usa o LLM configurado para identificar resultados adicionais que devem ser removidos.

O limite de resultado direto é aplicado antes da poda, portanto, o podador avalia apenas os resultados selecionados por esse limite e pode reduzir ainda mais a contagem de resultados. Forneça max_results em uma chamada de pesquisa regular. Para recuperação de cartão de contexto, o max_relevant_results fornece o limite inicial correspondente.

pruning_memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=search_llm,
    memory_store_id=memory_store_id,
    pruner_llm=search_llm,
)
thread = pruning_memory.create_thread(
    thread_id="search_result_pruning_demo",
    user_id=user_id,
)
pruned_results = thread.search(
    query="Which database does the service use?",
    max_results=50,
)
#Use PruningMemorySearchConfig for advanced modes and tuning.
extended_pruning_config = PruningMemorySearchConfig(
    pruner=search_llm,
    evaluation_mode=PruningEvaluationMode.EXTENDED,
    num_probe_points=3,
    protected_fraction=0.1,
)

Como a poda funciona em poucas palavras

O podador avalia os resultados classificados para determinar quantos documentos devem ser retidos. O protected_fraction garante que os documentos mais relevantes sejam sempre incluídos. Por exemplo, com protected_fraction=0.1, os 10% principais dos documentos classificados são protegidos contra remoção e permanecem nos resultados da pesquisa.

Defina evaluation_mode com PruningEvaluationMode para controlar o desempenho da poda de trabalho de avaliação:

FAST é o padrão. Ele prioriza a baixa latência e pode interromper a avaliação antecipadamente.
O EXTENDED avalia uma parte mais ampla dos resultados, com latência adicional e uso de LLM.
O EXHAUSTIVE avalia cada resultado do candidato individualmente e tem a maior latência e uso de LLM.

num_probe_points controla o número de regiões de resultados classificados consideradas nos modos FAST e EXTENDED. Omita-o ao usar EXHAUSTIVE.

Observação: a remoção usa um LLM, para que possa tornar as pesquisas mais lentas. Usá-lo ao obter um conjunto de resultados mais focado é mais importante do que minimizar a latência de pesquisa.

Referência de API: PruningMemorySearchConfig

PodandoModo de Avaliação

Aplicar Orçamentos de Token

Use soft_token_budget para direcionar o tamanho estimado da saída formatada. Os resultados completos são considerados em ordem de classificação, e o resultado que atinge ou cruza o alvo é mantido. Isso mantém pelo menos o primeiro resultado quando a pesquisa encontra uma correspondência.

Use token_budget como limite rígido. Um resultado completo que excederia esse limite é omitido, portanto, um limite rígido não pode produzir saída quando o primeiro resultado for muito grande. Os resultados individuais nunca são divididos. Recomendamos definir ambos os orçamentos, com o limite rígido maior que o alvo flexível. Um limite rígido cerca de três vezes o alvo suave é um ponto de partida útil.

Por exemplo, com soft_token_budget=800 e resultados estimados em 420, 300 e 250 tokens, todos os três são retornados. O terceiro resultado obtém a estimativa cumulativa de 720 a 970 tokens e conclui a seleção de orçamento flexível. Se token_budget=900 também for definido, somente os dois primeiros serão retornados porque o terceiro excederia o limite máximo.

Os orçamentos configurados se aplicam por padrão. Os valores positivos por chamada substituem seus orçamentos configurados correspondentes, enquanto os valores não positivos os desativam.

results = memory.search(
    query="Which database does the service use?",
    user_id=user_id,
    soft_token_budget=1_000,
    token_budget=3_000,
)

#Per-call values override the configured budgets.
larger_results = memory.search(
    query="Which database does the service use?",
    user_id=user_id,
    soft_token_budget=4_000,
    token_budget=12_000,
)

Referência de API: MemorySearchConfig

TopKMemorySearchConfig

Conclusão

Neste guia, aprendemos a configurar limites de resultado direto, reclassificação, poda baseada em LLM e orçamentos de token de resultado formatado e flexível.

→ Depois de aprender a personalizar a seleção de resultados de pesquisa, agora você pode prosseguir para Personalizar Conteúdo do Cartão de Contexto.

Código Inteiro

O exemplo completo está incluído neste guia para você copiar e executar.

#Copyright © 2026 Oracle and/or its affiliates.
#This software is under the Apache License 2.0
#(LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0) or Universal Permissive License
#(UPL) 1.0 (LICENSE-UPL or https://oss.oracle.com/licenses/upl), at your option.

#Oracle Agent Memory Code Example - Improve Search Result Relevance
#------------------------------------------------------------------

##Configure search components


import oracledb

from oracleagentmemory.core import (
    OracleAgentMemory,
    PruningEvaluationMode,
    PruningMemorySearchConfig,
    Reranker,
    SchemaPolicy,
    TopKMemorySearchConfig,
)
from oracleagentmemory.core.embedders.embedder import Embedder
from oracleagentmemory.core.llms.llm import Llm

embedder = Embedder(model="YOUR_EMBEDDING_MODEL")
search_llm = Llm(model="provider/search-llm-model")
reranker = Reranker(model="provider/reranker-model")
db_pool = oracledb.SessionPool(
    user="YOUR DB USER",
    password="YOUR DB PASSWORD",
    dsn="localhost:1521/...",
)
memory_store_id = "T_SEARCH_RESULTS"



##Configure top k search

top_k_config = TopKMemorySearchConfig(
    max_results=5,
    reranker=reranker
)
memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=search_llm,
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    memory_store_id=memory_store_id,
    search_config=top_k_config,
)
user_id = "user_123"



##Configure pruned search

pruning_memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=search_llm,
    memory_store_id=memory_store_id,
    pruner_llm=search_llm,
)
thread = pruning_memory.create_thread(
    thread_id="search_result_pruning_demo",
    user_id=user_id,
)
pruned_results = thread.search(
    query="Which database does the service use?",
    max_results=50,
)
#Use PruningMemorySearchConfig for advanced modes and tuning.
extended_pruning_config = PruningMemorySearchConfig(
    pruner=search_llm,
    evaluation_mode=PruningEvaluationMode.EXTENDED,
    num_probe_points=3,
    protected_fraction=0.1,
)



##Apply search token budgets

results = memory.search(
    query="Which database does the service use?",
    user_id=user_id,
    soft_token_budget=1_000,
    token_budget=3_000,
)

#Per-call values override the configured budgets.
larger_results = memory.search(
    query="Which database does the service use?",
    user_id=user_id,
    soft_token_budget=4_000,
    token_budget=12_000,
)