擷取回憶

本頁說明如何從記憶體庫擷取生成和上傳的記憶體。如要瞭解如何設定、產生及使用 Memory Bank 的完整工作流程，請參閱「使用 REST API 快速入門」。

事前準備

如要完成本頁的步驟，請先完成「設定記憶體庫」中的步驟。

擷取作業

您可以透過下列選項擷取生成的記憶內容：

取得記憶內容：使用 Vertex AI SDK 取得單一記憶內容的完整內容。
列出記憶內容：使用 Vertex AI SDK 或 Google Cloud 控制台列出記憶內容。
擷取記憶內容：使用 Vertex AI SDK，透過範圍式記憶內容擷取功能擷取記憶內容。使用相似度搜尋或範圍內的所有回憶集錦，擷取回憶集錦。

取得記憶體

使用 GetMemories 取得單一記憶內容的完整內容：

memory = client.agent_engines.memories.get(
    name="MEMORY_NAME")

更改下列內容：

MEMORY_NAME：記憶體的完整名稱，格式為「projects/.../locations/.../reasoningEngines/.../memories...」。

列出記憶

控制台

如果是已部署的代理程式，您可以使用 Google Cloud 控制台列出與 Agent Engine 執行個體相關聯的所有記憶體：

前往 Google Cloud 控制台的「Vertex AI Agent Engine」頁面。

前往 Agent Engine

清單中會顯示所選專案的 Agent Engine 執行個體。您可以使用「篩選」欄位，依指定欄篩選清單。
按一下 Agent Engine 執行個體的名稱。
按一下「回憶集錦」分頁標籤。系統會依 ID 顯示回憶清單。

Vertex AI SDK

使用 ListMemories 擷取記憶體庫中的所有記憶體。

pager = client.agent_engines.memories.list(name=agent_engine.api_resource.name)
for page in pager:
  print(page)

使用範圍式擷取功能擷取回憶集錦

您可以使用 RetrieveMemories 擷取特定範圍的記憶內容。系統只會傳回與擷取要求範圍完全相同的記憶內容 (不論順序)。舉例來說，您可以使用 {"user_id": "123"} 擷取特定使用者的所有回憶集錦。如果沒有傳回任何回憶集錦，表示記憶體資料庫沒有符合所提供範圍的回憶集錦。

記憶體的範圍會在生成或建立記憶體時定義，且無法變更。

您可以使用 RetrieveMemories，針對特定範圍執行下列作業：

使用相似度搜尋功能檢索回憶
取回所有回憶

使用相似度搜尋功能擷取回憶

如果特定範圍內有許多記憶內容，您可以提供相似度搜尋參數，只擷取最相似的記憶內容。執行相似度搜尋時，記憶體庫只會考慮與要求範圍完全相同的記憶體。相似度搜尋會比較記憶內容的事實和要求搜尋查詢之間的嵌入向量。

系統會根據相似程度排序回憶集錦 (從歐氏距離最短到最長)：

results = client.agent_engines.memories.retrieve(
    name=agent_engine.api_resource.name,
    scope=SCOPE,
    similarity_search_params={
        "search_query": "QUERY",
        # Optional. Defaults to 3.
        "top_k": 3
    }
)
# RetrieveMemories returns a pager. You can use `list` to retrieve all memories.
list(results)

"""
Returns:

[
    RetrieveMemoriesResponseRetrievedMemory(
      memory=Memory(
        name="projects/.../locations/.../reasoningEngines/.../memories/...",
        ...
        fact="This is a fact."
      },
      distance=0.5
    ),
    RetrieveMemoriesResponseRetrievedMemory(
      memory=Memory(
        name="projects/.../locations/.../reasoningEngines/.../memories/...",
        ...
        fact="This is another fact."
      },
      distance=0.7
    ),
]
"""

更改下列內容：

QUERY：要執行相似度搜尋的查詢。舉例來說，您可以將對話中最後一個使用者回合做為查詢。
SCOPE：字典，代表相似性搜尋的範圍。例如，{"user_id": "123"}。系統只會考慮與要求範圍相同的記憶內容。

擷取所有記憶

如未提供相似度搜尋參數，RetrieveMemories 會傳回所有具有指定範圍的記憶內容，無論這些內容與目前對話的相似度為何。

results = client.agent_engines.memories.retrieve(
    name=agent_engine.api_resource.name,
    scope=SCOPE
)
# RetrieveMemories returns a pager. You can use `list` to retrieve all pages' memories.
list(results)

"""
Returns:

[
    RetrieveMemoriesResponseRetrievedMemory(
      memory=Memory(
        name="projects/.../locations/.../reasoningEngines/.../memories/...",
        ...
        fact="This is a fact."
      }
    ),
    RetrieveMemoriesResponseRetrievedMemory(
      memory=Memory(
        name="projects/.../locations/.../reasoningEngines/.../memories/...",
        ...
        fact="This is another fact."
      }
    ),
]
"""

更改下列內容：

SCOPE：代表擷取範圍的字典。例如，{"user_id": "123"}。系統只會傳回與要求範圍相同的記憶內容。

篩選回憶集錦

本節說明如何使用篩選器，限制要擷取的記憶體。你可以依下列條件篩選：

使用 filter_groups 屬性的中繼資料，進行以範圍為準的擷取作業。
使用 filter 的系統欄位。系統欄位包括回憶集錦的 topics、create_time、update_time 和 fact。

您可以在同一個要求中同時使用中繼資料和系統欄位篩選。

依中繼資料篩選

建立、更新或生成回憶集時，你可以將結構化中繼資料套用至儲存的回憶集：

import datetime

from vertexai import types

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

client.agent_engines.memories.create(
  ...,
  config={"metadata": metadata}
)

client.agent_engines.memories.update(
  ...,
  config={"metadata": metadata}
)

client.agent_engines.memories.generate(
  ...,
  config={"metadata": metadata}
)

使用 filter_groups 屬性擷取回憶集錦時，可以根據這項中繼資料進行篩選。中繼資料篩選條件是以析取正規形式 (DNF) 定義，也就是對 AND 運算式進行 OR 邏輯運算。

舉例來說，下列要求會擷取包含中繼資料 ({"my_string_key": {"string_value": "my_value"}} 和 {"my_double_key": {"double": 1.23}}) 或 {"my_string_key": {"string_value": "other"}} 的回憶集錦。

字典

results = client.agent_engines.memories.retrieve(
  ...,
  config={
    # Each element of `filter_groups` is combined using OR logic.
    "filter_groups": [
      {
        # Each element of `filters` is combined using AND logic.
        "filters": [
          {
            "key": "my_string_key",
            "value": {"string_value": "my_value"}
          },
          {
            "key": "my_double_key",
            "value": {"double_value": 1.23}
          }
        ]
      },
      {
        "filters": [
          {
            "key": "my_string_key",
            "value": {"string_value": "other"}
          }
        ]
      }
    ]
  }
)

以類別為準

from vertexai import types

results = client.agent_engines.memories.retrieve(
  ...,
  config=types.RetrieveAgentEngineMemoriesConfig(
    # Each element of `filter_groups` is combined using OR logic.
    filter_groups=[
      types.MemoryConjunctionFilter(
        # Each element of `filters` is combined using AND logic.
        filters=[
          types.MemoryFilter(
            key="my_string_key",
            value=types.MemoryMetadataValue(string_value="my_value")
          ),
          types.MemoryFilter(
            key="my_double_key",
            value=types.MemoryMetadataValue(double_value=1.23)
          )
        ]
      ),
      types.MemoryConjunctionFilter(
        filters=[
          types.MemoryFilter(
            key="my_string_key",
            value=types.MemoryMetadataValue(string_value="other")
          )
        ]
      )
    ]
  )
)

依系統欄位篩選

您可以使用 filter 屬性，依系統欄位進行篩選，該屬性會採用 EBNF 語法，並預期使用字串值。系統欄位包括 create_time、update_time、fact 和 topics。

建構篩選字串時，EBNF 語法須符合下列規定：

如要合併篩選器，請使用 AND 和 OR。
字串應使用雙引號 "。
日期時間欄位 (例如 create_time) 應使用以雙引號括住的字串，代表 ISO 8601 日期時間，或是代表 Unix 紀元以來微秒數的數字欄位。

舉例來說，您可以使用下列篩選器擷取 fact 包含子字串「allergies」且 update_time 晚於 2026 年 1 月 1 日的記憶體。

filter_string = 'fact=~".*allergies.*" AND update_time>="2026-01-01T00:00:00Z"''

client.agent_engines.memories.retrieve(
  ...,
  config={"filter": filter_string}
)

client.agent_engines.memories.list(
  ...,
  config={"filter": filter_string}
)

依主題篩選

系統會自動為生成的回憶集錦加上相關的回憶集錦主題。

如要依管理主題篩選，請使用 topics.managed_memory_topic 做為欄位名稱，並使用預期 ManagedTopicEnum 做為值，例如 topics.managed_memory_topic: USER_PREFERENCES。

如要依自訂主題篩選，請使用 topics.custom_memory_topic_label 做為欄位名稱，並以預期主題的標籤做為值，例如 topics.custom_memory_topic_label: custom-label。

filter_string = "topics.managed_memory_topic: USER_PREFERENCES " + \
"OR topics.custom_memory_topic_label: custom-label"

client.agent_engines.memories.retrieve(
  ...,
  config={"filter": filter_string}
)

client.agent_engines.memories.list(
  ...,
  config={"filter": filter_string}
)

擷取回憶 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

擷取作業

取得記憶體

列出記憶

控制台

Vertex AI SDK

使用範圍式擷取功能擷取回憶集錦

使用相似度搜尋功能擷取回憶

擷取所有記憶

篩選回憶集錦

依中繼資料篩選

字典

以類別為準

依系統欄位篩選

依主題篩選

擷取回憶