Cómo mejorar la relevancia de los resultados de la búsqueda

La búsqueda puede recuperar registros útiles para una consulta, pero una búsqueda amplia aún puede devolver resultados más directos de los que puede utilizar una aplicación, incluidos los resultados que solo están ligeramente relacionados con la pregunta.

El posprocesamiento de búsqueda permite a una aplicación controlar el tamaño y el enfoque de ese conjunto de resultados después de la recuperación. Esto resulta especialmente útil cuando los resultados de la búsqueda se insertan en una petición de datos de agente o en una tarjeta de contexto con espacio limitado.

En esta guía se explica cómo configurar el comportamiento posterior a la búsqueda para búsquedas regulares y recuperación de tarjetas de contexto. Utilice TopKMemorySearchConfig para devolver un número máximo fijo de resultados de búsqueda directa y, opcionalmente, vuelva a clasificarlos. Utilice PruningMemorySearchConfig para eliminar, además, resultados menos relevantes con un LLM.

Nota: Al crear una tarjeta de contexto, la memoria del agente de Oracle busca registros similares a la memoria por separado de los mensajes del thread actual. Cuando se configura la modificación o depuración, se aplica por separado a cada conjunto de resultados antes de combinar los conjuntos. Los resultados combinados están limitados por max_relevant_results y el presupuesto de token.

Cuando se utiliza min_relevant_results_by_type, cada tipo de registro solicitado se busca por separado. La modificación o depuración, cuando se configura, también se aplica por separado a los resultados de cada búsqueda. Otra búsqueda en todos los tipos de registro similares a la memoria puede utilizar cualquier espacio de resultados que quede. En comparación, si la modificación o depuración está configurada para una búsqueda normal que solicita varios record_types, se aplica una vez a los resultados de búsqueda combinados.

En esta guía:

Configurar un número máximo fijo de resultados de búsqueda directa
usar reranking
utilizar la depuración basada en LLM
Utilizar presupuestos de token configurados y por llamada

Indicación: Para la configuración del paquete, consulte Get Started with Agent Memory. Si necesita una instancia local de Oracle AI Database para este ejemplo, siga Ejecución local de Oracle AI Database.

Configurar componentes de búsqueda

Cree los componentes de modelo que utiliza la configuración de búsqueda. El renumerador recibe la consulta y el texto del documento sin procesar, mientras que el podador utiliza el LLM para eliminar resultados directos 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"

Referencia de API: Reranker

Llm

Usar un límite fijo de resultados directos y cambio de nombre

Transfiera TopKMemorySearchConfig al crear el cliente o el thread. La búsqueda primero recupera como máximo los resultados directos max_results. A continuación, la opción reranker opcional recibe solo esos resultados y cambia su orden sin cambiar su identidad.

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"

Referencia de API: TopKMemorySearchConfig

OracleAgentMemoria

Utilizar depuración basada en LLM

Defina pruner_llm en OracleAgentMemory para activar la depuración en todo el cliente con el modo de evaluación FAST por defecto. Los subprocesos nuevos heredan este valor, mientras que los subprocesos que ya tienen una configuración de búsqueda almacenada lo conservan cuando se vuelven a abrir. Utilice PruningMemorySearchConfig cuando la búsqueda inicial contenga demasiados resultados menos relevantes y deba ajustar el comportamiento de depuración. Mantiene los resultados directos clasificados y utiliza el LLM configurado para identificar resultados adicionales que se deben eliminar.

El límite de resultado directo se aplica antes de la depuración, por lo que el depurador sólo evalúa los resultados seleccionados por ese límite y puede reducir aún más el recuento de resultados. Proporcione max_results en una llamada de búsqueda regular. Para la recuperación de tarjeta de contexto, max_relevant_results proporciona el límite inicial correspondiente.

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

Cómo funciona la poda en pocas palabras

El podador evalúa los resultados clasificados para determinar cuántos documentos se deben retener. protected_fraction garantiza que siempre se incluyan los documentos más relevantes. Por ejemplo, con protected_fraction=0.1, el 10% superior de los documentos clasificados está protegido de la poda y permanece en los resultados de búsqueda.

Defina evaluation_mode con PruningEvaluationMode para controlar la cantidad de tareas de depuración de evaluación que realiza:

FAST es el valor por defecto. Prioriza la baja latencia y puede detener la evaluación temprano.
EXTENDED evalúa una parte más amplia de los resultados, con latencia adicional y uso del LLM.
EXHAUSTIVE evalúa cada resultado candidato individualmente y tiene la latencia y el uso de LLM más altos.

num_probe_points controla el número de regiones de resultados clasificados que se consideran en los modos FAST y EXTENDED. Omítelo al utilizar EXHAUSTIVE.

Nota: La depuración utiliza un LLM, por lo que puede ralentizar las búsquedas. Utilícelo cuando obtener un juego de resultados más centrado es más importante que minimizar la latencia de búsqueda.

Referencia de API: PruningMemorySearchConfig

Modo de evaluación de depuración

Aplicar presupuestos de token

Utilice soft_token_budget para dirigir el tamaño estimado de la salida con formato. Los resultados completos se consideran en orden de clasificación y se mantiene el resultado que alcanza o cruza el destino. Esto mantiene al menos el primer resultado cuando la búsqueda encuentra una coincidencia.

Utilice token_budget como límite estricto. Se omite un resultado completo que superaría este límite, por lo que un límite estricto no puede producir ninguna salida cuando el primer resultado es demasiado grande. Los resultados individuales nunca se dividen. Recomendamos definir ambos presupuestos, con un límite estricto mayor que el objetivo flexible. Un límite estricto alrededor de tres veces el destino flexible es un punto de partida útil.

Por ejemplo, con soft_token_budget=800 y los resultados estimados en 420, 300 y 250 tokens, se devuelven los tres. El tercer resultado toma la estimación acumulada de 720 a 970 tokens y completa la selección de presupuesto flexible. Si también se define token_budget=900, solo se devuelven las dos primeras porque la tercera superaría el límite estricto.

Los presupuestos configurados se aplican por defecto. Los valores positivos por llamada sustituyen los presupuestos configurados correspondientes, mientras que los valores no positivos los desactivan.

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

Referencia de API: MemorySearchConfig

TopKMemorySearchConfig

Conclusión

En esta guía, aprendimos a configurar límites de resultados directos, cambio de nombre, poda basada en LLM y presupuestos de tokens de resultados con formato flexible y estricto.

→ Una vez que haya aprendido a personalizar la selección de resultados de búsqueda, ahora puede continuar con Personalizar contenido de tarjeta de contexto.

Código Completo

El ejemplo completo se incluye en esta guía para que pueda copiar y ejecutar.

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