Questions fréquentes (FAQ) et résolution des problèmes

Cet article traite des questions courantes d'installation, de configuration requise de la base de données, d'accès à la base de données et de compatibilité des packages pour la mémoire de l'agent Oracle AI.

Installation et mise à niveau

Pourquoi "Aucune distribution correspondante n'a été trouvée" lors de l'installation ?

La mémoire de l'agent Oracle AI prend en charge Python 3.10 à 3.13. Si vous l'installez avec Python 3.9, pip peut signaler une erreur générique comme celle-ci :

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

Vérifiez que le même interpréteur Python est utilisé pour python et pip :

python --version
python -m pip --version
python -m pip install oracleagentmemory

Si la version est antérieure à Python 3.10, créez un nouvel environnement avec Python 3.10, 3.11, 3.12 ou 3.13 et installez à nouveau :

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install oracleagentmemory

Python 3.14 n'est pas pris en charge actuellement car le package suit la plage Python prise en charge de sa dépendance LiteLLM.

Configuration requise pour la base de données

Comment la base de données doit-elle être configurée pour la recherche de vecteurs ?

La mémoire de l'agent Oracle AI nécessite que la mémoire vectorielle soit configurée dans Oracle Database avant d'utiliser la recherche vectorielle ou les schémas soutenus par index vectoriel. Si la zone de mémoire vectorielle n'est pas configurée ou est trop petite, les opérations de base de données peuvent échouer avec l'erreur suivante :

ORA-51962: The vector memory area is out of space for the current container.

Reportez-vous à l'aide d'erreur d'Oracle Database pour ORA-51962.

Demandez à un administrateur de base de données ou à un administrateur privilégié de dimensionner la mémoire vectorielle pour le conteneur racine et la base de données pluggable cible. Les valeurs exactes dépendent de la base de données et de la charge globale. Dans cet exemple, 512M est configuré à la racine et 256M pour la base de données pluggable :

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

Utilisateurs et privilèges de base de donnée

Un utilisateur de base de données peut-il créer le schéma de mémoire lorsqu'un autre utilisateur de base de données l'utilise ?

Utilisez un compte propriétaire privilégié pour créer le schéma géré, puis accordez uniquement les privilèges requis par chaque utilisateur runtime. Le démarrage normal de l'application doit utiliser SchemaPolicy.REQUIRE_EXISTING afin de valider le schéma sans créer ni modifier d'objets de base de données.

Configurez une connexion ou un pool pour le propriétaire du schéma et une autre pour l'utilisateur d'exécution :

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

Les exemples ci-dessous supposent que embedder et llm sont déjà configurés pour votre application. Ils définissent également memory_store_id="APP_MEMORY", qui utilise le préfixe de nom d'objet APP_MEMORY_. Si vous omettez cet argument, utilisez les noms d'objet géré non préfixés dans vos octrois.

Initialisez le schéma en tant que propriétaire :

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

Utilisez plutôt SchemaPolicy.CREATE_IF_NECESSARY lorsque vous souhaitez que le compte propriétaire applique les mises à niveau non destructives prises en charge pour un schéma géré plus ancien.

Quels privilèges dois-je accorder à un utilisateur d'exécution en lecture seule ?

Demandez à un administrateur de base de données ou à un administrateur privilégié d'accorder à l'utilisateur d'exécution le privilège de base de données normal requis pour la connexion, tel que CREATE SESSION. Accordez ensuite SELECT aux objets gérés à partir du propriétaire du schéma. Cela permet à l'utilisateur de rechercher des mémoires existantes sans écrire de messages, de mémoires, de fils ou de profils.

Exécutez cette opération en tant qu'administrateur de base de données ou administrateur privilégié :

GRANT CREATE SESSION TO memory_r;

Exécutez ensuite ces autorisations en tant que memory_owner. Les noms d'objet incluent le préfixe APP_MEMORY_ utilisé dans les exemples Python ci-dessus :

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;

Quels privilèges dois-je accorder à un utilisateur d'exécution en lecture/écriture ?

Pour un utilisateur d'exécution qui crée des threads, ajoute des messages, ajoute des mémoires, met à jour des enregistrements ou supprime des enregistrements, accordez le privilège de connexion et le code LMD sur les tables gérées.

Exécutez cette opération en tant qu'administrateur de base de données ou administrateur privilégié :

GRANT CREATE SESSION TO memory_rw;

Exécutez ensuite ces autorisations en tant que 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;

Comment me connecter à l'utilisateur runtime après les autorisations ?

Au moment de l'exécution, créez le client avec SchemaPolicy.REQUIRE_EXISTING à l'aide de l'utilisateur de base de données propriétaire du schéma géré :

from oracleagentmemory.core import OracleAgentMemory, SchemaPolicy

memory = OracleAgentMemory(
    connection=runtime_pool,
    embedder=embedder,
    schema_policy=SchemaPolicy.REQUIRE_EXISTING,
)

Les utilisateurs en lecture seule peuvent appeler des API de recherche par rapport aux enregistrements existants. Ils ne peuvent pas utiliser des API d'écriture telles que create_thread(), add_messages(), add_memory(), update() ou delete(), sauf s'ils reçoivent également les privilèges LMD correspondants.

Un utilisateur d'exécution en lecture/écriture peut utiliser le même modèle de connexion, puis appeler les API d'écriture et de recherche normales :

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

Compatibilité des packages

Comment résoudre les conflits de dépendance de package ?

La mémoire de l'agent Oracle AI dépend de LiteLLM pour l'intégration modèle-fournisseur. Les versions antérieures de la mémoire de l'agent Oracle AI, y compris la version 26.4.0, utilisaient une limite supérieure LiteLLM plus stricte qui pourrait entrer en conflit avec d'autres structures d'agent ou packages d'intégration lorsqu'elles nécessitaient des versions openai ou python-dotenv plus récentes.

La mémoire de l'agent Oracle AI 26.6.0 utilise litellm>=1.84.0,<2, ce qui permet des versions openai et python-dotenv plus récentes. Si votre résolveur signale un conflit :