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 에이전트 메모리에는 DB 지원 저장소에 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 작업은 Lock에 민감하므로 사용량이 많은 데이터베이스에서 다음과 같은 오류가 발생할 수 있습니다.

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 장애를 재시도하고 있습니다. 사용자 환경에서 오류가 계속 발생하면 DDL_LOCK_TIMEOUT 세션을 늘리는 것이 스키마 설정을 실행하는 연결에 적합한지 여부를 DBA 또는 권한 있는 관리자에게 문의하십시오. 이 설정은 Oracle AI Agent Memory뿐만 아니라 전체 데이터베이스 세션을 대기하는 DDL에 영향을 줍니다.

데이터베이스 유저 및 권한

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

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

여기서 owner은 관리 테이블 및 인덱스를 소유하는 Oracle AI Database 사용자를 의미합니다. 메모리 레코드와 연관된 응용 프로그램 레벨 사용자 또는 에이전트와 관련이 없습니다. 런타임 클라이언트는 이 데이터베이스 사용자를 schema_owner로 참조합니다.

스키마 소유자와 응용 프로그램 DB 유저에 대해 하나의 연결 또는 풀을 구성합니다.

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가 필요합니다. 기능별 권한은 에이전트 메모리 시작하기를 참조하십시오.

schema_owner를 사용하는 애플리케이션 연결은 소유자의 데이터베이스 테이블 또는 내부 데이터베이스 코드를 준비하거나 변경할 수 없습니다. 소유자로 연결하여 스키마 수명 주기 작업을 수행한 다음 SchemaPolicy.REQUIRE_EXISTING로 애플리케이션 클라이언트를 다시 연결합니다.

읽기 전용 런타임 사용자에게 어떤 권한을 부여해야 합니까?

DBA 또는 권한이 있는 관리자에게 CREATE SESSION과 같이 응용 프로그램 DB 사용자에게 연결에 필요한 일반 데이터베이스 권한을 부여하도록 요청합니다. 그런 다음 스키마 소유자의 관리 객체에 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;

읽기/쓰기 런타임 사용자에게 어떤 권한을 부여해야 합니까?

스레드를 생성하거나, 메시지를 추가하거나, 메모리를 추가하거나, 레코드를 업데이트하거나, 삭제하는 애플리케이션 DB 사용자의 경우 관리 스키마를 소유하는 데이터베이스 사용자를 사용하고 데이터베이스에 필요한 연결 권한을 부여합니다.

이 작업을 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;

애플리케이션 DB 사용자에게 데이터베이스 내 임베딩 모델에 대한 액세스 권한을 부여하려면 어떻게 해야 합니까?

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 대신 뷰를 사용할 수 있습니까?

예. 이 옵션은 보조 배포 옵션입니다. 애플리케이션 DB 사용자가 소유자 스키마의 객체에 대한 권한 부여를 수신할 수 있는 경우 schema_owner을 선호합니다. 뷰는 데이터베이스 설정에 유지 관리 요구 사항 및 다른 계층을 추가합니다. 뷰를 사용하는 경우 소유자 스키마가 존재하고 응용 프로그램 DB 유저에게 필요한 직접 객체 권한 부여가 있으면 응용 프로그램 DB 유저의 스키마에 동일한 이름의 뷰를 생성합니다. 전체 관리 객체를 나타내는 간단한 뷰를 사용합니다. 이러한 뷰는 레코드를 작성해야 하는 응용 프로그램 DB 유저에 대해 갱신할 수 있어야 합니다. 응용 프로그램 DB 유저로 또는 필요한 뷰 생성 권한을 가진 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를 사용하십시오. 응용 프로그램 DB 유저는 관리 스키마에 맞게 뷰를 유지해야 합니다. 새 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 권한도 수신하지 않는 한 create_thread(), add_messages(), add_memory(), update() 또는 delete()와 같은 쓰기 API를 사용할 수 없습니다.

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

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