אתם יכולים להשתמש ב-Memory Bank כדי ליצור פרופילים מובְנים, שהם מבני נתונים עם סכימות סטטיות שמאוכלסות ומתעדכנות באמצעות מודלים מסוג LLM. כשמגדירים סכימה קבועה, מבטיחים שלסוכנים תהיה גישה מיידית עם זמן אחזור קצר למידע שמתפתח, בלי צורך בפעולות חיפוש יקרות במהלך סשן.
כדי לבצע את השלבים שמוצגים במדריך הזה, קודם צריך לבצע את השלבים שמפורטים במאמר הגדרת Memory Bank.
סקירה כללית
שימוש בפרופילים מובְנים עם הנציג מבטיח שהמידע שנשלף – כמו העדפות או סטאקים טכניים של משתמש – יהיה זמין במהירות, בתמציתיות ובפורמט עקבי. לדוגמה, אתם יכולים לאחזר פרופילים שכוללים תוכן כמו:
MemoryProfile(
profile={
"technical_stacks": "ADK, Python",
"preferred_language": "Python",
"tone_preference": "Succinct"
},
schema_id="user-profile"
)
פרופילים מובְנים עוברים אופטימיזציה לשליפה בזמן אחזור קצר, כי העבודה הקשה של איסוף המידע מתבצעת בזמן היצירה. הם מעולים להתחלת אינטראקציה בין נציג למשתמש.
הסבר על פרופילי זיכרון מובנים
פרופילים מובְנים נוצרים באותן שיטות (GenerateMemories ו-IngestEvents) שבהן אתם משתמשים לזיכרונות בשפה טבעית. אחרי שמגדירים סכימה, Memory Bank מנסה ליצור באופן אוטומטי פרופילים שתואמים לסכימה באמצעות מקורות הנתונים שסופקו.
כשמשתמשים בפרופילים מובְנים, Memory Bank מבצע את הפעולות הבאות במהלך יצירת הזיכרון:
- חילוץ: חילוץ מידע והקשר שתואמים לסכימה ממקור הנתונים. רק מידע שתואם לסכימה יחולץ. אתם יכולים לבדוק איזה מידע והקשר חולצו באמצעות גרסאות הזיכרון.
- איחוד: עדכון (במקרה הצורך) של שדות קיימים בפרופיל. LLM יחליט איך לעדכן את התוכן הקיים על סמך המידע וההקשר החדשים שנשלפו. אם השדה עדיין לא קיים בפרופיל, המערכת תדלג על האיחוד ותעדכן את השדה ישירות עם המידע שחולץ.
הפרופילים מבודדים על סמך scope (כמו {"user_id": "123"}) שסיפקתם כשהטמעתם נתונים ב-Memory Bank. לכל סכימה והיקף, Memory Bank שומר פרופיל אחד כמקור מידע מהימן. פרופיל שנוצר מורכב ממופע אחד או יותר של Memory. כל מופע של Memory מייצג שדה אחד בפרופיל, שבו אפשר להשתמש כדי לבדוק את המטא-נתונים ואת היסטוריית הגרסאות של השדה, למשל:
Memory(
create_time=datetime.datetime(...),
memory_type=<MemoryType.STRUCTURED_PROFILE: 'STRUCTURED_PROFILE'>,
name='projects/.../locations/.../reasoningEngines/.../memories/...',
scope={
'user_id': '123'
},
structured_content=MemoryStructuredContent(
data={
'language_preference': 'Java'
},
schema_id='user-profile'
),
update_time=datetime.datetime(...),
expire_time=datetime.datetime(...),
metadata={...}
)
הגדרת הסכימה
הפרופילים שנוצרים ב-Memory Bank תואמים לסכימות שמוגדרות במכונה של Memory Bank. אפשר להגדיר כמה סכימות פרופיל נפרדות, ולכל סכימה צריך להיות מזהה ייחודי. חשוב לזכור שהוספה או עדכון של סכימה לא ממלאים פרופילים מזיכרונות קודמים.
המסוף
כדי להוסיף או לערוך סכימות של פרופילים במופע עצמאי של Memory Bank במסוף Google Cloud (צריך את ההרשאה aiplatform.reasoningEngines.update כדי לשמור את השינויים):
במסוף Google Cloud , נכנסים לדף Memory Bank ב-Agent Platform ולוחצים על המכונה של Memory Bank.
בסרגל הפעולות (או בקטע Generation בכרטיסייה Configuration), לוחצים על Schemas.
לוחצים על Add schema כדי ליצור סכימה עם מזהה ייחודי, או לוחצים על כותרת של כרטיס סכימה קיים כדי להרחיב אותו.
מגדירים או עורכים את שדות הסכימה באמצעות התצוגה Simple או JSON, ולוחצים על Save.
Agent Platform SDK
אתם יכולים להשתמש במודל pydantic כדי להגדיר את השדות שאתם רוצים ש-Memory Bank יחלץ וישמור. לדוגמה:
from pydantic import BaseModel, Field
from typing import Literal
class UserProfile(BaseModel):
name: str = Field(
description="Name of the user.")
technical_stack: str = Field(
description="Comma-separated list tools or languages used by the user.")
primary_goal: str = Field(
description="The main objective the user is pursuing.")
expertise_level: str = Field(
description="Current skill level (e.g., Junior, Senior).")
job_status: Literal['unemployed', 'part_time', 'full_time', 'student'] = Field(
description="The job status of the individual")
מעלים את הסכימה ל-Memory Bank כשיוצרים או מעדכנים את המכונה של Memory Bank:
schema_config = {
"id": "user-profile",
"memory_schema": UserProfile.model_json_schema()
}
memory_bank = client.memory_banks.create(
managed_semantic_memory_config={
"structured_memory_configs": [
{
"schema_configs": [schema_config]
}
]
}
)
כברירת מחדל, Memory Bank מחלץ זיכרונות בשפה טבעית. אם אתם רוצים ש-Memory Bank ייצור פרופילים רק על סמך הנחיות בשפה טבעית, אתם יכולים להשבית את יצירת הזיכרון:
memory_bank = client.memory_banks.create(
managed_semantic_memory_config={
"structured_memory_configs": [
{
"schema_configs": [schema_config]
}
],
# Optional: Turn off natural language memories.
"unstructured_memory_configs": [
{"disable_natural_language_memories": True}
]
}
)
יצירת פרופיל
כדי להפעיל את היצירה של זיכרונות מובְנים, צריך לספק היסטוריית שיחות (אירועים) לשיטות GenerateMemories או IngestEvents. בדומה לזיכרונות בשפה טבעית, Memory Bank משתמש במודלים מסוג LLM כדי לחלץ מידע משמעותי ממקורות הנתונים ולשלב אותו עם זיכרונות קיימים.
דוגמה
בדוגמה הבאה נסביר איך ליצור פרופיל זיכרון באמצעות הסכימה שהוגדרה קודם.
בסדרת האירועים הראשונה שנשלחה אל Memory Bank בהיקף {"user_id": "123"}, המשתמש מציין שהוא עובד עם סוכני ADK:
client.memory_banks.memories.generate(
name=memory_bank.name,
scope={"user_id": "123"},
direct_contents_source={
"events": [
{"content": {
"parts": [{
"text": "Can you help me build an ADK agent that organizes my daily tasks?"}]}}]
}
)
Memory Bank מחלץ את הערך "ADK" לשדה technical_stack בסכימה. שדות אחרים לא מאוכלסים כי האירוע שהוטמע לא מכיל מידע רלוונטי לשאר הסכימה. מכיוון שזו האינטראקציה הראשונה בהיקף הזה, המערכת מדלגת על האיחוד ומאתחלת את הפרופיל עם הערך הראשוני הזה.
result = client.memory_banks.memories.retrieve_profiles(
name=memory_bank.name,
scope={"user_id": "123"},
)
"""
Returns:
RetrieveProfilesResponse(
profiles={
'user-profile': MemoryProfile(
profile={
'technical_stack': 'ADK'
},
schema_id='user-profile'
)
}
)
"""
בסדרת האירועים הבאה שנשלחת אל Memory Bank, המשתמש מציין שהוא סטודנט ושהוא כותב קוד בעיקר ב-Python:
client.memory_banks.memories.generate(
name=memory_bank.name,
scope={"user_id": "123"},
direct_contents_source={
"events": [
{"content": {
"parts": [
{"text": "Do you have any career recommendations for students that specialize in Python?"}]}}]
}
)
Memory Bank מחלץ מהאינטראקציה גם את "פייתון" וגם את הסטטוס "סטודנט". הקטע technical_stack מאוחד, ומוסיף את "Python" לרשומה הקיימת "ADK". המערכת מאכלסת את השדה job_status שהיה ריק קודם לכן בערך enum של "student" ומדלגת על שלב האיחוד.
result = client.memory_banks.memories.retrieve_profiles(
name=memory_bank.name,
scope=scope
)
"""
Returns:
RetrieveProfilesResponse(
profiles={
'user-profile': MemoryProfile(
profile={
'technical_stack': 'ADK, Python',
'job_status': 'student'
},
schema_id='user-profile'
)
}
)
"""
אחזור פרופיל
אחרי שהפרופיל נוצר, אפשר לאחזר את הפרופיל המאוחד של היקף ספציפי באמצעות השיטה RetrieveProfiles. כך תקבלו את הנתונים הכי עדכניים שממופים לסכימה שלכם.
result = client.memory_banks.memories.retrieve_profiles(
name=memory_bank.name,
scope={"user_id": "123"},
)
# Accessing the data
for profile in result.profiles.values():
print(profile)
# Output: {'technical_stack': 'ADK, Python', 'job_status': 'student', ...}
בדיקת הפרופיל
מאחורי הקלעים, פרופיל מורכב מזיכרונות נפרדים מסוג STRUCTURED_PROFILE. כל שדה בסכימה ממופה לזיכרון אחד לכל היקף, וכך מתקבלת תצפיתיות מפורטת.
למרות ש-RetrieveProfiles היא השיטה העיקרית לאחזור פרופילים בסביבת הייצור, אתם יכולים לבדוק זיכרונות ספציפיים במסוףGoogle Cloud או באמצעות Agent Platform SDK כדי לבדוק את התפתחות הפרופיל:
- מטא-נתונים ברמת השדה: הצגה ועדכון של זמן חיים (TTL) ספציפי ו-
Memory.metadataלשדות נפרדים בפרופיל. היסטוריית גרסאות: אפשר לעקוב אחרי השושלת של שדה כדי לראות ערכים היסטוריים ואת ההקשר הספציפי של השיחה שהפעיל כל שינוי.
המסוף
במסוף Google Cloud , פותחים את המכונה העצמאית בדף Memory Bank או את הנציג שנפרס בדף Deployments, ובוחרים בכרטיסייה Memories.
בוחרים באפשרות Structured, ואז בוחרים ערכים לכל המפתחות בהיקף היעד (או מחילים מסנן היקף ב-Unstructured ולוחצים על Search structured memories). בשורות של הפרופילים התואמים מוצגים הערכים Schema, Type, Content, Created ו-Updated.
לוחצים על View בשורה של הפרופיל כדי לפתוח את החלונית Memory details. בחלונית הזו מוצגים הצ'יפ של ההיקף, קישור לסכימה, עובדות בזיכרון (עם View revisions לכל עובדה) וקובץ ה-JSON של הפרופיל המאוחד.
Agent Platform SDK
אפשר להשתמש ב-RetrieveMemories כדי לאחזר זיכרונות שמכילים חלקים מפרופיל המשתמש. כברירת מחדל, RetrieveMemories מאחזר רק זיכרונות בשפה טבעית, אז צריך לבקש במפורש זיכרונות STRUCTURED_PROFILE:
client.memory_banks.memories.retrieve(
name="...",
scope={"user_id": "123"},
config={
"memory_types": ["STRUCTURED_PROFILE"]
}
)
"""
Returns:
[RetrieveMemoriesResponseRetrievedMemory(
memory=Memory(
create_time=datetime.datetime(...),
memory_type=<MemoryType.STRUCTURED_PROFILE: 'STRUCTURED_PROFILE'>,
name='projects/.../locations/.../reasoningEngines/.../memories/...',
scope={
'user_id': '123'
},
structured_content=MemoryStructuredContent(
data={
'technical_stack': 'ADK, Python'
},
schema_id='user'
),
update_time=datetime.datetime(...)
)
)]
"""
אחרי זה, מאחזרים את היסטוריית הגרסאות של קטע פרופיל מובנה כדי לבדוק איך שדה הפרופיל השתנה לאורך זמן ואת ההקשר של כל שינוי:
for retrieved_memory in list(results):
list(client.memory_banks.memories.revisions.list(
name=retrieved_memory.memory.name
))
"""
Returns:
[MemoryRevision(
create_time=datetime.datetime(...),
expire_time=datetime.datetime(...),
extracted_memories=[
IntermediateExtractedMemory(
context='The user indicated that they have expertise in Python when asking about career options.',
structured_data={
'technical_stack': 'Python'
}
),
],
name='projects/.../locations/.../reasoningEngines/.../memories/.../revisions/...',
structured_data={
'technical_stack': 'ADK, Python'
}
),
MemoryRevision(
create_time=datetime.datetime(...),
expire_time=datetime.datetime(...),
extracted_memories=[
IntermediateExtractedMemory(
context='The user indicated that they need help building an ADK agent',
structured_data={
'technical_stack': 'ADK'
}
),
],
name='projects/.../locations/.../reasoningEngines/.../memories/.../revisions/...',
structured_data={
'technical_stack': 'ADK'
}
)]
"""