Uso de la Búsqueda Híbrida de Memoria de Oracle Agent

La búsqueda semántica ayuda a encontrar información relacionada incluso cuando las consultas utilizan palabras diferentes. La búsqueda por palabras clave ayuda a encontrar identificadores exactos, nombres y frases que la búsqueda semántica podría perderse.

En este artículo se explica cómo utilizar la búsqueda híbrida de memoria de agente de Oracle con Oracle Database.

La búsqueda híbrida ayuda a la memoria del agente de Oracle a buscar registros por significado y texto exacto. Combina la búsqueda de texto gestionada por Oracle con la clasificación basada en vectores, por lo que una consulta puede hacer coincidir identificadores como códigos de problema, nombres de productos y alias, al tiempo que se beneficia de la recuperación semántica.

En esta guía:

Nota: Utilice la búsqueda híbrida cuando ni la búsqueda semántica ni la búsqueda por palabras clave por sí solas proporcionan una recuperación fiable. La búsqueda híbrida es más útil cuando los registros incluyen contenido descriptivo y términos exactos que los usuarios necesitan encontrar.

Indicación: Para la configuración del paquete, consulte Introducción a la memoria del agente. Si necesita una base de datos Oracle local para este ejemplo, siga Ejecutar Oracle AI Database localmente.

Configuración de un cliente de búsqueda híbrida de Oracle

Cree un cliente de memoria de Oracle Agent con la búsqueda híbrida activada. El cliente almacena registros en Oracle Database y solicita a Oracle que utilice un índice vectorial híbrido gestionado para la búsqueda.

Utilice SchemaPolicy.CREATE_IF_NECESSARY cuando active por primera vez la búsqueda híbrida. Esto permite al SDK agregar las columnas de búsqueda gestionadas y crear el índice híbrido si aún no existen.

Utilice SearchStrategy.HYBRID cuando desee que Oracle combine palabras clave y clasificación de vectores. La búsqueda híbrida requiere OracleDBEmbedder como embedder principal del cliente para que el almacén y el índice vectorial híbrido gestionado por Oracle compartan el mismo modelo en la base de datos.

Si solo desea que el texto coincida, utilice SearchStrategy.KEYWORD en su lugar. En la siguiente sección, se muestra esa configuración.

Importante: Esta guía necesita oracleagentmemory 26.6.0 o posterior. Si el esquema gestionado ha sido creado por una versión anterior, inicie la aplicación una vez con SchemaPolicy.CREATE_IF_NECESSARY. Este cambio de versión soporta los esquemas liberados más antiguos y agrega los objetos de búsqueda necesarios para la estrategia seleccionada. Esa primera actualización puede realizar reescrituras de datos y DDL gestionadas, por lo que debe tratarse como un paso de migración planificado en lugar de un inicio normal barato. Una vez que el esquema esté listo, puede volver a SchemaPolicy.REQUIRE_EXISTING para el inicio normal.

Los esquemas de desarrollo o parcialmente actualizados que ya reclaman la unidad de versión actual no se han completado en su lugar; vuelva a crearlos.

Si utiliza SchemaPolicy.REQUIRE_EXISTING antes de actualizar el esquema, la creación del cliente falla y le indica qué objetos de búsqueda gestionados faltan.

Después de inicializar o actualizar un esquema para la búsqueda por palabra clave o híbrida, no vuelva a abrirlo con SearchStrategy.VECTOR a menos que vuelva a crear el esquema o ejecute una relleno de embebido. Es posible que las filas escritas por palabras clave o clientes híbridos no contengan incrustaciones locales, por lo que la búsqueda de vectores podría omitir registros.

Advertencia: la creación del índice híbrido para un esquema existente puede llevar tiempo. Oracle debe explorar el texto de búsqueda almacenado existente y crear el estado de vector/texto de índice híbrido gestionado desde el modelo de base de datos configurado. SchemaPolicy.CREATE_IF_NECESSARY espera a que ese DDL termine antes de que se devuelva el inicio del cliente, por lo que debe ejecutar la primera actualización híbrida como una operación de migración o mantenimiento planificada para esquemas grandes.

Nota: Cuando el SDK crea un índice de vector híbrido gestionado, también crea una preferencia de vectorizador DBMS_VECTOR_CHAIN denominada por el esquema gestionado. La preferencia almacena la configuración del vectorizador desde el modelo OracleDBEmbedder configurado y se espera que sean metadatos sencillos. El nombre de preferencia generado es determinista para el esquema gestionado y sigue el prefijo de nombre de tabla configurado cuando se ajusta al límite de nombre de preferencia de Oracle Text. Puede inspeccionar las preferencias con vistas de Oracle Text como CTX_USER_PREFERENCES y CTX_USER_PREFERENCE_VALUES.

