Exécuter Oracle AI Database localement

Cet article montre comment exécuter Oracle AI Database localement avec Docker ou Podman et connecter oracleagentmemory à cette base de données.

Dans cet article, vous apprendrez à :

• Extrayez et démarrez Oracle AI Database avec Docker ou Podman.

• Facultativement, créez un utilisateur Oracle local et un espace-table pour oracleagentmemory.

• Configurez une API oracleagentmemory soutenue par Oracle avec une intégration LiteLLM et des adaptateurs de LLM.

• Vérifiez que les enregistrements persistent en rouvrant la même unité d'exécution au moyen d'une deuxième instance d'API.

Conditions requises

Installez Docker ou Podman et assurez-vous que l'interface de ligne de commande correspondante est disponible dans votre interpréteur de commandes. Ensuite, extrayez l'image Oracle AI Database Free Lite du registre Oracle Container.

Sélectionnez un mot de passe fort pour l'utilisateur Oracle SYSTEM et exportez-le avant de démarrer le conteneur :

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

Démarrer le conteneur Oracle AI Database Container

Créez un volume nommé pour que les fichiers de base de données persistent pendant les redémarrages :

Docker :

docker volume create OracleDBData

Podman :

podman volume create OracleDBData

Démarrez ensuite le conteneur :

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

Remarque : Si Podman rencontre des problèmes d'étiquetage SELinux sur RHEL, vous pouvez consulter les paramètres de configuration security-opt.

Suivez ensuite le journal du conteneur jusqu'à ce que la base de données indique qu'elle est prête.

Docker :

docker logs -f oracle-free-lite

Podman :

podman logs -f oracle-free-lite

Lorsque le journal contient DATABASE IS READY TO USE!, le module d'écoute et la base de données enfichable par défaut sont actifs.

Une fois la base de données prête, connectez-vous à la base.

Docker :

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

Podman :

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

Exécutez une interrogation simple à partir du conteneur pour confirmer que la base de données enfichable est ouverte.

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

Vous devriez voir FREEPDB1.

Entrez ensuite exit et appuyez sur Enter pour quitter SQL*Plus.

[Facultatif] Créer un utilisateur Oracle local

Si vous disposez déjà d'Oracle AI Database et d'un utilisateur d'application, ignorez cette section et passez à la section suivante, Essayez oracleagentmemory par rapport à la base de données locale. Pour une présentation plus courte de l'API elle-même, voir Stocker et rechercher de la mémoire pour un utilisateur.

L'exemple de script de cet article utilise un utilisateur de base de données local dédié :

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

Sélectionnez un mot de passe fort pour cet utilisateur d'application et exportez-le avant d'exécuter le script :

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

Créez ensuite l'utilisateur dans la base de données enfichable :

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;

Remplacez CHOOSE_A_STRONG_PASSWORD par la valeur de mot de passe que vous stockez dans ORACLE_MEMORY_DB_PASSWORD.

Vérifiez ensuite que l'utilisateur est prêt :

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 première interrogation doit afficher DMUSER_TS en tant qu'espace-table permanent. La deuxième interrogation doit afficher DMUSER avec le statut OPEN et DMUSER_TS comme espace-table par défaut. L'interrogation de privilège doit inclure au moins CREATE SESSION, CREATE TABLE, CREATE SEQUENCE, CREATE VIEW et CREATE PROCEDURE.

Essayez oracleagentmemory dans la base de données locale

Maintenant que vos paramètres de connexion Oracle sont prêts, vous pouvez pointer oracleagentmemory sur FREEPDB1 et exécuter une petite vérification de persistance de bout en bout.

L'exemple ci-dessous fait deux choses :

• Il crée une première instance d'API de mémoire d'agent qui écrit des messages et des mémoires.
• Il crée une deuxième instance d'API de mémoire d'agent qui rouvre le même thread et l'interroge de nouveau à partir d'Oracle.

Définissez les variables de connexion de l'application avant d'exécuter l'exemple. L'utilisateur et la chaîne de connexion indiqués ci-dessous correspondent à la configuration facultative précédente, mais vous pouvez les remplacer par votre propre utilisateur Oracle et votre propre nom de source de données :

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

Configurer l'API soutenue par 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,
)

Cette configuration utilise le service Oracle AI Database local ainsi que les paramètres d'intégration et d'achèvement LiteLLM de paramètre fictif que vous pouvez remplacer par les valeurs de votre fournisseur.

Écrire des enregistrements et vérifier la persistance

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

Lorsque cet exemple s'exécute avec succès, la deuxième instance d'API de mémoire d'agent imprime les messages d'unité d'exécution stockés et retourne les résultats de la recherche à partir de la base de données. Cela confirme que les enregistrements ont été conservés dans Oracle plutôt que dans la mémoire de processus.

Nettoyer

Lorsque vous avez terminé avec la base de données locale :

Docker :

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

Podman :

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

Si vous souhaitez également supprimer les fichiers de base de données persistants :

Docker :

docker volume rm OracleDBData

Podman :

podman volume rm OracleDBData

Conclusion

Dans cet article, nous avons appris à démarrer Oracle AI Database Free Lite localement avec Docker ou Podman, à préparer un utilisateur Oracle dédié et un espace-table pour oracleagentmemory, à connecter une API oracleagentmemory à cette base de données et à vérifier la persistance en rouvrant et en recherchant le même thread au moyen d'une instance d'API distincte.

Conseil : Après avoir appris à exécuter oracleagentmemory sur une base Oracle AI Database locale, vous pouvez maintenant passer à Stocker et rechercher de la mémoire pour un utilisateur.

Code complet

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