Generare ricordi

Questo documento spiega come funziona il salvataggio di informazioni, come personalizzare l'estrazione delle informazioni con gli argomenti e come attivare le richieste di generazione di informazioni.

Per informazioni sulla configurazione dell'ambiente, vedi Configurazione per Memory Bank.

Informazioni sulla generazione di memoria

Memory Bank estrae i ricordi dai dati di origine e li seleziona automaticamente per una raccolta specifica (definita da un scope) aggiungendo, aggiornando e rimuovendo i ricordi nel tempo.

Quando attivi la generazione di ricordi, Memory Bank esegue le seguenti operazioni:

• Estrazione: estrae informazioni sull'utente dalle sue conversazioni con l'agente. Vengono conservate solo le informazioni che corrispondono ad almeno uno degli argomenti di memoria della tua 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 le memorie idonee al 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 un ricordo. Per identificare meglio le tendenze a lungo termine e confermare i dati, puoi aumentare revisions_per_candidate_count quando crei l'istanza di Agent Platform per includere più revisioni storiche nella logica di consolidamento.

Puoi esaminare i passaggi intermedi del salvataggio di informazioni 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 di 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 rese persistenti come ricordi generati. Memory Bank supporta due tipi di argomenti dei ricordi:

• 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 sulla classe

  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 utilizzati 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 sulla classe

  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 few-shot per mostrare come devono essere estratte le memorie dalla conversazione.

Per impostazione predefinita, Memory Bank conserva tutti gli argomenti gestiti seguenti:

• 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 preferiti 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 per ricordare / dimenticare (EXPLICIT_INSTRUCTIONS): Informazioni che l'utente chiede esplicitamente all'agente di ricordare o dimenticare. 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 di memoria gestita:

  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"}},
  ]

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 rende persistenti, 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, numeri reali, valori booleani o timestamp) insieme a un ricordo. È utile per filtrare o gestire i cicli di vita dei ricordi.

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

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: (impostazione predefinita) 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 di ricordi estrae i dati per tutti gli argomenti dei ricordi che hai configurato quando hai configurato l'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.

client.memory_banks.memories.generate(
    ...,
    config={
        "allowed_topics": [
            {"managed_memory_topic": "USER_PERSONAL_INFO"},
            {"custom_memory_topic_label": "business_feedback"}
        ]
    },
)

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"
            )
        ]
    )
)

Attivare la generazione di ricordi

Puoi attivare la generazione di ricordi utilizzando uno dei seguenti metodi:

• GenerateMemories: importa i dati in Memory Bank e attiva immediatamente la generazione di ricordi. 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: inserisci continuamente i dati in Memory Bank e lascia che Memory Bank li elabori quando i criteri di attivazione vengono soddisfatti. Questo metodo è utile quando hai un flusso continuo di eventi e vuoi che Memory Bank gestisca automaticamente il buffering e attivi il salvataggio di informazioni in base al volume o al tempo. Per saperne di più, consulta Importa eventi.

La generazione di ricordi estrae il contesto chiave dalle conversazioni di origine e lo combina con i ricordi 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 è stato aggiunto un nuovo ricordo, che rappresenta un nuovo concetto non acquisito dai ricordi esistenti.

• UPDATED: indica che una memoria esistente è stata aggiornata, il che si verifica se la memoria copriva concetti simili alle informazioni appena estratte. Il fatto del ricordo potrebbe essere aggiornato con nuove informazioni o rimanere invariato.

• DELETED: indica che il ricordo esistente è stato eliminato 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 di 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 comunicare agli utenti finali quali ricordi sono stati generati.

Tuttavia, per gli agenti di produzione, in genere vuoi eseguire la generazione di memoria in background come processo asincrono. Nella maggior parte dei casi, il client non deve utilizzare l'output per l'esecuzione corrente, pertanto non è necessario incorrere in una latenza aggiuntiva in attesa di una risposta. Se vuoi che la generazione di ricordi 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 separa l'importazione degli eventi dalla generazione di memoria ed elabora gli eventi in background per impostazione predefinita.

Origini dati

Esistono diversi modi per fornire i dati di origine per la generazione di ricordi:

• Fornire gli eventi direttamente nel payload.

• Fornisci eventi utilizzando Agent Platform Sessions.

• Fornisci fatti pre-estratti per consolidarli con i ricordi esistenti per lo stesso ambito.

Quando fornisci eventi direttamente nel payload o utilizzi Sessioni, le informazioni vengono estratte dalla conversazione e consolidate con i ricordi 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 consolidate con le informazioni esistenti per lo stesso ambito. Questo approccio può essere utilizzato se utilizzi un'archiviazione delle sessioni diversa da Agent Platform Sessions.

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

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

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 di ricordi.

Per definire l'ambito dei ricordi generati, Memory Bank estrae e utilizza l'ID utente dalla 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 un scope direttamente, che sostituisce l'utilizzo di user_id della sessione come ambito.

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

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 alcun valore, vengono inclusi tutti gli eventi nella sessione.

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
)

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 preestratti

In alternativa all'utilizzo della procedura di estrazione automatica di Memory Bank, puoi fornire direttamente i ricordi preestratti. I ricordi delle origini 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 delle memorie, ma vuoi comunque sfruttare il consolidamento di Memory Bank per assicurarti che non ci siano memorie duplicate o contraddittorie.

client.memory_banks.memories.generate(
    name=memory_bank.name,
    direct_memories_source={"direct_memories": [{"fact": "FACT"}]},
    scope=SCOPE
)

Sostituisci quanto segue:

• FACT: Il fatto preestratto che deve essere consolidato con i ricordi esistenti. Puoi fornire fino a 5 fatti preestratti 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"}. Per il consolidamento vengono presi in considerazione solo i ricordi con lo stesso ambito.

Utilizzo dell'input multimodale

Puoi estrarre ricordi da input multimodali. Tuttavia, i ricordi vengono estratti solo da testo, file in linea e dati dei file nei contenuti di origine. 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 significativo per le interazioni future, potrebbe essere creata una memoria testuale che includa 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:

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"
          }
        },
      ]
    }
  }
]

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

Passaggi successivi