Hybridsuche für Oracle Agent-Speicher verwenden

Die semantische Suche hilft bei der Suche nach verwandten Informationen, auch wenn Abfragen unterschiedliche Wörter verwenden. Mit der Stichwortsuche können Sie genaue IDs, Namen und Ausdrücke finden, die bei der semantischen Suche möglicherweise fehlen.

In diesem Artikel wird erläutert, wie Sie die hybride Oracle Agent Memory-Suche mit Oracle Database verwenden.

Die hybride Suche hilft Oracle Agent Memory dabei, Datensätze nach Bedeutung und exaktem Text zu finden. Es kombiniert die von Oracle verwaltete Textsuche mit vektorbasiertem Ranking, sodass eine Abfrage IDs wie Problemcodes, Produktnamen und Aliasnamen abgleichen kann, während sie dennoch vom semantischen Abruf profitiert.

In diesem Leitfaden werden Sie:

von Oracle gesicherten Client für die Verwendung von SearchStrategy.HYBRID konfigurieren
Nur-Schlüsselwort-Suche mit SearchStrategy.KEYWORD konfigurieren
verstehen, welche Suchstrategien dasselbe verwaltete Schema gemeinsam verwenden können
Speicher hinzufügen, der einen eigenen Text für die Suche verwendet
Identifikatoren und Aliasnamen im Speichertext speichern, damit Benutzer sie später suchen können
Suche diese Erinnerungen nach exakter Kennung oder natürlicher Sprache

Hinweis: Verwenden Sie die hybride Suche, wenn weder die semantische Suche noch die Stichwortsuche allein einen zuverlässigen Abruf ermöglicht. Die hybride Suche ist am nützlichsten, wenn Datensätze sowohl beschreibenden Inhalt als auch exakte Begriffe enthalten, die Benutzer finden müssen.

Hinweis: Informationen zum Package-Setup finden Sie unter Erste Schritte mit Agent-Speicher. Wenn Sie für dieses Beispiel eine lokale Oracle-Datenbank benötigen, folgen Sie Oracle AI Database lokal ausführen.

Oracle Hybrid Search-Client konfigurieren

Erstellen Sie einen Oracle Agent-Speicherclient mit aktivierter Hybridsuche. Der Client speichert Datensätze in Oracle Database und fordert Oracle auf, einen verwalteten Hybridvektorindex für die Suche zu verwenden.

Verwenden Sie SchemaPolicy.CREATE_IF_NECESSARY, wenn Sie die hybride Suche zum ersten Mal aktivieren. Dadurch kann das SDK die verwalteten Suchspalten hinzufügen und den Hybridindex erstellen, wenn er noch nicht vorhanden ist.

Verwenden Sie SearchStrategy.HYBRID, wenn Oracle Keyword- und Vektorranking kombinieren soll. Für die Hybridsuche ist eine OracleDBEmbedder als Haupt-embedder des Clients erforderlich, sodass der Speicher und der von Oracle verwaltete Hybridvektorindex dasselbe datenbankinterne Modell gemeinsam verwenden.

Wenn Sie nur Textabgleiche verwenden möchten, verwenden Sie stattdessen SearchStrategy.KEYWORD. Im nächsten Abschnitt wird dieses Setup angezeigt.

Wichtig: Für dieses Handbuch ist oracleagentmemory 26.6.0 oder höher erforderlich. Wenn das verwaltete Schema von einem älteren Release erstellt wurde, starten Sie die Anwendung einmal mit SchemaPolicy.CREATE_IF_NECESSARY. Dadurch werden ältere freigegebene Schemas aktualisiert, und die für die ausgewählte Strategie erforderlichen Suchobjekte werden hinzugefügt. Bei diesem ersten Upgrade können verwaltete DDL- und Datenumschreibungen durchgeführt werden. Behandeln Sie sie daher als geplanten Migrationsschritt anstelle eines billigen normalen Starts. Nachdem das Schema bereit ist, können Sie zum normalen Hochfahren zurück zu SchemaPolicy.REQUIRE_EXISTING wechseln.

Entwicklungsschemas oder teilweise aktualisierte Schemas, die bereits die aktuelle Releaseform beanspruchen, werden nicht abgeschlossen. Erstellen Sie sie stattdessen neu.

Wenn Sie SchemaPolicy.REQUIRE_EXISTING verwenden, bevor das Schema upgegradet wird, verläuft die Clienterstellung nicht erfolgreich und gibt an, welche verwalteten Suchobjekte fehlen.

Nachdem ein Schema für die Schlüsselwort- oder Hybridsuche initialisiert oder upgegradet wurde, öffnen Sie es nicht erneut mit SearchStrategy.VECTOR, es sei denn, Sie erstellen das Schema neu oder führen eine Einbettungs-Backfill aus. Zeilen, die von Schlüsselwörtern oder Hybridclients geschrieben wurden, dürfen keine lokalen Einbettungen enthalten, sodass die Vektorsuche andernfalls Datensätze verpassen könnte.

Warnung: Das Erstellen des Hybridindex für ein vorhandenes Schema kann einige Zeit in Anspruch nehmen. Oracle muss vorhandenen gespeicherten Suchtext scannen und den verwalteten Hybridindextext-/Vektorstatus aus dem konfigurierten datenbankinternen Modell erstellen. SchemaPolicy.CREATE_IF_NECESSARY wartet darauf, dass diese DDL beendet wird, bevor der Client hochgefahren wird. Führen Sie daher das erste Hybridupgrade als geplanten Migrations- oder Wartungsvorgang für große Schemas aus.

Hinweis: Wenn das SDK einen verwalteten Hybridvektorindex erstellt, erstellt es auch eine DBMS_VECTOR_CHAIN-Vektorisatorvoreinstellung, die vom verwalteten Schema benannt wird. Die Voreinstellung speichert die Vektorisiererkonfiguration aus dem konfigurierten OracleDBEmbedder-Modell und soll Lightweight-Metadaten sein. Der generierte Voreinstellungsname ist deterministisch für das verwaltete Schema und folgt dem konfigurierten Tabellennamenspräfix, wenn er dem Voreinstellungsnamenlimit von Oracle Text entspricht. Sie können Voreinstellungen mit Oracle Text-Ansichten prüfen, wie CTX_USER_PREFERENCES und CTX_USER_PREFERENCE_VALUES.

Hinweis: In diesem Beispiel wird OracleDBEmbedder verwendet. Oracle verwendet das datenbankinterne Modell des Einbetters, wenn der Hybridindex erstellt wird. Daher teilen sich der Haupteinbettungs- und der Hybridindex ein DB-Modell.

Im Beispiel wird auch SearchIndexSyncMode.ON_COMMIT verwendet. Dadurch bleibt der Hybridindex nach jedem festgeschriebenen Schreibvorgang aktuell, sodass neu hinzugefügte Speicher sofort durchsucht werden können. Verwenden Sie SearchIndexSyncMode.MANUAL, wenn Sie die Suchindexsynchronisierung selbst ausführen möchten, oder SearchIndexSyncMode.AUTO, wenn Oracle den Hybridindex im Hintergrund aktualisieren soll und Suchergebnisse tolerieren kann, die hinter den letzten Schreibvorgängen zurückbleiben. Diese Einstellung gilt für die laufende Wartung, nachdem der anfängliche Suchindex vorhanden ist. Sie macht die erste Indexerstellung nicht asynchron.

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

API-Referenz: OracleAgentMemory

Nur Stichwortsuche verwenden

Verwenden Sie SearchStrategy.KEYWORD, wenn bei der Suche gespeicherte Wörter, IDs, Aliasnamen, Produktnamen oder kurze Phrasen abgeglichen werden sollen und Sie kein Vektorranking wünschen. Die Stichwortsuche liest denselben gespeicherten Suchtext, der von der hybriden Suche verwendet wird, verwendet jedoch keine Vektorfusion.

Für die Stichwortsuche ist kein Python-Einbettung erforderlich. Wenn das SDK Suchobjekte für ein neues Schlüsselwortschema erstellen muss, erstellt es einen Oracle Text-Index über gespeicherten Suchtext. SearchIndexSyncMode.ON_COMMIT und SearchIndexSyncMode.MANUAL steuern die Textindexaktualisierung des Schlüsselworts.

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

Dieselben add_memory()- und search()-Aufrufe, die unten angezeigt werden, funktionieren mit SearchStrategy.KEYWORD. Der Unterschied ist das Ranking: Die Stichwortsuche gibt nur Datensätze basierend auf Textabgleich zurück, während die hybride Suche Textabgleich mit Vektorrangfolge kombiniert.

API-Referenz: OracleAgentMemory

Strategie suchen

Kompatible Suchstrategien verwenden

Beim ersten Erstellen oder Aktualisieren des verwalteten Schemas zeichnet das SDK auf, wie gespeicherte Abrufdaten für die Suche vorbereitet werden. Der aufgezeichnete Modus wird jedes Mal geprüft, wenn ein DB-Client gestartet wird. Dadurch wird verhindert, dass ein Kunde eine Strategie verwendet, die Datensätze stillschweigend verpassen könnte.

Wenn die angeforderte Strategie mit dem Schema kompatibel ist, aber nicht mit dem aufgezeichneten Modus übereinstimmt, gibt das SDK eine Warnung aus. Der Client kann noch starten, aber die Warnung hilft Ihnen, den Unterschied zu bemerken und zu bestätigen, dass es absichtlich ist.

SearchStrategy.VECTOR verwendet lokal gespeicherte Einbettungen. Öffnen Sie kein Schlüsselwort oder Hybridschema mit SearchStrategy.VECTOR, es sei denn, Sie erstellen das Schema neu oder führen eine Einbettungs-Backfill aus, da textbasierte Clients möglicherweise Zeilen ohne lokale Einbettungen geschrieben haben.
SearchStrategy.KEYWORD verwendet nur gespeicherten Suchtext. Es kann ein Schlüsselwortschema erstellen oder verwenden. Es kann auch ein vorhandenes Hybridschema öffnen und den Nur-Text-Zweig des Hybridindex verwenden. Ein Hybridschema wird nicht in den Schlüsselwortmodus zurückversetzt.
SearchStrategy.HYBRID verwendet gespeicherten Suchtext mit dem verwalteten Hybridvektorindex von Oracle. Sie kann ein Hybridschema erstellen, ein vorhandenes Hybridschema öffnen oder ein Schlüsselwortschema aktualisieren, wenn SchemaPolicy.CREATE_IF_NECESSARY verwendet wird. Im Hybridmodus muss der Client eine OracleDBEmbedder als Haupteinbettung verwenden.

Warnung: Die erste Erstellung des Hybridindex über vorhandene Daten kann lange dauern, da Oracle den verwalteten Hybridindexstatus aus gespeichertem Suchtext erstellt. SearchIndexSyncMode steuert die fortlaufende Indexverwaltung, nachdem der Index vorhanden ist. Der erste Build wird nicht asynchron.

Verwenden Sie SchemaPolicy.CREATE_IF_NECESSARY, wenn Sie ein Schema absichtlich von Vektor zu Schlüsselwort oder Hybrid oder von Schlüsselwort zu Hybrid verschieben. Verwenden Sie SchemaPolicy.REQUIRE_EXISTING, nachdem das Schema bereit ist und Sie das Schema validieren möchten, ohne Datenbankobjekte zu ändern.

API-Referenz: SchemaPolicy

Strategie suchen

Speicher für durchsuchbaren Speicher

Beginnen Sie mit einem normalen Speicher. Mit der OracleAgentMemory.add_memory()-API verwendet Oracle den Speicherinhalt selbst als durchsuchbaren Text. Dies ist der einfachste Pfad und reicht normalerweise aus, wenn Benutzer nach Wörtern oder Phrasen suchen, die bereits im Speicher angezeigt werden.

user_id = "user_123"

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

API-Referenz: OracleAgentMemory

Filial-IDs, nach denen Benutzer suchen können

Wenn Benutzer nach einem genauen Problemcode, einer Rechnungsnummer, einem Produktnamen oder einem Alias suchen können, fügen Sie diesen Text in den Speicher ein, den Sie speichern. Die hybride Suche kann dann mit dem genauen Text übereinstimmen und trotzdem das Vektor-Ranking für Abfragen in natürlicher Sprache verwenden.

Halten Sie den Speicher lesbar. Ein kurzer Satz, der die wichtige Kennung enthält, reicht oft aus. In diesem Beispiel enthalten die Speicher Problem- und Anforderungs-IDs, die Benutzer wahrscheinlich später eingeben.

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

API-Referenz: OracleAgentMemory

Nach ID oder Phrase suchen

Verwenden Sie die normale search()-API. Die hybride Suche wird hinter derselben Oracle Agent-Speichersuchoberfläche ausgeführt, sodass Sie wie gewohnt Geltungsbereiche, Ergebnislimits und Datensatztypfilter verwenden können.

Die erste Abfrage sucht nach einem genauen Problemcode, der im Speichertext gespeichert ist. Die zweite Abfrage sucht nach einem Satz in natürlicher Sprache aus derselben Gruppe von Speichern.

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)

Hinweis: Die Reihenfolge der Suchergebnisse kann je nach gespeicherten Daten, Hybridindexkonfiguration und Oracle-Bewertungsverhalten variieren. Prüfen Sie in Tests oder Demos, ob die erwarteten Datensätze zurückgegeben werden, anstatt sich auf ein genaues Ranking zu verlassen.

API-Referenz: OracleAgentMemory

OracleSearchResult

Schlussfolgerung

In dieser Dokumentation haben Sie die von Oracle verwaltete hybride Suche aktiviert, wann eine Nur-Schlüsselwort-Suche verwendet werden soll, einen regulären Speicher gespeichert, durchsuchbare IDs im Speichertext enthalten und Speicher mit exakten Bezeichnern und Phrasen in natürlicher Sprache abgefragt.

Nachdem Sie erfahren haben, wie Sie die hybride Suche in Oracle DB aktivieren, können Sie jetzt mit Speicher und Schema fortfahren.

Vollständiger Code

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