로컬에서 Oracle AI Database 실행

이 문서에서는 Docker 또는 Podman을 사용하여 로컬에서 Oracle AI Database를 실행하고 oracleagentmemory를 해당 데이터베이스에 연결하는 방법을 보여줍니다.

이 문서에서는 다음 작업을 수행하는 방법에 대해 알아봅니다.

필수 조건

Docker 또는 Podman을 설치하고 해당 CLI를 셸에서 사용할 수 있는지 확인합니다. 그런 다음 Oracle Container 레지스트리에서 Oracle AI Database Free Lite 이미지를 가져옵니다.

Oracle SYSTEM 사용자에 대한 강력한 비밀번호를 선택하고 컨테이너를 시작하기 전에 익스포트합니다.

export ORACLE_PWD='<your-secure-password>'

도커:

docker pull container-registry.oracle.com/database/free:latest-lite

Podman:

podman pull container-registry.oracle.com/database/free:latest-lite

Oracle AI Database Container 시작

재시작 후에도 데이터베이스 파일이 유지되도록 이름이 지정된 볼륨을 생성합니다.

도커:

docker volume create OracleDBData

Podman:

podman volume create OracleDBData

그런 다음 컨테이너를 시작합니다.

도커:

docker run -d \
  --name oracle-free-lite \
  -p 1521:1521 \
  -e ORACLE_PWD="$ORACLE_PWD" \
  -v OracleDBData:/opt/oracle/oradata \
  container-registry.oracle.com/database/free:latest-lite

Podman:

podman run -d \
  --name oracle-free-lite \
  -p 1521:1521 \
  -e ORACLE_PWD="$ORACLE_PWD" \
  -v OracleDBData:/opt/oracle/oradata \
  container-registry.oracle.com/database/free:latest-lite

주: Podman이 RHEL에서 SELinux 레이블 지정 문제를 발견하면 security-opt 구성 매개변수를 살펴볼 수 있습니다.

그런 다음 데이터베이스가 준비가 되었음을 보고할 때까지 컨테이너 로그를 따릅니다.

도커:

docker logs -f oracle-free-lite

Podman:

podman logs -f oracle-free-lite

로그에 DATABASE IS READY TO USE!가 포함된 경우 리스너와 기본 플러그인할 수 있는 데이터베이스가 작동 중입니다.

데이터베이스가 준비되면 데이터베이스에 연결합니다.

도커:

docker exec -it oracle-free-lite sqlplus system/"$ORACLE_PWD"@FREEPDB1

Podman:

podman exec -it oracle-free-lite sqlplus system/"$ORACLE_PWD"@FREEPDB1

컨테이너 내부에서 간단한 질의를 실행하여 PDB가 열려 있는지 확인합니다.

SELECT sys_context('USERENV', 'CON_NAME') AS container_name FROM dual;

FREEPDB1가 표시됩니다.

그런 다음 exit를 입력하고 Enter를 눌러 SQL*Plus를 종료합니다.

[선택사항] 로컬 Oracle 사용자 생성

Oracle AI Database 및 애플리케이션 사용자가 이미 있는 경우 이 섹션을 건너뛰고 다음 섹션인 로컬 데이터베이스에 대해 oracleagentmemory 시도를 계속합니다. API 자체에 대한 간단한 빠른 시작 스타일의 안내는 Store and Search Memory for One User를 참조하십시오.

이 문서의 예제 스크립트는 전용 로컬 데이터베이스 사용자를 사용합니다.

DB_USER = os.environ.get("ORACLE_MEMORY_DB_USER", "dmuser")
DB_PASSWORD = os.environ["ORACLE_MEMORY_DB_PASSWORD"]
DB_CONNECT_STRING = os.environ.get(
    "ORACLE_MEMORY_DB_CONNECT_STRING",
    "localhost:1521/FREEPDB1",
)

해당 응용 프로그램 유저에 대해 강력한 암호를 선택하고 스크립트를 실행하기 전에 엑스포트합니다.

export ORACLE_MEMORY_DB_PASSWORD='<your-app-user-password>'

그런 다음 PDB 내에 유저를 생성합니다.

도커:

docker exec -it oracle-free-lite sqlplus system/"$ORACLE_PWD"@FREEPDB1

Podman:

podman exec -it oracle-free-lite sqlplus system/"$ORACLE_PWD"@FREEPDB1
CREATE TABLESPACE dmuser_ts
DATAFILE '/opt/oracle/oradata/FREE/FREEPDB1/dmuser_ts01.dbf'
SIZE 200M
AUTOEXTEND ON NEXT 100M
SEGMENT SPACE MANAGEMENT AUTO;

CREATE USER dmuser IDENTIFIED BY "CHOOSE_A_STRONG_PASSWORD";
GRANT CREATE SESSION, CREATE TABLE, CREATE SEQUENCE, CREATE VIEW, CREATE PROCEDURE TO dmuser;
ALTER USER dmuser DEFAULT TABLESPACE dmuser_ts;
ALTER USER dmuser QUOTA UNLIMITED ON dmuser_ts;

