Preguntas frecuentes (FAQ) y solución de problemas

En este artículo se tratan las preguntas comunes de instalación, requisitos de base de datos, acceso a base de datos y compatibilidad de paquetes para la memoria del agente de Oracle AI.

Instalación y actualización

¿Por qué aparece "No se ha encontrado ninguna distribución coincidente" durante la instalación?

La memoria del agente de Oracle AI soporta Python 3.10 a 3.13. Si lo instala con Python 3.9, pip puede informar un error genérico como este:

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

Compruebe que se utiliza el mismo intérprete de Python tanto para python como para pip:

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

Si la versión es anterior a Python 3.10, cree un nuevo entorno con Python 3.10, 3.11, 3.12 o 3.13 y vuelva a realizar la instalación:

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

Python 3.14 no está soportado actualmente porque el paquete sigue el rango de Python admitido de su dependencia de LiteLLM.

Requisitos de bases de datos

¿Cómo se debe configurar la base de datos para la búsqueda vectorial?

La memoria del agente de Oracle AI necesita que la memoria vectorial se configure en Oracle Database antes de utilizar la búsqueda vectorial o los esquemas respaldados por el índice vectorial. Si el área de memoria del vector no está configurada o es demasiado pequeña, las operaciones de la base de datos pueden fallar con este error:

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

Consulte la ayuda de error de Oracle Database para ORA-51962.

Pida a un DBA o a un administrador con privilegios que cambie el tamaño de la memoria vectorial tanto para el contenedor raíz como para la base de datos conectable de destino. Los valores exactos dependen de la base de datos y la carga de trabajo; en este ejemplo, se configura 512M en la raíz y 256M para la PDB:

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

Privilegios y Usuarios de Base de Datos

¿Puede un usuario de base de datos crear el esquema de memoria mientras otro usuario de base de datos lo utiliza?

Utilice una cuenta de propietario con privilegios para crear el esquema gestionado y, a continuación, otorgue solo los privilegios necesarios para cada usuario de tiempo de ejecución. El inicio normal de la aplicación debe utilizar SchemaPolicy.REQUIRE_EXISTING para que valide el esquema sin crear ni cambiar los objetos de base de datos.

Configure una conexión o pool para el propietario del esquema y otra para el usuario de tiempo de ejecución:

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

En los siguientes ejemplos se asume que embedder y llm ya están configurados para la aplicación. También definen memory_store_id="APP_MEMORY", que utiliza el prefijo de nombre de objeto APP_MEMORY_; si omite ese argumento, utilice los nombres de objetos gestionados sin prefijo en los permisos.

Inicie el esquema como propietario:

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

En su lugar, utilice SchemaPolicy.CREATE_IF_NECESSARY cuando desee que la cuenta de propietario aplique actualizaciones no destructivas soportadas para un esquema gestionado anterior.

¿Qué privilegios debo otorgar a un usuario de tiempo de ejecución de solo lectura?

Solicite a un DBA o a un administrador con privilegios que otorgue al usuario de tiempo de ejecución el privilegio de base de datos normal necesario para conectarse, como CREATE SESSION. A continuación, otorgue SELECT en los objetos gestionados desde el propietario del esquema. Esto permite al usuario buscar recuerdos existentes sin escribir mensajes, recuerdos, hilos o perfiles.

Ejecute esto como DBA o administrador con privilegios:

GRANT CREATE SESSION TO memory_r;

A continuación, ejecute estos permisos como memory_owner. Los nombres de objeto incluyen el prefijo APP_MEMORY_ utilizado en los ejemplos de Python anteriores:

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;

¿Qué privilegios debo otorgar a un usuario de tiempo de ejecución de lectura/escritura?

Para un usuario de tiempo de ejecución que crea threads, agrega mensajes, agrega memorias, actualiza registros o suprime registros, otorgue el privilegio de conexión y DML en las tablas gestionadas.

Ejecute esto como DBA o administrador con privilegios:

GRANT CREATE SESSION TO memory_rw;

A continuación, ejecute estos permisos como 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;

¿Cómo puedo conectarme con el usuario de tiempo de ejecución después de los permisos?

En tiempo de ejecución, cree el cliente con SchemaPolicy.REQUIRE_EXISTING utilizando el usuario de base de datos propietario del esquema gestionado:

from oracleagentmemory.core import OracleAgentMemory, SchemaPolicy

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

Los usuarios de solo lectura pueden llamar a las API de búsqueda en los registros existentes. No pueden utilizar API de escritura como create_thread(), add_messages(), add_memory(), update() o delete() a menos que también reciban los privilegios DML correspondientes.

Un usuario de tiempo de ejecución de lectura/escritura puede utilizar el mismo patrón de conexión y, a continuación, llamar a las API de escritura y búsqueda 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,
)

Compatibilidad de paquetes

¿Cómo puedo resolver los conflictos de dependencia de paquetes?

La memoria del agente de Oracle AI depende de LiteLLM para la integración del proveedor de modelos. Las versiones anteriores de Oracle AI Agent Memory, incluida la 26.4.0, utilizaban un límite superior LiteLLM más estricto que podría entrar en conflicto con otros marcos de agentes o paquetes de integración cuando necesitaban versiones más recientes de openai o python-dotenv.

La memoria del agente de Oracle AI 26.6.0 utiliza litellm>=1.84.0,<2, que permite versiones openai y python-dotenv más recientes compatibles. Si el solucionador informa un conflicto: