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 add (Übung)
Textdatensätze einbetten und beibehalten.
- Parameter:
- contents
list[str | None]: Zu speichernde Text-Payloads. Diese Werte werden auch als Einbettungs-Payloads verwendet, wennindex_textsnicht angegeben wird. Wenn ein Element ausgelassen wird (None), wird es aus dem Metadatenschlüssel"content"aufgelöst, sofern verfügbar. Andernfalls wird leerer Inhalt beibehalten. - record_type
str: Datensatztyplabel für gespeicherte Datensätze (z.B."message"oder"memory"). - index_texts
list[str]: Optionale Payloads nur zur Einbettung, die aufcontentsausgerichtet sind. - Einbettungen
list[list[float]] | list[ndarray]– Optionale vorab berechnete Einbettungsvektoren, die aufcontentsausgerichtet sind. Bei der Bereitstellung verwenden Speicher diese Vektoren direkt und rufen den Einbettungsdienst nicht auf. - record_ids
str | None | list[str] | list[None]– Optionale durch Aufrufer sichtbare Datensatz-IDs. Muss entweder vollständig angegeben (einer pro Text) oder für alle Texte weggelassen werden. Die zurückgegebenen IDs entsprechen diesen Werten, sofern angegeben. - thread_ids
str | None | list[str | None]– Optionale Geltungsbereichs-IDs, die mit den Datensätzen gespeichert sind. - user_ids
str | None | list[str | None]– Optionale Geltungsbereichs-IDs, die mit den Datensätzen gespeichert werden. - agent_ids
str | None | list[str | None]– Optionale Geltungsbereichs-IDs, die mit den Datensätzen gespeichert sind. - Rollen
str | None | list[str | None]- Optionale Chatrolle für Nachrichtendatensätze. - Zeitstempel
str | None | list[str | None]– Optionaler Zeitstempel oder Zeitstempel pro Datensatz. - metadata
dict[str, Any] | list[dict[str, Any] | None] | None– Optionale Metadatenzuordnung oder Metadatenzuordnungen pro Datensatz. Metadaten können"content"als Fallback-Quelle für ausgelassene Textwerte enthalten. - **store_kwargs (Beliebige): Speicherspezifische Schreiboptionen, die von APIs auf höherer Ebene weitergeleitet werden.
- contents
- Rückgaben: Fügen Sie IDs für jedes Eingabeinhaltselement ein. Diese stimmen mit
record_idsüberein, sofern angegeben; andernfalls werden generierte IDs gespeichert. - Rückgabetyp: list[str]
Beispiele
store.add(["Abstract memory"], record_type="memory", record_ids="mem-abstract-docs")
['mem-abstract-docs']
Methode search (Übung)
Datensätze nach Ähnlichkeit suchen
- Parameter:
- query
str | None– Abfrage in natürlicher Sprache. Muss angegeben werden, wennquery_vectorausgelassen wird. - query_vector
list[float] | None– Optionale vorberechnete Abfrageeinbettung. Es muss genau einer vonqueryundquery_vectorangegeben werden. - k
int– Maximale Anzahl von Ergebnissen, die zurückgegeben werden. Explizite Werte müssen mindestens1sein. - 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.
- query
- Rückgaben:
(record, distance)-Paare nach zunehmender Entfernung sortiert. - Rückgabetyp: list[tuple[Record, float]]
- Gelöst: ValueError – Wenn
kkleiner als1ist.
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
Datenbankgesicherte Persistenz für Nachrichten und eingegebene Speicherdatensätze.
Oracle DB-Speicher erstellen
- Parameter:
- embedder
IEmbedder | None: Einbettung für vektorisierte Datensatztypen. KannNonesein, wenn Aufrufer immer vorab berechnete Vektoren inadd,updateundsearchbereitstellen. - 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 SieSchemaPolicy.CREATE_IF_NECESSARY, um fehlende Objekte auszufüllen, oderSchemaPolicy.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.
- embedder
Methode add
Fügen Sie dem Speicherspeicher Datensätze hinzu.
- Parameter:
- contents
list[str | None]: Zu speichernde Text-Payloads. Diese Werte werden auch zur Berechnung der Einbettung verwendet, es sei denn,index_textsoderembeddingssind angegeben. Wenn ein Element ausgelassen wird (None), wird es aus dem Metadatenschlüssel"content"aufgelöst, sofern verfügbar. Andernfalls wird leerer Inhalt beibehalten. - record_type
str: Datensatztyplabel für gespeicherte Datensätze (z.B."message","memory",guideline,factoderpreference). - index_texts
list[str]– Optionale alternative Payloads, die nur zum Einbetten/Indexieren verwendet werden. Wenn angegeben, muss die Länge voncontentsidentisch sein. - Einbettungen
list[list[float]] | list[ndarray]– Optionale vorab berechnete Einbettungsvektoren, die aufcontentsausgerichtet sind. Wenn angegeben, müssen die Speicher diese Vektoren direkt verwenden und dürfen den Embedder nicht aufrufen. Wenn der Speicher ausgelassen wird, verwendet er den Embedder nur für nicht leere Indizierungs-Payloads. Explizite leere Zeichenfolgen werden ohne Chunk-Einbettungen gespeichert. - record_ids
str | None | list[str] | list[None]– Optionale durch Aufrufer sichtbare Datensatz-IDs. Muss entweder vollständig angegeben (einer pro Text) oder für alle Texte weggelassen werden. Die zurückgegebenen IDs entsprechen diesen Werten, sofern angegeben. Wenn der Speicher ausgelassen wird, generiert er clientseitige IDs. - thread_ids
str | None | list[str | None]– Optionale Geltungsbereichs-IDs, die mit den Datensätzen gespeichert sind. - user_ids
str | None | list[str | None]– Optionale Geltungsbereichs-IDs, die mit den Datensätzen gespeichert werden. - agent_ids
str | None | list[str | None]– Optionale Geltungsbereichs-IDs, die mit den Datensätzen gespeichert sind. - Rollen
str | None | list[str | None]- Optionale Chatrolle für Nachrichtendatensätze. - Zeitstempel
str | None | list[str | None]– Optionale vom Aufrufer bereitgestellte Ereigniszeitstempel. - metadata
dict[str, Any] | list[dict[str, Any] | None] | None– Optionale Metadatenwörterbücher, die vom Aufrufer bereitgestellt werden. Metadaten können"content"als Fallback-Quelle für ausgelassene Textwerte enthalten. - **store_kwargs (Beliebig) – Speicherspezifische Schreiboptionen. Unterstützte Schlüssel umfassen derzeit
batch_sizefür das Oracleexecutemany-Batching.
- contents
- Rückgaben: Fügen Sie IDs für jedes Eingabeinhaltselement ein. Diese stimmen mit
record_idsüberein, sofern angegeben. Andernfalls werden generierte IDs gespeichert. - Rückgabetyp: list[str]
Beispiele
store.add(
["Hello from docs"],
record_type="message",
record_ids="msg-docs-add",
thread_ids="c-docs-add",
roles="user",
)
['msg-docs-add']
Methode add_agent
Agent-Profildatensatz hinzufügen.
- Parameter:
- agent_id
str: Agent-ID. - Informationen
str– Freiforminformationen zum Agent.
- agent_id
- Rücksendungen: ID des eingefügten Agent-Profildatensatzes.
- Rückgabetyp: str
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.
- user_id
- Rücksendungen: ID des eingefügten Benutzerprofildatensatzes.
- Rückgabetyp: str
Beispiele
store.add_user("u-docs-profile", "Prefers concise answers.")
'u-docs-profile'
Methode delete
Löschen Sie eine verwaltete Vektor-Record-Zeile und die zugehörigen Blockzeilen nach ID.
- Parameter:
- record_type
str: Datensatztyplabel, dessen verwaltete Tabelle als Ziel festgelegt werden soll, wie"message","memory","guideline","fact"oder"preference" - record_id
str: ID der zu entfernenden Zeile.
- record_type
- Rückgaben: Anzahl der entfernten Zeilen (
0, wenn die ID nicht gefunden wurde). - Rückgabetyp: int
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
Löschen Sie einen Thread und die zugehörigen Vektor-Records und Chunk-Zeilen.
- Parameter: thread_id
str: Thread-ID, deren Zeilen entfernt werden sollen (einschließlich kaskadierend gelöschter untergeordneter Zeilen). - Rückgaben: Anzahl der gelöschten Threadzeilen (
0oder1). - Rückgabetyp: int
Beispiele
store.delete_thread("c1")
0
Method get
Rufen Sie eine gespeicherte Nachricht oder einen gespeicherten Speicher nach Kennung ab.
- Parameter:
- record_type
str: Das Label des Datensatztyps wird in eine verwaltete Vektordatensatzzeile aufgelöst, wie"message","memory","guideline","fact"oder"preference". - record_id
str: ID für die Suche.
- record_type
- Rückgaben: Der Datensatz wird mit entschlüsselten Metadaten aufgefüllt, wenn er gefunden wird. Andernfalls wird
Noneverwendet. - 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: Beschriftung des Datensatztyps (z.B."message","memory","guideline","fact"oder"preference"). - Limit
int: Maximale Anzahl der zurückzugebenden Datensätze. - thread_id
str | None– Exakter Thread-Geltungsbereichsfilter. Wenn keine Filter angewendet werden, wird keine Filterung angewendet. Wenn dieser Wert aufNonegesetzt ist, werden nur Datensätze zurückgegeben, die in der Threaddimension nicht kopiert wurden. - user_id
str | None: Exakter Filter für den Benutzerumfang. Wenn keine Filter angewendet werden, wird keine Filterung angewendet. Wenn dieser Wert aufNonegesetzt ist, werden nur Datensätze zurückgegeben, die in der Benutzerdimension nicht kopiert wurden. - agent_id
str | None: Exakter Agent-Geltungsbereichsfilter. Wenn keine Filter angewendet werden, wird keine Filterung angewendet. Wenn dieser Wert aufNonegesetzt ist, werden nur Datensätze zurückgegeben, die in der Agent-Dimension nicht kopiert wurden. - metadata_filter
dict[str, Any] | None– Metadatenfilter. Wenn keine Filter angewendet werden, wird keine Filterung angewendet. Wenn dieser Wert aufNonegesetzt 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.
- record_type
- Retouren: Datensätze nach Einfügereihenfolge sortiert.
- Liste Rückgabetyp:[Datensatz]
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']
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.
- thread_id
- 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, wennquery_vectorausgelassen wird. - query_vector
list[float] | None– Optionale vorberechnete Abfrageeinbettung. Es muss genau einer vonqueryundquery_vectorangegeben werden. - k
int– Maximale Anzahl von Ergebnissen, die zurückgegeben werden. Explizite Werte müssen mindestens1sein. - thread_id
str | None– Optionale Thread-Geltungsbereichs-ID.exact_thread_match=Falselässt die Threaddimension uneingeschränkt bestehen.exact_thread_match=Trueentspricht genau dem angegebenenthread_id. Beithread_id=Nonewerden 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 Kennzeichenexact_*_match=Falselässt diese Dimension uneingeschränkt bestehen.exact_*_match=Truestimmt genau mit der angegebenen ID überein. Wenn die IDNonelautet, 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 Kennzeichenexact_*_match=Falselässt diese Dimension uneingeschränkt bestehen.exact_*_match=Truestimmt genau mit der angegebenen ID überein. Wenn die IDNonelautet, 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. BeiFalseist diese Dimension uneingeschränkt.Truestimmt genau mit dem angegebenen Wert überein. Wenn dieser WertNonelautet, werden nur nicht kopierte Datensätze in dieser Dimension abgeglichen. - exact_agent_match
bool: Gibt an, ob jede Geltungsbereichs-ID genau abgeglichen werden muss. BeiFalseist diese Dimension uneingeschränkt.Truestimmt genau mit dem angegebenen Wert überein. Wenn dieser WertNonelautet, werden nur nicht kopierte Datensätze in dieser Dimension abgeglichen. - exact_thread_match
bool– Gibt an, ob jede Geltungsbereichs-ID genau abgeglichen werden muss. BeiFalseist diese Dimension uneingeschränkt.Truestimmt genau mit dem angegebenen Wert überein. Wenn dieser WertNonelautet, werden nur nicht kopierte Datensätze in dieser Dimension abgeglichen. - record_types
set[str] | None– Optionale Datensatztypen, die eingeschlossen werden sollen. Wenn diese Option ausgelassen wird, deckt die Suche jeden Datensatztyp ab. - 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.
- query
- Rückgaben:
(record, distance)-Paare nach zunehmender Entfernung sortiert. - Rückgabetyp: list[tuple[Record, float]]
- Gelöst: ValueError – Wenn
kkleiner als1ist.
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,factoderpreference) - record_id
str: ID der zu aktualisierenden Nachricht oder Speicherzeile. - text
str | None– Optionaler Ersatztext, der in der Spaltecontentpersistiert wird. Übergeben SieNone, um den gespeicherten Text zu löschen und die gespeicherte Einbettung zu löschen. Übergeben Sie nurNoneoder 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, wirdtexteingebettet. - einbetten
list[float] | ndarray | None– Optionaler vorab berechneter Einbettungsvektor. Wenn angegeben, wird dies direkt verwendet, und es erfolgt kein Einbettungsaufruf. Übergeben SieNone, um die gespeicherte Einbettung zu löschen. - metadata
dict[str, Any] | None– Optionale Metadatenzuordnung, die in JSON serialisiert und inmetadatagespeichert wird.
- record_type
- Rückgaben: Anzahl der aktualisierten Zeilen (
0oder1). Gibt0zurück, wenn kein logischer Datensatz mitrecord_typeundrecord_idübereinstimmt. - Rückgabetyp: int
- Raises: ValueError – Wenn
record_typenicht 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.