Speicher und Schema

Auf dieser Seite werden die Core-Speicherabstraktionen und Schemakontrollen angezeigt, die vom Oracle Agent-Speicher-SDK verwendet werden.

Shop-API

Klasse oracleagentmemory.core.OracleMemoryStore

Basen: IMemoryStore

Gemeinsame Speicherschnittstelle, die von OracleAgentMemory verwendet wird.

Eine Store-Implementierung ist dafür verantwortlich, Text-Records zu persistieren und Ähnlichkeitssuchen durchzuführen. Sowohl synchrone als auch asynchrone Einstiegspunkte werden definiert, sodass APIs auf höherer Ebene übereinstimmende Synchronisierungs-/asynchrone Oberflächen bereitstellen können, ohne dass eine speicherspezifische Logik dupliziert wird.

Methode search (Übung)

Datensätze nach Ähnlichkeit suchen

• Parameter:
  • query str | None – Abfrage in natürlicher Sprache. Muss angegeben werden, wenn query_vector ausgelassen wird.
  • query_vector list[float] | None – Optionale vorberechnete Abfrageeinbettung. Es muss genau einer von query und query_vector angegeben werden.
  • k int – Maximale Anzahl von Ergebnissen, die zurückgegeben werden. Explizite Werte müssen mindestens 1 sein.
  • thread_id str | None – Optionaler Threadgeltungsbereich.
  • user_id str | None – Optionale Filter für Benutzer- und Agent-Geltungsbereich.
  • agent_id str | None: Optionale Filter für Benutzer- und Agent-Geltungsbereich.
  • exact_user_match bool: Gibt an, ob jede angegebene Geltungsbereichs-ID genau abgeglichen werden muss.
  • exact_agent_match bool: Gibt an, ob jede angegebene Geltungsbereichs-ID genau abgeglichen werden muss.
  • exact_thread_match bool: Gibt an, ob jede angegebene Geltungsbereichs-ID genau abgeglichen werden muss.
  • record_types set[str] | None – Optionale Datensatztypen, die eingeschlossen werden sollen.
  • metadata_filter dict[str, Any] | None – Optionale partielle Metadatenzuordnung. Ein Datensatz stimmt nur überein, wenn seine gespeicherten Metadaten alle angeforderten Schlüssel und Werte enthalten. Verschachtelte Wörterbücher werden rekursiv abgeglichen. Listenwerte werden nach genauer Gleichheit und nicht nach rekursiver Zuordnung der Teilmenge abgeglichen. Daher müssen Listenreihenfolge und -länge ebenfalls übereinstimmen.
• Rückgaben: (record, distance)-Paare nach zunehmender Entfernung sortiert.
• Rückgabetyp: list[tuple[Record, float]]
• Gelöst: ValueError – Wenn k kleiner als 1 ist.

Beispiele

store.add(
    ["Searchable abstract memory"],
    record_type="memory",
    record_ids="mem-search-abstract-docs",
)
['mem-search-abstract-docs']
store.search("Searchable", 1, record_types={"memory"})[0][0].id
'mem-search-abstract-docs'

Nach einem skalaren Metadatenwert filtern:

store.add(
    ["pizza release"],
    record_type="memory",
    record_ids="mem-search-meta-source-docs",
    metadata={"source": "slack"},
)
['mem-search-meta-source-docs']
any(
    record.id == "mem-search-meta-source-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"source": "slack"},
    )
)
True

Nach verschachtelten Metadaten filtern:

store.add(
    ["pizza review"],
    record_type="memory",
    record_ids="mem-search-meta-review-docs",
    metadata={"review": {"status": "open"}},
)
['mem-search-meta-review-docs']
any(
    record.id == "mem-search-meta-review-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"review": {"status": "open"}},
    )
)
True

Ordnen Sie einen Listenwert genau zu, einschließlich Reihenfolge:

store.add(
    ["pizza tags"],
    record_type="memory",
    record_ids="mem-search-meta-tags-docs",
    metadata={"tags": ["prod", "urgent"]},
)
['mem-search-meta-tags-docs']
any(
    record.id == "mem-search-meta-tags-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"tags": ["prod", "urgent"]},
    )
)
True

Oracle DB-Speicher

Klasse oracleagentmemory.core.OracleDBMemoryStore

Basis: OracleMemoryStore

Datenbankgestützte Persistenz für Nachrichten, Speicher und Akteurprofile.

Oracle DB-Speicher erstellen

• Parameter:
  • embedder IEmbedder | None: Einbettung für vektorisierte Datensatztypen. Kann None sein, wenn Aufrufer immer vorab berechnete Vektoren in add, update und search bereitstellen.
  • pool Any: Oracle DB-Verbindung oder -Pool. Das Übergeben einer Raw-Verbindung ermöglicht den Single-Session-Modus für diese Speicherinstanz: gleichzeitige Speicheraufrufe werden lokal serialisiert, um die von Schreibvorgängen verwendeten Zeilensperren und Transaktionsannahmen beizubehalten. Verwenden Sie einen Connection Pool für gleichzeitige Anforderungen.
  • schema_policy SchemaPolicy | str – Schemasetupmodus. Standardmäßig ist ein vorhandenes, aktuelles verwaltetes Schema erforderlich, und es werden keine DDL-Änderungen vorgenommen. Verwenden Sie SchemaPolicy.CREATE_IF_NECESSARY, um fehlende Objekte auszufüllen, oder SchemaPolicy.RECREATE, um verwaltete Objekte zu löschen und neu zu erstellen.
  • vector_dim int: Einbettungsdimension für die Schemaerstellung, wenn VECTOR-Spalten erstellt werden.
  • table_name_prefix str – Optionales Präfix, das zu verwalteten Tabellen-/Indexnamen hinzugefügt wurde.

Methode add_agent

Agent-Profildatensatz hinzufügen.

• Parameter:
  • agent_id str: Agent-ID.
  • Informationen str – Freiforminformationen zum Agent. Dieser Text wird als Profilinhalt gespeichert und zum Erstellen der Profileinbettungszeile in RECORD_CHUNKS verwendet.
• Rücksendungen: ID des eingefügten Agent-Profildatensatzes.
• Rückgabetyp: str

Hinweise

Agent-Profildatensätze werden nicht kopiert. Die eingefügte öffentliche Datensatz-ID ist derselbe Wert, der als agent_id übergeben wird.

Beispiele

store.add_agent("a-docs-agent", "Support assistant")
'a-docs-agent'

Methode add_user

Benutzerprofildatensatz hinzufügen

• Parameter:
  • user_id str: Benutzer-ID.
  • Informationen str – Freiforminformationen zum Benutzer. Dieser Text wird als Profilinhalt gespeichert und zum Erstellen der Profileinbettungszeile in RECORD_CHUNKS verwendet.
• Rücksendungen: ID des eingefügten Benutzerprofildatensatzes.
• Rückgabetyp: str

Hinweise

Benutzerprofildatensätze werden nicht kopiert. Die eingefügte öffentliche Datensatz-ID ist derselbe Wert, der als user_id übergeben wird.

Beispiele

store.add_user("u-docs-profile", "Prefers concise answers.")
'u-docs-profile'

Methode delete

Löschen Sie einen verwalteten Datensatz und die zugehörigen Blockzeilen nach ID.

• Parameter:
  • record_type str: Zu löschendes Label für Datensatztyp. Unterstützte Typen sind "thread", "message", "memory", "guideline", "fact", "preference", "user_profile" und "agent_profile".
  • record_id str: Zu löschende ID.
  • kaskadieren bool: Wenn Sie True verwenden, blenden Sie unterstützte Ziele der obersten Ebene, wie z.B. Akteurprofile, in die untergeordneten Zeilen des Geltungsbereichs innerhalb derselben Transaktion ein. Bei einem Benutzerprofil- oder Agent-Profilziel werden zuerst die eigenen Threadzeilen gelöscht. Dadurch werden die Threadzeilen mit Threadgeltungsbereich und die Zeilen der Speichertabellen entfernt. Anschließend werden alle verbleibenden direkt auf Akteur ausgerichteten Nachrichten und speicherähnlichen Zeilen gelöscht (memory, guideline, fact, preference). Diese Bereichsbereinigung wird noch ausgeführt, wenn die übereinstimmende Profilzeile bereits fehlt.
• Rückgaben: Anzahl der angeforderten Ziele der obersten Ebene, die entfernt wurden, in der Regel 0 oder 1. Kaskadierte untergeordnete Zeilen werden nicht separat gezählt. Daher kann dies immer noch 0 sein, wenn ein fehlendes Akteurprofil eine bereichsbezogene Bereinigung auslöst.
• Rückgabetyp: int

Hinweise

Der Vorgang wird innerhalb einer Transaktion ausgeführt. Wenn cascade für ein unterstütztes Ziel der obersten Ebene aktiviert ist, werden das Löschen des Profils und alle untergeordneten Löschvorgänge mit Geltungsbereich festgeschrieben oder zusammen zurückgesetzt.

Beispiele

store.add(["Delete me"], record_type="memory", record_ids="mem-delete-docs")
['mem-delete-docs']
store.delete("memory", "mem-delete-docs")
1

Methode delete_thread

Thread und die zugehörigen gespeicherten Zeilen löschen

• Parameter: thread_id str: Thread-ID, deren Zeilen entfernt werden sollen, einschließlich Threadzeile, abhängigen untergeordneten Zeilen und expliziter Bereinigung der Chunk-Zeile.
• Rückgaben: Anzahl der gelöschten Threadzeilen (0 oder 1).
• Rückgabetyp: int

Hinweise

Verwenden Sie diesen Vorgang, wenn Sie eine Thread-bezogene kaskadierende Bereinigung benötigen. Wenn Sie den Thread im DB-backed-Speicher löschen, wird die verwaltete Threadzeile zusammen mit den zugehörigen Nachrichten- und Speicherzeilen sowie den Datensatz-Chunk-Zeilen entfernt, die für den Abruf verwaltet werden. Dies ist breiter als ein Löschvorgang auf Nachrichtenebene, bei dem nur die Zeile mit Raw-Nachrichten entfernt wird. Beim Löschen von Threads werden die abhängigen Nachrichten- und Speicherzeilen, die von THREAD referenziert werden, zusammen mit den übereinstimmenden RECORD_CHUNKS-Zeilen in derselben Transaktion entfernt.

Beispiele

store.delete_thread("c1")
0

Method get

Gespeicherten Datensatz nach Kennung abrufen

• Parameter:
  • record_type str: Das Label des Datensatztyps wird in eine verwaltete Zeile aufgelöst, wie "message", "memory", "guideline", "fact", "preference", "user_profile" oder "agent_profile".
  • record_id str: ID für die Suche.
• Rückgaben: Der Datensatz wird mit entschlüsselten Metadaten aufgefüllt, wenn er gefunden wird. Andernfalls wird None verwendet.
• Rückgabetyp: Datensatz | Keine

Beispiele

store.add(["Remember this"], record_type="memory", record_ids="mem-get-docs")
['mem-get-docs']
store.get("memory", "mem-get-docs").id
'mem-get-docs'

Methode list

Permanente Datensätze für einen Datensatztyp auflisten.

• Parameter:
  • record_type str: Label des Datensatztyps (z.B. "message", "memory", "guideline", "fact", "preference", "user_profile" oder "agent_profile").
  • limit int | None – Optionale maximale Anzahl zurückzugebender Datensätze. Wenn diese Option ausgelassen wird, verwendet der Store seine Standard-Auflistungs-Cap. Übergeben Sie None, um diese Memory Cap zu deaktivieren und jeden übereinstimmenden Datensatz zurückzugeben.
  • thread_id str | None – Exakter Thread-Geltungsbereichsfilter. Wenn keine Filter angewendet werden, wird keine Filterung angewendet. Wenn dieser Wert auf None gesetzt ist, werden nur Zeilen zurückgegeben, deren thread_id SQL NULL ist. Nicht kopierte Datensatztypen ignorieren diesen Filter.
  • user_id str | None: Exakter Filter für den Benutzerumfang. Wenn keine Filter angewendet werden, wird keine Filterung angewendet. Wenn dieser Wert auf None gesetzt ist, werden nur Zeilen zurückgegeben, deren user_id SQL NULL ist. Nicht kopierte Datensatztypen ignorieren diesen Filter.
  • agent_id str | None: Exakter Agent-Geltungsbereichsfilter. Wenn keine Filter angewendet werden, wird keine Filterung angewendet. Wenn dieser Wert auf None gesetzt ist, werden nur Zeilen zurückgegeben, deren agent_id SQL NULL ist. Nicht kopierte Datensatztypen ignorieren diesen Filter.
  • metadata_filter dict[str, Any] | None – Metadatenfilter. Wenn keine Filter angewendet werden, wird keine Filterung angewendet. Wenn dieser Wert auf None gesetzt ist, werden nur Datensätze ohne gespeicherte Metadaten zurückgegeben. Wenn diese Eigenschaft auf ein Diktat gesetzt ist, müssen gespeicherte Metadaten alle angeforderten Schlüssel und Werte enthalten. Verschachtelte Wörterbücher werden rekursiv abgeglichen. Listenwerte werden nach genauer Gleichheit und nicht nach rekursiver Zuordnung der Teilmenge abgeglichen. Daher müssen Listenreihenfolge und -länge ebenfalls übereinstimmen.
• Retouren: Datensätze nach Einfügereihenfolge sortiert.
• Liste Rückgabetyp:[Datensatz]

Hinweise

"user_profile" und "agent_profile" sind nicht kopierte Datensatztypen. Für diese Datensatztypen werden thread_id, user_id und agent_id ignoriert, und die Akteuridentität bleibt in record.id.

Beispiele

store.add(
    ["First listed", "Second listed"],
    record_type="memory",
    record_ids=["mem-list-docs-1", "mem-list-docs-2"],
)
['mem-list-docs-1', 'mem-list-docs-2']
[record.id for record in store.list("memory", limit=2)]
['mem-list-docs-1', 'mem-list-docs-2']
store.add_user("u-list-docs", "Prefers concise answers.")
'u-list-docs'
any(
    record.id == "u-list-docs"
    for record in store.list("user_profile", user_id=None, limit=10)
)
True

Methode list_thread_messages

Permanente Nachrichten für einen Thread zurückgeben.

• Parameter:
  • thread_id str: Thread-ID, deren Nachrichten zurückgegeben werden sollen.
  • last_n int | None – Optionale Anzahl der zuletzt zurückgegebenen Nachrichten.
• Rücksendungen: Nach Einfügereihenfolge sortierte Meldungsdatensätze.
• Liste Rückgabetyp:[MessageRecord]

Beispiele

store.list_thread_messages("c1")
[]

Methode search

Datensätze nach Ähnlichkeit suchen

• Parameter:
  • query str | None – Abfrage in natürlicher Sprache. Muss angegeben werden, wenn query_vector ausgelassen wird.
  • query_vector list[float] | None – Optionale vorberechnete Abfrageeinbettung. Es muss genau einer von query und query_vector angegeben werden.
  • k int – Maximale Anzahl von Ergebnissen, die zurückgegeben werden. Explizite Werte müssen mindestens 1 sein.
  • thread_id str | None – Optionale Thread-Geltungsbereichs-ID. exact_thread_match=False lässt die Threaddimension uneingeschränkt bestehen. exact_thread_match=True entspricht genau dem angegebenen thread_id. Bei thread_id=None werden nur Datensätze abgeglichen, die in der Threaddimension nicht kopiert wurden.
  • user_id str | None – Optionale Geltungsbereichs-IDs für Benutzer und Agents. Das entsprechende Kennzeichen exact_*_match=False lässt diese Dimension uneingeschränkt bestehen. exact_*_match=True stimmt genau mit der angegebenen ID überein. Wenn die ID None lautet, entspricht sie nur Datensätzen, die in dieser Dimension nicht kopiert wurden.
  • agent_id str | None – Optionale Geltungsbereichs-IDs von Benutzern und Agents. Das entsprechende Kennzeichen exact_*_match=False lässt diese Dimension uneingeschränkt bestehen. exact_*_match=True stimmt genau mit der angegebenen ID überein. Wenn die ID None lautet, entspricht sie nur Datensätzen, die in dieser Dimension nicht kopiert wurden.
  • exact_user_match bool: Gibt an, ob jede Geltungsbereichs-ID genau abgeglichen werden muss. Bei False ist diese Dimension uneingeschränkt. True stimmt genau mit dem angegebenen Wert überein. Wenn dieser Wert None lautet, werden nur nicht kopierte Datensätze in dieser Dimension abgeglichen.
  • exact_agent_match bool: Gibt an, ob jede Geltungsbereichs-ID genau abgeglichen werden muss. Bei False ist diese Dimension uneingeschränkt. True stimmt genau mit dem angegebenen Wert überein. Wenn dieser Wert None lautet, werden nur nicht kopierte Datensätze in dieser Dimension abgeglichen.
  • exact_thread_match bool – Gibt an, ob jede Geltungsbereichs-ID genau abgeglichen werden muss. Bei False ist diese Dimension uneingeschränkt. True stimmt genau mit dem angegebenen Wert überein. Wenn dieser Wert None lautet, werden nur nicht kopierte Datensätze in dieser Dimension abgeglichen.
  • record_types set[str] | None: Optionale Gruppe durchsuchbarer Datensatztypen, die eingeschlossen werden sollen. Wenn diese Option ausgelassen wird, deckt die DB-Suche Nachrichten, Speichertabellenzeilen und Akteurprofile ab. Actor-Profile tragen ihre information-Payload bei, während Nachrichten- und Speicherzeilen ihre content-Payload beitragen. Bei der Suche verwenden Profildatensatztypen ihre Darsteller-ID für die anwendbare Umfangsdimension, während sich die verbleibenden Umfangsdimensionen wie None verhalten.
  • metadata_filter dict[str, Any] | None – Optionale partielle Metadatenzuordnung. Ein Datensatz stimmt nur überein, wenn seine gespeicherten Metadaten alle angeforderten Schlüssel und Werte enthalten. Verschachtelte Wörterbücher werden rekursiv abgeglichen. Listenwerte werden nach genauer Gleichheit und nicht nach rekursiver Zuordnung der Teilmenge abgeglichen. Daher müssen Listenreihenfolge und -länge ebenfalls übereinstimmen.
• Rückgaben: (record, distance)-Paare nach zunehmender Entfernung sortiert.
• Rückgabetyp: list[tuple[Record, float]]
• Gelöst: ValueError – Wenn k kleiner als 1 ist.

Beispiele

store.add(
    ["pizza preference"],
    record_type="memory",
    record_ids="mem-search-docs",
    thread_ids="c-search-docs",
)
['mem-search-docs']
results = store.search(
    "pizza",
    1,
    thread_id="c-search-docs",
    exact_thread_match=True,
    record_types={"memory"},
)
results[0][0].id
'mem-search-docs'

Nach einem skalaren Metadatenwert filtern:

store.add(
    ["pizza release"],
    record_type="memory",
    record_ids="mem-search-meta-source-docs",
    metadata={"source": "slack"},
)
['mem-search-meta-source-docs']
any(
    record.id == "mem-search-meta-source-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"source": "slack"},
    )
)
True

Nach verschachtelten Metadaten filtern:

store.add(
    ["pizza review"],
    record_type="memory",
    record_ids="mem-search-meta-review-docs",
    metadata={"review": {"status": "open"}},
)
['mem-search-meta-review-docs']
any(
    record.id == "mem-search-meta-review-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"review": {"status": "open"}},
    )
)
True

Ordnen Sie einen Listenwert genau zu, einschließlich Reihenfolge:

store.add(
    ["pizza tags"],
    record_type="memory",
    record_ids="mem-search-meta-tags-docs",
    metadata={"tags": ["prod", "urgent"]},
)
['mem-search-meta-tags-docs']
any(
    record.id == "mem-search-meta-tags-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"tags": ["prod", "urgent"]},
    )
)
True

Methode update

Aktualisieren Sie gespeicherten Datensatzinhalt, Chunk-Einbettungen und Metadatenwerte.

• Parameter:
  • record_type str: Label des Datensatztyps der zu ändernden Zeile (Beispiel: "message", "memory", "guideline", "fact", "preference", "user_profile" oder "agent_profile")
  • record_id str: ID der zu aktualisierenden gespeicherten Zeile.
  • text str | None – Optionaler Ersatztext, der in der Spalte content persistiert wird. Übergeben Sie None, um den gespeicherten Text zu löschen und die gespeicherte Einbettung zu löschen. Übergeben Sie nur None oder ausgelassene semantische Argumente im selben Aufruf. Übergeben Sie "", um expliziten leeren Inhalt beizubehalten, während Sie eine Chunk-Einbettung für diesen Datensatz löschen. Wird der Inhalt ausgelassen, bleibt der vorhandene Inhalt unverändert.
  • index_text str | None – Optionale Payload, die nur zur Einbettung dient. Wenn keine Angabe gemacht wird, wird text eingebettet.
  • einbetten list[float] | ndarray | None – Optionaler vorab berechneter Einbettungsvektor. Wenn angegeben, wird dies direkt verwendet, und es erfolgt kein Einbettungsaufruf. Übergeben Sie None, um die gespeicherte Einbettung zu löschen.
  • metadata dict[str, Any] | None – Optionale Metadatenzuordnung, die in JSON serialisiert und in metadata gespeichert wird.
• Rückgaben: Anzahl der aktualisierten Zeilen (0 oder 1). Gibt 0 zurück, wenn kein logischer Datensatz mit record_type und record_id übereinstimmt.
• Rückgabetyp: int
• Raises: ValueError – Wenn record_type nicht unterstützt wird, keine Update-Payload angegeben wird oder die semantischen Aktualisierungsargumente inkompatibel sind.

Beispiele

store.add(["Original note"], record_type="memory", record_ids="mem-update-docs")
['mem-update-docs']
store.update("memory", "mem-update-docs", text="Updated note")
1
store.get("memory", "mem-update-docs").content
'Updated note'

Schema-Policy

Klasse oracleagentmemory.core.SchemaPolicy

Basis: str, Enum

Schemaerstellungs-Policy für Oracle DB-Speicher.

ERFORDERLICH

Stellen Sie sicher, dass das vollständige verwaltete Schema bereits vorhanden ist und aktuell ist. Erstellen oder ändern Sie keine DB-Objekte.

CREATE_IF_LEER

Wenn keine verwalteten Objekte vorhanden sind, Bootstrap-Schema. Wenn bereits Objekte vorhanden sind, benötigen Sie ein vollständiges und aktuelles verwaltetes Schema.

ERSTELLEN_IF_NOTWENDIG

Erstellen Sie nur fehlende verwaltete Objekte, einschließlich Metadaten.

NEU ERSTELLEN

Alle verwalteten Schemaobjekte löschen und neu erstellen. Das ist destruktiv.