Nota: En este ejemplo se utiliza OracleDBEmbedder. Oracle utiliza el modelo de incrustación en la base de datos cuando crea el índice híbrido, de modo que el embebido principal y el índice híbrido comparten un modelo de base de datos.

En el ejemplo también se utiliza SearchIndexSyncMode.ON_COMMIT. Esto mantiene el índice híbrido actualizado después de cada escritura confirmada, por lo que las memorias recién agregadas se pueden buscar de inmediato. Utilice SearchIndexSyncMode.MANUAL cuando desee ejecutar la sincronización de índice de búsqueda usted mismo o SearchIndexSyncMode.AUTO cuando desee que Oracle refresque el índice híbrido en segundo plano y pueda tolerar que los resultados de búsqueda se retrasen con respecto a las escrituras recientes. Este valor se aplica al mantenimiento continuo después de que exista el índice de búsqueda inicial; no hace que la primera creación de índice sea asíncrona.

import oracledb

from oracleagentmemory.core import (
    MemoryExtractionConfig,
    OracleAgentMemory,
    SchemaPolicy,
    SearchIndexSyncMode,
    SearchStrategy,
)
from oracleagentmemory.core.embedders import OracleDBEmbedder


db_pool = oracledb.SessionPool(
    user="YOUR DB USER",
    password="YOUR DB PASSWORD",
    dsn="YOUR DB CONNECT STRING",
)

db_embedder = OracleDBEmbedder(
    connection=db_pool,
    model="YOUR_DB_EMBEDDING_MODEL",
    embedding_dimension=384,
)

memory = OracleAgentMemory(
    connection=db_pool,
    embedder=db_embedder,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    search_strategy=SearchStrategy.HYBRID,
    search_index_sync=SearchIndexSyncMode.ON_COMMIT,
)
Referencia de API: OracleAgentMemory OracleDBEmbedder Política de Esquema Estrategia de búsqueda Modo de sincronización de índice de búsqueda

Usar solo búsqueda por palabras clave

Utilice SearchStrategy.KEYWORD cuando desee que la búsqueda coincida con palabras almacenadas, identificadores, alias, nombres de productos o frases cortas, y no desee clasificar los vectores. La búsqueda por palabras clave lee el mismo texto de búsqueda almacenado utilizado por la búsqueda híbrida, pero no utiliza la fusión de vectores.

La búsqueda por palabras clave no necesita un embebido de Python. Si el SDK necesita crear objetos de búsqueda para un nuevo esquema de palabra clave, crea un índice de Oracle Text sobre el texto de búsqueda almacenado. Refrescamiento de índice de texto de palabras clave de control SearchIndexSyncMode.ON_COMMIT y SearchIndexSyncMode.MANUAL.

keyword_memory = OracleAgentMemory(
    connection=db_pool,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    search_strategy=SearchStrategy.KEYWORD,
)

Las mismas llamadas add_memory() y search() que se muestran a continuación funcionan con SearchStrategy.KEYWORD. La diferencia es la clasificación: la búsqueda por palabras clave devuelve registros basados sólo en la coincidencia de texto, mientras que la búsqueda híbrida combina la coincidencia de texto con la clasificación vectorial.

Referencia de API: OracleAgentMemory Estrategia de búsqueda

Usar estrategias de búsqueda compatibles

La primera vez que el SDK crea o actualiza el esquema gestionado, registra cómo se preparan los datos de recuperación almacenados para la búsqueda. El modo registrado se comprueba cada vez que se inicia un cliente de base de datos. Esto evita que un cliente utilice una estrategia que podría perder registros de forma silenciosa.

Si la estrategia solicitada es compatible con el esquema pero no coincide con el modo registrado, el SDK emite una advertencia. El cliente todavía puede comenzar, pero la advertencia le ayuda a notar la diferencia y confirmar que es intencional.

Advertencia: la primera creación del índice híbrido sobre los datos existentes puede ser de larga ejecución porque Oracle crea el estado de índice híbrido gestionado a partir del texto de búsqueda almacenado. SearchIndexSyncMode controla el mantenimiento continuo del índice después de que exista el índice; no hace que la primera creación sea asíncrona.

Utilice SchemaPolicy.CREATE_IF_NECESSARY cuando mueva intencionalmente un esquema de vector a palabra clave o híbrida, o de palabra clave a híbrida. Utilice SchemaPolicy.REQUIRE_EXISTING una vez que el esquema esté listo y desee iniciar para validar el esquema sin cambiar los objetos de base de datos.

Referencia de API: SchemaPolicy Estrategia de búsqueda

Almacenar una memoria apta para búsqueda

Comience con una memoria normal. Con la API OracleAgentMemory.add_memory(), Oracle utiliza el contenido de la memoria como texto apto para la búsqueda. Esta es la ruta más sencilla y suele ser suficiente cuando los usuarios buscan palabras o frases que ya aparecen en la memoria.

user_id = "user_123"

memory.add_memory(
    "The user calls the Milan outage the renewal blocker.",
    user_id=user_id,
)

Referencia de API: OracleAgentMemory

Identificadores de tienda que los usuarios pueden buscar

Cuando los usuarios puedan buscar por un código de emisión exacto, número de factura, nombre de producto o alias, incluya ese texto en la memoria que almacena. La búsqueda híbrida puede coincidir con el texto exacto y seguir utilizando la clasificación vectorial para las consultas en lenguaje natural.

Mantenga la memoria legible. Una frase corta que incluya el identificador importante suele ser suficiente. En este ejemplo, las memorias incluyen identificadores de problemas y solicitudes que es probable que los usuarios escriban más tarde.

memory.add_memory(
    "The follow-up fix for the Milan outage is the edge-cluster retry patch, "
    "tracked as ORA-27102.",
    user_id=user_id,
)

memory.add_memory(
    "The renewal request INV-48291 stays attached to the Milan blocker ORA-27102.",
    user_id=user_id,
)

Referencia de API: OracleAgentMemory

Buscar por identificador o frase

Utilice la API search() normal. La búsqueda híbrida se ejecuta detrás de la misma interfaz de búsqueda de memoria de Oracle Agent, para que pueda seguir utilizando ámbitos, límites de resultados y filtros de tipo de registro como de costumbre.

La primera consulta busca un código de problema exacto almacenado en el texto de la memoria. La segunda consulta busca una frase en lenguaje natural del mismo conjunto de recuerdos.

for query in ["ORA-27102", "renewal blocker"]:
    print(f"\nSearch results for {query!r}:")
    results = memory.search(
        query=query,
        user_id=user_id,
        max_results=5,
        record_types=["memory"],
    )
    print_search_results(results)

Nota: El orden de los resultados de la búsqueda puede variar según los datos almacenados, la configuración del índice híbrido y el comportamiento de puntuación de Oracle. En las pruebas o demostraciones, compruebe que los registros esperados se devuelven en lugar de depender de una clasificación exacta.

Referencia de API: OracleAgentMemory Resultado de búsqueda de Oracle

Conclusión

En esta guía, ha activado la búsqueda híbrida gestionada por Oracle, ha visto cuándo utilizar la búsqueda solo por palabras clave, ha almacenado una memoria normal, ha incluido identificadores que se pueden buscar en el texto de la memoria y ha consultado memorias por identificador exacto y frase en lenguaje natural.

Después de aprender a activar la búsqueda híbrida en Oracle DB, ahora puede continuar con Tiendas y esquema.

Código Completo

#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 - Oracle Hybrid Search
#-------------------------------------------------------

##Configure an Oracle hybrid search client

import oracledb

from oracleagentmemory.core import (
    MemoryExtractionConfig,
    OracleAgentMemory,
    SchemaPolicy,
    SearchIndexSyncMode,
    SearchStrategy,
)
from oracleagentmemory.core.embedders import OracleDBEmbedder


db_pool = oracledb.SessionPool(
    user="YOUR DB USER",
    password="YOUR DB PASSWORD",
    dsn="YOUR DB CONNECT STRING",
)

db_embedder = OracleDBEmbedder(
    connection=db_pool,
    model="YOUR_DB_EMBEDDING_MODEL",
    embedding_dimension=384,
)

memory = OracleAgentMemory(
    connection=db_pool,
    embedder=db_embedder,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    search_strategy=SearchStrategy.HYBRID,
    search_index_sync=SearchIndexSyncMode.ON_COMMIT,
)



##Configure an Oracle keyword search client

keyword_memory = OracleAgentMemory(
    connection=db_pool,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    search_strategy=SearchStrategy.KEYWORD,
)


def print_search_results(results: list) -> None:
    for result in results:
        print(f"- [{result.record.record_type}] {result.content}")



##Store a basic hybrid search memory

user_id = "user_123"

memory.add_memory(
    "The user calls the Milan outage the renewal blocker.",
    user_id=user_id,
)



##Store identifiers users may search for

memory.add_memory(
    "The follow-up fix for the Milan outage is the edge-cluster retry patch, "
    "tracked as ORA-27102.",
    user_id=user_id,
)

memory.add_memory(
    "The renewal request INV-48291 stays attached to the Milan blocker ORA-27102.",
    user_id=user_id,
)



##Search hybrid records by identifier or phrase

for query in ["ORA-27102", "renewal blocker"]:
    print(f"\nSearch results for {query!r}:")
    results = memory.search(
        query=query,
        user_id=user_id,
        max_results=5,
        record_types=["memory"],
    )
    print_search_results(results)