よく ある質問(FAQ)と トラブルシューティング

この記事では、Oracle AI Agent Memoryの一般的なインストール、データベース要件、データベース・アクセスおよびパッケージ互換性の質問について説明します。

インストールおよびアップグレード

インストール中に「一致するディストリビューションが見つかりません」と表示されるのはなぜですか。

Oracle AI Agent Memoryは、Python 3.10から3.13をサポートしています。Python 3.9を使用してインストールした場合、pipは、次のような汎用エラーを報告することがあります:

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

pythonとpipの両方に同じPythonインタプリタが使用されていることを確認します。

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

バージョンが Python 3.10より前の場合は、Python 3.10、3.11、3.12、または3.13で新しい環境を作成し、再度インストールします。

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

パッケージがLiteLLM依存関係のサポートされる Python範囲に従っているため、Python 3.14は現在サポートされていません。

データベースの要件

データベースをベクトル検索用にどのように構成しますか。

Oracle AI Agent Memoryでは、ベクトル検索またはベクトル索引でバックアップされたスキーマを使用する前に、Oracle Databaseでベクトル・メモリーを構成する必要があります。ベクトル・メモリー領域が構成されていないか、小さすぎる場合、データベース操作は次のエラーで失敗する可能性があります。

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

ORA-51962のOracle Databaseエラー・ヘルプを参照してください。

DBAまたは特権管理者に、ルート・コンテナとターゲット・プラガブル・データベースの両方のベクトル・メモリーのサイズを尋ねます。正確な値は、データベースおよびワークロードによって異なります。この例では、ルートで512M、PDBで256Mを構成します。

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';

データベース・ユーザーおよび権限

あるDBユーザーがメモリー・スキーマを作成し、別のDBユーザーがそれを使用することはできますか。

特権所有者アカウントを使用して管理対象スキーマを作成し、各ランタイム・ユーザーに必要な権限のみを付与します。通常のアプリケーションの起動では、SchemaPolicy.REQUIRE_EXISTINGを使用して、DBオブジェクトを作成または変更せずにスキーマを検証する必要があります。

スキーマ所有者用に1つの接続またはプールを構成し、ランタイム・ユーザー用に別の接続またはプールを構成します。

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

次の例では、embedderおよびllmがアプリケーションにすでに構成されていることを前提としています。また、APP_MEMORY_オブジェクト名の接頭辞を使用するmemory_store_id="APP_MEMORY"も設定します。この引数を省略した場合は、接頭辞のない管理対象オブジェクト名を権限で使用します。

スキーマを所有者としてブートストラップします。

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

古い管理対象スキーマに対して、所有者アカウントがサポートされる非破壊アップグレードを意図的に適用する場合は、かわりにSchemaPolicy.CREATE_IF_NECESSARYを使用します。

読取り専用ランタイム・ユーザーにどのような権限を付与する必要がありますか。

DBAまたは特権管理者に、接続に必要な通常のデータベース権限(CREATE SESSIONなど)をランタイム・ユーザーに付与するよう依頼します。次に、スキーマ所有者から管理対象オブジェクトにSELECTを付与します。これにより、ユーザーはメッセージ、メモリ、スレッド、またはプロファイルを記述せずに、既存のメモリを検索できます。

これをDBAまたは特権管理者として実行します。

GRANT CREATE SESSION TO memory_r;

次に、これらの権限をmemory_ownerとして実行します。オブジェクト名には、前述のPythonの例で使用されるAPP_MEMORY_接頭辞が含まれます。

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;

読取り/書込みランタイム・ユーザーにどのような権限を付与する必要がありますか。

スレッドの作成、メッセージの追加、メモリーの追加、レコードの更新または削除を実行するランタイム・ユーザーには、管理対象表に対する接続権限およびDMLを付与します。

これをDBAまたは特権管理者として実行します。

GRANT CREATE SESSION TO memory_rw;

次に、次の権限付与をmemory_ownerとして実行します。

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;

権限付与後にランタイム・ユーザーと接続するにはどうすればよいですか。

実行時に、管理対象スキーマを所有するデータベース・ユーザーを使用して、SchemaPolicy.REQUIRE_EXISTINGでクライアントを構築します。

from oracleagentmemory.core import OracleAgentMemory, SchemaPolicy

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

読取り専用ユーザーは、既存のレコードに対して検索APIをコールできます。create_thread()、add_messages()、add_memory()、update()、delete()などの書込みAPIは、対応するDML権限も受け取らないかぎり使用できません。

読取り/書込みランタイム・ユーザーは、同じ接続パターンを使用し、通常の書込みおよび検索APIをコールできます。

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

パッケージの互換性

パッケージ依存関係の競合を解決するにはどうすればよいですか。

Oracle AI Agent Memoryは、モデル・プロバイダの統合のためにLiteLLMに依存しています。古いOracle AI Agent Memoryリリース(26.4.0を含む)では、より厳密なLiteLLM上限が使用され、新しいopenaiまたはpython-dotenvバージョンが必要になったときに他のエージェント・フレームワークまたは統合パッケージと競合する可能性があります。

Oracle AI Agent Memory 26.6.0では、litellm>=1.84.0,<2を使用して、より新しい互換性のあるopenaiおよびpython-dotenvバージョンを使用できます。リゾルバが競合を報告する場合: