此页面由 Cloud Translation API 翻译。

内存修订版本

本页面介绍了如何为 Vertex AI Agent Engine 记忆库创建和管理记忆库修订版资源。

记忆及其修订版本的生命周期

数据源和内存修订版本

您可以直接（分别使用 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 天。您可以为发送到记忆库实例的所有请求或每个单独的请求配置过期时间。记忆修订版本过期后，将无法进行检查或回滚。

您可以在设置记忆库实例时，为向该实例发出的所有请求配置 TTL：

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：

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
)

内存修订版本 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

记忆及其修订版本的生命周期

记忆创建

记忆更新

记忆删除

内存修订版操作

列出修订版本

获取修订版本

回滚回忆

停用内存修订版本

生成

创建

更新

修订版本过期

TTL

到期日期

内存修订版本