Agent Platform Memory Bank gestisce automaticamente una cronologia delle versioni delle tue memorie tramite le risorse di revisione della memoria. Ogni volta che un ricordo viene creato o modificato, viene salvata una nuova revisione immutabile, che garantisce la trasparenza sull'evoluzione delle informazioni e su ciò che è stato estratto in ogni passaggio.
Questo documento spiega il ciclo di vita dei ricordi e delle relative revisioni e descrive operazioni come l'elenco, il recupero e il rollback delle revisioni.
Per ulteriori informazioni sulla generazione di ricordi, consulta Genera ricordi.
Ciclo di vita di una memoria e delle sue revisioni
I ricordi possono essere creati, aggiornati o eliminati direttamente (utilizzando rispettivamente CreateMemory, UpdateMemory o DeleteMemory) o in modo dinamico (utilizzando GenerateMemories). Le risorse di revisione dei ricordi forniscono una cronologia delle versioni completa di una risorsa di memoria in tutte le operazioni di mutazione. Ogni volta che la memoria viene creata o modificata, viene salvata automaticamente una nuova revisione immutabile. In questo modo, hai visibilità su come si è evoluta una memoria e (per la generazione della memoria) su quali informazioni specifiche sono state estratte e consolidate in ogni passaggio.
Ogni risorsa di memoria ha una o più risorse di revisione della memoria secondarie associate:
Le risorse
Memoryriflettono sempre lo stato attuale e consolidato delle informazioni. Un singolo ricordo può riflettere dati derivati da più richieste e origini dati.Memory( create_time=datetime.datetime(...), fact='This is my current memory content after consolidation', name='projects/.../locations/.../reasoningEngines/../memories/...', scope={ 'my_scope_key': 'my_scope_value' }, topics=[ MemoryTopicId( managed_memory_topic=<ManagedTopicEnum.USER_PERSONAL_INFO: 'USER_PERSONAL_INFO'> ), ], update_time=datetime.datetime(...) )Le risorse
MemoryRevisionsrappresentano gli stati storici della memoria padre. Ogni revisione è uno snapshot della memoria in un mutation event. Se una memoria è stata modificata utilizzandoGenerateMemories, la revisione include anche le informazioni estratte dall'origine dati (extracted_memories) prima che venissero consolidate con i contenuti esistenti della memoria.MemoryRevision( create_time=datetime.datetime(...), expire_time=datetime.datetime(...), extracted_memories=[ IntermediateExtractedMemory( fact='This information was extracted from my data source' ), ], fact='This is my current memory content after consolidation', name='projects/.../locations/.../reasoningEngines/.../memories/.../revisions/...' )Le revisioni della memoria sono attive per impostazione predefinita. Per disattivare le revisioni della memoria, consulta Disattivare le revisioni della memoria.
Creazione di ricordi
I ricordi possono essere creati direttamente utilizzando CreateMemory o dinamicamente utilizzando GenerateMemories. Con la generazione di ricordi, viene creato un ricordo se non esistono ricordi che coprono informazioni simili per lo stesso ambito:
# Direct creation using CreateMemory
client.memory_banks.memories.create(name=memory_bank_name, ...)
# Dynamic creation using GenerateMemory
client.memory_banks.memories.generate(name=memory_bank_name, ...)
Quando viene creato un ricordo, vengono create una singola risorsa Memory e una risorsa MemoryRevision secondaria:
client.memory_banks.memories.get(name=memory_name)
"""
Memory(
name="projects/123/locations/us-central1/reasoningEngines/456/memories/789",
fact="This is my original fact.",
...
)
"""
list(client.memory_banks.memories.revisions.list(name=memory_name))
"""
[
MemoryRevision(
name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/123",
fact="This is my original fact",
...
)
]
"""
Aggiornamento della memoria
I ricordi possono essere aggiornati direttamente utilizzando UpdateMemory o dinamicamente utilizzando GenerateMemories. Con la generazione di ricordi, i ricordi vengono aggiornati dinamicamente quando il processo di consolidamento decide che le nuove informazioni sono duplicate, complementari o contraddittorie rispetto a tutti i ricordi esistenti per lo stesso ambito.
# Direct update using UpdateMemory
client.memory_banks.memories.update(name=memory_name, ...)
# Dynamic update using GenerateMemories
client.memory_banks.memories.generate(name=memory_bank_name, ...)
Quando un ricordo viene aggiornato, la risorsa Memory esistente viene aggiornata e viene creata una nuova risorsa MemoryRevision secondaria.
client.memory_banks.memories.get(name=memory_name)
"""
Memory(
name="projects/123/locations/us-central1/reasoningEngines/456/memories/789",
fact="This is my updated fact.",
...
)
"""
list(client.memory_banks.memories.revisions.list(name=memory_name))
"""
[
MemoryRevision(
name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/456",
fact="This is my updated fact",
...
),
MemoryRevision(
name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/123",
fact="This is my original fact",
...
)
]
"""
Eliminazione della memoria
I ricordi possono essere utilizzati direttamente tramite DeleteMemory o dinamicamente tramite GenerateMemories. Con la generazione della memoria, i ricordi vengono eliminati dinamicamente quando il processo di consolidamento decide che le nuove informazioni invalidano quelle esistenti per lo stesso ambito.
# Direct deletion using UpdateMemory
client.memory_banks.memories.delete(name=memory_name, ...)
# Dynamic delete using GenerateMemories
client.memory_banks.memories.generate(name=memory_bank_name, ...)
Quando un ricordo viene eliminato, la risorsa Memory esistente viene eliminata e viene creato un nuovo MemoryRevision secondario. La fact nell'ultima revisione della memoria è vuota perché riflette una mutazione di eliminazione.
client.memory_banks.memories.get(name=memory_name)
"""
404 Not Found.
"""
list(client.memory_banks.memories.revisions.list(name=memory_name))
"""
[
MemoryRevision(
name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/789",
fact="",
...
),
MemoryRevision(
name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/456",
fact="This is my updated fact",
...
),
MemoryRevision(
name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/123",
fact="This is my original fact",
...
)
]
"""
Le revisioni della memoria secondaria sono accessibili solo per un massimo di 48 ore dopo l'eliminazione della memoria principale. Durante questa finestra di recupero, puoi continuare a esaminare le revisioni della memoria e puoi recuperarla eseguendo il rollback a una revisione precedente.
Operazioni di revisione della memoria
Questa sezione descrive come ispezionare le revisioni della memoria ed eseguire il rollback di una memoria a una revisione precedente.
Elenca revisioni
Puoi esaminare le revisioni della memoria nella console Google Cloud o con l'SDK Agent Platform.
Console
Per visualizzare le revisioni della memoria nella console Google Cloud è necessaria l'autorizzazione aiplatform.memoryRevisions.list (inclusa in roles/aiplatform.memoryViewer e roles/aiplatform.memoryUser) e non è disponibile in modalità Express.
Apri l'istanza nella console Google Cloud :
Istanza di Memory Bank autonoma: vai alla pagina Memory Bank di Agent Platform e fai clic sulla tua istanza.
Agente di cui è stato eseguito il deployment su Agent Runtime: vai alla pagina Deployment di Agent Platform e fai clic sul tuo agente.
Apri la scheda Ricordi:
- Ricordi non strutturati: in una riga di un ricordo, fai clic sul menu Altre azioni () > Visualizza revisioni.
- Profili strutturati (istanze autonome): seleziona Strutturato, scegli un ambito completo, fai clic su Visualizza nella riga di un profilo per aprire Dettagli memoria e fai clic su Visualizza revisioni per un fatto memorizzato.
Il riquadro delle revisioni elenca i campi Data di creazione, Scadenza, Dato e Contesto di ogni revisione.
SDK Agent Platform
Utilizza ListMemoryRevisions per restituire tutte le revisioni di un ricordo.
list(client.memory_banks.memories.revisions.list(name=MEMORY_NAME))
Sostituisci quanto segue:
MEMORY_NAME: il nome della risorsa della memoria nel formato:projects/.../locations/.../reasoningEngines/.../memories/...
Quando generi i ricordi, puoi fornire etichette di revisione che vengono applicate alle revisioni affiliate. Le etichette sono coppie chiave-valore arbitrarie. Ad esempio, puoi etichettare le revisioni con un ID dell'origine dati utilizzata per generare la memoria e poi filtrare le revisioni in base a questa etichetta:
response = client.memory_banks.memories.generate(
...,
config={
"revision_labels": {
"data_source": "321"
}
}
)
list(client.memory_banks.memories.revisions.list(
name=MEMORY_NAME,
config={
"filter": "labels.data_source=\"321\""
}
))
"""
[
MemoryRevision(
name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/123",
labels={
"data_source": "123"
}
...
)
]
"""
Richiedi una revisione
Utilizza GetMemoryRevision per recuperare una singola revisione della memoria.
client.memory_banks.memories.revisions.get(name=MEMORY_REVISION_NAME)
Sostituisci quanto segue:
MEMORY_REVISION_NAME: il nome della risorsa della revisione della memoria da recuperare nel formato:projects/.../locations/.../reasoningEngines/.../memories/.../revisions/...
Esegui il rollback di un ricordo
Utilizza RollbackMemory per ripristinare una versione precedente di una memoria.
client.memory_banks.memories.rollback(
name="MEMORY_NAME",
target_revision_id="REVISION_ID"
)
Sostituisci quanto segue:
MEMORY_NAME: il nome della risorsa della memoria da aggiornare nel formato:projects/.../locations/.../reasoningEngines/.../memories/...REVISION_ID: l'ID della revisione di cui eseguire il rollback. Questo è l'ultimo segmento del nome della risorsa di revisione della memoria, ad esempio789inprojects/MyProject/locations/us-central1/reasoningEngines/123/memories/456/revisions/789.
Se vuoi annullare una modifica apportata a un ricordo da GenerateMemories, esegui il rollback
del ricordo alla revisione precedente alla modifica. La risposta della generazione della memoria include un riferimento alla revisione precedente (previous_revision) per ogni memoria aggiornata o eliminata:
operation = client.memory_banks.memories.generate(
...
)
# Rollback the first generated memory to the previous revision.
client.memory_banks.memories.rollback(
name=operation.response.generated_memories[0].memory.name,
target_revision_id=operation.response.generated_memories[0].previous_revision
)
Disattivazione delle revisioni della memoria
Le revisioni della memoria sono attive per impostazione predefinita. Puoi disattivare le revisioni della memoria per tutte le richieste all'istanza di Memory Bank o per ogni singola richiesta. Se le revisioni della memoria sono disattivate, non viene creata una revisione della memoria quando questa viene modificata.
Puoi disattivare le revisioni della memoria per tutte le richieste alla tua istanza di Memory Bank nella console Google Cloud (in Configurazione > Conservazione o Configurazione del servizio > Memory Bank per gli agenti di cui è stato eseguito il deployment) o con l'SDK Agent Platform:
memory_bank = client.memory_banks.create(
managed_semantic_memory_config={
"disable_memory_revisions": True
}
)
Puoi disattivare le revisioni della memoria a livello di richiesta quando invii la richiesta:
Genera
client.memory_banks.memories.generate(
...,
"config": {
"disable_memory_revisions": True
}
)
Crea
client.memory_banks.memories.create(
...,
"config": {
"disable_memory_revisions": True
}
)
Aggiorna
client.memory_banks.memories.update(
...,
"config": {
"disable_memory_revisions": True
}
)
Scadenza della revisione
Le revisioni della memoria non vengono conservate per sempre. Devi impostare la scadenza delle revisioni o utilizzare la scadenza predefinita. La durata (TTL) predefinita è di 365 giorni. Puoi configurare la scadenza per tutte le richieste alla tua istanza di Memory Bank o per ogni singola richiesta. Una volta scaduta una revisione della memoria, non è disponibile per l'ispezione o i rollback.
Puoi configurare il TTL della cronologia delle revisioni per tutte le richieste alla tua istanza di Memory Bank nella console Google Cloud (in Configurazione > Conservazione o Configurazione del servizio > Memory Bank per gli agenti di cui è stato eseguito il deployment) o con l'SDK Agent Platform:
client.memory_banks.create(
managed_semantic_memory_config={
"ttl_config": {
# Persist memory revisions for 30 days after they're created.
"revision_ttl": f"{30 * 60 * 60 * 24}s"
}
}
)
Per configurare il TTL per ogni revisione della memoria a livello di richiesta, includi
revision_expire_time o revision_ttl nella richiesta:
TTL
config = {
# Persist memory revisions for 30 days after they're created.
"revision_ttl": f"{30 * 60 * 60 * 24}s"
}
client.memory_banks.memories.create(
...,
config=config
)
client.memory_banks.memories.update(
...,
config=config
)
client.memory_banks.memories.generate(
...,
config=config
)
Scadenza
import datetime
config = {
"revision_expire_time": datetime.datetime.now(tz=datetime.timezone.utc) + datetime.timedelta(weeks=3)
}
client.memory_banks.memories.create(
...,
config=config
)
client.memory_banks.memories.update(
...,
config=config
)
client.memory_banks.memories.generate(
...,
config=config
)