FAQ(자주 묻는 질문과 대답) 및 문제 해결

이 문서에서는 Oracle AI 에이전트 메모리에 대한 일반적인 설치, 데이터베이스 요구 사항, 데이터베이스 액세스 및 패키지 호환성 질문에 대해 다룹니다.

설치 및 업그레이드

설치 중에 "일치하는 배포판을 찾을 수 없음"이 표시되는 이유는 무엇입니까?

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

데이터베이스 유저 및 권한

한 DB 유저가 다른 DB 유저가 사용하는 동안 메모리 스키마를 생성할 수 있습니까?

권한 있는 소유자 계정을 사용하여 관리 스키마를 생성한 다음 각 런타임 사용자에게 필요한 권한만 부여합니다. 일반 응용 프로그램 시작 시에는 SchemaPolicy.REQUIRE_EXISTING를 사용해야 하므로 DB 객체를 생성하거나 변경하지 않고 스키마를 검증합니다.

스키마 소유자와 런타임 유저에 대해 하나의 연결 또는 풀을 구성합니다.

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 권한도 수신하지 않는 한 create_thread(), add_messages(), add_memory(), update() 또는 delete()와 같은 쓰기 API를 사용할 수 없습니다.

읽기/쓰기 런타임 사용자는 동일한 연결 패턴을 사용한 다음 일반 쓰기 및 검색 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에 의존합니다. 26.4.0을 포함한 이전 Oracle AI Agent Memory 릴리스는 최신 openai 또는 python-dotenv 버전이 필요할 때 다른 에이전트 프레임워크 또는 통합 패키지와 충돌할 수 있는 더 엄격한 LiteLLM 상한을 사용했습니다.

Oracle AI Agent Memory 26.6.0은 호환되는 최신 openai 및 python-dotenv 버전을 지원하는 litellm>=1.84.0,<2를 사용합니다. 분석기가 충돌을 보고하는 경우: