記憶體修訂

Agent Platform 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.memory_banks.memories.create(name=memory_bank_name, ...)

# Dynamic creation using GenerateMemory
client.memory_banks.memories.generate(name=memory_bank_name, ...)

建立記憶時,系統會建立單一 Memory 資源和子項 MemoryRevision:

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

記憶體更新

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

# 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, ...)

更新記憶時,系統會更新現有的 Memory 資源,並建立新的子項 MemoryRevision。

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

刪除記憶

您可以使用 DeleteMemory 直接建立回憶,或使用 GenerateMemories 動態建立回憶。使用記憶生成功能時,如果整合程序判定新資訊會使相同範圍的現有資訊失效,系統就會動態刪除記憶。

# 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, ...)

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

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

刪除父項記憶後,子項記憶修訂版本最多只能存取 48 小時。在這段復原期間,您可以繼續檢查記憶體修訂版本,並將記憶體復原至先前的修訂版本。

記憶修訂版本操作

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

列出修訂版本

您可以在 Google Cloud 控制台或使用 Agent Platform SDK 檢查記憶體修訂版本。

控制台

如要在 Google Cloud 控制台查看記憶體修訂版本,必須具備aiplatform.memoryRevisions.list權限 (包含在roles/aiplatform.memoryViewer和roles/aiplatform.memoryUser中),且無法在快捷模式中使用。

  1. 在 Google Cloud 控制台中開啟執行個體:

    • 獨立 Memory Bank 執行個體:前往 Agent Platform 的「Memory Bank」頁面,然後點選執行個體。

      前往記憶庫

    • 部署至 Agent Runtime 的代理:前往 Agent Platform 的「Deployments」(部署作業) 頁面,然後點選代理。

      前往「Deployments」(部署作業) 頁面

  2. 開啟「回憶集錦」分頁:

    • 非結構化記憶:在記憶列上,依序點選「更多動作」選單 () 「查看修訂版本」。
    • 結構化設定檔 (獨立執行個體):選取「Structured」,選擇完整範圍,按一下設定檔列上的「View」開啟「Memory details」,然後按一下記憶體事實的「View revisions」。

    修訂版本面板會列出每個修訂版本的「建立時間」、「到期時間」、「事實」和「背景資訊」欄位。

Agent Platform SDK

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

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

更改下列內容:

  • MEMORY_NAME:記憶體的資源名稱,格式如下:projects/.../locations/.../reasoningEngines/.../memories/...

產生記憶體時,您可以提供修訂版本標籤,套用至相關聯的修訂版本。標籤是任意鍵/值組合。舉例來說,您可以使用用於產生記憶體的資料來源 ID 標記修訂版本,然後依據這個標籤篩選修訂版本:

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

要求修改

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

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

更改下列內容:

  • MEMORY_REVISION_NAME:要擷取的記憶體修訂版本資源名稱,格式如下:projects/.../locations/.../reasoningEngines/.../memories/.../revisions/...

復原回憶集錦

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

client.memory_banks.memories.rollback(
    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.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
)

停用記憶修訂版本

記憶修訂功能預設為啟用。您可以針對傳送至記憶庫執行個體的所有要求,或個別要求停用記憶修訂版本。如果停用記憶修訂版本,則記憶變更時不會建立記憶修訂版本。

如要關閉記憶庫執行個體所有要求的記憶修訂功能,請前往 Google Cloud 控制台 (依序點選「設定」>「保留」,或依序點選「服務設定」>「記憶庫」),或使用 Agent Platform SDK:

memory_bank = client.memory_banks.create(
  managed_semantic_memory_config={
    "disable_memory_revisions": True
  }
)

傳送要求時,您可以在要求層級停用記憶修訂版本:

產生

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

建立

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

更新

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

修訂版本到期日

記憶修訂版本不會永久保留。您必須設定修訂版本的到期時間,或使用預設到期時間。預設存留時間 (TTL) 為 365 天。您可以為 Memory Bank 執行個體的所有要求設定到期時間,也可以為個別要求設定。記憶體修訂版本過期後,就無法檢查或復原。

您可以在 Google Cloud 控制台 (依序點選「設定」>「保留」,或依序點選「服務設定」>「記憶庫」,適用於已部署的代理),或使用 Agent Platform SDK,為所有傳送至記憶庫執行個體的要求設定修訂版本記錄存留時間:

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

如要在要求層級為每個記憶體修訂版本設定存留時間,請在要求中加入 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.memory_banks.memories.create(
  ...,
  config=config
)

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

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

有效期限

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
)