CHOOSE_A_STRONG_PASSWORD를 ORACLE_MEMORY_DB_PASSWORD에 저장한 것과 동일한 비밀번호 값으로 바꿉니다.

그런 다음 사용자가 준비되었는지 확인합니다.

SELECT tablespace_name, contents
FROM dba_tablespaces
WHERE tablespace_name = 'DMUSER_TS';

SELECT username, account_status, default_tablespace, temporary_tablespace
FROM dba_users
WHERE username = 'DMUSER';

SELECT privilege
FROM dba_sys_privs
WHERE grantee = 'DMUSER'
ORDER BY privilege;

첫번째 질의는 DMUSER_TS를 영구 테이블스페이스로 표시해야 합니다. 두번째 질의는 OPEN 상태의 DMUSER와 기본 테이블스페이스의 DMUSER_TS를 표시해야 합니다. 권한 질의에는 CREATE SESSION, CREATE TABLE, CREATE SEQUENCE, CREATE VIEW 및 CREATE PROCEDURE 이상이 포함되어야 합니다.

로컬 데이터베이스에 대해 oracleagentmemory 시도

이제 Oracle 접속 설정이 준비되었으므로 oracleagentmemory(FREEPDB1)을 가리키고 작은 종단간 지속성 검사를 실행할 수 있습니다.

아래 예제는 다음 두 가지 작업을 수행합니다.

예제를 실행하기 전에 응용 프로그램 연결 변수를 설정합니다. 아래 표시된 사용자 및 연결 문자열은 이전 선택적 설정과 일치하지만 기존 Oracle 사용자 및 DSN으로 바꿀 수 있습니다.

export ORACLE_MEMORY_DB_USER='dmuser'
export ORACLE_MEMORY_DB_PASSWORD='<your-app-user-password>'
export ORACLE_MEMORY_DB_CONNECT_STRING='localhost:1521/FREEPDB1'

Oracle 지원 API 구성

import os

os.environ["LITELLM_LOCAL_MODEL_COST_MAP"] = "True"

import oracledb

from oracleagentmemory.core import OracleAgentMemory, SchemaPolicy
from oracleagentmemory.core.embedders.embedder import Embedder
from oracleagentmemory.core.llms.llm import Llm


embedder = Embedder(
    model="YOUR_EMBEDDING_MODEL",
    api_base="YOUR_EMBEDDING_API_BASE",
    api_key="YOUR_EMBEDDING_API_KEY",
)
llm = Llm(
    model="YOUR_LLM_MODEL",
    api_base="YOUR_LLM_API_BASE",
    api_key="YOUR_LLM_API_KEY",
)


DB_USER = os.environ.get("ORACLE_MEMORY_DB_USER", "dmuser")
DB_PASSWORD = os.environ["ORACLE_MEMORY_DB_PASSWORD"]
DB_CONNECT_STRING = os.environ.get("ORACLE_MEMORY_DB_CONNECT_STRING", "localhost:1521/FREEPDB1")
TABLE_NAME_PREFIX = "T_ORACLEMEM_DEMO_"

db_pool = oracledb.SessionPool(
    user=DB_USER,
    password=DB_PASSWORD,
    dsn=DB_CONNECT_STRING,
    min=1,
    max=4,
    increment=1,
    homogeneous=True,
)

agent_memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
    schema_policy=SchemaPolicy.RECREATE,
    table_name_prefix=TABLE_NAME_PREFIX,
)

이 구성은 자체 제공자 값으로 바꿀 수 있는 위치 표시자 LiteLLM 포함 및 완료 설정과 함께 로컬 Oracle AI Database를 사용합니다.

레코드 작성 및 지속성 확인

#Keep the same user identifier for the same end user across sessions
#so durable memory can be retrieved consistently.
user_id = "user_123"

thread = agent_memory.create_thread(user_id=user_id)
thread.add_messages(
    [
        {
            "role": "user",
            "content": "Orange juice is my usual breakfast drink.",
        },
        {
            "role": "assistant",
            "content": "Pair it with eggs, toast, or Greek yogurt.",
        },
    ]
)
thread.add_memory("The user currently prefers orange juice with breakfast.")

db_pool2 = oracledb.SessionPool(
    user=DB_USER,
    password=DB_PASSWORD,
    dsn=DB_CONNECT_STRING,
    min=1,
    max=4,
    increment=1,
    homogeneous=True,
)

agent_memory2 = OracleAgentMemory(
    connection=db_pool2,
    embedder=embedder,
    llm=llm,
    schema_policy=SchemaPolicy.REQUIRE_EXISTING,
    table_name_prefix=TABLE_NAME_PREFIX,
)
persisted_thread = agent_memory2.get_thread(thread.thread_id)

print("Messages stored in Oracle:")
print_messages(persisted_thread.get_messages())

print("\nSearch results for 'orange juice':")
print_search_results(
    agent_memory2.search(
        query="orange juice",
        user_id=user_id,
        max_results=5,
        record_types=["memory", "message"],
    )
)

이 예제가 성공적으로 실행되면 두번째 에이전트 메모리 API 인스턴스는 저장된 스레드 메시지를 인쇄하고 데이터베이스에서 검색 결과를 반환합니다. 이를 통해 레코드가 프로세스 메모리에만 보관되지 않고 Oracle에 보관되었음을 확인할 수 있습니다.

정리

로컬 데이터베이스를 사용한 경우 다음을 수행합니다.

도커:

docker stop oracle-free-lite
docker rm oracle-free-lite

Podman:

podman stop oracle-free-lite
podman rm oracle-free-lite

지속 데이터베이스 파일도 삭제하려는 경우

도커:

docker volume rm OracleDBData

Podman:

podman volume rm OracleDBData

결론

이 기사에서는 Docker 또는 Podman을 사용하여 로컬에서 Oracle AI Database Free Lite를 시작하고, oracleagentmemory에 대한 전용 Oracle 사용자 및 테이블스페이스를 준비하고, oracleagentmemory API를 해당 데이터베이스에 연결하고, 별도의 API 인스턴스를 통해 동일한 스레드를 다시 열고 검색하여 지속성을 확인하는 방법을 배웠습니다.

참고: 로컬 Oracle AI Database에 대해 oracleagentmemory를 실행하는 방법을 배웠을 때 이제 Store and Search Memory for One User로 이동할 수 있습니다.

전체 코드

#Copyright © 2026 Oracle and/or its affiliates.
#isort:skip_file
#fmt: off
#%%[markdown]
#Agent Memory Code Example - Run Oracle DB locally
#--------------------------------------------------------


#How to use:
#Create a new Python virtual environment and install the latest oracleagentmemory version.

#You can now run the script
#1. As a Python file:
#```bash
#python howto_run_oracledb.py
#```
#2. As a Notebook (in VSCode):
#When viewing the file,
#- press the keys Ctrl + Enter to run the selected cell
#- or Shift + Enter to run the selected cell and move to the cell below


##Configure the local Oracle connection

#%%
import os

os.environ["LITELLM_LOCAL_MODEL_COST_MAP"] = "True"

import oracledb

from oracleagentmemory.core import OracleAgentMemory, SchemaPolicy
from oracleagentmemory.core.embedders.embedder import Embedder
from oracleagentmemory.core.llms.llm import Llm


embedder = Embedder(
    model="YOUR_EMBEDDING_MODEL",
    api_base="YOUR_EMBEDDING_API_BASE",
    api_key="YOUR_EMBEDDING_API_KEY",
)
llm = Llm(
    model="YOUR_LLM_MODEL",
    api_base="YOUR_LLM_API_BASE",
    api_key="YOUR_LLM_API_KEY",
)


DB_USER = os.environ.get("ORACLE_MEMORY_DB_USER", "dmuser")
DB_PASSWORD = os.environ["ORACLE_MEMORY_DB_PASSWORD"]
DB_CONNECT_STRING = os.environ.get("ORACLE_MEMORY_DB_CONNECT_STRING", "localhost:1521/FREEPDB1")
TABLE_NAME_PREFIX = "T_ORACLEMEM_DEMO_"

db_pool = oracledb.SessionPool(
    user=DB_USER,
    password=DB_PASSWORD,
    dsn=DB_CONNECT_STRING,
    min=1,
    max=4,
    increment=1,
    homogeneous=True,
)

agent_memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
    schema_policy=SchemaPolicy.RECREATE,
    table_name_prefix=TABLE_NAME_PREFIX,
)


def print_messages(messages: list) -> None:
    for message in messages:
        print(f"[{message.role}] {message.content}")


def print_search_results(results: list) -> None:
    for result in results:
        print(
            f"- [{result.record.record_type}] "
            f"id={result.id} "
            f"user_id={result.record.user_id} "
            f"thread_id={result.record.thread_id} "
            f"content={result.content}"
        )


##Create data and query it

#%%
#Keep the same user identifier for the same end user across sessions so
#durable memory can be retrieved consistently.
user_id = "user_123"

thread = agent_memory.create_thread(user_id=user_id)
#add_messages will add messages to the DB and extract memories automatically
thread.add_messages(
    [
        {
            "role": "user",
            "content": "Orange juice is my usual breakfast drink.",
        },
        {
            "role": "assistant",
            "content": "Pair it with eggs, toast, or Greek yogurt.",
        },
    ]
)
#add_memory adds memory to the DB
thread.add_memory("The user currently prefers orange juice with breakfast.")

db_pool2 = oracledb.SessionPool(
    user=DB_USER,
    password=DB_PASSWORD,
    dsn=DB_CONNECT_STRING,
    min=1,
    max=4,
    increment=1,
    homogeneous=True,
)

agent_memory2 = OracleAgentMemory(
    connection=db_pool2,
    embedder=embedder,
    llm=llm,
    schema_policy=SchemaPolicy.REQUIRE_EXISTING,
    table_name_prefix=TABLE_NAME_PREFIX,
)
persisted_thread = agent_memory2.get_thread(thread.thread_id)

print("Messages stored in Oracle:")
print_messages(persisted_thread.get_messages())

print("\nSearch results for 'orange juice':")
print_search_results(
    agent_memory2.search(
        query="orange juice",
        user_id=user_id,
        max_results=5,
        record_types=["memory", "message"],
    )
)