Usa ricerca ibrida memoria agente Oracle

La ricerca semantica aiuta a trovare le informazioni correlate anche quando le query utilizzano parole diverse. La ricerca per parola chiave consente di trovare identificatori, nomi e frasi esatti che la ricerca semantica potrebbe non riuscire.

Questo articolo spiega come utilizzare la ricerca ibrida di Oracle Agent Memory con Oracle Database.

La ricerca ibrida consente alla memoria dell'agente Oracle di trovare i record in base al significato e al testo esatto. Combina la ricerca di testo gestita da Oracle con la classificazione basata su vettori, in modo che una query possa corrispondere a identificativi quali codici di problema, nomi di prodotti e alias, pur beneficiando del recupero semantico.

In questa guida potrai:

Nota: utilizzare la ricerca ibrida quando né la ricerca semantica né la sola ricerca per parola chiave forniscono un recupero affidabile. La ricerca ibrida è più utile quando i record includono sia il contenuto descrittivo che i termini esatti che gli utenti devono trovare.

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

Configurare un client di ricerca ibrido Oracle

Creare un client Oracle Agent Memory con la ricerca ibrida abilitata. Il client memorizza i record in Oracle Database e chiede a Oracle di utilizzare un indice vettoriale ibrido gestito per la ricerca.

Utilizzare SchemaPolicy.CREATE_IF_NECESSARY quando si abilita la ricerca ibrida per la prima volta. Ciò consente all'SDK di aggiungere le colonne di ricerca gestita e creare l'indice ibrido se non esistono già.

Utilizzare SearchStrategy.HYBRID quando si desidera che Oracle combini la classificazione delle parole chiave e dei vettori. La ricerca ibrida richiede un OracleDBEmbedder come embedder principale del client, in modo che l'area di memorizzazione e l'indice vettoriale ibrido gestito da Oracle condividano lo stesso modello nel database.

Se si desidera trovare solo testo corrispondente, utilizzare SearchStrategy.KEYWORD. La sezione successiva mostra questa impostazione.

Importante: questa guida richiede oracleagentmemory 26.6.0 o una versione più recente. Se lo schema gestito è stato creato da una release precedente, avviare l'applicazione una sola volta con SchemaPolicy.CREATE_IF_NECESSARY. Questo aggiornamento supporta gli schemi rilasciati meno recenti e aggiunge gli oggetti di ricerca richiesti dalla strategia selezionata. Il primo aggiornamento può eseguire DDL gestiti e riscritture dei dati, quindi trattalo come un passo di migrazione pianificato invece di un avvio normale economico. Al termine dello schema, è possibile tornare a SchemaPolicy.REQUIRE_EXISTING per un avvio normale.

Gli schemi di sviluppo o parzialmente aggiornati che già rivendicano la forma di rilascio corrente non sono stati completati; ricrearli invece.

Se si utilizza SchemaPolicy.REQUIRE_EXISTING prima dell'aggiornamento dello schema, la creazione del client non riesce e indica quali oggetti di ricerca gestiti mancano.

Dopo aver inizializzato o aggiornato uno schema per la ricerca per parola chiave o ibrida, non riaprirlo con SearchStrategy.VECTOR a meno che non si crei lo schema o non si esegua un backfill di incorporamento. Le righe scritte da una parola chiave o da client ibridi potrebbero non contenere incorporamenti locali, pertanto la ricerca vettoriale potrebbe perdere i record.

Avvertenza: la creazione dell'indice ibrido per uno schema esistente può richiedere tempo. Oracle deve eseguire la scansione del testo di ricerca memorizzata esistente e creare lo stato del vettore/testo dell'indice ibrido gestito dal modello configurato nel database. SchemaPolicy.CREATE_IF_NECESSARY attende il completamento di tale DDL prima che l'avvio del client ritorni, quindi eseguire il primo aggiornamento ibrido come operazione di migrazione o manutenzione pianificata per schemi di grandi dimensioni.

Nota: quando l'SDK crea un indice vettoriale ibrido gestito, crea anche una preferenza vectorizer DBMS_VECTOR_CHAIN denominata dallo schema gestito. La preferenza memorizza la configurazione del vectorizer dal modello OracleDBEmbedder configurato e dovrebbe essere metadati leggeri. Il nome preferenza generato è deterministico per lo schema gestito e segue il prefisso nome tabella configurato quando si adatta al limite di nomi preferenze di Oracle Text. È possibile esaminare le preferenze mediante le viste di Oracle Text, ad esempio CTX_USER_PREFERENCES e CTX_USER_PREFERENCE_VALUES.

Nota: in questo esempio viene utilizzato OracleDBEmbedder. Oracle utilizza il modello in-database dell'incorporatore quando crea l'indice ibrido, in modo che l'incorporatore principale e l'indice ibrido condividano un modello DB.

Nell'esempio viene utilizzato anche SearchIndexSyncMode.ON_COMMIT. Ciò mantiene la corrente dell'indice ibrido dopo ogni scrittura di commit, quindi le memorie appena aggiunte sono immediatamente ricercabili. Utilizzare SearchIndexSyncMode.MANUAL quando si prevede di eseguire la sincronizzazione dell'indice di ricerca personalmente oppure SearchIndexSyncMode.AUTO quando si desidera che Oracle aggiorni l'indice ibrido in background e si tollerino risultati di ricerca in ritardo rispetto alle scritture recenti. Questa impostazione si applica alla manutenzione continua dopo l'esistenza dell'indice di ricerca iniziale; non rende asincrona la prima build dell'indice.

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,
)
Riferimento API: OracleAgentMemory OracleDBEmbedder Criterio schema Strategia di ricerca CercaIndexSyncMode

