Foire aux questions (FAQ) et dépannage

Cette page 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 Oracle AI Agent Memory.

Script/notebook Python pour les fragments de code de cette page.

Installation et mise à niveau

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

Oracle AI Agent Memory prend en charge Python 3.10 à 3.14. 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.8.0 (from versions: none)
ERROR: No matching distribution found for oracleagentmemory==26.8.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, 3.13 ou 3.14 et installez à nouveau :

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

Configuration requise pour la base de données

Quelles sont les versions et stratégies de recherche d'Oracle AI Database prises en charge ?

La mémoire de l'agent Oracle requiert Oracle AI Database 23ai (23.4) ou une version ultérieure pour son emplacement de stockage sauvegardé par la base de données. SearchStrategy.HYBRID requiert également la version 23.6 ou ultérieure. Reportez-vous aux conditions requises pour les fonctionnalités d'Oracle AI Database pour connaître les exigences de stratégie complètes, y compris le paramètre COMPATIBLE requis pour Oracle AI Vector Search.

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

Oracle AI Agent Memory 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 un 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 sur les erreurs Oracle AI 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';

Et si la configuration du schéma géré échoue avec ORA-00054 ?

La configuration de schéma géré peut créer des index de recherche vectoriels, Oracle Text ou hybrides. Ces opérations LDD sont sensibles au verrouillage, de sorte qu'une base de données occupée peut parfois générer une erreur de ce type :

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 retente déjà les échecs ORA-00054 non persistants lors de la création d'index vectoriel, de mot-clé-texte-index et d'index hybride gérés. Si l'erreur persiste dans votre environnement, demandez à un administrateur de base de données ou à un administrateur privilégié si l'augmentation de la session DDL_LOCK_TIMEOUT est appropriée pour la connexion qui exécute la configuration du schéma. Ce paramètre affecte les instructions LDD qui attendent toute la session de base de données, et pas seulement Oracle AI Agent Memory.

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 de base de données d'application. 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.

Ici, owner désigne l'utilisateur Oracle AI Database propriétaire des tables et des index gérés. Il n'est pas lié à l'utilisateur ou à l'agent de niveau application associé à un enregistrement de mémoire. Le client d'exécution fait référence à cet utilisateur de base de données en tant que schema_owner.

Configurez une connexion ou un pool pour le propriétaire du schéma et une autre pour l'utilisateur de base de données d'application :

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

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 object-name APP_MEMORY_. La table AGENT_MEMORY_STORES partagée n'a pas de préfixe ; les utilisateurs d'application ont besoin de SELECT pour pouvoir lire la configuration enregistrée de l'emplacement de stockage. Il contient des lignes pour chaque magasin de ce schéma propriétaire, de sorte que l'octroi autorise également la lecture de ces lignes de registre. Reportez-vous à l'avertissement dans la section des vues ci-dessous pour connaître les implications en matière de visibilité.

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

Cette initialisation s'exécute lorsque vous êtes connecté en tant que propriétaire du schéma. Si nécessaire, il crée les tables de base de données et le code de base de données interne (package PL/SQL) utilisés par la mémoire de l'agent Oracle dans ce schéma. Exécutez-le avant que les clients d'application ne se connectent à schema_owner.

Si les tables de base de données existantes ou le code de base de données interne ne correspondent pas au package Python installé, le démarrage normal ne les remplace pas. Connectez-vous en tant que propriétaire du schéma et utilisez SchemaPolicy.RECREATE uniquement lorsque le remplacement de l'emplacement de stockage nommé est acceptable. Sinon, demandez à l'administrateur de base de données de mettre à jour le schéma propriétaire avant de reconnecter les clients d'application.

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. Traitez cette opération comme une opération de maintenance coordonnée : exécutez une connexion de propriétaire de schéma, arrêtez les instances d'application qui écrivent dans les tables gérées et ne laissez pas plusieurs clients effectuer la mise à niveau simultanément. Une fois la mise à niveau terminée, redémarrez les instances d'application avec SchemaPolicy.REQUIRE_EXISTING. Cette restriction est importante car les mises à niveau gérées peuvent effectuer des remplissages de données et Oracle AI Database valide implicitement des instructions DDL, de sorte qu'une mise à niveau peut exposer temporairement des formes de table intermédiaires.

Si une mise à niveau est interrompue, résolvez le problème de base de données signalé et réexécutez la même opération de propriétaire de schéma. Les étapes de mise à niveau prises en charge reconnaissent leurs états intermédiaires documentés et peuvent reprendre sans recommencer.

Traitez les opérations de cycle de vie de schéma (création, réparation, mise à niveau, recréation et suppression) comme un travail de maintenance coordonné. Pour une banque de mémoire donnée, exécutez une seule opération de cycle de vie à la fois à partir d'une connexion propriétaire de schéma. Ne mélangez pas l'administration des packages Python de la mémoire de l'agent Oracle avec l'administration manuelle de la base de données pour le même emplacement de stockage et ne modifiez pas les tables de base de données gérées ou le code de base de données interne pendant qu'une opération de cycle de vie est en cours. Les clients d'application standard doivent utiliser SchemaPolicy.REQUIRE_EXISTING.

Pourquoi la configuration du schéma côté propriétaire échoue-t-elle avant la création d'une banque de mémoire ?

Avant de créer ou d'ouvrir une banque de schémas, le package Python de mémoire d'agent Oracle peut avoir besoin de créer les tables de base de données et le code de base de données interne qu'il utilise dans le compte du propriétaire du schéma. Le propriétaire a besoin de CREATE TABLE et CREATE PROCEDURE, ainsi que des privilèges requis par les fonctionnalités de stockage sélectionnées. Par exemple, la mémoire liée a besoin de CREATE TRIGGER et CREATE PROPERTY GRAPH. Pour connaître les privilèges propres aux fonctionnalités, reportez-vous à Introduction à la mémoire d'agent.

