Come migliorare la pertinenza dei risultati di ricerca

La ricerca può recuperare record utili per un'interrogazione, ma una ricerca estesa può comunque restituire risultati più diretti di quelli che un'applicazione può utilizzare, inclusi i risultati che sono solo vagamente correlati alla domanda.

La post-elaborazione della ricerca consente a un'applicazione di controllare le dimensioni e lo stato attivo del set di risultati dopo il recupero. Ciò è particolarmente utile quando i risultati della ricerca vengono inseriti in un prompt agente o in una scheda contesto con spazio limitato.

Questa guida spiega come configurare il comportamento post-ricerca per ricerche regolari e il recupero delle schede di contesto. Utilizzare TopKMemorySearchConfig per restituire un numero massimo fisso di risultati di ricerca diretta e, facoltativamente, riordinarli. Utilizzare PruningMemorySearchConfig per rimuovere anche risultati meno rilevanti con un LLM.

Nota: quando si crea una scheda di contesto, la memoria dell'agente Oracle cerca i record simili alla memoria separatamente dai messaggi nel thread corrente. Quando la ridefinizione o la potatura è configurata, viene applicata separatamente a ciascun set di risultati prima che i set vengano combinati. I risultati combinati sono limitati da max_relevant_results e dal budget token.

Se si utilizza min_relevant_results_by_type, la ricerca di ogni tipo di record richiesto viene eseguita separatamente. Anche la riassegnazione o la potatura, se configurata, viene applicata separatamente ai risultati di ogni ricerca. Un'altra ricerca su tutti i tipi di record simili alla memoria può quindi utilizzare tutti gli slot dei risultati che rimangono. In confronto, se la riassegnazione o l'eliminazione è configurata per una ricerca regolare che richiede più di record_types, viene applicata una volta ai risultati della ricerca combinata.

In questa guida potrai:

configurare un numero massimo fisso di risultati di ricerca diretta
usa nuova classificazione
usa potatura basata su LLM
utilizza budget token configurati e per chiamata

Suggerimento: per l'impostazione dei package, vedere Introduzione alla memoria dell'agente. Se hai bisogno di un Oracle AI Database locale per questo esempio, segui Esegui Oracle AI Database localmente.

Configura componenti di ricerca

Creare i componenti del modello utilizzati dalla configurazione di ricerca. Il reranker riceve la query e il testo del documento raw, mentre il pruner utilizza l'LLM per rimuovere risultati diretti meno rilevanti.


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"

Riferimento API: Reranker

LLM

Usa un limite di risultato diretto e un nuovo ranking

Passare TopKMemorySearchConfig durante la creazione del client o del thread. La ricerca recupera in primo luogo al massimo max_results risultati diretti. L'opzionale reranker riceve quindi solo questi risultati e modifica il proprio ordine senza modificare la propria identità.

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"

Riferimento API: TopKMemorySearchConfig

OracleAgentMemoria

Usa eliminazione basata su LLM

Impostare pruner_llm su OracleAgentMemory per abilitare l'eliminazione a livello di client con la modalità di valutazione FAST predefinita. I nuovi thread ereditano questa impostazione, mentre i thread che dispongono già di una configurazione di ricerca memorizzata la conservano quando viene riaperta. Utilizzare PruningMemorySearchConfig quando la ricerca iniziale contiene troppi risultati meno rilevanti ed è necessario ottimizzare il comportamento di eliminazione. Mantiene i risultati diretti classificati e utilizza l'LLM configurato per identificare risultati aggiuntivi da rimuovere.

Il limite di risultato diretto viene applicato prima della potatura, quindi il potatore valuta solo i risultati selezionati da tale limite e può ridurre ulteriormente il conteggio dei risultati. Fornire max_results in una chiamata di ricerca regolare. Per il recupero della scheda di contesto, max_relevant_results fornisce il limite iniziale corrispondente.

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

Come funziona la potatura in un guscio di noci

Il compratore valuta i risultati classificati per determinare il numero di documenti da conservare. protected_fraction garantisce che i documenti più rilevanti siano sempre inclusi. Ad esempio, con protected_fraction=0.1, il primo 10% dei documenti classificati è protetto dall'eliminazione e rimane nei risultati della ricerca.

Impostare evaluation_mode con PruningEvaluationMode per controllare la quantità di prestazioni di eliminazione del lavoro di valutazione:

FAST è l'impostazione predefinita. Assegna la priorità alla bassa latenza e può interrompere la valutazione in anticipo.
EXTENDED valuta una parte più ampia dei risultati, con latenza aggiuntiva e uso di LLM.
EXHAUSTIVE valuta ogni singolo risultato del candidato e ha la latenza e l'uso LLM più elevati.

num_probe_points controlla il numero di aree con risultati classificati considerate nelle modalità FAST e EXTENDED. Ometterlo quando si utilizza EXHAUSTIVE.

Nota: l'eliminazione utilizza un LLM, in modo che possa rallentare le ricerche. Utilizzarlo quando si ottiene un set di risultati più mirato è più importante che ridurre al minimo la latenza di ricerca.

Riferimento API: PruningMemorySearchConfig

Modo valutazione eliminazione

Applica budget token

Utilizzare soft_token_budget per indirizzare la dimensione stimata dell'output formattato. I risultati completi vengono considerati in ordine di classificazione e il risultato che raggiunge o attraversa la destinazione viene mantenuto. Questo mantiene almeno il primo risultato quando la ricerca trova una corrispondenza.

Usare token_budget come limite assoluto. Un risultato completo che supererebbe questo limite viene omesso, quindi un limite rigido può non produrre output quando il primo risultato è troppo grande. I risultati individuali non sono mai divisi. Si consiglia di impostare entrambi i budget, con il limite assoluto più grande del soft target. Un limite duro circa tre volte il soft target è un utile punto di partenza.

Ad esempio, con soft_token_budget=800 e risultati stimati a 420, 300 e 250 token, vengono restituiti tutti e tre. Il terzo risultato prende la stima cumulativa da 720 a 970 token e completa la selezione del soft-budget. Se è impostato anche token_budget=900, vengono restituiti solo i primi due perché il terzo supererebbe il limite massimo.

I budget configurati vengono applicati per impostazione predefinita. I valori positivi per chiamata sostituiscono i budget configurati corrispondenti, mentre i valori non positivi li disabilitano.

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

Riferimento API: MemorySearchConfig

Configurazione TopKMemorySearch

Conclusione

In questa guida abbiamo imparato a configurare limiti di risultato diretto, ri-classificazione, potatura basata su LLM e budget di token soft e hard formatted-result.

→ Dopo aver appreso come personalizzare la selezione dei risultati di ricerca, ora è possibile passare a Personalizza contenuto scheda contesto.

Codice completo

L'esempio completo è incluso in questa guida per la copia e l'esecuzione.

#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,
)