Domande frequenti (FAQ) e problemi

In questa pagina vengono descritte le domande comuni sull'installazione, i requisiti del database, l'accesso al database e la compatibilità dei pacchetti per Oracle AI Agent Memory.

Script/notebook Python per gli snippet in questa pagina.

Installazione e aggiornamento

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

Oracle AI Agent Memory supporta Python 3.10 a 3.14. 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.8.0 (from versions: none)
ERROR: No matching distribution found for oracleagentmemory==26.8.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, 3.13 o 3.14 e ripetere l'installazione:

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

Requisiti database

Quali versioni e strategie di ricerca di Oracle AI Database sono supportate?

La memoria dell'agente Oracle richiede Oracle AI Database 23ai (23.4) o versione successiva per l'area di memorizzazione supportata dal database. SearchStrategy.HYBRID richiede inoltre l'aggiornamento della release 23.6 o versioni successive. Consulta i requisiti delle funzioni di Oracle AI Database per i requisiti completi della strategia, inclusa l'impostazione COMPATIBLE richiesta per Oracle AI Vector Search.

Come deve essere configurato il database per la ricerca vettoriale?

Oracle AI Agent Memory richiede la configurazione della memoria vettoriale in Oracle Database prima di utilizzare la ricerca vettoriale o gli schemi con supporto di vector-index. 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.

Consulta la Guida sugli errori di Oracle AI 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';

Cosa succede se l'impostazione dello schema gestito non riesce con ORA-00054?

L'impostazione dello schema gestito può creare indici vettoriali, Oracle Text o di ricerca ibrida. Queste operazioni DDL fanno distinzione tra lock-sensitive, quindi un database occupato può occasionalmente evidenziare un errore come questo:

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 esegue già un nuovo tentativo di errori ORA-00054 transitori durante la creazione di un indice vettoriale gestito, un indice di testo con parole chiave e un indice ibrido. Se l'errore persiste nell'ambiente in uso, chiedere a un DBA o a un amministratore con privilegi se l'aumento della sessione DDL_LOCK_TIMEOUT è appropriato per la connessione che esegue l'impostazione dello schema. Questa impostazione ha effetto sulle DDL in attesa dell'intera sessione del database, non solo su Oracle AI Agent Memory.

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 DB dell'applicazione. L'avvio normale dell'applicazione deve utilizzare SchemaPolicy.REQUIRE_EXISTING in modo che convalida lo schema senza creare o modificare gli oggetti DB.

In questo caso, owner indica l'utente di Oracle AI Database proprietario delle tabelle e degli indici gestiti. Non è correlato all'utente o all'agente a livello di applicazione associato a un record di memoria. Il client runtime fa riferimento a questo utente del database come schema_owner.

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

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

Gli esempi riportati di seguito presuppongono che embedder e llm siano già configurati per l'applicazione. Impostano anche memory_store_id="APP_MEMORY", che utilizza il prefisso object-name APP_MEMORY_. La tabella AGENT_MEMORY_STORES condivisa non ha prefissi; gli utenti dell'applicazione hanno bisogno di SELECT in modo che possano leggere la configurazione salvata dell'area di memorizzazione. Contiene righe per ogni negozio in questo schema proprietario, in modo che la concessione consenta anche la lettura di tali righe del registro. Per informazioni sulle implicazioni di visibilità, vedere l'avvertenza nella sezione delle viste riportata di seguito.

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

Questa inizializzazione viene eseguita durante la connessione come proprietario dello schema. Se necessario, crea le tabelle di database e il codice di database interno (pacchetto PL/SQL) utilizzati da Oracle Agent Memory nello schema. Eseguire prima che i client dell'applicazione si connettano a schema_owner.

Se le tabelle di database esistenti o il codice di database interno non corrispondono al pacchetto Python installato, l'avvio normale non le sostituisce. Connettersi come proprietario dello schema e utilizzare SchemaPolicy.RECREATE solo quando la sostituzione dell'area di memorizzazione denominata è accettabile. In caso contrario, chiedere all'amministratore del database di aggiornare lo schema proprietario prima che i client dell'applicazione si riconnettano.

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. Trattare questa operazione come operazione di manutenzione coordinata: eseguire una connessione schema-proprietario, arrestare le istanze dell'applicazione che scrivono nelle tabelle gestite e non consentire a più client di eseguire l'upgrade contemporaneamente. Al termine dell'aggiornamento, riavviare le istanze dell'applicazione con SchemaPolicy.REQUIRE_EXISTING. Questa limitazione è importante perché gli upgrade gestiti possono eseguire i backfill dei dati e Oracle AI Database esegue il commit implicito delle istruzioni DDL, pertanto un upgrade può esporre temporaneamente le forme di tabella intermedie.

Se un aggiornamento viene interrotto, risolvere il problema del database segnalato ed eseguire di nuovo la stessa operazione schema-proprietario. I passi di aggiornamento supportati riconoscono i loro stati intermedi documentati e possono riprendere senza ricominciare da capo.

Tratta le operazioni del ciclo di vita dello schema (creazione, riparazione, aggiornamento, ricreazione ed eliminazione) come lavoro di manutenzione coordinato. Per un'area di memorizzazione di memoria specifica, eseguire una sola operazione del ciclo di vita alla volta da una connessione schema-proprietario. Non combinare l'amministrazione del pacchetto Python di memoria dell'agente Oracle con l'amministrazione manuale del database per la stessa area di memorizzazione e non modificare le tabelle del database gestito o il codice del database interno durante l'esecuzione di un'operazione del ciclo di vita. I normali client delle applicazioni devono utilizzare SchemaPolicy.REQUIRE_EXISTING.

Perché l'impostazione dello schema lato proprietario non riesce prima di creare un'area di memorizzazione della memoria?

Prima di creare o aprire un'area di memorizzazione con lo stesso schema, potrebbe essere necessario che il package Python Memory Oracle Agent crei le tabelle di database e il codice di database interno utilizzato nell'account del proprietario dello schema. Il proprietario deve disporre di CREATE TABLE e CREATE PROCEDURE, insieme ai privilegi richiesti dalle funzioni dell'area di memorizzazione selezionata. Ad esempio, la memoria collegata richiede CREATE TRIGGER e CREATE PROPERTY GRAPH. Per informazioni sui privilegi specifici della funzione, vedere Introduzione alla memoria agente.

Una connessione all'applicazione che utilizza schema_owner non è autorizzata a preparare o modificare le tabelle del database o il codice interno del database del proprietario. Connettersi come proprietario per eseguire le operazioni del ciclo di vita dello schema, quindi riconnettere i client dell'applicazione con SchemaPolicy.REQUIRE_EXISTING.

Quali privilegi concedere a un utente runtime di sola lettura?

Chiedere a un DBA o a un amministratore con privilegi di concedere all'utente DB dell'applicazione 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.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;

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

Per un utente DB dell'applicazione che crea thread, aggiunge messaggi, aggiunge memorie, aggiorna record o elimina record, utilizzare l'utente del database proprietario dello schema gestito e concedere il privilegio di connessione richiesto dal database.

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

Come concedo a un utente DB dell'applicazione l'accesso a un modello di incorporamento nel database?

Quando si utilizza OracleDBEmbedder con il valore predefinito provider="database", l'SDK esegue VECTOR_EMBEDDING come utente del database connesso. I privilegi dell'utente sulle tabelle di memoria agente non concedono l'accesso al modello di incorporamento. Anche l'account che esegue l'istruzione SQL di incorporamento deve essere autorizzato ad applicare tale modello.

Se l'utente del database è proprietario del modello, non è necessaria alcuna concessione aggiuntiva. Se un altro schema è proprietario del modello, il proprietario del modello o un DBA deve concedere all'utente runtime l'autorizzazione per utilizzarlo:

GRANT SELECT ON MINING MODEL memory_owner.DOC_MODEL TO memory_rw;

Poiché la connessione runtime utilizza memory_rw, assegnare all'embedder il nome completo del modello:

from oracleagentmemory.core.embedders import OracleDBEmbedder

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

SELECT ANY MINING MODEL è un'opzione più ampia per le applicazioni che devono utilizzare modelli in molti schemi. Per un modello noto, utilizzare la sovvenzione specifica sopra riportata. Per i dettagli dei privilegi del modello, vedere il modello di sicurezza DBMS_DATA_MINING di Oracle.

È possibile utilizzare le viste anziché schema_owner?

Sì, ma si tratta di un'opzione di distribuzione secondaria. Preferire schema_owner quando l'utente DB dell'applicazione può ricevere privilegi sugli oggetti dello schema proprietario; le viste aggiungono un requisito di manutenzione e un altro livello all'impostazione del database. Se si utilizzano le viste, dopo che lo schema proprietario esiste e l'utente DB dell'applicazione dispone delle autorizzazioni per l'oggetto diretto richieste, creare viste con lo stesso nome nello schema dell'utente DB dell'applicazione. Utilizza viste semplici che espongono gli oggetti gestiti completi; queste viste devono essere aggiornabili per gli utenti DB dell'applicazione che devono scrivere record. Eseguire quanto segue come utente DB dell'applicazione o tramite un DBA con il privilegio di creazione della vista richiesto:

Gli esempi utilizzano il prefisso APP_MEMORY_ derivato da memory_store_id="APP_MEMORY" in precedenza; sostituirlo con il prefisso personale quando si utilizza un ID diverso.

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;

Quando si utilizzano queste viste, omettere schema_owner e aprire il client con SchemaPolicy.REQUIRE_EXISTING. L'SDK convalida le viste come schema gestito esistente e lascia gli indici e altri oggetti di proprietà dello schema nello schema proprietario. Questa soluzione alternativa è supportata solo per gli schemi in modalità vettoriale; utilizzare schema_owner per la ricerca per parola chiave o ibrida. L'utente DB dell'applicazione è responsabile di mantenere le viste allineate allo schema gestito: ogni volta che una nuova versione di OAM aggiunge una tabella gestita o modifica le colonne richieste, creare o aggiornare la vista corrispondente prima di aprire il client rispetto a tale schema.

Avvertenza: questa impostazione non isola gli utenti dell'applicazione l'uno dall'altro. memory_owner.AGENT_MEMORY_STORES contiene una riga per ogni negozio di proprietà di memory_owner. La vista espone tutte le righe. Ad esempio, se il proprietario dispone di aree di memorizzazione SALES e SUPPORT, un utente dell'applicazione che può eseguire una query su questa vista può leggere i dettagli del registro per entrambi i negozi.

OWNER_ID rimane come memory_owner; non diventa mai l'ID dell'utente dell'app. Lo stesso vale quando si utilizza schema_owner. Un utente di app con accesso SELECT può leggere l'intero registro, non solo lo store che apre. Per l'isolamento, inserire i negozi in schemi di database diversi e concedere l'accesso separatamente.

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

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 DB dell'applicazione di 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,
    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à pacchetto

Come si risolvono i conflitti di dipendenza dei package?

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

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