Preguntas frecuentes (FAQ) y solución de problemas

En esta página se tratan las preguntas comunes de instalación, requisitos de base de datos, acceso a base de datos y compatibilidad de paquetes para Oracle AI Agent Memory.

Script/notebook de Python para los fragmentos de esta página.

Instalación y actualización

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

Oracle AI Agent Memory admite de Python 3.10 a 3.14. 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.8.0 (from versions: none)
ERROR: No matching distribution found for oracleagentmemory==26.8.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, 3.13 o 3.14 y vuelva a realizar la instalación:

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

Requisitos de bases de datos

¿Qué versiones y estrategias de búsqueda de Oracle AI Database están soportadas?

Oracle Agent Memory necesita Oracle AI Database 23ai (23.4) o posterior para su almacén con copia de seguridad de base de datos. SearchStrategy.HYBRID también requiere la actualización de la versión 23.6 o posterior. Consulte Requisitos de funciones de Oracle AI Database para conocer los requisitos de estrategia completos, incluida la configuración de COMPATIBLE necesaria para Oracle AI Vector Search.

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

Oracle AI Agent Memory necesita que la memoria vectorial se configure en Oracle Database antes de utilizar la búsqueda vectorial o los esquemas respaldados por í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 AI 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';

¿Qué ocurre si la configuración del esquema gestionado falla con ORA-00054?

La configuración de esquema gestionado puede crear índices de búsqueda vectoriales, de Oracle Text o híbridos. Esas operaciones DDL son sensibles al bloqueo, por lo que una base de datos ocupada ocasionalmente puede mostrar un error como este:

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 ya reintenta fallos ORA-00054 transitorios durante la creación de vector-índice, palabra clave-texto-índice e índice híbrido gestionados. Si el error aún persiste en el entorno, pregunte a un DBA o a un administrador con privilegios si aumentar la sesión DDL_LOCK_TIMEOUT es adecuado para la conexión que ejecuta la configuración del esquema. Esta configuración afecta a DDL que espera toda la sesión de la base de datos, no solo a Oracle AI Agent Memory.

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 la base de datos de la aplicació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.

Aquí, owner significa el usuario de Oracle AI Database que posee las tablas e índices gestionados. No está relacionado con el usuario o agente de nivel de aplicación asociado a un registro de memoria. El cliente de tiempo de ejecución hace referencia a este usuario de base de datos como schema_owner.

Configure una conexión o pool para el propietario del esquema y otra para el usuario de la base de datos de la aplicación:

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

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_. La tabla AGENT_MEMORY_STORES compartida no tiene ningún prefijo; los usuarios de la aplicación necesitan SELECT para poder leer la configuración guardada del almacén. Contiene filas para cada almacén de este esquema de propietario, de modo que el permiso también permite la lectura de esas filas de registro. Consulte la advertencia en la sección de vistas a continuación para conocer las implicaciones de visibilidad.

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

Esta inicialización se ejecuta mientras está conectada como propietario del esquema. Si es necesario, crea las tablas de base de datos y el código de base de datos interno (paquete PL/SQL) que utiliza la memoria del agente de Oracle en ese esquema. Ejecutarlo antes de que los clientes de aplicación se conecten con schema_owner.

Si las tablas de base de datos existentes o el código de base de datos interno no coinciden con el paquete de Python instalado, el inicio normal no las sustituye. Conéctese como propietario del esquema y utilice SchemaPolicy.RECREATE solo cuando se acepte la sustitución del almacén con nombre. De lo contrario, solicite al administrador de la base de datos que actualice el esquema de propietario antes de volver a conectar los clientes de la aplicación.

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. Se trata de una operación de mantenimiento coordinada: ejecute una conexión de propietario de esquema, pare las instancias de aplicación que escriben en las tablas gestionadas y no permita que varios clientes realicen la actualización simultáneamente. Una vez que el cambio de versión se haya completado correctamente, reinicie las instancias de la aplicación con SchemaPolicy.REQUIRE_EXISTING. Esta restricción es importante porque las actualizaciones gestionadas pueden realizar rellenos de datos y Oracle AI Database confirma las sentencias DDL de forma implícita, por lo que un cambio de versión puede exponer temporalmente las unidades de tabla intermedias.

Si se interrumpe una actualización, resuelva el problema de la base de datos informada y vuelva a ejecutar la misma operación de propietario de esquema. Los pasos de actualización admitidos reconocen sus estados intermedios documentados y pueden reanudarse sin volver a empezar.

Tratar las operaciones del ciclo de vida del esquema (creación, reparación, actualización, nueva creación y supresión) como un trabajo de mantenimiento coordinado. Para un determinado almacén de memoria, ejecute solo una operación de ciclo de vida a la vez desde una conexión de propietario de esquema. No mezcle la administración de paquetes Python de memoria de agente de Oracle con la administración manual de la base de datos para el mismo almacén y no cambie las tablas de base de datos gestionadas ni el código interno de la base de datos mientras haya una operación de ciclo de vida en curso. Los clientes de aplicación normales deben utilizar SchemaPolicy.REQUIRE_EXISTING.

¿Por qué falla la configuración del esquema del lado del propietario antes de crear un almacén de memoria?

