Häufig gestellte Fragen (FAQs) und Problembehandlung

Auf dieser Seite werden allgemeine Fragen zu Installation, Datenbankanforderungen, Datenbankzugriff und Packagekompatibilität für Oracle AI Agent Memory behandelt.

Python-Skript/Notebook für die Snippets auf dieser Seite.

Installation und Upgrade

Warum wird bei der Installation "Keine übereinstimmende Verteilung gefunden" angezeigt?

Oracle AI Agent Memory unterstützt Python 3.10 bis 3.14. Wenn Sie es mit Python 3.9 installieren, meldet pip möglicherweise einen generischen Fehler wie den folgenden:

ERROR: Could not find a version that satisfies the requirement oracleagentmemory==26.8.0 (from versions: none)
ERROR: No matching distribution found for oracleagentmemory==26.8.0

Prüfen Sie, ob derselbe Python-Interpreter sowohl für python als auch für pip verwendet wird:

python --version
python -m pip --version
python -m pip install oracleagentmemory

Wenn die Version vor Python 3.10 liegt, erstellen Sie eine neue Umgebung mit Python 3.10, 3.11, 3.12, 3.13 oder 3.14, und installieren Sie erneut:

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install oracleagentmemory

Datenbankanforderungen

Welche Oracle AI Database-Versionen und Suchstrategien werden unterstützt?

Für Oracle Agent Memory ist Oracle AI Database 23ai (23.4) oder höher für den DB-Backed Store erforderlich. SearchStrategy.HYBRID erfordert zusätzlich Release Update 23.6 oder höher. Die vollständigen Strategieanforderungen, einschließlich der erforderlichen Einstellung COMPATIBLE für Oracle AI Vector Search, finden Sie unter Oracle AI Database-Featureanforderungen.

Wie sollte die Datenbank für die Vektorsuche konfiguriert werden?

Für Oracle AI Agent Memory muss der Vektorspeicher in Oracle Database konfiguriert werden, bevor Vektorsuche oder vektorindexgesicherte Schemas verwendet werden. Wenn der Vektorspeicherbereich nicht konfiguriert oder zu klein ist, können Datenbankvorgänge mit dem folgenden Fehler fehlschlagen:

ORA-51962: The vector memory area is out of space for the current container.

Weitere Informationen finden Sie in der Oracle AI Database-Fehlerhilfe für ORA-51962.

Bitten Sie einen DBA oder privilegierten Administrator, die Größe des Vektorspeichers sowohl für den Root-Container als auch für die integrierbare Zieldatenbank festzulegen. Die genauen Werte hängen von Ihrer Datenbank und Workload ab. In diesem Beispiel wird 512M in der Root und 256M für die PDB konfiguriert:

ALTER SESSION SET CONTAINER = CDB$ROOT;
ALTER SYSTEM SET vector_memory_size = 512M SCOPE=SPFILE SID='*';
SHUTDOWN IMMEDIATE;
STARTUP;
ALTER PLUGGABLE DATABASE <PDB_NAME> OPEN;
ALTER SESSION SET CONTAINER = <PDB_NAME>;
ALTER SYSTEM SET vector_memory_size = 256M SCOPE=BOTH;
SELECT value FROM v$parameter WHERE name = 'vector_memory_size';

Was geschieht, wenn das Setup des verwalteten Schemas mit ORA-00054 nicht erfolgreich verläuft?

Das Setup verwalteter Schemas kann Vektor-, Oracle Text- oder hybride Suchindizes erstellen. Diese DDL-Vorgänge sind sperrempfindlich, sodass eine ausgelastete Datenbank gelegentlich einen Fehler wie den folgenden anzeigen kann:

RuntimeError: Managed schema DDL failed (ORA-00054). Check that the database user has the
required schema privileges and quota to create, alter, and drop the SDK managed tables and
indexes. If those look correct, check for existing object-name conflicts or transient DDL
locks, then retry.

Oracle AI Agent Memory wiederholt bereits transiente ORA-00054-Fehler während der Erstellung von verwaltetem Vektorindex, Schlüsselwort-Text-Index und Hybridindex. Wenn der Fehler weiterhin in Ihrer Umgebung besteht, fragen Sie einen DBA oder einen privilegierten Administrator, ob die Erhöhung der Session DDL_LOCK_TIMEOUT für die Verbindung geeignet ist, die das Schemasetup ausführt. Diese Einstellung wirkt sich auf die DDL aus, die auf die gesamte Datenbank-Session wartet, nicht nur auf Oracle AI Agent Memory.

Datenbankbenutzer und -berechtigungen

Kann ein DB-Benutzer das Speicherschema erstellen, während ein anderer DB-Benutzer es verwendet?

Verwenden Sie einen privilegierten Eigentümeraccount, um das verwaltete Schema zu erstellen, und erteilen Sie dann nur die Berechtigungen, die für jeden Anwendungs-DB-Benutzer erforderlich sind. Beim normalen Hochfahren der Anwendung muss SchemaPolicy.REQUIRE_EXISTING verwendet werden, damit das Schema validiert wird, ohne DB-Objekte zu erstellen oder zu ändern.

Hier bedeutet owner den Oracle AI Database-Benutzer, der Eigentümer der verwalteten Tabellen und Indizes ist. Sie steht nicht im Zusammenhang mit dem Benutzer oder Agent auf Anwendungsebene, der einem Speicherdatensatz zugeordnet ist. Der Laufzeitclient verweist auf diesen Datenbankbenutzer als schema_owner.

Konfigurieren Sie eine Verbindung oder einen Pool für den Schemaeigentümer und eine andere für den Anwendungs-DB-Benutzer:

import os

from oracleagentmemory.core.embedders import Embedder
from oracleagentmemory.core.llms import Llm
import oracledb

DB_CONNECT_STRING = os.environ.get("ORACLE_MEMORY_DB_CONNECT_STRING", "localhost:1521/FREEPDB1")
OWNER_DB_USER = os.environ.get("ORACLE_MEMORY_OWNER_DB_USER", "memory_owner")
RUNTIME_DB_USER = os.environ.get("ORACLE_MEMORY_RUNTIME_DB_USER", "memory_r")
MEMORY_STORE_ID = "APP_MEMORY"

owner_pool = oracledb.SessionPool(
    user=OWNER_DB_USER,
    password=os.environ["ORACLE_MEMORY_OWNER_DB_PASSWORD"],
    dsn=DB_CONNECT_STRING,
)
runtime_pool = oracledb.SessionPool(
    user=RUNTIME_DB_USER,
    password=os.environ["ORACLE_MEMORY_RUNTIME_DB_PASSWORD"],
    dsn=DB_CONNECT_STRING,
)

Bei den folgenden Beispielen wird davon ausgegangen, dass embedder und llm bereits für Ihre Anwendung konfiguriert sind. Sie legen auch memory_store_id="APP_MEMORY" fest, das das Objektnamenspräfix APP_MEMORY_ verwendet. Die gemeinsam verwendete Tabelle AGENT_MEMORY_STORES enthält kein Präfix. Anwendungsbenutzer benötigen SELECT, damit sie die gespeicherte Konfiguration des Speichers lesen können. Er enthält Zeilen für jeden Speicher in diesem Eigentümerschema, sodass er auch das Lesen dieser Registry-Zeilen zulässt. Die Auswirkungen auf die Sichtbarkeit finden Sie in der folgenden Warnung im Abschnitt "Ansichten".

Bootstrap für das Schema als Eigentümer:

from oracleagentmemory.core import (
    OracleAgentMemory,
    SchemaPolicy,
)

owner_memory = OracleAgentMemory(
    connection=owner_pool,
    embedder=embedder,
    llm=llm,
    schema_policy=SchemaPolicy.CREATE_IF_EMPTY,
    memory_store_id=MEMORY_STORE_ID,
)

Diese Initialisierung wird ausgeführt, während sie als Schemaeigentümer angemeldet ist. Bei Bedarf werden die Datenbanktabellen und der interne Datenbankcode (PL/SQL-Package) erstellt, den Oracle Agent Memory in diesem Schema verwendet. Führen Sie ihn aus, bevor sich Anwendungsclients mit schema_owner verbinden.

Wenn die vorhandenen Datenbanktabellen oder der interne Datenbankcode nicht mit dem installierten Python-Package übereinstimmen, werden sie beim normalen Hochfahren nicht ersetzt. Melden Sie sich als Schemaeigentümer an, und verwenden Sie SchemaPolicy.RECREATE nur, wenn Sie den benannten Speicher ersetzen. Bitten Sie andernfalls den Datenbankadministrator, das Eigentümerschema zu aktualisieren, bevor sich die Anwendungsclients erneut verbinden.

Verwenden Sie stattdessen SchemaPolicy.CREATE_IF_NECESSARY, wenn der Eigentümeraccount absichtlich unterstützte nicht-destruktive Upgrades für ein älteres verwaltetes Schema anwenden soll. Behandeln Sie dies als koordinierten Wartungsvorgang: Führen Sie eine Verbindung mit einem Schemaeigentümer aus, stoppen Sie Anwendungsinstanzen, die in die verwalteten Tabellen schreiben, und lassen Sie das Upgrade nicht von mehreren Clients gleichzeitig ausführen. Nachdem das Upgrade erfolgreich abgeschlossen wurde, starten Sie Anwendungsinstanzen mit SchemaPolicy.REQUIRE_EXISTING neu. Diese Einschränkung ist wichtig, da verwaltete Upgrades Daten-Backfills ausführen können und Oracle AI Database DDL-Anweisungen implizit festschreibt, sodass ein Upgrade temporär Ausprägungen von Zwischentabellen verfügbar machen kann.

Wenn ein Upgrade unterbrochen wird, beheben Sie das gemeldete Datenbankproblem, und führen Sie denselben Vorgang für den Schemaeigentümer erneut aus. Unterstützte Upgradeschritte erkennen ihre dokumentierten Zwischenstatuswerte und können ohne Neustart fortgesetzt werden.

Behandeln Sie Schema-Lebenszyklusvorgänge (Erstellung, Reparatur, Upgrade, Neuerstellung und Löschen) als koordinierte Wartungsarbeiten. Führen Sie für einen bestimmten Speicherspeicher jeweils nur einen Lebenszyklusvorgang von einer Verbindung mit einem Schemaeigentümer aus. Mischen Sie die Oracle Agent Memory Python-Packageadministration nicht mit der manuellen Datenbankadministration für denselben Speicher, und ändern Sie die verwalteten Datenbanktabellen oder den internen Datenbankcode nicht, während ein Lebenszyklusvorgang ausgeführt wird. Normale Anwendungsclients müssen SchemaPolicy.REQUIRE_EXISTING verwenden.

Warum schlägt das Schema-Setup auf Eigentümerseite vor dem Erstellen eines Speichers fehl?

Bevor ein Same-Schema-Speicher erstellt oder geöffnet wird, muss das Oracle Agent Memory-Python-Package möglicherweise die Datenbanktabellen und den internen Datenbankcode erstellen, die im Account des Schemaeigentümers verwendet werden. Der Eigentümer benötigt CREATE TABLE und CREATE PROCEDURE sowie die Berechtigungen, die für die ausgewählten Speicherfeatures erforderlich sind. Beispiel: Für den verknüpften Speicher sind CREATE TRIGGER und CREATE PROPERTY GRAPH erforderlich. Die funktionsspezifischen Berechtigungen finden Sie unter Erste Schritte mit Agent-Speicher.

Eine Anwendungsverbindung, die schema_owner verwendet, darf die Datenbanktabellen oder den internen Datenbankcode des Eigentümers nicht vorbereiten oder ändern. Melden Sie sich als Eigentümer an, um Lebenszyklusvorgänge des Schemas auszuführen, und verbinden Sie Anwendungsclients erneut mit SchemaPolicy.REQUIRE_EXISTING.

Welche Berechtigungen sollte ich einem schreibgeschützten Laufzeitbenutzer erteilen?

Bitten Sie einen DBA oder privilegierten Administrator, dem Anwendungs-DB-Benutzer die normale Datenbankberechtigung zu erteilen, die für die Anmeldung erforderlich ist, wie CREATE SESSION. Erteilen Sie dann SELECT für die verwalteten Objekte vom Schemaeigentümer. Auf diese Weise kann der Benutzer vorhandene Speicher durchsuchen, ohne Nachrichten, Speicher, Threads oder Profile zu schreiben.

Führen Sie diesen Vorgang als DBA- oder privilegierter Administrator aus:

GRANT CREATE SESSION TO memory_r;

Führen Sie diese Berechtigungen dann als memory_owner aus. Die Objektnamen umfassen das Präfix APP_MEMORY_, das in den Python-Beispielen oben verwendet wird:

GRANT SELECT ON memory_owner.AGENT_MEMORY_STORES TO memory_r;
GRANT EXECUTE ON memory_owner.DBMS_AGENT_MEMORY_STORE TO memory_r;
GRANT SELECT ON memory_owner.APP_MEMORY_THREAD TO memory_r;
GRANT SELECT ON memory_owner.APP_MEMORY_ACTOR_PROFILE TO memory_r;
GRANT SELECT ON memory_owner.APP_MEMORY_MESSAGE TO memory_r;
GRANT SELECT ON memory_owner.APP_MEMORY_MEMORY TO memory_r;
GRANT SELECT ON memory_owner.APP_MEMORY_RECORD_CHUNKS TO memory_r;

Welche Berechtigungen sollte ich einem Laufzeitbenutzer mit Lese-/Schreibzugriff erteilen?

Verwenden Sie für einen Anwendungs-DB-Benutzer, der Threads erstellt, Nachrichten hinzufügt, Speicherungen hinzufügt, Datensätze aktualisiert oder Datensätze löscht, den Datenbankbenutzer, der Eigentümer des verwalteten Schemas ist, und erteilen Sie ihm die für die Datenbank erforderliche Verbindungsberechtigung.

Führen Sie diesen Vorgang als DBA- oder privilegierter Administrator aus:

GRANT CREATE SESSION TO memory_rw;

Führen Sie dann die folgenden Berechtigungen als memory_owner aus:

GRANT SELECT ON memory_owner.AGENT_MEMORY_STORES TO memory_rw;
GRANT EXECUTE ON memory_owner.DBMS_AGENT_MEMORY_STORE TO memory_rw;
GRANT SELECT, INSERT, UPDATE, DELETE ON memory_owner.APP_MEMORY_THREAD TO memory_rw;
GRANT SELECT, INSERT, UPDATE, DELETE ON memory_owner.APP_MEMORY_ACTOR_PROFILE TO memory_rw;
GRANT SELECT, INSERT, UPDATE, DELETE ON memory_owner.APP_MEMORY_MESSAGE TO memory_rw;
GRANT SELECT, INSERT, UPDATE, DELETE ON memory_owner.APP_MEMORY_MEMORY TO memory_rw;
GRANT SELECT, INSERT, UPDATE, DELETE ON memory_owner.APP_MEMORY_RECORD_CHUNKS TO memory_rw;

Wie erteile ich einem Anwendungs-DB-Benutzer Zugriff auf ein datenbankinternes Einbettungsmodell?

Wenn Sie OracleDBEmbedder mit dem Standard provider="database" verwenden, führt das SDK VECTOR_EMBEDDING als angemeldeten Datenbankbenutzer aus. Die Berechtigungen des Benutzers für die Agent-Speichertabellen erteilen keinen Zugriff auf das Einbettungsmodell. Das Konto, auf dem die Einbettungs-SQL ausgeführt wird, muss auch berechtigt sein, dieses Modell anzuwenden.

Wenn der Datenbankbenutzer Eigentümer des Modells ist, ist keine zusätzliche Berechtigung erforderlich. Wenn ein anderes Schema Eigentümer des Modells ist, muss der Modelleigentümer oder ein DBA dem Laufzeitbenutzer die Berechtigung zur Verwendung dieses Modells erteilen:

GRANT SELECT ON MINING MODEL memory_owner.DOC_MODEL TO memory_rw;

Da die Laufzeitverbindung memory_rw verwendet, geben Sie dem Embedder den vollständigen Modellnamen:

from oracleagentmemory.core.embedders import OracleDBEmbedder

db_embedder = OracleDBEmbedder(
    connection=runtime_pool,
    model="MEMORY_OWNER.DOC_MODEL",
    embedding_dimension=384,
)

SELECT ANY MINING MODEL ist eine umfassendere Option für Anwendungen, die Modelle in vielen Schemas verwenden müssen. Verwenden Sie für ein bekanntes Modell die oben angegebene Berechtigung. Die Modellberechtigungsdetails finden Sie im Oracle-Sicherheitsmodell DBMS_DATA_MINING.

Kann ich Ansichten anstelle von schema_owner verwenden?

Ja, aber dies ist eine sekundäre Deployment-Option. Wählen Sie schema_owner, wenn der Anwendungs-DB-Benutzer Berechtigungen für die Objekte des Eigentümerschemas erhalten kann. Views fügen dem Datenbanksetup eine Wartungsanforderung und eine weitere Schicht hinzu. Wenn Sie Views verwenden, nachdem das Eigentümerschema vorhanden ist und der Anwendungs-DB-Benutzer über die erforderlichen direkten Objektberechtigungen verfügt, erstellen Sie gleichnamige Views im Schema des Anwendungs-DB-Benutzers. Verwenden Sie einfache Views, in denen die vollständigen verwalteten Objekte angezeigt werden. Diese Views müssen für Anwendungs-DB-Benutzer, die Datensätze schreiben müssen, aktualisierbar sein. Führen Sie Folgendes als Anwendungs-DB-Benutzer oder über einen DBA mit der erforderlichen Berechtigung zum Erstellen von Ansichten aus:

In den Beispielen wird das von memory_store_id="APP_MEMORY" abgeleitete Präfix APP_MEMORY_ verwendet. Ersetzen Sie es durch Ihr eigenes Präfix, wenn Sie eine andere ID verwenden.

CREATE VIEW AGENT_MEMORY_STORES AS
   SELECT * FROM memory_owner.AGENT_MEMORY_STORES;
CREATE VIEW APP_MEMORY_THREAD AS
   SELECT * FROM memory_owner.APP_MEMORY_THREAD;
CREATE VIEW APP_MEMORY_ACTOR_PROFILE AS
   SELECT * FROM memory_owner.APP_MEMORY_ACTOR_PROFILE;
CREATE VIEW APP_MEMORY_MESSAGE AS
   SELECT * FROM memory_owner.APP_MEMORY_MESSAGE;
CREATE VIEW APP_MEMORY_MEMORY AS
   SELECT * FROM memory_owner.APP_MEMORY_MEMORY;
CREATE VIEW APP_MEMORY_RECORD_CHUNKS AS
   SELECT * FROM memory_owner.APP_MEMORY_RECORD_CHUNKS;

Wenn Sie diese Ansichten verwenden, lassen Sie schema_owner weg, und öffnen Sie den Client mit SchemaPolicy.REQUIRE_EXISTING. Das SDK validiert die Views als das vorhandene verwaltete Schema und hinterlässt Indizes und andere Schemaeigene Objekte im Eigentümerschema. Diese Workaround wird nur für Vektormodusschemas unterstützt. Verwenden Sie schema_owner für die Schlüsselwort- oder Hybridsuche. Der Anwendungs-DB-Benutzer ist dafür verantwortlich, die Ansichten an das verwaltete Schema anzupassen: Wenn eine neue OAM-Version eine verwaltete Tabelle hinzufügt oder die erforderlichen Spalten ändert, erstellen oder aktualisieren Sie die entsprechende Ansicht, bevor Sie den Client für dieses Schema öffnen.

Warnung: Dieses Setup isoliert keine Anwendungsbenutzer voneinander. memory_owner.AGENT_MEMORY_STORES enthält eine Zeile für jeden Speicher, der zu memory_owner gehört. Die Ansicht zeigt alle diese Zeilen an. Beispiel: Wenn der Eigentümer SALES- und SUPPORT-Speicher hat, kann ein App-Benutzer, der diese Ansicht abfragen kann, Registry-Details für beide Speicher lesen.

OWNER_ID bleibt als memory_owner bestehen. Es wird nie zur ID des App-Benutzers. Dasselbe gilt für die Verwendung von schema_owner. Ein App-Benutzer mit SELECT-Zugriff kann die gesamte Registry lesen, nicht nur den Speicher, den er öffnet. Legen Sie zur Isolation Speicher in verschiedenen Datenbankschemas ab, und erteilen Sie den Zugriff separat.

Wie stelle ich nach den Berechtigungen eine Verbindung zum Laufzeitbenutzer her?

Erstellen Sie zur Laufzeit den Client mit SchemaPolicy.REQUIRE_EXISTING mit dem Datenbankbenutzer, der Eigentümer des verwalteten Schemas ist:

from oracleagentmemory.core import OracleAgentMemory, SchemaPolicy

memory = OracleAgentMemory(
    connection=runtime_pool,
    embedder=embedder,
    llm=llm,
    schema_policy=SchemaPolicy.REQUIRE_EXISTING,
    memory_store_id=MEMORY_STORE_ID,
    #Schema owner of the tables; this avoids ALTER SESSION
    #SET CURRENT_SCHEMA for the runtime connection.
    schema_owner=OWNER_DB_USER,
)

Schreibgeschützte Benutzer können Such-APIs für vorhandene Datensätze aufrufen. Sie können keine Schreib-APIs wie create_thread(), add_messages(), add_memory(), update() oder delete() verwenden, es sei denn, sie erhalten auch die entsprechenden DML-Berechtigungen.

Ein DB-Benutzer der Lese-/Schreibanwendung kann dasselbe Verbindungsmuster verwenden und dann die normalen Schreib- und Such-APIs aufrufen:

memory = OracleAgentMemory(
    connection=runtime_pool,
    embedder=embedder,
    llm=llm,
    schema_policy=SchemaPolicy.REQUIRE_EXISTING,
    memory_store_id=MEMORY_STORE_ID,
)

thread = memory.create_thread(user_id="user_123")
thread.add_memory("The user prefers concise answers.")

results = memory.search(
    "concise answers",
    user_id="user_123",
    record_types=["memory"],
    max_results=5,
)

Paketkompatibilität

Wie löse ich Packageabhängigkeitskonflikte auf?

Oracle AI Agent Memory ist für die Integration von Modell-Provider auf LiteLLM angewiesen. Ältere Oracle AI Agent Memory-Releases, einschließlich 26.4.0, verwendeten eine engere LiteLLM-Obergrenze, die mit anderen Agent-Frameworks oder Integrationspaketen in Konflikt stehen könnte, wenn neuere openai- oder python-dotenv-Versionen erforderlich waren.

Oracle AI Agent Memory 26.8.0 verwendet litellm>=1.84.0,<2, wodurch neuere kompatible openai- und python-dotenv-Versionen zulässig sind. Wenn Ihr Resolver einen Konflikt meldet: