Esegui Oracle AI Database localmente

Questo articolo mostra come eseguire Oracle AI Database localmente con Docker o Podman e connettere oracleagentmemory a tale database.

In questo articolo imparerai come:

Prerequisiti

Installare Docker o Podman e assicurarsi che l'interfaccia CLI corrispondente sia disponibile nella shell. Quindi estrarre l'immagine di Oracle AI Database Free Lite dal registro Oracle Container.

Scegliere una password sicura per l'utente SYSTEM Oracle ed esportarla prima di avviare il contenitore:

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

Docker:

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

Podman:

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

Avviare Oracle AI Database Container

Creare un volume denominato in modo che i file del database siano persistenti tra i riavvii:

Docker:

docker volume create OracleDBData

Podman:

podman volume create OracleDBData

Quindi avviare il contenitore:

Docker:

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

Nota: se Podman riscontra problemi di etichettatura SELinux su RHEL, è possibile esaminare i parametri di configurazione security-opt.

Quindi seguire il log del contenitore fino a quando il database segnala che è pronto.

Docker:

docker logs -f oracle-free-lite

Podman:

podman logs -f oracle-free-lite

Quando il log contiene DATABASE IS READY TO USE!, il listener e il pluggable database predefinito sono attivi.

Una volta che il database è pronto, connettersi al database.

Docker:

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

Podman:

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

Eseguire una query semplice dall'interno del contenitore per confermare che il PDB è aperto.

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

Si veda FREEPDB1.

Immettere quindi exit e premere Enter per uscire da SQL*Plus.

[Facoltativo] Creare un utente Oracle locale

Se si dispone già di un Oracle AI Database e di un utente dell'applicazione, saltare questa sezione e continuare con la sezione successiva, Prova oracleagentmemory con il database locale. Per un'introduzione rapida più breve all'API stessa, vedere Memorizza e cerca memoria per un utente.

Lo script di esempio in questo articolo utilizza un utente di database locale dedicato:

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",
)

Scegliere una password sicura per l'utente dell'applicazione ed esportarla prima di eseguire lo script:

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

Quindi creare l'utente all'interno del PDB:

Docker:

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;

Sostituire CHOOSE_A_STRONG_PASSWORD con lo stesso valore di password memorizzato in ORACLE_MEMORY_DB_PASSWORD.

Verificare che l'utente sia pronto:

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;

La prima query deve mostrare DMUSER_TS come tablespace permanente. La seconda query deve mostrare DMUSER con lo stato OPEN e DMUSER_TS come tablespace predefinita. La query dei privilegi deve includere almeno CREATE SESSION, CREATE TABLE, CREATE SEQUENCE, CREATE VIEW e CREATE PROCEDURE.

Prova oracleagentmemory nel database locale

Ora che le impostazioni di connessione Oracle sono pronte, puoi puntare a oracleagentmemory all'indirizzo FREEPDB1 ed eseguire un piccolo controllo di persistenza end-to-end.

L'esempio seguente fa due cose:

Impostare le variabili di connessione all'applicazione prima di eseguire l'esempio. L'utente e la stringa di connessione riportati di seguito corrispondono all'impostazione facoltativa precedente, ma è possibile sostituirli con l'utente Oracle e il DSN esistenti:

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

Configurare l'API supportata da Oracle

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,
)

Questa configurazione utilizza Oracle AI Database locale insieme alle impostazioni di incorporamento e completamento LiteLLM segnaposto che è possibile sostituire con i valori del provider.

Scrivere record e verificare la persistenza

#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"],
    )
)

Quando questo esempio viene eseguito correttamente, la seconda istanza dell'API di memoria agente stampa i messaggi dei thread memorizzati e restituisce i risultati della ricerca dal database. Ciò conferma che i record sono stati resi persistenti in Oracle anziché conservati solo nella memoria del processo.

Cleanup

Al termine dell'operazione con il database locale:

Docker:

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

Podman:

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

Se si desidera eliminare anche i file di database persistenti:

Docker:

docker volume rm OracleDBData

Podman:

podman volume rm OracleDBData

Conclusione

In questo articolo abbiamo imparato come avviare Oracle AI Database Free Lite in locale con Docker o Podman, preparare un utente Oracle dedicato e una tablespace per oracleagentmemory, connettere un'API oracleagentmemory a tale database e verificare la persistenza riaprendo e cercando lo stesso thread tramite un'istanza API separata.

Suggerimento: dopo aver appreso come eseguire oracleagentmemory su un Oracle AI Database locale, è ora possibile passare a Memorizza e cerca memoria per un utente.

Codice completo

#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"],
    )
)