Antes de crear o abrir un almacén del mismo esquema, puede que el paquete Python de memoria del agente de Oracle necesite crear las tablas de base de datos y el código de base de datos interno que utiliza en la cuenta del propietario del esquema. El propietario necesita CREATE TABLE y CREATE PROCEDURE, junto con los privilegios necesarios para las funciones de almacén seleccionadas. Por ejemplo, la memoria enlazada necesita CREATE TRIGGER y CREATE PROPERTY GRAPH. Consulte Introducción a la memoria del agente para obtener los privilegios específicos de la función.

Una conexión de aplicación que utilice schema_owner no puede preparar ni cambiar las tablas de base de datos del propietario ni el código de base de datos interno. Conéctese como propietario para realizar operaciones de ciclo de vida de esquema y, a continuación, vuelva a conectar los clientes de aplicación con SchemaPolicy.REQUIRE_EXISTING.

¿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 la base de datos de la aplicació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.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;

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

Para un usuario de base de datos de aplicación que crea threads, agrega mensajes, agrega memorias, actualiza registros o suprime registros, utilice el usuario de base de datos propietario del esquema gestionado y otorgue el privilegio de conexión necesario para la base de datos.

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

¿Cómo puedo otorgar a un usuario de base de datos de aplicación acceso a un modelo de embebido en la base de datos?

Al utilizar OracleDBEmbedder con su valor por defecto provider="database", el SDK ejecuta VECTOR_EMBEDDING como usuario de base de datos conectada. Los privilegios del usuario en las tablas de memoria del agente no otorgan acceso al modelo de embebido. La cuenta que ejecuta el SQL embebido también debe poder aplicar ese modelo.

Si el usuario de la base de datos es propietario del modelo, no se necesita ningún permiso adicional. Si otro esquema es propietario del modelo, el propietario del modelo o un DBA deben otorgar permiso al usuario de tiempo de ejecución para utilizarlo:

GRANT SELECT ON MINING MODEL memory_owner.DOC_MODEL TO memory_rw;

Debido a que la conexión en tiempo de ejecución utiliza memory_rw, proporcione al embebido el nombre completo del modelo:

from oracleagentmemory.core.embedders import OracleDBEmbedder

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

SELECT ANY MINING MODEL es una opción más amplia para las aplicaciones que necesitan utilizar modelos en muchos esquemas. Para un modelo conocido, utilice la subvención específica anterior. Consulte el modelo de seguridad DBMS_DATA_MINING de Oracle para obtener los detalles del privilegio del modelo.

¿Puedo utilizar vistas en lugar de schema_owner?

Sí, pero se trata de una opción de despliegue secundaria. Preferir schema_owner cuando el usuario de la base de datos de la aplicación puede recibir permisos en los objetos del esquema del propietario; las vistas agregan un requisito de mantenimiento y otra capa a la configuración de la base de datos. Si utiliza vistas, después de que exista el esquema de propietario y el usuario de la base de datos de la aplicación tenga los permisos de objeto directo necesarios, cree vistas con el mismo nombre en el esquema del usuario de la base de datos de la aplicación. Utilice vistas simples que expongan los objetos gestionados completos; estas vistas deben ser actualizables para los usuarios de la base de datos de la aplicación que necesitan escribir registros. Ejecute lo siguiente como usuario de la base de datos de la aplicación o a través de un DBA con el privilegio de creación de vistas necesario:

En los ejemplos se utiliza el prefijo APP_MEMORY_ derivado de memory_store_id="APP_MEMORY" anteriormente; sustitúyalo por su propio prefijo al utilizar un identificador diferente.

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;

Al utilizar estas vistas, omita schema_owner y abra el cliente con SchemaPolicy.REQUIRE_EXISTING. El SDK valida las vistas como el esquema gestionado existente y deja índices y otros objetos propiedad del esquema en el esquema propietario. Esta solución alternativa solo está soportada para esquemas de modo vectorial; utilice schema_owner para la búsqueda por palabra clave o híbrida. El usuario de la base de datos de la aplicación es responsable de mantener las vistas alineadas con el esquema gestionado: siempre que una nueva versión de OAM agregue una tabla gestionada o cambie las columnas necesarias, cree o actualice la vista correspondiente antes de abrir el cliente con ese esquema.

Advertencia: esta configuración no aísla a los usuarios de la aplicación entre sí. memory_owner.AGENT_MEMORY_STORES tiene una fila para cada almacén propiedad de memory_owner. La vista expone todas esas filas. Por ejemplo, si el propietario tiene tiendas SALES y SUPPORT, un usuario de aplicación que puede consultar esta vista puede leer los detalles del registro de ambas tiendas.

OWNER_ID permanece como memory_owner; nunca se convierte en el ID del usuario de la aplicación. Lo mismo ocurre cuando se utiliza schema_owner. Un usuario de la aplicación con acceso SELECT puede leer todo el registro, no solo la tienda que abre. Para el aislamiento, coloque almacenes en diferentes esquemas de base de datos y otorgue acceso por separado.

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

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 base de datos de aplicació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,
    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,
)

Compatibilidad de paquetes

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

Oracle AI Agent Memory depende de LiteLLM para la integración de 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.

Oracle AI Agent Memory 26.8.0 utiliza litellm>=1.84.0,<2, que permite versiones openai y python-dotenv más recientes compatibles. Si el solucionador informa un conflicto: