Domande frequenti (FAQ) e risoluzione dei problemi

Questo articolo descrive le domande comuni sull'installazione, i requisiti del database, l'accesso al database e la compatibilità dei pacchetti per Oracle AI Agent Memory.

Installazione e aggiornamento

Perché viene visualizzato "Nessuna distribuzione corrispondente trovata" durante l'installazione?

La memoria dell'agente Oracle AI supporta Python 3.10 - 3.13. Se lo si installa con Python 3.9, pip potrebbe segnalare un errore generico come questo:

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

Verificare che lo stesso interprete Python venga utilizzato sia per python che per pip:

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

Se la versione è precedente a Python 3.10, creare un nuovo ambiente con Python 3.10, 3.11, 3.12 o 3.13 e ripetere l'installazione:

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

Python 3.14 non è attualmente supportato perché il pacchetto segue l'intervallo Python supportato della relativa dipendenza LiteLLM.

Requisiti database

Come deve essere configurato il database per la ricerca vettoriale?

La memoria dell'agente Oracle AI richiede che la memoria vettoriale venga configurata in Oracle Database prima di utilizzare la ricerca vettoriale o gli schemi con supporto di indice vettoriale. Se l'area di memoria vettoriale non è configurata o è troppo piccola, le operazioni del database possono non riuscire con questo errore:

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

Consultare la Guida sugli errori di Oracle Database per ORA-51962.

Chiedere a un DBA o a un amministratore con privilegi di ridimensionare la memoria vettoriale sia per il contenitore radice che per il pluggable database di destinazione. I valori esatti dipendono dal database e dal carico di lavoro in uso; questo esempio configura 512M all'indirizzo root e 256M per il 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';

Utenti e privilegi del database

Un utente DB può creare lo schema di memoria mentre un altro utente DB lo utilizza?

Utilizzare un account proprietario con privilegi per creare lo schema gestito, quindi concedere solo i privilegi richiesti da ciascun utente runtime. L'avvio normale dell'applicazione deve utilizzare SchemaPolicy.REQUIRE_EXISTING in modo che convalida lo schema senza creare o modificare gli oggetti DB.

Configurare una connessione o un pool per il proprietario dello schema e un'altra per l'utente runtime:

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

Gli esempi riportati di seguito presuppongono che embedder e llm siano già configurati per l'applicazione. Inoltre, impostano memory_store_id="APP_MEMORY", che utilizza il prefisso object-name APP_MEMORY_; se si omette tale argomento, utilizzare i nomi degli oggetti gestiti senza prefisso nei privilegi.

Eseguire il bootstrap dello schema come proprietario:

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

Utilizzare invece SchemaPolicy.CREATE_IF_NECESSARY quando si desidera che l'account proprietario applichi gli aggiornamenti non distruttivi supportati per uno schema gestito meno recente.

Quali privilegi concedere a un utente runtime di sola lettura?

Chiedere a un DBA o a un amministratore con privilegi di concedere all'utente runtime il privilegio di database normale richiesto per la connessione, ad esempio CREATE SESSION. Concedere quindi SELECT sugli oggetti gestiti dal proprietario dello schema. Ciò consente all'utente di cercare le memorie esistenti senza scrivere messaggi, memorie, thread o profili.

Eseguire questa operazione come DBA o amministratore con privilegi:

GRANT CREATE SESSION TO memory_r;

Eseguire quindi questi privilegi come memory_owner. I nomi degli oggetti includono il prefisso APP_MEMORY_ utilizzato negli esempi Python riportati sopra:

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;

Quali privilegi concedere a un utente runtime in lettura/scrittura?

Per un utente runtime che crea thread, aggiunge messaggi, aggiunge memorie, aggiorna record o elimina record, concedere il privilegio di connessione e il DML sulle tabelle gestite.

Eseguire questa operazione come DBA o amministratore con privilegi:

GRANT CREATE SESSION TO memory_rw;

Eseguire quindi questi privilegi come 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;

Come connettersi all'utente runtime dopo i privilegi?

In fase di esecuzione, creare il client con SchemaPolicy.REQUIRE_EXISTING utilizzando l'utente del database proprietario dello schema gestito:

from oracleagentmemory.core import OracleAgentMemory, SchemaPolicy

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

Gli utenti di sola lettura possono chiamare le API di ricerca per i record esistenti. Non possono utilizzare API di scrittura come create_thread(), add_messages(), add_memory(), update() o delete() a meno che non ricevano anche i privilegi DML corrispondenti.

Un utente runtime in lettura/scrittura può utilizzare lo stesso pattern di connessione, quindi chiamare le normali API di scrittura e ricerca:

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à pacchetto

Come si risolvono i conflitti di dipendenza dei package?

La memoria dell'agente Oracle AI dipende da LiteLLM per l'integrazione tra modello e provider. Le release precedenti della memoria dell'agente Oracle AI, inclusa la 26.4.0, utilizzavano un limite superiore LiteLLM più stretto che poteva entrare in conflitto con altri framework dell'agente o pacchetti di integrazione quando richiedevano versioni openai o python-dotenv più recenti.

Oracle AI Agent Memory 26.6.0 utilizza litellm>=1.84.0,<2, che consente versioni openai e python-dotenv più recenti compatibili. Se il risolutore segnala un conflitto: