Häufig gestellte Fragen (FAQs) und Problembehandlung

In diesem Artikel werden allgemeine Fragen zu Installation, Datenbankanforderungen, Datenbankzugriff und Packagekompatibilität für Oracle AI Agent Memory behandelt.

Installation und Upgrade

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

Der Oracle AI Agent-Speicher unterstützt Python 3.10 bis 3.13. 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.4.0 (from versions: none)
ERROR: No matching distribution found for oracleagentmemory==26.4.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 oder 3.13, und installieren Sie erneut:

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

Python 3.14 wird derzeit nicht unterstützt, da das Package dem unterstützten Python-Bereich seiner LiteLLM-Abhängigkeit folgt.

Datenbankanforderungen

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

Für den Oracle AI Agent-Speicher 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 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';

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 Laufzeitbenutzer 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.

Konfigurieren Sie eine Verbindung oder einen Pool für den Schemaeigentümer und eine andere für den Laufzeitbenutzer:

import os

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. Wenn Sie dieses Argument weglassen, verwenden Sie die Namen nicht vorangestellter verwalteter Objekte in Ihren Berechtigungen.

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

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.

Welche Berechtigungen sollte ich einem schreibgeschützten Laufzeitbenutzer erteilen?

Bitten Sie einen DBA oder privilegierten Administrator, dem Laufzeitbenutzer die normale Datenbankberechtigung zu erteilen, die für die Verbindung 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.APP_MEMORY_ORACLEAGENTMEMORY_SCHEMA_META 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?

Für einen Laufzeitbenutzer, der Threads erstellt, Nachrichten hinzufügt, Erinnerungen hinzufügt, Datensätze aktualisiert oder Datensätze löscht, erteilen Sie die Verbindungsberechtigung und DML für die verwalteten Tabellen.

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.APP_MEMORY_ORACLEAGENTMEMORY_SCHEMA_META 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 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,
    schema_policy=SchemaPolicy.REQUIRE_EXISTING,
)

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 Laufzeitbenutzer mit Lese-/Schreibzugriff 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,
)

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 hängt von LiteLLM für die Modell-Provider-Integration ab. Ä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.6.0 verwendet litellm>=1.84.0,<2, was neuere kompatible openai- und python-dotenv-Versionen zulässt. Wenn Ihr Resolver einen Konflikt meldet: