שליפת זיכרונות

ב-Agent Platform Memory Bank אתם יכולים לאחזר זיכרונות שמורים באמצעות פעולות שונות, בהתאם לצרכים שלכם. אתם יכולים לאחזר זיכרון אחד, להציג רשימה של זיכרונות ולסנן אותם, או לבצע אחזור מבוסס-היקף באמצעות חיפוש דמיון.

במאמר הזה מוסבר איך לאחזר ולבדוק זיכרונות במסוף Google Cloud או באמצעות Agent Platform SDK.

אם אתם משתמשים בערכה לפיתוח סוכנים (ADK), הסוכן יכול לתזמר את הקריאות האלה באופן אוטומטי. מדריך למתחילים: שימוש ב-ADK

לפני שמתחילים

כדי לבצע את השלבים שבדף הזה, קודם צריך לבצע את השלבים שמפורטים בקטע הגדרה של Memory Bank.

פעולות אחזור

יש כמה אפשרויות לאחזור הזיכרונות שנוצרו:

• Get memory: קבלת התוכן המלא של זיכרון יחיד באמצעות Agent Platform SDK.

• אחזור זיכרונות: באמצעות Agent Platform SDK, אפשר לאחזר זיכרונות לפי היקף. אחזור זיכרונות באמצעות חיפוש דמיון או כל הזיכרונות בהיקף.

• הצגת רשימת זיכרונות: הצגה וסינון של זיכרונות בGoogle Cloud מסוף או באמצעות Agent Platform SDK.

אחזור הזיכרון

כדי לקבל את התוכן המלא של זיכרון אחד, משתמשים ב-GetMemories:

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

מחליפים את מה שכתוב בשדות הבאים:

• ‫MEMORY_NAME: שם זיכרון מלא בפורמט "projects/.../locations/.../reasoningEngines/.../memories...‎".

אחזור זיכרונות באמצעות אחזור מבוסס-היקף

אתם יכולים להשתמש ב-RetrieveMemories כדי לאחזר זיכרונות בהיקף מסוים. יוחזרו רק זיכרונות עם היקף זהה (ללא קשר לסדר) לזה של בקשת השליפה. לדוגמה, אפשר לאחזר את כל הזיכרונות שמוגדרים למשתמש מסוים באמצעות {"user_id": "123"}. אם לא מוחזרים זיכרונות, סימן שאין ב-Memory Bank זיכרונות בהיקף שצוין.

ההיקף של הזיכרון מוגדר כשהזיכרון נוצר, ואי אפשר לשנות אותו.

אתם יכולים להשתמש ב-RetrieveMemories כדי לבצע את הפעולות הבאות בהיקף מסוים:

• אחזור זיכרונות באמצעות חיפוש דמיון
• איך מאחזרים את כל הזיכרונות

אחזור זיכרונות באמצעות חיפוש לפי דמיון

אם יש לכם הרבה זיכרונות בהיקף מסוים, אתם יכולים להשתמש בחיפוש דמיון כדי לאחזר רק את הזיכרונות הכי דומים, על ידי ציון פרמטרים של חיפוש דמיון. במהלך חיפוש דמיון, Memory Bank מתייחס רק לזיכרונות עם היקף זהה לזה של הבקשה. בחיפוש דמיון, המערכת משווה בין וקטורי ההטמעה של העובדות בזיכרונות לבין שאילתת החיפוש בבקשה.

הזיכרונות שמוחזרים ממוינים מהכי דומה (המרחק האוקלידי הקצר ביותר) להכי פחות דומה (המרחק האוקלידי הארוך ביותר):

results = client.memory_banks.memories.retrieve(
    name=memory_bank.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 מחזיר את כל הזיכרונות עם ההיקף שצוין, בלי קשר לדמיון שלהם לשיחה הנוכחית.

אזהרה: אם מאחזרים את כל הזיכרונות בלי חיפוש דמיון, יכול להיות שיוחזרו כמה דפים. קריאה ל-list() בתגובה של RetrieveMemories מפעילה חלוקה אוטומטית לדפים בכל הדפים. באוספים גדולים, כדאי להשתמש ישירות ב-response.page כדי לאחזר פריטים דף אחד בכל פעם ולמנוע קריאות לא צפויות.

results = client.memory_banks.memories.retrieve(
    name=memory_bank.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"}. התשובה תכלול רק זיכרונות עם אותו היקף כמו הבקשה.

אחזור רשימת זיכרונות

אפשר להציג ולבדוק זיכרונות במסוף Google Cloud או באמצעות Agent Platform SDK.

המסוף

כדי לראות ולסנן את הזיכרונות במסוף Google Cloud (נדרשת ההרשאה aiplatform.memories.list, שכלולה בתפקידים roles/aiplatform.memoryViewer ו-roles/aiplatform.memoryUser):

1. פותחים את המכונה במסוף Google Cloud :

   • מכונה נפרדת של Memory Bank: נכנסים לדף Memory Bank ב-Agent Platform ולוחצים על המכונה.

     מעבר אל Memory Bank

   • סוכן שנפרס ב-Agent Runtime: נכנסים לדף Deployments ב-Agent Platform ולוחצים על הסוכן.

     מעבר אל Deployments

2. פותחים את הכרטיסייה זיכרונות. כברירת מחדל, בתצוגה Unstructured מוצגת טבלה של זיכרונות (Scope,‏ Resource Name,‏ Fact,‏ Created ו-Updated).

3. אופציונלי: מסננים או מנהלים את הזיכרונות:

   • סינון לפי היקף: מקלידים צמד key:value (למשל user_id:123) בסרגל הסינון, או לוחצים על צ'יפ של היקף בכל שורה.
   • הצגת פרופילים מובְנים: עוברים אל מובְנים ובוחרים היקף מלא, או מחילים מסנן היקף בלא מובְנים ולוחצים על חיפוש זיכרונות מובְנים. לפרטים נוספים, קראו את המאמר פרופילי זיכרון.
   • לערוך, לבדוק גרסאות או למחוק: לוחצים על תפריט הפעולות הנוספות () בשורה של הזיכרון ובוחרים באפשרות עריכה, הצגת גרסאות או מחיקה.

Agent Platform SDK

אזהרה: קריאה ל-list() בתגובה של ListMemories מפעילה חלוקה אוטומטית לדפים בכל הדפים. באוספים גדולים, כדאי להשתמש ב-response.page ישירות כדי לאחזר פריטים דף אחד בכל פעם ולמנוע קריאות לא צפויות.

כדי להציג רשימה של זיכרונות מ-Memory Bank בלי סינון לפי היקף, משתמשים ב-ListMemories. כדי לאחזר לפי היקף, צריך להשתמש ב-RetrieveMemories. לא מומלץ להשתמש ב-ListMemories לאחזור עם זמן אחזור קצר.

pager = client.memory_banks.memories.list(name=memory_bank.name)
for page in pager:
  print(page)

סינון הזיכרונות

בקטע הזה מוסבר איך להשתמש במסננים כדי להגביל את הזיכרונות שמאוחזרים. אפשר לסנן לפי:

• מטא-נתונים שמשתמשים במאפיין filter_groups לאחזור מבוסס-היקף.

• שדות מערכת שמשתמשים ב-filter. שדות המערכת כוללים את topics, create_time, update_time ו-fact של הזיכרונות.

אפשר להשתמש בסינון של מטא-נתונים ושל שדות מערכת באותה בקשה.

סינון לפי מטא-נתונים

הערה: אפשר לסנן לפי מטא-נתונים רק כשמבצעים אחזור מבוסס-היקף ומחיקת זיכרונות.

כשיוצרים, מעדכנים או יוצרים זיכרונות, אפשר להחיל מטא-נתונים מובְנים על הזיכרונות ששמורים:

import datetime

from agentplatform 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.memory_banks.memories.create(
  ...,
  config={"metadata": metadata}
)

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

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

אתם יכולים לסנן את המטא-נתונים האלה כשאתם מאחזרים זיכרונות באמצעות המאפיין filter_groups. מסנני מטא-נתונים מוגדרים בצורה נורמלית דיסיונקטיבית (DNF), שהיא ביטוי לוגי של ORs של ANDs.

לדוגמה, הבקשה הבאה תאחזר זיכרונות שכוללים את המטא-נתונים ({"my_string_key": {"string_value": "my_value"}} וגם {"my_double_key": {"double": 1.23}}) או {"my_string_key": {"string_value": "other"}}.

מילון

results = client.memory_banks.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 agentplatform import types

results = client.memory_banks.memories.retrieve(
  ...,
  config=types.RetrieveMemoriesConfig(
    # 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 epoch).

לדוגמה, אפשר להשתמש במסנן הבא כדי לאחזר זיכרונות שבהם fact כולל את מחרוזת המשנה "אלרגיות" ו-update_time היה אחרי 1 בינואר 2026.

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

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

client.memory_banks.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.memory_banks.memories.retrieve(
  ...,
  config={"filter": filter_string}
)

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