常见问题 (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

Python 3。14 当前不受支持，因为软件包遵循其 LiteLLM 依赖性的受支持 Python 范围。

数据库需求

应如何配置数据库以进行向量搜索？

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

数据库用户和权限

一个数据库用户是否可以在另一个数据库用户使用内存方案时创建内存方案？

使用授权所有者帐户创建托管方案，然后仅授予每个运行时用户所需的权限。常规应用程序启动应使用 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。它们还设置了 memory_store_id="APP_MEMORY"，该参数使用 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。它们不能使用写 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,
)

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 版本。如果您的解析器报告冲突：