本頁面由 Cloud Translation API 翻譯而成。

回憶集錦修訂版本

本頁面說明如何為 Vertex AI Agent Engine Memory Bank 建立及管理記憶體修訂版本資源。

回憶集和修訂版本的生命週期

資料來源和記憶體修訂版本

您可以直接 (分別使用 CreateMemory、UpdateMemory 或 DeleteMemory) 或動態 (使用 GenerateMemories) 建立、更新或刪除記憶體。記憶體修訂版本資源會提供記憶體資源在所有變更作業中的完整版本記錄。每當建立或修改記憶體時，系統都會自動儲存新的不可變更修訂版本。讓您清楚瞭解記憶內容的演變過程，以及 (如果是生成記憶內容) 每個步驟中擷取和整合的具體資訊。

每個記憶體資源都有一或多個相關聯的子項記憶體修訂版本資源：

Memory 資源一律會反映資訊的目前整合狀態。單一記憶體可以反映多個要求和資料來源的衍生資料。

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(...)
)

MemoryRevisions 資源代表父項記憶體的歷史狀態。每個修訂版本都是突變事件發生時的記憶體快照。如果記憶體是使用 GenerateMemories 突變，修訂版本也會包含從資料來源 (extracted_memories) 擷取的資訊，然後再與記憶體的現有內容合併。

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/...'
)

記憶體修訂版本預設為啟用。如要停用記憶體修訂版本，請參閱「停用記憶體修訂版本」。

建立記憶

您可以直接使用 CreateMemory 建立記憶體，也可以使用 GenerateMemories 動態建立記憶體。如果沒有涵蓋相同範圍類似資訊的現有記憶內容，系統就會生成記憶內容：

# Direct creation using CreateMemory
client.agent_engines.memories.create(name=agent_engine_name, ...)

# Dynamic creation using GenerateMemory
client.agent_engines.memories.generate_memories(name=agent_engine_name, ...)

建立記憶體時，系統會建立單一 Memory 資源和子項 MemoryRevision：

client.agent_engines.memories.get(name=memory_name)
"""
Memory(
  name="projects/123/locations/us-central1/reasoningEngines/456/memories/789",
  fact="This is my original fact.",
  ...
)
"""

list(client.agent_engines.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",
    ...
  )
]
"""

記憶體更新

您可以直接使用 UpdateMemory 更新記憶體，也可以使用 GenerateMemories 動態更新記憶體。透過記憶生成功能，當整合程序判定新資訊與相同範圍的所有現有記憶重複、互補或矛盾時，系統就會動態更新記憶。

# Direct update using UpdateMemory
client.agent_engines.memories.update(name=memory_name, ...)

# Dynamic update using GenerateMemories
client.agent_engines.memories.generate_memories(name=agent_engine_name, ...)

回憶集錦更新時，現有的 Memory 資源會更新，並建立新的子項 MemoryRevision。

client.agent_engines.memories.get(name=memory_name)
"""
Memory(
  name="projects/123/locations/us-central1/reasoningEngines/456/memories/789",
  fact="This is my updated fact.",
  ...
)
"""

list(client.agent_engines.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",
    ...
  )
]
"""

刪除個人化記憶

記憶體可以直接使用 DeleteMemory，也可以動態使用 GenerateMemories。在記憶生成過程中，如果整併程序判定新資訊會使相同範圍的現有資訊失效，系統就會動態刪除記憶。

# Direct deletion using UpdateMemory
client.agent_engines.memories.delete(name=memory_name, ...)

# Dynamic delete using GenerateMemories
client.agent_engines.memories.generate_memories(name=agent_engine_name, ...)

刪除記憶體時，系統會刪除現有的 Memory 資源，並建立新的子項 MemoryRevision。最新記憶體修訂版本中的 fact 為空，因為這反映了刪除突變。

client.agent_engines.memories.get(name=memory_name)
"""
404 Not Found.
"""

list(client.agent_engines.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",
    ...
  )
]
"""

家長刪除回憶集錦後，孩子的回憶集錦修訂版本只會保留 48 小時。在復原期限內，您可以繼續檢查記憶體修訂版本，並將記憶體復原到先前的修訂版本。

記憶體修訂作業

本節說明如何檢查記憶體修訂版本，以及將記憶體復原至先前的修訂版本。

列出修訂版本

使用 ListMemoryRevisions 傳回記憶體的所有修訂版本。

list(client.agent_engines.memories.revisions.list(name=MEMORY_NAME))

更改下列內容：

MEMORY_NAME：記憶體的資源名稱，格式為：projects/.../locations/.../reasoningEngines/.../memories/...

生成回憶集時，您可以提供要套用至相關修訂版本的修訂版本標籤。標籤是任意鍵/值組合。舉例來說，您可以為修訂版本加上標籤，標示用於生成記憶體的資料來源 ID，然後依據這個標籤篩選修訂版本：

response = client.agent_engines.memories.generate(
    ...,
    config={
        "revision_labels": {
            "data_source": "321"
        }
    }
)

list(client.agent_engines.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"
    }
    ...
  )
]
"""

取得修訂版本

使用 GetMemoryRevision 擷取個別記憶體修訂版本。

client.agent_engines.memories.revisions.get(name=MEMORY_REVISION_NAME)

更改下列內容：

MEMORY_REVISION_NAME：要擷取的記憶體修訂版本資源名稱，格式為：projects/.../locations/.../reasoningEngines/.../memories/.../revisions/...

復原回憶集錦

使用 RollbackMemory 將記憶體復原至先前的修訂版本。

client.agent_engines.memories.rollback(
    name=name=MEMORY_NAME,
    target_revision_id=REVISION_ID
)

更改下列內容：

MEMORY_NAME：要更新的記憶體資源名稱，格式為：projects/.../locations/.../reasoningEngines/.../memories/...
REVISION_ID：應還原的修訂版本 ID。這是記憶體修訂版本資源名稱的最後一個區隔，例如 projects/MyProject/locations/us-central1/reasoningEngines/123/memories/456/revisions/789 中的 789。

如要復原 GenerateMemories 對回憶集錦所做的變更，請將回憶集錦還原至變更前的版本。記憶體生成回應會包含每個更新或刪除記憶體的前一個修訂版本參照 (previous_revision)：

operation = client.agent_engines.memories.generate(
  ...
)

# Rollback the first generated memory to the previous revision.
client.agent_engines.memories.rollback(
    name=operation.response.generated_memories[0].memory.name,
    target_revision_id=operation.response.generated_memories[0].previous_revision
)

停用記憶體修訂版本

記憶體修訂版本預設為啟用。您可以為所有對記憶庫執行個體的要求，或為每個個別要求停用記憶體修訂版本。如果停用記憶體修訂版本，記憶體發生變化時就不會建立記憶體修訂版本。

設定記憶庫執行個體時，可以針對所有要求停用記憶體修訂版本：

client.agent_engines.create(
  config={
    "context_spec": {
      "memory_bank_config": {
        "disable_memory_revisions": True
      }
    }
  }
)

傳送要求時，您可以在要求層級停用記憶體修訂：

產生

client.agent_engines.memories.generate(
  ...,
  "config": {
    "disable_memory_revisions": True
  }
)

建立

client.agent_engines.memories.create(
  ...,
  "config": {
    "disable_memory_revisions": True
  }
)

更新

client.agent_engines.memories.update(
  ...,
  "config": {
    "disable_memory_revisions": True
  }
)

修訂版本到期

記憶體修訂內容不會永久保留。您必須設定修訂版本的到期日，或使用預設到期日。預設存留時間 (TTL) 為 365 天。您可以為所有傳送至 Memory Bank 執行個體的要求設定到期時間，也可以為每項要求個別設定。記憶體修訂版本過期後，就無法檢查或回溯。

設定 Memory Bank 執行個體時，您可以為所有要求設定存留時間：

client.agent_engines.create(
  config={
    "context_spec": {
      "memory_bank_config": {
        "ttl_config": {
          # Persist memory revisions for 30 days after they're created.
          "revision_ttl": f"{30 * 60 * 60 * 24}s"
        }
      }
    }
  }
)

如要在要求層級為每個記憶體修訂版本設定 TTL，請在要求中加入 revision_expire_time 或 revision_ttl：

存留時間

config = {
    # Persist memory revisions for 30 days after they're created.
    "revision_ttl": f"{30 * 60 * 60 * 24}s"
}

client.agent_engines.memories.create(
  ...,
  config=config
)

client.agent_engines.memories.update(
  ...,
  config=config
)

client.agent_engines.memories.generate(
  ...,
  config=config
)

有效期限

import datetime

config = {
    "revision_expire_time": datetime.datetime.now(tz=datetime.timezone.utc) + datetime.timedelta(weeks=3)
}

client.agent_engines.memories.create(
  ...,
  config=config
)

client.agent_engines.memories.update(
  ...,
  config=config
)

client.agent_engines.memories.generate(
  ...,
  config=config
)

回憶集錦修訂版本 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

回憶集和修訂版本的生命週期

建立記憶

記憶體更新

刪除個人化記憶

記憶體修訂作業

列出修訂版本

取得修訂版本

復原回憶集錦

停用記憶體修訂版本

產生

建立

更新

修訂版本到期

存留時間

有效期限

回憶集錦修訂版本