本文說明如何使用 Agent Platform SDK 執行這些擷取作業。
如果您使用 Agent Development Kit (ADK)，代理程式可以自動為您協調這些呼叫。請參閱「開始使用 ADK」。
事前準備
如要完成本頁的步驟，請先完成「設定記憶體庫」中的步驟。
擷取作業
您可以透過下列選項擷取生成的記憶內容：
取得記憶內容：使用 Agent Platform SDK 取得單一記憶內容的完整內容。
擷取記憶內容：使用 Agent Platform SDK，透過以範圍為準的記憶內容擷取方式擷取記憶內容。使用相似度搜尋或範圍內的所有回憶集錦，擷取回憶集錦。
列出記憶內容：使用 Agent Platform SDK 列出記憶內容。
取得記憶體
使用 GetMemories 取得單一記憶體的完整內容：
memory = client.agent_engines.memories.get(
name="MEMORY_NAME")
更改下列內容：
MEMORY_NAME：完整記憶體名稱，格式為「projects/.../locations/.../reasoningEngines/.../memories...」。
使用範圍式檢索功能擷取回憶
您可以使用 RetrieveMemories 擷取特定範圍的回憶內容。系統只會傳回與擷取要求範圍完全相同的記憶體 (不論順序)。舉例來說，您可以使用 {"user_id": "123"} 擷取範圍限定為特定使用者的所有回憶集錦。如果沒有傳回任何記憶，表示 Memory Bank 沒有提供範圍的記憶。
回憶集錦的範圍會在生成或建立時定義，且無法變更。
您可以使用 RetrieveMemories，針對特定範圍執行下列作業：
使用相似度搜尋功能擷取回憶
如果特定範圍內有許多記憶，您可以提供相似度搜尋參數，只擷取最相似的記憶。執行相似度搜尋時，Memory Bank 只會考量與要求範圍完全相同的記憶體。相似度搜尋功能會比較記憶內容的事實與要求搜尋查詢之間的嵌入向量。
系統會根據相似程度排序傳回的回憶集錦 (從歐氏距離最短到最長)：
results = client.agent_engines.memories.retrieve(
name=memory_bank.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 `page` to retrieve memories.
results.page
"""
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=memory_bank.api_resource.name,
scope=SCOPE
)
# RetrieveMemories returns a pager. You can use `page` to retrieve up to 100 memories per page.
results.page
"""
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"}。系統只會傳回與要求範圍相同的記憶內容。
列出記憶
使用 ListMemories 從 Memory Bank 中回憶過往，不必根據範圍篩選。如要依範圍擷取，請改用 RetrieveMemories。不建議使用 ListMemories 擷取低延遲資料。
pager = client.agent_engines.memories.list(name=memory_bank.api_resource.name)
for page in pager:
print(page)
篩選回憶集錦
本節說明如何使用篩選器，限制要擷取的記憶體。你可以依下列條件篩選：
使用
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}
)