Usa solo ricerca con parole chiave

Utilizzare SearchStrategy.KEYWORD quando si desidera che la ricerca corrisponda alle parole memorizzate, agli identificatori, agli alias, ai nomi dei prodotti o alle frasi brevi e non si desidera classificare i vettori. La ricerca per parola chiave legge lo stesso testo di ricerca memorizzato utilizzato dalla ricerca ibrida, ma non utilizza la fusione vettoriale.

La ricerca per parola chiave non richiede un incorporamento Python. Se l'SDK deve creare oggetti di ricerca per un nuovo schema di parole chiave, crea un indice Oracle Text sul testo di ricerca memorizzato. Aggiornamento dell'indice di testo delle parole chiave di controllo SearchIndexSyncMode.ON_COMMIT e 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,
)

Le stesse chiamate add_memory() e search() mostrate di seguito funzionano con SearchStrategy.KEYWORD. La differenza è la classificazione: la ricerca per parola chiave restituisce i record solo in base alla corrispondenza del testo, mentre la ricerca ibrida combina la corrispondenza del testo con la classificazione vettoriale.

Riferimento API: OracleAgentMemory Strategia di ricerca

Usa strategie di ricerca compatibili

La prima volta che l'SDK crea o aggiorna lo schema gestito, registra la modalità di preparazione dei dati di recupero memorizzati per la ricerca. La modalità registrata viene selezionata ogni volta che viene avviato un client DB. Ciò impedisce a un cliente di utilizzare una strategia che potrebbe silenziosamente perdere i record.

Se la strategia richiesta è compatibile con lo schema ma non corrisponde alla modalità registrata, l'SDK emette un'avvertenza. Il client può ancora iniziare, ma l'avviso ti aiuta a notare la differenza e a confermare che è intenzionale.

Avvertenza: la prima creazione dell'indice ibrido sui dati esistenti può essere eseguita a lungo perché Oracle crea lo stato dell'indice ibrido gestito dal testo di ricerca memorizzato. SearchIndexSyncMode controlla la manutenzione continua dell'indice dopo che l'indice esiste; non rende la prima build asincrona.

Utilizzare SchemaPolicy.CREATE_IF_NECESSARY quando si sposta intenzionalmente uno schema da vettore a parola chiave o ibrido o da parola chiave a ibrido. Utilizzare SchemaPolicy.REQUIRE_EXISTING dopo che lo schema è pronto e si desidera che l'avvio convalidi lo schema senza modificare gli oggetti di database.

Riferimento API: SchemaPolicy Strategia di ricerca

Memoria ricercabile

Inizia con una memoria normale. Con l'API OracleAgentMemory.add_memory(), Oracle utilizza il contenuto di memoria stesso come testo ricercabile. Questo è il percorso più semplice e di solito è sufficiente quando gli utenti cercano parole o frasi che appaiono già nella memoria.

user_id = "user_123"

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

Riferimento API: OracleAgentMemory

Gli utenti identificativi negozio possono cercare

Quando gli utenti possono eseguire ricerche in base a un codice di emissione esatto, un numero di fattura, un nome di prodotto o un alias, includere il testo nella memoria memorizzata. La ricerca ibrida può quindi corrispondere al testo esatto e utilizzare comunque la classificazione vettoriale per le query in linguaggio naturale.

Mantieni la memoria leggibile. Una breve frase che include l'identificatore importante è spesso sufficiente. In questo esempio, le memorie includono gli identificatori di problemi e richieste che gli utenti potrebbero digitare in seguito.

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

Riferimento API: OracleAgentMemory

Cerca per identificativo o frase

Utilizzare la normale API search(). La ricerca ibrida viene eseguita dietro la stessa interfaccia di ricerca della memoria Oracle Agent, in modo da poter continuare a utilizzare gli ambiti, i limiti dei risultati e i filtri dei tipi di record come al solito.

La prima query cerca un codice di problema esatto memorizzato nel testo della memoria. La seconda query cerca una frase in linguaggio naturale dallo stesso insieme di memorie.

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: l'ordine dei risultati della ricerca può variare in base ai dati memorizzati, alla configurazione dell'indice ibrido e al comportamento del punteggio Oracle. Nei test o nelle demo, verificare che i record previsti vengano restituiti piuttosto che basarsi su una classificazione esatta.

Riferimento API: OracleAgentMemory Risultati ricerca Oracle

Conclusione

In questa guida è stata abilitata la ricerca ibrida gestita da Oracle, è stato rilevato quando utilizzare la ricerca solo per parole chiave, è stata memorizzata una memoria normale, sono stati inclusi gli identificativi ricercabili nel testo della memoria e sono state eseguite query sulle memorie in base all'identificativo esatto e alla frase in lingua naturale.

Dopo aver appreso come abilitare la ricerca ibrida in Oracle DB, ora è possibile passare a Negozi e schema.

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