Questo documento spiega come funziona la generazione dei ricordi, come personalizzare l'estrazione dei ricordi con gli argomenti e come attivare le richieste di generazione dei ricordi.
Per informazioni sulla configurazione dell'ambiente, consulta Configura per Memory Bank.
Informazioni sulla generazione di memoria
Memory Bank estrae le memorie dai dati di origine e le cura autonomamente per una raccolta specifica di memorie (definita da un scope) aggiungendo, aggiornando e rimuovendo le memorie nel tempo.
Quando attivi la generazione di memoria, Memory Bank esegue le seguenti operazioni:
Estrazione: estrae informazioni sull'utente dalle sue conversazioni con l'agente. Verranno conservate solo le informazioni che corrispondono ad almeno uno degli argomenti della memoria dell'istanza.
Consolidamento: identifica se i ricordi esistenti con lo stesso ambito devono essere eliminati o aggiornati in base alle informazioni estratte. Memory Bank verifica che i nuovi ricordi non siano duplicati o contraddittori prima di unirli a quelli esistenti. Se i ricordi esistenti non si sovrappongono alle nuove informazioni, verrà creato un nuovo ricordo.
Per impostazione predefinita, Memory Bank prenderà in considerazione tutti i ricordi esistenti per lo stesso ambito durante il consolidamento. Se vuoi limitare in modo più granulare i ricordi idonei per il consolidamento utilizzando i metadati, utilizza la strategia di unione dei metadati
REQUIRE_EXACT_MATCH.Per impostazione predefinita, per il confronto viene utilizzata solo la revisione più recente di una memoria. Per identificare meglio le tendenze a lungo termine e confermare i dati, puoi aumentare
revisions_per_candidate_countquando crei l'istanza della piattaforma dell'agente per includere più revisioni storiche nella logica di consolidamento.
Puoi esaminare i passaggi intermedi della generazione della memoria e vedere come cambia una memoria
tra più richieste utilizzando le revisioni
della memoria. Ogni revisione include l'output intermedio del passaggio di estrazione (extracted_memories) e il passaggio di consolidamento finale (fact) per ogni richiesta di generazione della memoria.
list(client.memory_banks.memories.revisions.list(
name="projects/.../locations/.../reasoningEngines/.../memories/.../revisions/..."))
"""
[
MemoryRevision(
name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/456",
fact="This is my updated fact",
extracted_memories=[
IntermediateExtractedMemory(
fact='This is the output of extraction for a single request.'
),
],
...
),
MemoryRevision(
name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/123",
fact="This is my original fact",
extracted_memories=[
IntermediateExtractedMemory(
fact='This is my original fact.'
),
],
...
)
]
"""
Argomenti della memoria
Gli "argomenti della memoria" identificano le informazioni che Memory Bank considera significative e che, pertanto, devono essere conservate come memorie generate. Memory Bank supporta due tipi di argomenti di memoria:
Argomenti gestiti: l'etichetta e le istruzioni sono definite da Memory Bank. Devi solo fornire il nome dell'argomento gestito. Ad esempio:
Dizionario
memory_topic = { "managed_memory_topic": { "managed_topic_enum": "USER_PERSONAL_INFO" } }Basato su classi
from agentplatform.types import ManagedTopicEnum from agentplatform.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic from agentplatform.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic memory_topic = MemoryTopic( managed_memory_topic=ManagedMemoryTopic( managed_topic_enum=ManagedTopicEnum.USER_PERSONAL_INFO ) )Argomenti personalizzati: l'etichetta e le istruzioni vengono definite da te durante la configurazione dell'istanza di Memory Bank. Verranno utilizzate nel prompt per il passaggio di estrazione di Memory Bank. Ad esempio:
Dizionario
memory_topic = { "custom_memory_topic": { "label": "business_feedback", "description": """Specific user feedback about their experience at the coffee shop. This includes opinions on drinks, food, pastries, ambiance, staff friendliness, service speed, cleanliness, and any suggestions for improvement.""" } }Basato su classi
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic from agentplatform.types import MemoryBankCustomizationConfigMemoryTopicCustomMemoryTopic as CustomMemoryTopic memory_topic = MemoryTopic( custom_memory_topic=CustomMemoryTopic( label="business_feedback", description="""Specific user feedback about their experience at the coffee shop. This includes opinions on drinks, food, pastries, ambiance, staff friendliness, service speed, cleanliness, and any suggestions for improvement.""" ) )Quando utilizzi argomenti personalizzati, ti consigliamo di fornire anche esempi di few-shot per mostrare come estrarre i ricordi dalla conversazione.
Per impostazione predefinita, Memory Bank conserva tutti i seguenti argomenti gestiti:
Informazioni utente (
USER_PERSONAL_INFO): informazioni significative sull'utente, come nomi, relazioni, hobby e date importanti. Ad esempio, "Lavoro in Google" o "Il mio anniversario di matrimonio è il 31 dicembre".Preferenze dell'utente (
USER_PREFERENCES): Mi piace, Non mi piace, stili o comportamenti tipici dichiarati o impliciti. Ad esempio, "Preferisco il posto centrale".Eventi chiave della conversazione e risultati delle attività (
KEY_CONVERSATION_DETAILS): traguardi o conclusioni importanti all'interno del dialogo. Ad esempio, "Ho prenotato biglietti aerei per un viaggio di andata e ritorno tra JFK e SFO. Parto il 1° giugno 2025 e torno il 7 giugno 2025."Istruzioni esplicite di memorizzazione/eliminazione (
EXPLICIT_INSTRUCTIONS): informazioni che l'utente chiede esplicitamente all'agente di memorizzare o eliminare. Ad esempio, se l'utente dice "Ricorda che utilizzo principalmente Python", Memory Bank genera un ricordo come "Utilizzo principalmente Python".
Ciò equivale a utilizzare il seguente insieme di argomenti sulla memoria gestita:
Dizionario
memory_topics = [
{"managed_memory_topic": {"managed_topic_enum": "USER_PERSONAL_INFO"}},
{"managed_memory_topic": {"managed_topic_enum": "USER_PREFERENCES"}},
{"managed_memory_topic": {"managed_topic_enum": "KEY_CONVERSATION_DETAILS"}},
{"managed_memory_topic": {"managed_topic_enum": "EXPLICIT_INSTRUCTIONS"}},
]
Basato su classi
from agentplatform.types import ManagedTopicEnum
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic
memory_topics = [
MemoryTopic(
managed_memory_topic=ManagedMemoryTopic(
managed_topic_enum=ManagedTopicEnum.USER_PERSONAL_INFO)),
MemoryTopic(
managed_memory_topic=ManagedMemoryTopic(
managed_topic_enum=ManagedTopicEnum.USER_PREFERENCES)),
MemoryTopic(
managed_memory_topic=ManagedMemoryTopic(
managed_topic_enum=ManagedTopicEnum.KEY_CONVERSATION_DETAILS)),
MemoryTopic(
managed_memory_topic=ManagedMemoryTopic(
managed_topic_enum=ManagedTopicEnum.EXPLICIT_INSTRUCTIONS)),
]
Se vuoi personalizzare gli argomenti che la Memory Bank conserva, imposta gli argomenti della memoria nella configurazione di personalizzazione durante la configurazione della Memory Bank.
Utilizzo dei metadati durante il consolidamento
Puoi allegare metadati ai ricordi generati. I metadati ti consentono di archiviare informazioni strutturate (stringhe, valori double, booleani o timestamp) insieme a un fatto memorizzato. Questo è utile per filtrare o gestire i cicli di vita dei ricordi.
Dizionario
import datetime
client.memory_banks.memories.generate(
...,
config={
"metadata": {
"my_string_key": {"string_value": "my_string_value"},
"my_double_key": {"double_value": 123.456},
"my_boolean_key": {"bool_value": True},
"my_timestamp_key": {
"timestamp_value": datetime.datetime(
2027, 1, 1, 12, 30, 00, tzinfo=datetime.timezone.utc
)
}
},
"metadata_merge_strategy": "MERGE"
},
)
Basato su classi
import datetime
from agentplatform import types
client.memory_banks.memories.generate(
...,
config=types.GenerateMemoriesConfig(
metadata={
"my_string_key": types.MemoryMetadataValue(string_value="my_string_value"),
"my_double_key": types.MemoryMetadataValue(double_value=123.456),
"my_boolean_key": types.MemoryMetadataValue(bool_value=True),
"my_timestamp_key": types.MemoryMetadataValue(
timestamp_value=datetime.datetime(
2027, 1, 1, 12, 30, 00, tzinfo=datetime.timezone.utc
)
),
},
metadata_merge_strategy=types.MemoryMetadataMergeStrategy.MERGE,
)
)
Utilizzando un metadata_merge_strategy, puoi controllare il modo in cui i nuovi metadati interagiscono con i ricordi esistenti durante il consolidamento:
MERGE: (predefinito) combina i nuovi metadati con quelli esistenti. Se una chiave esiste già, il nuovo valore sovrascrive quello precedente.OVERWRITE: sostituisci i metadati dei ricordi aggiornati con i nuovi metadati.REQUIRE_EXACT_MATCH: limita il consolidamento ai ricordi che hanno esattamente gli stessi metadati della richiesta. Se un ricordo non ha gli stessi metadati, non è idoneo per il consolidamento e non verrà aggiornato.
Generazione di ricordi per un sottoinsieme di argomenti
Per impostazione predefinita, la generazione della memoria estrae i dati per tutti gli argomenti della memoria che hai configurato durante la configurazione dell'istanza di Memory Bank.
Per una richiesta GenerateMemories specifica, puoi limitare l'estrazione a un sottoinsieme di argomenti configurati. Per configurare gli argomenti consentiti, utilizza il campo allowed_topics.
Dizionario
client.memory_banks.memories.generate(
...,
config={
"allowed_topics": [
{"managed_memory_topic": "USER_PERSONAL_INFO"},
{"custom_memory_topic_label": "business_feedback"}
]
},
)
Basato su classi
from agentplatform import types
client.memory_banks.memories.generate(
...,
config=types.GenerateMemoriesConfig(
allowed_topics=[
types.MemoryTopicId(
managed_memory_topic=types.ManagedTopicEnum.USER_PERSONAL_INFO
),
types.MemoryTopicId(
custom_memory_topic_label="business_feedback"
)
]
)
)
Attivazione della generazione di memoria
Puoi attivare la generazione dei ricordi utilizzando uno dei seguenti metodi:
GenerateMemories: importa i dati in Memory Bank e attiva immediatamente la generazione della memoria. Questo metodo è utile quando vuoi generare ricordi in un momento specifico, ad esempio alla fine di una sessione o a intervalli regolari all'interno di una sessione.IngestEvents: importa i dati in Memory Bank in modo continuo e lascia che Memory Bank li elabori quando vengono soddisfatti i criteri di attivazione. Questo metodo è utile quando hai un flusso continuo di eventi e vuoi che Memory Bank gestisca automaticamente il buffering e attivi la generazione di ricordi in base al volume o al tempo. Per saperne di più, consulta Importa eventi.
La generazione di informazioni salvate estrae il contesto chiave dalle conversazioni di origine e lo combina con le informazioni salvate esistenti per lo stesso ambito. Ad esempio, puoi creare
memorie a livello di sessione utilizzando un ambito come {"user_id": "123",
"session_id": "456"}. I ricordi con lo stesso ambito possono essere consolidati e recuperati insieme.
GenerateMemories è un'operazione a lunga esecuzione.
Una volta completata l'operazione, GenerateMemoriesOperation contiene un elenco di ricordi generati, se presenti:
GenerateMemoriesOperation(
name="projects/.../locations/.../reasoningEngines/.../operations/...",
done=True,
response=GenerateMemoriesResponse(
generatedMemories=[
GenerateMemoriesResponseGeneratedMemory(
memory=Memory(
"name": "projects/.../locations/.../reasoningEngines/.../memories/..."
),
action="CREATED",
),
GenerateMemoriesResponseGeneratedMemory(
memory=Memory(
"name": "projects/.../locations/.../reasoningEngines/.../memories/..."
),
action="UPDATED",
),
GenerateMemoriesResponseGeneratedMemory(
memory=Memory(
"name": "projects/.../locations/.../reasoningEngines/.../memories/..."
),
action="DELETED",
),
]
)
)
Ogni ricordo generato include l'action eseguita su quel ricordo:
CREATED: indica che è stata aggiunta una nuova memoria, che rappresenta un nuovo concetto non acquisito dalle memorie esistenti.UPDATED: indica che un ricordo esistente è stato aggiornato, il che accade se il ricordo copre concetti simili alle informazioni appena estratte. Il fatto del ricordo potrebbe essere aggiornato con nuove informazioni o rimanere invariato.DELETED: indica che la memoria esistente è stata eliminata perché le sue informazioni erano in contraddizione con le nuove informazioni estratte dalla conversazione.
Per i ricordi CREATED o UPDATED, puoi utilizzare GetMemories per recuperare i contenuti completi del ricordo.
Il recupero dei ricordi di DELETED genera un errore 404.
Generazione dei ricordi in background
GenerateMemories è un'operazione a lunga esecuzione. Per impostazione predefinita,
client.memory_banks.memories.generate è una funzione di blocco che esegue il polling dell'operazione fino al suo completamento. L'esecuzione della generazione di ricordi come operazione di blocco è utile quando vuoi ispezionare manualmente i ricordi generati o informare gli utenti finali sui ricordi generati.
Tuttavia, per gli agenti di produzione, in genere è consigliabile eseguire la generazione della memoria in background come processo asincrono. Nella maggior parte dei casi, il client non ha bisogno di utilizzare l'output per l'esecuzione corrente, quindi non è necessario incorrere in una latenza aggiuntiva in attesa di una risposta. Se vuoi che la generazione della memoria venga eseguita in background, imposta wait_for_completion su False:
client.memory_banks.memories.generate(
...,
config={
"wait_for_completion": False
}
)
In alternativa alla chiamata asincrona di GenerateMemories, puoi utilizzare IngestEvents, che disaccoppia l'importazione degli eventi dalla generazione della memoria ed elabora gli eventi in background per impostazione predefinita.
Origini dati
Esistono diversi modi per fornire i dati di origine per la generazione dei ricordi:
Fornisci gli eventi utilizzando le sessioni della piattaforma dell'agente.
Fornisci informazioni pre-estratte per consolidarle con i ricordi esistenti per lo stesso ambito.
Quando fornisci gli eventi direttamente nel payload o utilizzi le sessioni, le informazioni vengono estratte dalla conversazione e consolidate con le informazioni salvate esistenti. Se vuoi solo estrarre informazioni da queste origini dati, puoi disattivare il consolidamento:
client.memory_banks.memories.generate(
...
config={
"disable_consolidation": True
}
)
Utilizzo degli eventi nel payload come origine dati
Utilizza direct_contents_source quando vuoi generare ricordi utilizzando gli eventi
forniti direttamente nel payload. Da questi eventi vengono estratte informazioni significative, che vengono poi consolidate con le informazioni esistenti per lo stesso ambito. Questo approccio può essere utilizzato se utilizzi uno spazio di archiviazione delle sessioni diverso da Agent Platform Sessions.
Dizionario
Gli eventi devono includere dizionari Content.
events = [
{
"content": {
"role": "user",
"parts": [
{"text": "I work with LLM agents!"}
]
}
}
]
client.memory_banks.memories.generate(
name=memory_bank.name,
direct_contents_source={
"events": EVENTS
},
# For example, `scope={"user_id": "123"}`.
scope=SCOPE,
config={
"wait_for_completion": True
}
)
Sostituisci quanto segue:
SCOPE: un dizionario che rappresenta l'ambito dei ricordi generati. Ad esempio,{"session_id": "MY_SESSION"}. Solo i ricordi con lo stesso ambito vengono presi in considerazione per il consolidamento.
Basato su classi
Gli eventi devono includere oggetti Content.
from google import genai
from agentplatform import types
events = [
types.GenerateMemoriesRequestDirectContentsSourceEvent(
content=genai.types.Content(
role="user",
parts=[
genai.types.Part.from_text(text="I work with LLM agents!")
]
)
)
]
client.memory_banks.memories.generate(
name=memory_bank.name,
direct_contents_source={
"events": events
},
# For example, `scope={"user_id": "123"}`.
scope=SCOPE,
config={
"wait_for_completion": True
}
)
Sostituisci quanto segue:
SCOPE: un dizionario che rappresenta l'ambito dei ricordi generati. Ad esempio,{"session_id": "MY_SESSION"}. Solo i ricordi con lo stesso ambito vengono presi in considerazione per il consolidamento.
Utilizzo delle sessioni di Agent Platform come origine dati
Con le sessioni, Memory Bank utilizza gli eventi di sessione come conversazione di origine per la generazione della memoria.
Per definire l'ambito dei ricordi generati, Memory Bank estrae e utilizza l'ID utente della sessione per impostazione predefinita. Ad esempio, l'ambito dei ricordi viene
memorizzato come {"user_id": "123"} se il user_id
della sessione
è "123". Puoi anche fornire direttamente un scope, che sostituisce l'utilizzo del user_id della sessione come ambito.
Dizionario
client.memory_banks.memories.generate(
name=memory_bank.name,
vertex_session_source={
# For example, projects/.../locations/.../reasoningEngines/.../sessions/...
"session": "SESSION_NAME"
},
# Optional when using Sessions. Defaults to {"user_id": session.user_id}.
scope=SCOPE,
config={
"wait_for_completion": True
}
)
Sostituisci quanto segue:
SESSION_NAME: il nome della sessione completo.(Facoltativo)
SCOPE: un dizionario che rappresenta l'ambito dei ricordi generati. Ad esempio,{"session_id": "MY_SESSION"}. Solo i ricordi con lo stesso ambito vengono presi in considerazione per il consolidamento. Se non viene fornito, viene utilizzato{"user_id": session.user_id}.
Basato su classi
from agentplatform import types
client.memory_banks.memories.generate(
name=memory_bank.name,
vertex_session_source=types.GenerateMemoriesRequestVertexSessionSource(
# For example, projects/.../locations/.../reasoningEngines/.../sessions/...
session="SESSION_NAME"
),
# Optional when using Sessions. Defaults to {"user_id": session.user_id}.
scope=SCOPE,
config={
"wait_for_completion": True
}
)
Se vuoi, puoi fornire un intervallo di tempo che indica quali eventi della sessione devono essere inclusi. Se non viene fornito, vengono inclusi tutti gli eventi della sessione.
Dizionario
import datetime
client.memory_banks.memories.generate(
name=memory_bank.name,
vertex_session_source={
"session": "SESSION_NAME",
# Extract memories from the last hour of events.
"start_time": datetime.datetime.now(tz=datetime.timezone.utc) - datetime.timedelta(seconds=24 * 60),
"end_time": datetime.datetime.now(tz=datetime.timezone.utc)
},
scope=SCOPE
)
Basato su classi
import datetime
from agentplatform import types
client.memory_banks.memories.generate(
name=memory_bank.name,
vertex_session_source=types.GenerateMemoriesRequestVertexSessionSource(
session="SESSION_NAME",
# Extract memories from the last hour of events.
start_time=datetime.datetime.now(tz=datetime.timezone.utc) - datetime.timedelta(seconds=24 * 60),
end_time=datetime.datetime.now(tz=datetime.timezone.utc)
),
scope=SCOPE
)
Consolidamento dei ricordi pre-estratti
In alternativa all'utilizzo del processo di estrazione automatica di Memory Bank, puoi fornire direttamente i ricordi pre-estratti. I ricordi delle fonti dirette verranno consolidati con i ricordi esistenti per lo stesso ambito. Questo può essere utile quando vuoi che il tuo agente o un human-in-the-loop sia responsabile dell'estrazione dei ricordi, ma vuoi comunque sfruttare il consolidamento di Memory Bank per assicurarti che non ci siano ricordi duplicati o contraddittori.
client.memory_banks.memories.generate(
name=memory_bank.name,
direct_memories_source={"direct_memories": [{"fact": "FACT"}]},
scope=SCOPE
)
Sostituisci quanto segue:
FACT: il fatto pre-estratto che deve essere consolidato con i ricordi esistenti. Puoi fornire fino a 5 fatti pre-estratti in un elenco come il seguente:{"direct_memories": [{"fact": "fact 1"}, {"fact": "fact 2"}]}SCOPE: un dizionario che rappresenta l'ambito dei ricordi generati. Ad esempio,{"session_id": "MY_SESSION"}. Solo i ricordi con lo stesso ambito vengono presi in considerazione per il consolidamento.
Utilizzo dell'input multimodale
Puoi estrarre i ricordi da un input multimodale. Tuttavia, i ricordi vengono estratti solo dal testo, dai file incorporati e dai dati dei file nei contenuti della fonte. Tutti gli altri contenuti, incluse le chiamate di funzione e le risposte, vengono ignorati durante la generazione dei ricordi.
I ricordi possono essere estratti da immagini, video e audio forniti dall'utente. Se il contesto fornito dall'input multimodale viene giudicato da Memory Bank come significativo per le interazioni future, potrebbe essere creata una memoria testuale che include le informazioni estratte dall'input. Ad esempio, se l'utente fornisce un'immagine di un golden retriever con il testo "Questo è il mio cane", Memory Bank genera un ricordo come "Il mio cane è un golden retriever".
Ad esempio, puoi fornire un'immagine e il contesto dell'immagine nel payload:
Dizionario
with open(file_name, "rb") as f:
inline_data = f.read()
events = [
{
"content": {
"role": "user",
"parts": [
{"text": "This is my dog"},
{
"inline_data": {
"mime_type": "image/jpeg",
"data": inline_data
}
},
{
"file_data": {
"file_uri": "gs://cloud-samples-data/generative-ai/image/dog.jpg",
"mime_type": "image/jpeg"
}
},
]
}
}
]
Basato su classi
from google import genai
from agentplatform import types
with open(file_name, "rb") as f:
inline_data = f.read()
events = [
types.GenerateMemoriesRequestDirectContentsSourceEvent(
content=genai.types.Content(
role="user",
parts=[
genai.types.Part.from_text(text="This is my dog"),
genai.types.Part.from_bytes(
data=inline_data,
mime_type="image/jpeg",
),
genai.types.Part.from_uri(
file_uri="gs://cloud-samples-data/generative-ai/image/dog.jpg",
mime_type="image/jpeg",
)
]
)
)
]