Une connexion d'application qui utilise schema_owner n'est pas autorisée à préparer ou modifier les tables de base de données ou le code de base de données interne du propriétaire. Connectez-vous en tant que propriétaire pour effectuer des opérations de cycle de vie de schéma, puis reconnectez les clients d'application à SchemaPolicy.REQUIRE_EXISTING.

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 de base de données d'application 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.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;

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

Pour un utilisateur de base de données d'application qui crée des threads, ajoute des messages, ajoute des mémoires, met à jour des enregistrements ou supprime des enregistrements, utilisez l'utilisateur de base de données propriétaire du schéma géré et accordez-lui le privilège de connexion requis par la base de donné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.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;

Comment accorder à un utilisateur de base de données d'application l'accès à un modèle d'intégration dans la base de données ?

Lorsque vous utilisez OracleDBEmbedder avec sa valeur par défaut provider="database", le kit SDK exécute VECTOR_EMBEDDING en tant qu'utilisateur de base de données connecté. Les privilèges de l'utilisateur sur les tables de mémoire d'agent n'accordent pas l'accès au modèle d'intégration. Le compte qui exécute l'instruction SQL d'intégration doit également être autorisé à appliquer ce modèle.

Si l'utilisateur de base de données est propriétaire du modèle, aucune autorisation supplémentaire n'est nécessaire. Si un autre schéma est propriétaire du modèle, le propriétaire du modèle ou un DBA doit accorder à l'utilisateur d'exécution le droit de l'utiliser :

GRANT SELECT ON MINING MODEL memory_owner.DOC_MODEL TO memory_rw;

Etant donné que la connexion d'exécution utilise memory_rw, attribuez le nom de modèle complet à l'intégrateur :

from oracleagentmemory.core.embedders import OracleDBEmbedder

db_embedder = OracleDBEmbedder(
    connection=runtime_pool,
    model="MEMORY_OWNER.DOC_MODEL",
    embedding_dimension=384,
)

SELECT ANY MINING MODEL est une option plus large pour les applications qui doivent utiliser des modèles dans de nombreux schémas. Pour un modèle connu, utilisez l'octroi spécifique ci-dessus. Pour plus d'informations sur les privilèges de modèle, reportez-vous au modèle de sécurité DBMS_DATA_MINING d'Oracle.

Puis-je utiliser des vues au lieu de schema_owner ?

Oui, mais cette option de déploiement secondaire. Préférez schema_owner lorsque l'utilisateur de base de données d'application peut recevoir des autorisations sur les objets du schéma propriétaire. Les vues ajoutent une exigence de maintenance et une autre couche à la configuration de la base de données. Si vous utilisez des vues, une fois que le schéma propriétaire existe et que l'utilisateur de base de données d'application dispose des autorisations d'objet directes requises, créez des vues portant le même nom dans le schéma de l'utilisateur de base de données d'application. Utilisez des vues simples qui exposent les objets gérés complets. Ces vues doivent pouvoir être mises à jour pour les utilisateurs de base de données d'application qui doivent écrire des enregistrements. Exécutez la commande suivante en tant qu'utilisateur de base de données d'application ou via un administrateur de base de données disposant du privilège de création de vue requis :

Les exemples utilisent le préfixe APP_MEMORY_ dérivé de memory_store_id="APP_MEMORY" précédemment. Remplacez-le par votre propre préfixe lorsque vous utilisez un autre 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;

Lorsque vous utilisez ces vues, omettez schema_owner et ouvrez le client avec SchemaPolicy.REQUIRE_EXISTING. Le kit SDK valide les vues en tant que schéma géré existant et laisse les index et autres objets appartenant au schéma dans le schéma propriétaire. Cette solution de contournement est prise en charge pour les schémas en mode vectoriel uniquement. Utilisez schema_owner pour la recherche par mot-clé ou hybride. L'utilisateur de base de données de l'application est chargé de maintenir les vues alignées sur le schéma géré : chaque fois qu'une nouvelle version d'OAM ajoute une table gérée ou modifie les colonnes requises, créez ou mettez à jour la vue correspondante avant d'ouvrir le client par rapport à ce schéma.

Avertissement : Cette configuration n'isole pas les utilisateurs d'application les uns des autres. memory_owner.AGENT_MEMORY_STORES comporte une ligne pour chaque magasin appartenant à memory_owner. La vue affiche toutes ces lignes. Par exemple, si le propriétaire dispose de magasins SALES et SUPPORT, un utilisateur d'application qui peut interroger cette vue peut lire les détails du registre pour les deux magasins.

OWNER_ID reste memory_owner ; il ne devient jamais l'ID de l'utilisateur de l'application. Il en va de même lorsque vous utilisez schema_owner. Un utilisateur d'application disposant d'un accès SELECT peut lire l'ensemble du registre, et pas seulement le magasin qu'il ouvre. Pour l'isolation, placez les magasins dans différents schémas de base de données et accordez l'accès séparément.

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

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 de base de données d'application 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,
    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,
)

Compatibilité des packages

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

Oracle AI Agent Memory dépend de LiteLLM pour l'intégration modèle-fournisseur. Les anciennes versions d'Oracle AI Agent Memory, 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.

Oracle AI Agent Memory 26.8.0 utilise litellm>=1.84.0,<2, ce qui permet de nouvelles versions compatibles openai et python-dotenv. Si votre résolveur signale un conflit :