常见问题 (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 Agent Memory 需要 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 或授权管理员为根容器和目标可插入数据库设置向量内存大小。确切值取决于数据库和工作量；此示例在根处配置 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';

如果在 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 Agent Memory 在该方案中使用的数据库表和内部数据库代码（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 Agent Memory Python 程序包可能需要创建数据库表及其在方案所有者帐户中使用的内部数据库代码。所有者需要 CREATE TABLE 和 CREATE PROCEDURE 以及所选存储功能所需的权限。例如，链接内存需要 CREATE TRIGGER 和 CREATE PROPERTY GRAPH。有关特定于功能的特权，请参见 Get Started with Agent Memory 。

不允许使用 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。它们不能使用写 API，例如 create_thread()、add_messages()、add_memory()、update() 或 delete()，除非它们还具有相应的 DML 权限。

读/写应用程序数据库用户可以使用相同的连接模式，然后调用常规的写和搜索 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 版本。如果您的解析器报告冲突：