常見問題 (FAQ) 與疑難排解

本頁涵蓋 Oracle AI Agent Memory 的一般安裝、資料庫需求、資料庫存取及套裝程式相容性問題。

此頁面程式碼片段的 Python 命令檔 / 記事本。

安裝與升級。

為何安裝時會看到「找不到相符的發行套件」？

Oracle AI Agent Memory 支援 Python 3。10 至 3.14。如果使用 Python 3。9 安裝，pip 可能會報告一般錯誤，如下所示：

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

檢查相同的 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 或 3.14 建立新環境，然後再次安裝：

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

資料庫需求

支援哪些 Oracle AI Database 版本和搜尋策略？

Oracle 代理程式記憶體需要 Oracle AI Database 23ai (23.4) 或更新版本的資料庫備份存放區。SearchStrategy.HYBRID 還需要版本更新 23.6 或更新版本。如需完整的策略需求，包括 Oracle AI Vector Search 所需的 COMPATIBLE 設定，請參閱 Oracle AI Database 功能需求。

如何設定向量搜尋的資料庫？

Oracle AI Agent Memory 需要在 Oracle Database 中設定向量記憶體，才能使用向量搜尋或向量索引備份的綱要。如果未設定向量記憶體區域或區域太小，資料庫作業可能會因下列錯誤而失敗：

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

請參閱 ORA-51962 的 Oracle AI 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';

如果 ORA-00054 的受管理綱要設定失敗，該怎麼辦？

受管理的綱要設定可以建立向量、Oracle Text 或混合式搜尋索引。這些 DDL 作業有鎖定限制，因此忙碌的資料庫有時候可能會出現像下列這樣的錯誤：

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 已在管理向量索引、關鍵字文字索引和混合索引建立期間重試暫時 ORA-00054 失敗。如果錯誤仍然存在於您的環境中，請詢問 DBA 或授權管理員，增加階段作業 DDL_LOCK_TIMEOUT 是否適用於執行綱要設定的連線。該設定會影響 DDL 等待整個資料庫階段作業，而不僅影響 Oracle AI Agent Memory。

資料庫使用者和權限

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

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

此處的 owner 代表擁有受管理表格和索引的 Oracle AI Database 使用者。它與記憶體記錄關聯的應用程式層級使用者或代理程式無關。程式實際執行從屬端會將此資料庫使用者視為 schema_owner。

為綱要擁有者設定一個連線或集區，並為應用程式資料庫使用者設定另一個連線或集區：

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

下列範例假設您的應用程式已經設定了 embedder 和 llm。它們也會設定使用 APP_MEMORY_ 物件名稱前置碼的 memory_store_id="APP_MEMORY"。共用的 AGENT_MEMORY_STORES 表格沒有前置碼；應用程式使用者需要 SELECT，才能讀取儲存的組態。它包含此擁有者綱要中每個存放區的資料列，因此也允許讀取這些登錄資料列。請參閱下方檢視區段中的警告以取得可見性影響。

以擁有者身分啟動綱要：

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

此初始化會在以綱要擁有者身分連線時執行。如果需要，它會建立「Oracle 代理程式記憶體」在該綱要中使用的資料庫表格和內部資料庫程式碼 (PL/SQL 套裝程式)。在應用程式從屬端連線至 schema_owner 之前執行。

如果現有的資料庫表格或內部資料庫程式碼與已安裝的 Python 套裝軟體不符，一般啟動就不會取代它們。以綱要擁有者的身分連線，只有在取代指定的存放區時才可使用 SchemaPolicy.RECREATE。否則，請要求資料庫管理員在應用程式從屬端重新連線之前更新擁有者綱要。

當您刻意希望擁有者帳戶對舊版受管理綱要套用支援的非破壞性升級時，請改用 SchemaPolicy.CREATE_IF_NECESSARY。將此視為協調維護作業：執行一個綱要擁有者連線、停止寫入受管理表格的應用程式執行處理，而且不讓多個從屬端同時執行升級。升級順利完成之後，請使用 SchemaPolicy.REQUIRE_EXISTING 重新啟動應用程式執行處理。這項限制非常重要，因為受管理的升級可以執行資料備份，而且 Oracle AI Database 會以隱含方式確認 DDL 敘述句，因此升級可能會暫時顯示中間的表格資源配置。

如果升級中斷，請解決回報的資料庫問題，然後重新執行相同的綱要擁有者作業。支援的升級步驟可辨識其記載的中介狀態，且無須重新開始即可繼續。

將綱要生命週期作業 (建立、修復、升級、重新建立及刪除) 視為協調的維護工作。針對指定的記憶體存放區，一次只從一個綱要擁有者連線執行一個生命週期作業。請勿混合 Oracle Agent Memory Python 套裝程式管理與相同存放區的手動資料庫管理，而且在進行週期作業時，請勿變更受管理資料庫表格或內部資料庫程式碼。一般應用程式從屬端應該使用 SchemaPolicy.REQUIRE_EXISTING。

為何擁有者端綱要設定在建立記憶體存放區之前失敗？

在建立或開啟相同綱要存放區之前，Oracle 代理程式記憶體 Python 套裝程式可能需要建立資料庫表格，以及它在綱要擁有者帳戶中使用的內部資料庫程式碼。擁有者需要 CREATE TABLE 和 CREATE PROCEDURE，以及所選存放區功能所需的權限。例如，連結的記憶體需要 CREATE TRIGGER 和 CREATE PROPERTY GRAPH。如需特定功能的權限，請參閱開始使用代理程式記憶體。

不允許使用 schema_owner 的應用程式連線準備或變更擁有者的資料庫表格或內部資料庫程式碼。以擁有者身分連線以執行綱要生命週期作業，然後以 SchemaPolicy.REQUIRE_EXISTING 重新連線應用程式從屬端。

我應該授與唯讀程式實際執行使用者什麼權限？

要求 DBA 或授權管理員授與應用程式資料庫使用者連線所需的一般資料庫權限，例如 CREATE SESSION。然後從綱要擁有者授予受管理物件的 SELECT。這樣做可讓使用者不需編寫訊息、記憶體、執行緒或設定檔即可搜尋現有的記憶體。

以 DBA 或授權管理員身分執行此操作：

GRANT CREATE SESSION TO memory_r;

然後以 memory_owner 身分執行這些授權。物件名稱包含上述 Python 範例中使用的 APP_MEMORY_ 前置碼：

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;

我應該授與讀取 / 寫入程式實際執行使用者哪些權限？

對於建立繫線、新增訊息、新增記憶體、更新記錄或刪除記錄的應用程式資料庫使用者，請使用擁有受管理綱要的資料庫使用者，並授予該使用者資料庫所需的連線權限。

以 DBA 或授權管理員身分執行此操作：

GRANT CREATE SESSION TO memory_rw;

然後以 memory_owner 身分執行這些授權：

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;

如何將應用程式資料庫使用者存取權授予資料庫內內嵌模型？

將 OracleDBEmbedder 與其預設 provider="database" 搭配使用時，SDK 會以連線的資料庫使用者身分執行 VECTOR_EMBEDDING。使用者在「代理程式記憶體」表格上的權限未授與內嵌模型的存取權。執行內嵌 SQL 的帳戶也必須允許套用該模型。

如果資料庫使用者擁有該模型，則不需要額外的授權。如果另一個綱要擁有該模型，則模型擁有者或 DBA 必須授予程式實際執行使用者權限，才能使用該模型：

GRANT SELECT ON MINING MODEL memory_owner.DOC_MODEL TO memory_rw;

因為程式實際執行連線使用 memory_rw，所以請提供內嵌程式的完整模型名稱：

from oracleagentmemory.core.embedders import OracleDBEmbedder

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

對於需要在許多綱要中使用模型的應用程式，SELECT ANY MINING MODEL 是更廣泛的選項。若為已知模型，請使用上述特定授權。如需模型權限詳細資訊，請參閱 Oracle 的 DBMS_DATA_MINING 安全模型。

是否可以使用檢視而非 schema_owner？

是，但這是次要部署選項。當應用程式資料庫使用者可以接收擁有者綱要物件的授權時，偏好使用 schema_owner；視觀表會在資料庫設定中新增維護需求和另一個層。如果您使用視觀表，在擁有者綱要存在且應用程式資料庫使用者具有必要的直接物件授權後，請在應用程式資料庫使用者的綱要中建立相同名稱的視觀表。使用可公開完整受管理物件的簡單視觀表；這些視觀表必須可供需要寫入記錄的應用程式資料庫使用者更新。以應用程式資料庫使用者身分或具有必要檢視建立權限的 DBA，執行下列動作：

這些範例使用先前從 memory_store_id="APP_MEMORY" 衍生的 APP_MEMORY_ 字首；使用其他 ID 時，請以您自己的字首取代它。

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;

使用這些檢視時，請省略 schema_owner 並使用 SchemaPolicy.REQUIRE_EXISTING 開啟從屬端。SDK 會將視觀表驗證為現有的受管理綱要，並在擁有者綱要中留下索引和其他綱要擁有的物件。此解決方法僅支援向量模式綱要；使用 schema_owner 進行關鍵字或混合式搜尋。應用程式資料庫使用者負責保留與受管理綱要一致的視觀表：每當新的 OAM 版本新增受管理表格或變更必要的資料欄時，請先建立或更新對應的視觀表，再開啟該綱要的從屬端。

警告：此設定不會將應用程式使用者彼此隔離。memory_owner.AGENT_MEMORY_STORES 具有 memory_owner 所擁有之每個商店的資料列。此檢視會顯示所有這些列。例如，如果擁有者有 SALES 和 SUPPORT 存放區，則可以查詢此檢視的應用程式使用者可以讀取這兩個存放區的登錄詳細資訊。

OWNER_ID 保持為 memory_owner；絕不會成為應用程式使用者的 ID。使用 schema_owner 時也是如此。具有 SELECT 存取權的應用程式使用者可以讀取整個登錄檔，而不僅可讀取其開啟的商店。若要進行隔離，請將存放區放在不同的資料庫綱要中，然後個別授予存取權。

如何在授權後與程式實際執行使用者連線？

在程式實際執行時，使用擁有受管理綱要的資料庫使用者，以 SchemaPolicy.REQUIRE_EXISTING 建構從屬端：

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

唯讀使用者可以針對現有記錄呼叫搜尋 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,
    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,
)

套件相容性

如何解決套裝軟體相依性衝突？

Oracle AI Agent Memory 依賴 LiteLLM 進行模型提供者整合。較舊的 Oracle AI Agent Memory 版本 (包括 26.4.0) 使用較嚴格的 LiteLLM 上限，當其他代理程式架構或整合套件需要較新的 openai 或 python-dotenv 版本時，可能會與其他代理程式架構或整合套件衝突。

Oracle AI Agent Memory 26.8.0 使用 litellm>=1.84.0,<2，允許較新的相容 openai 與 python-dotenv 版本。如果您的解析器回報衝突：