產生回憶集錦

記憶庫可從使用者與代理之間的對話建構長期記憶。本頁說明記憶集錦的生成方式、如何自訂記憶集錦的擷取方式，以及如何觸發記憶集錦生成作業。

瞭解記憶體生成

記憶體庫會從來源資料擷取記憶，並隨著時間新增、更新及移除記憶，自行為特定記憶集合 (由 scope 定義) 策劃記憶。

觸發記憶體生成作業時，記憶體庫會執行下列作業：

  • 擷取：從使用者與服務專員的對話中擷取使用者資訊。系統只會保留符合至少一個執行個體記憶體主題的資訊。

  • 合併：根據擷取的資訊，判斷是否應刪除或更新相同範圍的現有記憶內容。記憶體庫會先檢查新記憶體是否重複或矛盾，再與現有記憶體合併。如果現有記憶內容與新資訊不重疊，系統會建立新記憶內容。

記憶內容只能從來源內容中的文字、內嵌檔案和檔案資料擷取。生成回憶集錦時，系統會忽略所有其他內容，包括函式呼叫和回應。

系統會從使用者提供的圖片、影片和音訊中擷取記憶。如果記憶庫判斷多模態輸入提供的內容對日後互動有意義，系統可能會建立文字記憶，當中包含從輸入內容擷取的資訊。舉例來說，如果使用者提供黃金獵犬的圖片和「這是我的狗」文字，記憶庫就會生成「我的狗是黃金獵犬」等記憶。

回憶集錦主題

「記憶體主題」會識別記憶體銀行認為有意義的資訊，因此應保留為生成的回憶。記憶體庫支援兩種記憶體主題：

  • 管理主題：標籤和操作說明由記憶體庫定義。您只需要提供受管理主題的名稱。例如：

    字典

    memory_topic = {
    "managed_memory_topic": {
        "managed_topic_enum": "USER_PERSONAL_INFO"
    }
}

    以類別為準

    from vertexai.types import ManagedTopicEnum
from vertexai.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from vertexai.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic

memory_topic = MemoryTopic(
    managed_memory_topic=ManagedMemoryTopic(
        managed_topic_enum=ManagedTopicEnum.USER_PERSONAL_INFO
    )
)

  • 自訂主題：設定記憶體庫執行個體時，您可以自行定義標籤和說明。這些資訊會用於記憶體庫擷取步驟的提示。例如：

    字典

    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."""
    }
}

    以類別為準

    from vertexai.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from vertexai.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."""
    )
)

    使用自訂主題時，建議一併提供少量樣本，說明如何從對話中擷取記憶內容。

根據預設，記憶體庫會保留下列所有受管理的主題：

  • 個人資訊 (USER_PERSONAL_INFO)：使用者的重要個人資訊，例如姓名、關係、興趣和重要日期。例如「我在 Google 工作」或「我的結婚紀念日是 12 月 31 日」。
  • 使用者偏好設定 (USER_PREFERENCES)：明確或隱含的喜好、不喜好、偏好的風格或模式。例如「我比較喜歡中間的座位」。
  • 重要對話事件和工作結果 (KEY_CONVERSATION_DETAILS)：對話中的重要里程碑或結論。舉例來說，「我預訂了從 JFK 機場到 SFO 機場的來回機票。我將於 2025 年 6 月 1 日出發，並於 2025 年 6 月 7 日返回。
  • 明確的記憶 / 忘記指令 (EXPLICIT_INSTRUCTIONS)：使用者明確要求代理程式記憶或忘記的資訊。舉例來說，如果使用者說「記住我主要使用 Python」，記憶庫就會產生「我主要使用 Python」這類記憶。

這相當於使用下列一組受管理記憶體主題：

字典

  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 vertexai.types import ManagedTopicEnum
from vertexai.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from vertexai.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)),
]

如要自訂記憶體庫保留的主題，請在設定記憶體庫時，於自訂設定中設定記憶體主題。

生成回憶集錦

如要完成本指南中示範的步驟，請先按照「設定記憶體庫」中的步驟操作。

您可以在工作階段結束時或工作階段期間，以固定間隔使用 GenerateMemories 觸發記憶體生成作業。記憶內容生成功能會從來源對話中擷取重要脈絡，並與相同範圍的現有記憶內容合併。舉例來說，您可以使用 {"user_id": "123", "session_id": "456"} 等範圍建立工作階段層級的記憶體。您可以合併相同範圍的記憶內容，並一起擷取。

呼叫 GenerateMemories 時，您必須透過 Agent Engine Sessions 提供來源對話，或直接透過 JSON 格式提供：

JSON 格式

如果您使用的工作階段儲存空間與 Agent Engine Sessions 不同，請直接以 JSON 格式提供來源對話：

client.agent_engines.generate_memories(
    name=agent_engine.api_resource.name,
    direct_contents_source={
      "events": EVENTS
    },
    scope=SCOPE,
    config={
        "wait_for_completion": True
    }
)

更改下列內容：

  • EVENTS：內容字典清單。例如：
[
  {
    "content": {
      "role": "user",
      "parts": [
        {"text": "I'm work with LLM agents!"}
      ]
    }
  }
]
  • SCOPE：字典，代表生成回憶的範圍。例如，{"session_id": "MY_SESSION"}。只有相同範圍的記憶體才會合併。

Agent Engine 階段

透過 Agent Engine 工作階段，記憶體庫會使用工作階段事件做為產生記憶體的來源對話。

為限定生成的記憶內容範圍，記憶體庫預設會從工作階段中擷取並使用使用者 ID。舉例來說，如果工作階段的 user_id 是「123」，記憶體範圍就會儲存為 {"user_id": "123"}。您也可以直接提供 scope，這會覆寫以工作階段的 user_id 做為範圍的做法。

client.agent_engines.generate_memories(
  name=agent_engine.api_resource.name,
  vertex_session_source={
    "session": "SESSION_NAME"
  },
  # Optional when using Agent Engine Sessions. Defaults to {"user_id": session.user_id}.
  scope=SCOPE,
  config={
      "wait_for_completion": True
  }
)

更改下列內容：

  • SESSION_NAME：工作階段名稱。

  • (選用) SCOPE：字典，代表所產生回憶的範圍。例如，{"session_id": "MY_SESSION"}。系統只會合併範圍相同的記憶體。如果未提供，則使用 {"user_id": session.user_id}。

GenerateMemories 是長時間執行的作業。作業完成後，AgentEngineGenerateMemoriesOperation 會包含產生的回憶集錦清單 (如有)：

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

每個生成的記憶體都包含對該記憶體執行的 action：

  • CREATED：表示新增了記憶內容，代表現有記憶內容未擷取的新概念。
  • UPDATED：表示現有記憶內容已更新，如果記憶內容涵蓋的概念與新擷取的資訊類似，就會發生這種情況。記憶內容的事實可能會更新為新資訊，也可能維持不變。
  • DELETED：表示系統已刪除現有記憶內容，因為該內容與從對話中擷取的新資訊有矛盾之處。

如果是 CREATED 或 UPDATED 記憶體，可以使用 GetMemories 擷取記憶體的完整內容。擷取 DELETED 記憶體時發生 404 錯誤。

在背景生成回憶集錦

GenerateMemories 是長時間執行的作業。根據預設，client.agent_engines.generate_memories 是封鎖函式，會持續輪詢作業，直到作業完成為止。如要手動檢查產生的回憶集錦，或通知使用者產生了哪些回憶集錦，以封鎖作業的形式執行回憶集錦生成作業會很有幫助。

不過，對於正式版代理程式，您通常會希望在背景以非同步程序執行記憶體生成作業。在大多數情況下，用戶端不需要使用目前執行的輸出內容，因此不必等待回應而產生額外延遲。如要讓記憶體生成作業在背景執行，請將 wait_for_completion 設為 False：

client.agent_engines.generate_memories(
    ...,
    config={
        "wait_for_completion": False
    }
)

整合預先擷取的記憶內容

除了使用記憶體庫的自動擷取程序，你也可以直接提供預先擷取的記憶。直接來源回憶集錦會與相同範圍的現有回憶集錦合併。這項功能非常實用，因為您可讓專員或參與迴圈的人員負責擷取記憶內容，同時利用記憶庫的整合功能，確保沒有重複或矛盾的記憶內容。

client.agent_engines.generate_memories(
    name=agent_engine.api_resource.name,
    direct_memories_source={"direct_memories": [{"fact": "FACT"}]},
    scope=SCOPE
)

更改下列內容：

  • FACT：應與現有記憶內容合併的預先擷取事實。您最多可以在清單中提供 5 個預先擷取的事實，如下所示：

    {"direct_memories": [{"fact": "fact 1"}, {"fact": "fact 2"}]}

  • SCOPE：字典，代表生成回憶的範圍。例如，{"session_id": "MY_SESSION"}。只有相同範圍的記憶體才會合併。

後續步驟