常見問題 (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 解譯器是否同時用於 python 和 pip：

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 或授權管理員同時調整 root 容器與目標可插式資料庫的向量記憶體大小。確實的值取決於您的資料庫與工作負載；此範例會在 root 與 256M 設定 PDB 的 512M：

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

資料庫使用者和權限

一個資料庫使用者是否可以在另一個資料庫使用者使用記憶體綱要時建立記憶體綱要？

使用授權的擁有者帳戶來建立受管理綱要，然後只授予每個程式實際執行使用者所需的權限。一般應用程式啟動應該使用 SchemaPolicy.REQUIRE_EXISTING，以便在不建立或變更資料庫物件的情況下驗證綱要。

為綱要擁有者設定一個連線或集區，並為程式實際執行使用者設定另一個連線或集區：

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。除非同時收到對應的 DML 權限，否則它們無法使用寫入 API，例如 create_thread()、add_messages()、add_memory()、update() 或 delete()。

讀取 / 寫入程式實際執行使用者可以使用相同的連線樣式，然後呼叫一般寫入和搜尋 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 版本。如果您的解析器回報衝突：