1. مقدمة

1. التحدّي
في سيناريوهات الاستجابة للكوارث، يتطلب تنسيق الناجين ذوي المهارات والموارد والاحتياجات المختلفة عبر مواقع متعددة إدارة ذكية للبيانات وإمكانات بحث. تعلّمك ورشة العمل هذه كيفية إنشاء نظام ذكاء اصطناعي للإنتاج يجمع بين:
- 🗄️ قاعدة بيانات الرسم البياني (Spanner): تخزين العلاقات المعقّدة بين الناجين والمهارات والموارد
- 🔍 البحث المستند إلى الذكاء الاصطناعي: بحث مختلط دلالي + بالكلمات الرئيسية باستخدام التضمينات
- 📸 المعالجة المتعددة الوسائط: استخراج البيانات المنظَّمة من الصور والنصوص والفيديوهات
- 🤖 تنسيق المهام بين عدة وكلاء: يمكنك تنسيق المهام بين وكلاء متخصّصين لتنفيذ مهام سير عمل معقّدة
- 🧠 الذاكرة الطويلة المدى: التخصيص باستخدام Vertex AI Memory Bank

2. ما ستقوم بإنشائه
قاعدة بيانات رسم بياني لشبكة الناجين تتضمّن:
- 🗺️ رسم بياني تفاعلي ثلاثي الأبعاد يعرض العلاقات بين الناجين
- 🔍 البحث الذكي (الكلمات الرئيسية والدلالية والمختلطة)
- 📸 مسار تحميل متعدد الوسائط (استخراج الكيانات من الصور/الفيديو)
- 🤖 نظام متعدّد الوكلاء لتنظيم المهام المعقّدة
- 🧠 دمج Memory Bank لتفاعلات مخصّصة
3- التكنولوجيات الأساسية
المكوّن | تكنولوجيا | الغرض |
قاعدة البيانات | Cloud Spanner Graph | تخزين العُقد (الناجون والمهارات) والحواف (العلاقات) |
البحث بالذكاء الاصطناعي | Gemini + التضمينات | الفهم الدلالي + البحث عن التشابه |
إطار عمل الوكيل | حزمة تطوير الوكلاء (ADK) | تنظيم مهام سير العمل المستندة إلى الذكاء الاصطناعي |
الذاكرة | Vertex AI Memory Bank | تخزين الإعدادات المفضّلة للمستخدم على المدى الطويل |
Frontend | React + Three.js | تمثيل بياني تفاعلي ثلاثي الأبعاد |
2. 🛠️ إعداد البيئة (يمكنك تخطّي هذه الخطوة إذا كنت في ورشة العمل)
الجزء الأول: تفعيل حساب الفوترة
لتنفيذ هذا الدرس التطبيقي حول الترميز، تحتاج إلى حساب فوترة يتضمّن بعض الرصيد. استخدِم الأرصدة من البانر في أعلى هذا الدرس التطبيقي حول الترميز للبدء. إذا كنت مرتبطًا بحساب فوترة، يمكنك تخطّي هذه الخطوة.
الجزء الثاني: البيئة المفتوحة
- 👉 انقر على هذا الرابط للانتقال مباشرةً إلى محرِّر Cloud Shell
- 👉 إذا طُلب منك منح الإذن في أي وقت اليوم، انقر على منح الإذن للمتابعة.

- 👉 إذا لم يظهر Terminal في أسفل الشاشة، افتحه:
- انقر على عرض
- انقر على Terminal

- 👉💻 في الوحدة الطرفية، تأكَّد من أنّه تمّت مصادقتك وأنّ المشروع مضبوط على رقم تعريف مشروعك باستخدام الأمر التالي:
gcloud auth list - 👉💻 استنسِخ مشروع bootstrap من GitHub:
git clone https://github.com/gca-americas/way-back-home.git
الجزء الثالث: إنشاء مشروع جديد
👉💻 في الوحدة الطرفية، اجعل النص البرمجي init قابلاً للتنفيذ وشغِّله:
cd ~/way-back-home/level_2
./init.sh
3- 🛠️ إعداد البيئة
1. فتح Cloud Shell
في وحدة طرفية في محرِّر Cloud Shell، إذا لم تظهر الوحدة الطرفية في أسفل الشاشة، افتحها باتّباع الخطوات التالية:
- انقر على عرض
- انقر على Terminal

2. إعداد المشروع
👉💻 في Terminal، اضبط رقم تعريف مشروعك:
gcloud config set project $(cat ~/project_id.txt) --quiet
👉💻 تفعيل واجهات برمجة التطبيقات المطلوبة (يستغرق ذلك دقيقتَين إلى 3 دقائق تقريبًا):
gcloud services enable compute.googleapis.com \
aiplatform.googleapis.com \
run.googleapis.com \
cloudbuild.googleapis.com \
artifactregistry.googleapis.com \
spanner.googleapis.com \
storage.googleapis.com
3- تشغيل نص التهيئة البرمجي
👉💻 نفِّذ نص التهيئة البرمجي:
cd ~/way-back-home/level_2
./setup.sh
سيؤدي هذا الإجراء إلى إنشاء .env لك. في cloudshell، افتح مشروع way_back_home. ضمن المجلد level_2، يمكنك الاطّلاع على ملف .env الذي تم إنشاؤه لك. إذا لم تتمكّن من العثور عليه، يمكنك النقر على View -> Toggle Hidden File للاطّلاع عليه. 
4. تحميل عيّنات البيانات
👉💻 انتقِل إلى الخلفية وثبِّت التبعيات:
cd ~/way-back-home/level_2/backend
uv sync
👉💻 تحميل بيانات الناجين الأولية:
uv run python ~/way-back-home/level_2/backend/setup_data.py
يؤدي ذلك إلى إنشاء:
- مثيل Spanner (
survivor-network) - قاعدة البيانات (
graph-db) - جميع جداول العُقد والحواف
- الناتج المتوقَّع للرسومات البيانية للسمات عند الاستعلام:
============================================================
SUCCESS! Database setup complete.
============================================================
Instance: survivor-network
Database: graph-db
Graph: SurvivorGraph
Access your database at:
https://console.cloud.google.com/spanner/instances/survivor-network/databases/graph-db?project=waybackhome
إذا نقرت على الرابط بعد Access your database at في الناتج، يمكنك فتح Google Cloud Console Spanner.

وسيظهر لك Spanner في Google Cloud Console.

4. 🚀 عرض بيانات الرسم البياني بشكل مرئي في Spanner Studio
يساعدك هذا الدليل في عرض بيانات الرسم البياني لشبكة Survivor Network والتفاعل معها مباشرةً في Google Cloud Console باستخدام Spanner Studio. هذه طريقة رائعة للتحقّق من بياناتك وفهم بنية الرسم البياني قبل إنشاء وكيل الذكاء الاصطناعي.
1. الوصول إلى Spanner Studio
- في الخطوة الأخيرة، تأكَّد من النقر على الرابط وفتح Spanner Studio.

2. فهم بنية الرسم البياني ("الصورة الكبيرة")
يمكنك اعتبار مجموعة بيانات Survivor Network بمثابة لغز منطقي أو حالة لعبة:
الكيان | الدور في النظام | التشبيه |
الناجون | الوكلاء/اللاعبون | اللاعبون |
المناطق الأحيائية | موقعهم الجغرافي | مناطق الخريطة |
المهارات | الإجراءات التي يمكنهم اتّخاذها | الإمكانات |
الاحتياجات | ما ينقصهم (الأزمات) | المهام |
المراجع | العناصر التي تم العثور عليها في العالم | غنيمة |
الهدف: تتمثّل مهمة وكيل الذكاء الاصطناعي في ربط المهارات (الحلول) بالاحتياجات (المشاكل)، مع مراعاة المناطق الأحيائية (القيود المتعلّقة بالموقع الجغرافي).
🔗 الحواف (العلاقات):
-
SurvivorInBiome: تتبُّع الموقع الجغرافي -
SurvivorHasSkill: قائمة بالقدرات -
SurvivorHasNeed: قائمة بالمشاكل النشطة -
SurvivorFoundResource: مستودع السلع -
SurvivorCanHelp: علاقة مستنتَجة (يحتسبها الذكاء الاصطناعي)
3- الاستعلام عن الرسم البياني
لِنُجرِ بعض طلبات البحث للاطّلاع على "القصة" في البيانات.
يستخدم Spanner Graph لغة GQL (لغة طلبات الرسم البياني). لتنفيذ طلب بحث، استخدِم GRAPH SurvivorNetwork متبوعًا بنمط المطابقة.
👉 الطلب 1: القائمة العالمية (من يعمل أين؟) هذا هو الأساس، ففهم الموقع الجغرافي أمر بالغ الأهمية لعمليات الإنقاذ.
GRAPH SurvivorNetwork
MATCH result = (s:Survivors)-[:SurvivorInBiome]->(b:Biomes)
RETURN TO_JSON(result) AS json_result
من المفترض أن تظهر النتيجة على النحو التالي: 
👉 الطلب 2: مصفوفة المهارات (القدرات) بعد معرفة مكان كل شخص، يمكنك معرفة ما يمكنه فعله.
GRAPH SurvivorNetwork
MATCH result = (s:Survivors)-[h:SurvivorHasSkill]->(k:Skills)
RETURN TO_JSON(result) AS json_result
من المفترض أن تظهر النتيجة على النحو التالي: 
👉 السؤال 3: من هم الأشخاص الذين يمرّون بأزمة؟ ("لوحة المهام") يمكنك الاطّلاع على الناجين الذين يحتاجون إلى المساعدة وما يحتاجون إليه.
GRAPH SurvivorNetwork
MATCH result = (s:Survivors)-[h:SurvivorHasNeed]->(n:Needs)
RETURN TO_JSON(result) AS json_result
من المفترض أن تظهر النتيجة على النحو التالي: 
🔎 [اختياري] التوفيق بين المشاركين - مَن يمكنه مساعدة مَن؟
هنا تكمن أهمية الرسم البياني. يعثر طلب البحث هذا على الناجين الذين لديهم مهارات يمكنها تلبية احتياجات الناجين الآخرين.
GRAPH SurvivorNetwork
MATCH result = (helper:Survivors)-[:SurvivorHasSkill]->(skill:Skills)-[:SkillTreatsNeed]->(need:Needs)<-[:SurvivorHasNeed]-(helpee:Survivors)
RETURN TO_JSON(result) AS json_result
من المفترض أن تظهر النتيجة على النحو التالي: 
aside positive What This Query Does:
بدلاً من عرض "الإسعافات الأولية تعالج الحروق" فقط (وهو أمر واضح من المخطط)، يعثر هذا الطلب على ما يلي:
- الدكتورة إيلينا فروست (التي لديها تدريب طبي) ← يمكنها علاج ← الكابتن تاناكا (الذي يعاني من حروق)
- ديفيد تشين (الذي لديه إسعافات أولية) ← يمكنه علاج ← الملازم بارك (الذي يعاني من التواء في الكاحل)
أهمية هذه الميزة:
ما سيقوم به وكيل الذكاء الاصطناعي:
عندما يسأل المستخدم "من يمكنه علاج الحروق؟"، سيقوم الوكيل بما يلي:
- تنفيذ طلب بحث مشابه في الرسم البياني
- النتيجة: "لدى الدكتور فريد تدريب طبي ويمكنه مساعدة الكابتن طارق"
- لا يحتاج المستخدم إلى معرفة الجداول أو العلاقات الوسيطة!
5- 🚀 التضمينات المستندة إلى الذكاء الاصطناعي في Spanner
1. أهمية التضمينات (لا يلزم اتخاذ أي إجراء، إذن بالقراءة فقط)
في سيناريو البقاء على قيد الحياة، الوقت مهم للغاية. عندما يبلّغ أحد الناجين عن حالة طارئة، مثل I need someone who can treat burns أو Looking for a medic، لا يمكنه إضاعة الوقت في تخمين أسماء المهارات الدقيقة في قاعدة البيانات.
سيناريو حقيقي: الناجي: Captain Tanaka has burns—we need medical help NOW!
البحث التقليدي عن الكلمة الرئيسية "طبيب" ← 0 نتيجة ❌
البحث الدلالي باستخدام التضمينات ← يعثر على "تدريب طبي" و"إسعافات أولية" ✅
هذا هو بالضبط ما يحتاجه الوكلاء: بحث ذكي يشبه البحث البشري يفهم القصد، وليس الكلمات الرئيسية فقط.
2. إنشاء نموذج تضمين

لننشئ الآن نموذجًا يحوّل النص إلى تضمينات باستخدام text-embedding-004 من Google.
👉 في Spanner Studio، نفِّذ أمر SQL التالي (استبدِل $YOUR_PROJECT_ID برقم تعريف مشروعك الفعلي):
‼️ في محرِّر Cloud Shell، افتح File -> Open Folder -> way-back-home/level_2 للاطّلاع على المشروع بأكمله.

👉 يمكنك تنفيذ طلب البحث هذا في Spanner Studio من خلال نسخه ولصقه أدناه، ثم النقر على الزر "تنفيذ":
CREATE OR REPLACE MODEL TextEmbeddings
INPUT(content STRING(MAX))
OUTPUT(embeddings STRUCT<values ARRAY<FLOAT32>>)
REMOTE OPTIONS (
endpoint = '//aiplatform.googleapis.com/projects/$YOUR_PROJECT_ID/locations/us-central1/publishers/google/models/text-embedding-004'
);
ماذا يحدث؟:
- ينشئ نموذجًا افتراضيًا في Spanner (لا يتم تخزين أوزان النماذج على الجهاز)
- يشير إلى
text-embedding-004من Google على Vertex AI - يحدّد العقد: الإدخال هو نص، والإخراج هو مصفوفة عائمة من 768 بُعدًا
ما هي مزايا "الخيارات عن بُعد"؟
- لا يشغّل Spanner النموذج نفسه
- ويستدعي Vertex AI من خلال واجهة برمجة التطبيقات عند استخدام
ML.PREDICT - Zero-ETL: لا حاجة إلى تصدير البيانات إلى Python ومعالجتها وإعادة استيرادها
انقر على الزر Run، وعند نجاح العملية، يمكنك الاطّلاع على النتيجة كما هو موضّح أدناه:

3- إضافة عمود التضمين
👉 أضِف عمودًا لتخزين التضمينات:
ALTER TABLE Skills ADD COLUMN skill_embedding ARRAY<FLOAT32>;
انقر على الزر Run، وعند نجاح العملية، يمكنك الاطّلاع على النتيجة كما هو موضّح أدناه:

4. إنشاء التضمينات
👉 استخدام الذكاء الاصطناعي لإنشاء تضمينات متّجهة لكل مهارة:
UPDATE Skills
SET skill_embedding = (
SELECT embeddings.values
FROM ML.PREDICT(
MODEL TextEmbeddings,
(SELECT name AS content)
)
)
WHERE skill_embedding IS NULL;
انقر على الزر Run، وعند نجاح العملية، يمكنك الاطّلاع على النتيجة كما هو موضّح أدناه:

ما يحدث: يتم تحويل كل اسم مهارة (مثل "الإسعافات الأولية") إلى متجه مكوّن من 768 سمة يمثّل معناه الدلالي.
5- التحقّق من التضمينات
👉 تأكَّد من إنشاء التضمينات:
SELECT
skill_id,
name,
ARRAY_LENGTH(skill_embedding) AS embedding_dimensions
FROM Skills
LIMIT 5;
الناتج المتوقَّع:

6. اختبار البحث الدلالي
والآن، سنختبر حالة الاستخدام المحددة في السيناريو: العثور على مهارات طبية باستخدام عبارة "طبيب".
👉 البحث عن مهارات مشابهة لـ "مسعف":
WITH query_embedding AS (
SELECT embeddings.values AS val
FROM ML.PREDICT(MODEL TextEmbeddings, (SELECT "medic" AS content))
)
SELECT
s.name AS skill_name,
s.category,
COSINE_DISTANCE(s.skill_embedding, (SELECT val FROM query_embedding)) AS distance
FROM Skills AS s
WHERE s.skill_embedding IS NOT NULL
ORDER BY distance ASC
LIMIT 10;
- يتم تحويل عبارة البحث "طبيب" التي أدخلها المستخدم إلى تضمين
- يتم تخزينها في الجدول المؤقت
query_embedding
النتائج المتوقّعة (كلما كانت المسافة أقل، زاد التشابه):

7. إنشاء نموذج Gemini للتحليل

👉 أنشِئ مرجعًا لنموذج الذكاء الاصطناعي التوليدي (استبدِل $YOUR_PROJECT_ID برقم تعريف مشروعك الفعلي):
CREATE OR REPLACE MODEL GeminiPro
INPUT(prompt STRING(MAX))
OUTPUT(content STRING(MAX))
REMOTE OPTIONS (
endpoint = '//aiplatform.googleapis.com/projects/$YOUR_PROJECT_ID/locations/us-central1/publishers/google/models/gemini-2.5-pro',
default_batch_size = 1
);
الفرق عن نموذج التضمينات:
- التضمينات: نص ← متّجه (للبحث عن التشابه)
- Gemini: نص ← نص من إنشاء الذكاء الاصطناعي (للاستدلال/التحليل)

8. استخدام Gemini لتحليل التوافق
👉 تحليل أزواج الناجين لمعرفة مدى توافقهم مع المهمة:
WITH PairData AS (
SELECT
s1.name AS Name_A,
s2.name AS Name_B,
CONCAT(
"Assess compatibility of these two survivors for a resource-gathering mission. ",
"Survivor 1: ", s1.name, ". ",
"Survivor 2: ", s2.name, ". ",
"Give a score from 1-10 and a 1-sentence reason."
) AS prompt
FROM Survivors s1
JOIN Survivors s2 ON s1.survivor_id < s2.survivor_id
LIMIT 1
)
SELECT
Name_A,
Name_B,
content AS ai_assessment
FROM ML.PREDICT(
MODEL GeminiPro,
(SELECT Name_A, Name_B, prompt FROM PairData)
);
الناتج المتوقَّع:
Name_A | Name_B | ai_assessment
----------------|-------------------|----------------
"David Chen" | "Dr. Elena Frost" | "**Score: 9/10** Their compatibility is extremely high as David's practical, hands-on scavenging skills are perfectly complemented by Dr. Frost's specialized knowledge to identify critical medical supplies and avoid biological hazards."
6. 🚀 إنشاء وكيل Graph RAG باستخدام البحث المختلط
1. نظرة عامة على بنية النظام
ينشئ هذا القسم نظام بحث متعدّد الطرق يمنح وكيلك المرونة في التعامل مع أنواع مختلفة من طلبات البحث. يتكوّن النظام من ثلاث طبقات: طبقة الوكيل وطبقة الأدوات وطبقة الخدمة.

لماذا ثلاث طبقات؟
- فصل الاهتمامات: يركّز الوكيل على الغرض، والأدوات على الواجهة، والخدمة على التنفيذ
- المرونة: يمكن للوكيل فرض طرق معيّنة أو السماح للذكاء الاصطناعي بالتوجيه التلقائي
- التحسين: يمكن تخطّي تحليل الذكاء الاصطناعي المكلف عندما تكون الطريقة معروفة
في هذا القسم، ستنفّذ بشكل أساسي البحث الدلالي (RAG)، أي العثور على النتائج حسب المعنى وليس فقط الكلمات الرئيسية. سنشرح لاحقًا كيف يدمج البحث المختلط طرقًا متعددة.
2. تنفيذ خدمة RAG
👉💻 في الوحدة الطرفية، افتح الملف في محرِّر Cloud Shell من خلال تشغيل:
cloudshell edit ~/way-back-home/level_2/backend/services/hybrid_search_service.py
العثور على التعليق "# TODO: REPLACE_SQL"
استبدِل هذا السطر بالكامل بالرمز التالي:
# This is your working query from the successful run!
sql = """
WITH query_embedding AS (
SELECT embeddings.values AS val
FROM ML.PREDICT(
MODEL TextEmbeddings,
(SELECT @query AS content)
)
)
SELECT
s.survivor_id,
s.name AS survivor_name,
s.biome,
sk.skill_id,
sk.name AS skill_name,
sk.category,
COSINE_DISTANCE(
sk.skill_embedding,
(SELECT val FROM query_embedding)
) AS distance
FROM Survivors s
JOIN SurvivorHasSkill shs ON s.survivor_id = shs.survivor_id
JOIN Skills sk ON shs.skill_id = sk.skill_id
WHERE sk.skill_embedding IS NOT NULL
ORDER BY distance ASC
LIMIT @limit
"""
3- تعريف أداة البحث الدلالي
👉💻 في الوحدة الطرفية، افتح الملف في محرِّر Cloud Shell من خلال تشغيل:
cloudshell edit ~/way-back-home/level_2/backend/agent/tools/hybrid_search_tools.py
في "hybrid_search_tools.py"، ابحث عن التعليق "# TODO: REPLACE_SEMANTIC_SEARCH_TOOL"
👉استبدِل هذا السطر بالكامل بالرمز التالي:
async def semantic_search(query: str, limit: int = 10) -> str:
"""
Force semantic (RAG) search using embeddings.
Use this when you specifically want to find things by MEANING,
not just matching keywords. Great for:
- Finding conceptually similar items
- Handling vague or abstract queries
- When exact terms are unknown
Example: "healing abilities" will find "first aid", "surgery",
"herbalism" even though no keywords match exactly.
Args:
query: What you're looking for (describe the concept)
limit: Maximum results
Returns:
Semantically similar results ranked by relevance
"""
try:
service = _get_service()
result = service.smart_search(
query,
force_method=SearchMethod.RAG,
limit=limit
)
return _format_results(
result["results"],
result["analysis"],
show_analysis=True
)
except Exception as e:
return f"Error in semantic search: {str(e)}"
عندما يستخدم الوكيل:
- طلبات البحث عن التشابه ("العثور على صور مشابهة لـ X")
- طلبات البحث المفاهيمية ("قدرات الشفاء")
- عندما يكون فهم المعنى أمرًا بالغ الأهمية
4. دليل اتخاذ القرار لموظف الدعم (التعليمات)
في تعريف الوكيل، انسخ الجزء المتعلّق بالبحث الدلالي والصقه في التعليمات.
👉💻 في الوحدة الطرفية، افتح الملف في محرِّر Cloud Shell من خلال تشغيل:
cloudshell edit ~/way-back-home/level_2/backend/agent/agent.py
يستخدم الوكيل هذه التعليمات لاختيار الأداة المناسبة:
👉في ملف agent.py، ابحث عن التعليق # TODO: REPLACE_SEARCH_LOGIC، واستبدِل هذا السطر بأكمله بالرمز التالي:
- `semantic_search`: Force RAG/embedding search
Use for: "Find similar to X", conceptual queries, unknown terminology
Example: "Find skills related to healing"
👉ابحث عن التعليق # TODO: ADD_SEARCH_TOOLReplace this whole line واستبدِله بالرمز التالي:
semantic_search, # Force RAG
5- فهم طريقة عمل البحث المختلط (للقراءة فقط، لا حاجة إلى اتخاذ أي إجراء)
في الخطوات من 2 إلى 4، نفّذت البحث الدلالي (التوليد المعزّز بالاسترجاع)، وهو طريقة البحث الأساسية التي تعثر على النتائج حسب المعنى. ولكن ربما لاحظت أنّ النظام يُسمّى "البحث المختلط". إليك كيفية عمل كل هذه العناصر معًا:
طريقة عمل ميزة "الدمج المختلط":
في الملف way-back-home/level_2/backend/services/hybrid_search_service.py، عند استدعاء hybrid_search()، تُجري الخدمة عمليتَي البحث وتدمج النتائج:
# Location: backend/services/hybrid_search_service.py
rank_kw = keyword_ranks.get(surv_id, float('inf'))
rank_rag = rag_ranks.get(surv_id, float('inf'))
rrf_score = 0.0
if rank_kw != float('inf'):
rrf_score += 1.0 / (K + rank_kw)
if rank_rag != float('inf'):
rrf_score += 1.0 / (K + rank_rag)
combined_score = rrf_score
في هذا الدرس التطبيقي حول الترميز، نفّذت مكوّن البحث الدلالي (RAG)، وهو الأساس. تم تنفيذ طريقتَي الكلمات الرئيسية والبحث المختلط في الخدمة، ويمكن لوكيلك استخدام الطرق الثلاث.
تهانينا! لقد أكملت بنجاح إنشاء وكيل Graph RAG باستخدام البحث المختلط.
7. 🚀 اختبار الوكيل باستخدام ADK Web
أسهل طريقة لاختبار وكيلك هي استخدام الأمر adk web، الذي يشغّل وكيلك بواجهة محادثة مدمجة.
1. تشغيل الوكيل
👉💻 انتقِل إلى دليل الخلفية (حيث يتم تحديد الوكيل) وشغِّل واجهة الويب:
cd ~/way-back-home/level_2/backend
uv run adk web
يبدأ هذا الأمر الوكيل المحدّد في
agent/agent.py
ويفتح واجهة ويب للاختبار.
👉 افتح عنوان URL:
سيُخرج الأمر عنوان URL محليًا (عادةً http://127.0.0.1:8000 أو ما شابه). افتح هذا الرابط في متصفّحك.

بعد النقر على عنوان URL، ستظهر لك واجهة مستخدم الويب الخاصة بـ ADK. تأكَّد من اختيار "الوكيل" من أعلى يمين الصفحة.

2. اختبار إمكانات البحث
تم تصميم الوكيل لتوجيه طلباتك بذكاء. جرِّب الإدخالات التالية في نافذة المحادثة للاطّلاع على طرق البحث المختلفة أثناء العمل.
🧬 أ. Graph RAG (البحث الدلالي)
يعثر على العناصر استنادًا إلى المعنى والمفهوم، حتى إذا لم تتطابق الكلمات الرئيسية.
طلبات البحث الاختبارية: (اختَر أيًا مما يلي)
Who can help with injuries?
What abilities are related to survival?
ما يجب الانتباه له:
- يجب أن يشير السبب إلى البحث الدلالي أو البحث المعزّز بالاسترجاع.
- من المفترض أن تظهر لك نتائج ذات صلة من حيث المفهوم (على سبيل المثال، "جراحة" عند طلب "إسعافات أولية").
- ستظهر النتائج مع الرمز 🧬.
🔀 ب- البحث المختلط
يجمع بين فلاتر الكلمات الرئيسية والفهم الدلالي لطلبات البحث المعقّدة.
طلبات البحث الاختبارية:(اختَر أيًا مما يلي)
Find someone who can fly a plane in the volcanic area
Who has healing abilities in the FOSSILIZED?
Who has healing abilities in the mountains?
ما يجب الانتباه له:
- يجب أن يشير الاستدلال إلى البحث المختلط.
- يجب أن تتطابق النتائج مع كلا المعيارَين (المفهوم + الموقع الجغرافي/الفئة).
- ستظهر النتائج التي تم العثور عليها بكلتا الطريقتين مع الرمز 🔀 وستكون في أعلى الترتيب.
👉💻 عند الانتهاء من الاختبار، يمكنك إنهاء العملية بالضغط على Ctrl+C في سطر الأوامر.
8. 🚀 تشغيل التطبيق الكامل
نظرة عامة على بنية التطبيق المتكاملة

إضافة SessionService وRunner
👉💻 في الوحدة الطرفية، افتح الملف chat.py في محرِّر Cloud Shell من خلال تشغيل (تأكَّد من الضغط على "ctrl+C" لإنهاء العملية السابقة قبل المتابعة):
cloudshell edit ~/way-back-home/level_2/backend/api/routes/chat.py
👉في ملف chat.py، ابحث عن التعليق # TODO: REPLACE_INMEMORY_SERVICES، واستبدِل هذا السطر بأكمله بالرمز التالي:
session_service = InMemorySessionService()
memory_service = InMemoryMemoryService()
👉في ملف chat.py، ابحث عن التعليق # TODO: REPLACE_RUNNER، واستبدِل هذا السطر بأكمله بالرمز التالي:
runner = Runner(
agent=root_agent,
session_service=session_service,
memory_service=memory_service,
app_name="survivor-network"
)
1. بدء الطلب
إذا كان Terminal السابق لا يزال قيد التشغيل، يمكنك إنهاؤه بالضغط على Ctrl+C.
👉💻 بدء استخدام التطبيق:
cd ~/way-back-home/level_2/
./start_app.sh
عند بدء تشغيل الخلفية بنجاح، سيظهر لك Local: http://localhost:5173/" على النحو التالي: 
👉 انقر على Local: http://localhost:5173/ من الوحدة الطرفية.

2. اختبار البحث الدلالي
طلب البحث:
Find skills similar to healing

ماذا يحدث:
- يتعرّف الوكيل على طلب التشابه
- يتم إنشاء تضمين لـ "الشفاء"
- تستخدم مسافة جيب التمام للعثور على مهارات متشابهة من الناحية الدلالية
- النتيجة: الإسعافات الأولية (على الرغم من أنّ الأسماء لا تتطابق مع "الشفاء")
3- اختبار البحث المختلط
طلب البحث:
Find medical skills in the mountains
ماذا يحدث:
- مكوّن الكلمة الرئيسية: فلتر لـ
category='medical' - المكوّن الدلالي: تضمين "طبي" والترتيب حسب التشابه
- الدمج: دمج النتائج، مع إعطاء الأولوية لتلك التي تم العثور عليها من خلال الطريقتَين 🔀
Query(optional):
Who is good at survival and in the forest?
ماذا يحدث:
- نتائج البحث عن الكلمة الرئيسية:
biome='forest' - نتائج البحث الدلالي: مهارات مشابهة لـ "البقاء على قيد الحياة"
- يجمع النموذج المختلط بين الاثنين لتحقيق أفضل النتائج
👉💻 عند الانتهاء من الاختبار، يمكنك إنهاؤه في الوحدة الطرفية بالضغط على Ctrl+C.
4. (!ONLY FOR WORKSHOP ATTENDEE) Update your location
👉💻 شغِّل النص البرمجي الخاص بالإكمال:
cd ~/way-back-home/level_2
./set_level_2.sh
افتح الآن "waybackhome.dev"، وسيظهر لك موقعك الجغرافي المعدَّل. تهانينا على إكمال المستوى 2.

9. ☕️ [اختياري] مسار المعالجة المتعدّد الوسائط (إذن بالقراءة فقط) — طبقة الأدوات
لماذا نحتاج إلى مسار معالجة متعدد الوسائط؟
شبكة النجاة ليست مجرد نص. يرسل الناجون في الميدان بيانات غير منظَّمة مباشرةً من خلال المحادثة:
- 📸 الصور: صور للموارد أو المخاطر أو المعدات
- 🎥 الفيديوهات: تقارير الحالة أو بثّ رسائل الطوارئ
- 📄 النصوص: الملاحظات الميدانية أو السجلّات
ما هي الملفات التي نعالجها؟
على عكس الخطوة السابقة التي بحثنا فيها في البيانات الحالية، نعالج هنا الملفات التي حمّلها المستخدم. تتعامل واجهة chat.py مع مرفقات الملفات بشكل ديناميكي:
المصدر | المحتوى | الهدف |
مرفق المستخدم | صورة/فيديو/نص | المعلومات التي تريد إضافتها إلى الرسم البياني |
سياق المحادثة | "إليك صورة للمستلزمات" | الهدف والتفاصيل الإضافية |
النهج المخطَّط له: مسار الوكلاء المتسلسل
نستخدم وكيلاً تسلسليًا (multimedia_agent.py) يربط الوكلاء المتخصّصين معًا:

يتم تحديد ذلك في backend/agent/multimedia_agent.py على أنّه SequentialAgent.
توفّر طبقة الأدوات الإمكانات التي يمكن للوكلاء استخدامها. تتولى الأدوات معالجة "كيفية" تنفيذ المهام، مثل تحميل الملفات واستخراج الكيانات وحفظها في قاعدة البيانات.
1. فتح ملف الأدوات
👉💻 افتح الملف level_2/backend/agent/tools/extraction_tools.py أو اكتب الأمر التالي في الوحدة الطرفية. افتح وحدة طرفية جديدة. في الوحدة الطرفية، افتح الملف في محرِّر Cloud Shell:
cloudshell edit ~/way-back-home/level_2/backend/agent/tools/extraction_tools.py
2. تنفيذ أداة "upload_media"
تحمّل هذه الأداة ملفًا على الجهاز إلى Google Cloud Storage.
👉 في def upload_media(file_path: str, survivor_id: Optional[str] = None) -> Dict[str, Any]:، يتعلّق الرمز التالي بكيفية تحميل الملفات إلى GCS ورصد نوعها:
"""
Upload media file to GCS and detect its type.
Args:
file_path: Path to the local file
survivor_id: Optional survivor ID to associate with upload
Returns:
Dict with gcs_uri, media_type, and status
"""
try:
if not file_path:
return {"status": "error", "error": "No file path provided"}
# Strip quotes if present
file_path = file_path.strip().strip("'").strip('"')
if not os.path.exists(file_path):
return {"status": "error", "error": f"File not found: {file_path}"}
gcs_uri, media_type, signed_url = gcs_service.upload_file(file_path, survivor_id)
return {
"status": "success",
"gcs_uri": gcs_uri,
"signed_url": signed_url,
"media_type": media_type.value,
"file_name": os.path.basename(file_path),
"survivor_id": survivor_id
}
except Exception as e:
logger.error(f"Upload failed: {e}")
return {"status": "error", "error": str(e)}
3- تنفيذ أداة "extract_from_media"
هذه الأداة هي موجّه، فهي تتحقّق من media_type وترسلها إلى أداة الاستخراج الصحيحة (النص أو الصورة أو الفيديو).
👉 في async def extract_from_media(gcs_uri: str, media_type: str, signed_url: Optional[str] = None) -> Dict[str, Any]:، يوضّح الرمز التالي كيفية استخراج الكيانات والعلاقات من الوسائط التي تم تحميلها.
"""
Extract entities and relationships from uploaded media.
Args:
gcs_uri: GCS URI of the uploaded file
media_type: Type of media (text/image/video)
signed_url: Optional signed URL for public/temporary access
Returns:
Dict with extraction results
"""
try:
if not gcs_uri:
return {"status": "error", "error": "No GCS URI provided"}
# Select appropriate extractor
if media_type == MediaType.TEXT.value or media_type == "text":
result = await text_extractor.extract(gcs_uri)
elif media_type == MediaType.IMAGE.value or media_type == "image":
result = await image_extractor.extract(gcs_uri)
elif media_type == MediaType.VIDEO.value or media_type == "video":
result = await video_extractor.extract(gcs_uri)
else:
return {"status": "error", "error": f"Unsupported media type: {media_type}"}
# Inject signed URL into broadcast info if present
if signed_url:
if not result.broadcast_info:
result.broadcast_info = {}
result.broadcast_info['thumbnail_url'] = signed_url
return {
"status": "success",
"extraction_result": result.to_dict(), # Return valid JSON dict instead of object
"summary": result.summary,
"entities_count": len(result.entities),
"relationships_count": len(result.relationships),
"entities": [e.to_dict() for e in result.entities],
"relationships": [r.to_dict() for r in result.relationships]
}
except Exception as e:
logger.error(f"Extraction failed: {e}")
return {"status": "error", "error": str(e)}
تفاصيل التنفيذ الرئيسية:
- إدخال متعدد الوسائط: نرسل كلاً من الطلب النصي (
_get_extraction_prompt()) وعنصر الصورة إلىgenerate_content. - المخرجات المنظَّمة: يضمن
response_mime_type="application/json"أن يعرض نموذج اللغة الكبير ملف JSON صالحًا، وهو أمر بالغ الأهمية لمسار المعالجة. - ربط الكيانات المرئية: يتضمّن الطلب كيانات معروفة لكي يتمكّن Gemini من التعرّف على شخصيات معيّنة.
4. تنفيذ أداة "save_to_spanner"
تحفظ هذه الأداة الكيانات والعلاقات المستخرَجة في قاعدة بيانات Spanner Graph.
👉 في def save_to_spanner(extraction_result: Any, survivor_id: Optional[str] = None) -> Dict[str, Any]:، يوضّح الرمز التالي كيفية حفظ الكيانات والعلاقات المستخرَجة في قاعدة بيانات Spanner Graph.
"""
Save extracted entities and relationships to Spanner Graph DB.
Args:
extraction_result: ExtractionResult object (or dict from previous step if passed as dict)
survivor_id: Optional survivor ID to associate with the broadcast
Returns:
Dict with save statistics
"""
try:
# Handle if extraction_result is passed as the wrapper dict from extract_from_media
result_obj = extraction_result
if isinstance(extraction_result, dict) and 'extraction_result' in extraction_result:
result_obj = extraction_result['extraction_result']
# If result_obj is a dict (from to_dict()), reconstruct it
if isinstance(result_obj, dict):
from extractors.base_extractor import ExtractionResult
result_obj = ExtractionResult.from_dict(result_obj)
if not result_obj:
return {"status": "error", "error": "No extraction result provided"}
stats = spanner_service.save_extraction_result(result_obj, survivor_id)
return {
"status": "success",
"entities_created": stats['entities_created'],
"entities_existing": stats['entities_found_existing'],
"relationships_created": stats['relationships_created'],
"broadcast_id": stats['broadcast_id'],
"errors": stats['errors'] if stats['errors'] else None
}
except Exception as e:
logger.error(f"Spanner save failed: {e}")
return {"status": "error", "error": str(e)}
من خلال تزويد الوكلاء بأدوات عالية المستوى، نضمن صحّة البيانات مع الاستفادة من قدرات الاستدلال لدى الوكيل.
5- تحديث خدمة GCS
يتولّى GCSService معالجة عملية تحميل الملفات إلى Google Cloud Storage.
👉💻 افتح الملف level_2/backend/services/gcs_service.py، أو يمكنك الكتابة في الوحدة الطرفية لفتح الملف في "محرِّر Cloud Shell":
cloudshell edit ~/way-back-home/level_2/backend/services/gcs_service.py
👉 في def upload_file(self, file_path: str, survivor_id: Optional[str] = None) -> Tuple[str, MediaType, str]:، يوضّح الرمز التالي كيفية حفظ الكيانات والعلاقات المستخرَجة في قاعدة بيانات Spanner Graph.
blob = self.bucket.blob(blob_name)
blob.upload_from_filename(file_path)
من خلال تجريد هذه العملية في خدمة، لا يحتاج الوكيل إلى معرفة حِزم GCS أو أسماء العناصر الثنائية الكبيرة أو إنشاء عناوين URL موقَّعة. يطلب فقط "التحميل".
6. لماذا سير العمل المستند إلى الوكلاء أفضل من النُهُج التقليدية؟
مزايا الذكاء الاصطناعي الوكيل:
الميزة | مسار المعالجة المجمّعة | مستندة إلى الأحداث | سير العمل المستند إلى الذكاء الاصطناعي الوكيل |
التعقيد | منخفض (نص برمجي واحد) | مرتفع (أكثر من 5 خدمات) | منخفض (ملف Python واحد: |
إدارة الحالة | المتغيّرات العمومية | صعب (غير مرتبط) | موحَّد (حالة الوكيل) |
معالجة الأخطاء | حوادث سير | السجلّات الصامتة | تفاعلي ("لم أتمكّن من قراءة هذا الملف") |
ملاحظات المستخدمين | طباعة رسائل وحدة التحكّم | بحاجة إلى استطلاع | فوري (جزء من المحادثة) |
القدرة على التكيّف | تم إصلاح المنطق | الدوال الثابتة | ذكي (يحدّد النموذج اللغوي الكبير الخطوة التالية) |
الوعي بالسياق | بدون | بدون | كامل (يعرف نية المستخدم) |
أهمية ذلك: من خلال استخدام multimedia_agent.py (وهو SequentialAgent يتضمّن 4 وكلاء فرعيين: التحميل ← الاستخراج ← الحفظ ← الملخّص)، نستبدل البنية الأساسية المعقّدة والنصوص البرمجية الهشة بمنطق تطبيق ذكي وحواري.
10. ☕️ [اختياري] مسار المعالجة المتعدّد الوسائط (إذن بالقراءة فقط) — طبقة الوكيل
تحدّد طبقة الوكلاء الذكاء، أي الوكلاء الذين يستخدمون الأدوات لإنجاز المهام. لكل وكيل دور محدّد وينقل السياق إلى الوكيل التالي. في ما يلي مخطّط بياني لبنية النظام المستند إلى عدّة وكلاء.

1. فتح ملف الوكيل
👉💻 افتح الملف level_2/backend/agent/multimedia_agent.py أو اكتب الأمر التالي في الوحدة الطرفية. افتح وحدة طرفية جديدة. في الوحدة الطرفية، افتح الملف في محرِّر Cloud Shell:
cloudshell edit ~/way-back-home/level_2/backend/agent/multimedia_agent.py
2. تعريف "وكيل التحميل"
يستخرج هذا الوكيل مسار ملف من رسالة المستخدم ويحمّله إلى GCS.
👉في الملف multimedia_agent.py، باستخدام الرمز التالي، يتم إنشاء upload_agent الذي يتم تحميله إلى GCS:
upload_agent = LlmAgent(
name="UploadAgent",
model="gemini-2.5-flash",
instruction="""Extract the file path from the user's message and upload it.
Use `upload_media(file_path, survivor_id)` to upload the file.
The survivor_id is optional - include it if the user mentions a specific survivor (e.g., "survivor Sarah" -> "Sarah").
If the user provides a path like "/path/to/file", use that.
Return the upload result with gcs_uri and media_type.""",
tools=[upload_media],
output_key="upload_result"
)
3- تحديد وكيل الاستخراج
"يرى" هذا الوكيل الوسائط التي تم تحميلها ويستخرج البيانات المنظَّمة باستخدام Gemini Vision.
👉في الملف multimedia_agent.py، وباستخدام الرمز التالي، يتم إنشاء extraction_agent لاستخراج المعلومات من الوسائط التي تم تحميلها:
extraction_agent = LlmAgent(
name="ExtractionAgent",
model="gemini-2.5-flash",
instruction="""Extract information from the uploaded media.
Previous step result: {upload_result}
Use `extract_from_media(gcs_uri, media_type, signed_url)` with the values from the upload result.
The gcs_uri is in upload_result['gcs_uri'], media_type in upload_result['media_type'], and signed_url in upload_result['signed_url'].
Return the extraction results including entities and relationships found.""",
tools=[extract_from_media],
output_key="extraction_result"
)
لاحِظ كيف يشير instruction إلى {upload_result}، فهذه هي الطريقة التي يتم بها تمرير الحالة بين الوكلاء في ADK.
4. تعريف وكيل Spanner
يحفظ هذا الوكيل الكيانات والعلاقات المستخرَجة في قاعدة بيانات الرسم البياني.
👉في الملف multimedia_agent.py، باستخدام الرمز التالي، يتم إنشاء spanner_agent لحفظ المعلومات المستخرَجة في قاعدة البيانات:
spanner_agent = LlmAgent(
name="SpannerAgent",
model="gemini-2.5-flash",
instruction="""Save the extracted information to the database.
Upload result: {upload_result}
Extraction result: {extraction_result}
Use `save_to_spanner(extraction_result, survivor_id)` to save to Spanner.
Pass the WHOLE `extraction_result` object/dict from the previous step.
Include survivor_id if it was provided in the upload step.
Return the save statistics.""",
tools=[save_to_spanner],
output_key="spanner_result"
)
يتلقّى هذا الوكيل سياقًا من كلتا الخطوتين السابقتين (upload_result وextraction_result).
5- تعريف وكيل التلخيص
يجمع هذا الوكيل النتائج من جميع الخطوات السابقة في ردّ سهل الاستخدام.
👉في الملف multimedia_agent.py، يحدّد الرمز التالي الطلب لـ summary_agent الذي يلخّص النتيجة:
USE_MEMORY_BANK = os.getenv("USE_MEMORY_BANK", "false").lower() == "true"
save_msg = "6. Mention that the data is also being synced to the memory bank." if USE_MEMORY_BANK else ""
summary_instruction = f"""Provide a user-friendly summary of the media processing.
Upload: {{upload_result}}
Extraction: {{extraction_result}}
Database: {{spanner_result}}
Summarize:
1. What file was processed (name and type)
2. Key information extracted (survivors, skills, needs, resources found) - list names and counts
3. Relationships identified
4. What was saved to the database (broadcast ID, number of entities)
5. Any issues encountered
{save_msg}
Be concise but informative."""
لا يحتاج هذا الوكيل إلى أدوات، بل يقرأ السياق المشترَك وينشئ ملخّصًا واضحًا للمستخدم.
🧠 ملخّص البنية
طبقة | ملف | المسؤولية |
الأدوات |
| كيفية الاستخدام: التحميل والاستخراج والحفظ |
الوكيل |
| ماذا: تنظيم المسار |
11. 🚀 مسار البيانات المتعدّد الوسائط — التنسيق
The core of our new system is the MultimediaExtractionPipeline defined in backend/agent/multimedia_agent.py. ويستخدم نمط الوكيل التسلسلي من "حزمة تطوير الوكلاء" (ADK).
1. لماذا نستخدم Sequential؟
تتم معالجة عملية التحميل من خلال سلسلة اعتمادية خطية:
- لا يمكنك استخراج البيانات حتى تحصل على الملف (تحميل).
- لا يمكنك حفظ البيانات إلا بعد استخراجها (الاستخراج).
- لا يمكنك التلخيص حتى تحصل على النتائج (حفظ).
وSequentialAgent هو الخيار المثالي لذلك. ويتم تمرير مخرجات أحد الوكلاء كسياق أو مدخلات إلى الوكيل التالي.
2. تعريف الوكيل
لنلقِ نظرة على كيفية تجميع المسار في أسفل multimedia_agent.py: 👉💻 في الوحدة الطرفية، افتح الملف في محرِّر Cloud Shell من خلال تنفيذ الأمر التالي:
cloudshell edit ~/way-back-home/level_2/backend/agent/multimedia_agent.py
ويتلقّى مدخلات من كلتا الخطوتَين السابقتَين. ابحث عن التعليق "# TODO: REPLACE_ORCHESTRATION". استبدِل هذا السطر بالكامل بالرمز التالي:
sub_agents=[upload_agent, extraction_agent, spanner_agent, summary_agent]
3- التواصل مع Root Agent
👉💻 في الوحدة الطرفية، افتح الملف في محرِّر Cloud Shell من خلال تشغيل:
cloudshell edit ~/way-back-home/level_2/backend/agent/agent.py
ابحث عن التعليق "# TODO: REPLACE_ADD_SUBAGENT". استبدِل هذا السطر بالكامل بالرمز التالي:
sub_agents=[multimedia_agent],
يجمع هذا الكائن الفردي بشكل فعّال أربعة "خبراء" في كيان واحد قابل للاستدعاء.
4. تدفق البيانات بين الوكلاء
يخزّن كل وكيل مخرجاته في سياق مشترك يمكن للوكلاء اللاحقين الوصول إليه:

5- افتح التطبيق (تخطَّ هذه الخطوة إذا كان التطبيق لا يزال قيد التشغيل)
👉💻 بدء استخدام التطبيق:
cd ~/way-back-home/level_2/
./start_app.sh
👉 انقر على Local: http://localhost:5173/ من الوحدة الطرفية.
6. تحميل صورة الاختبار
👉 في واجهة المحادثة، اختَر أيًا من الصور هنا وحمِّلها إلى واجهة المستخدم:
في واجهة المحادثة، أخبِر الوكيل عن سياقك المحدّد:
Here is the survivor note
بعد ذلك، أرفِق الصورة هنا.


👉💻 في الوحدة الطرفية، عند الانتهاء من الاختبار، اضغط على "Ctrl+C" لإنهاء العملية.
6. التحقّق من التحميل المتعدد الوسائط في حزمة GCS
- افتح Google Cloud Console Storage.
- اختيار "حزمة" في Cloud Storage

- اختَر حزمتك وانقر على
media.

- يمكنك الاطّلاع على الصورة التي حمّلتها هنا.

7. التحقّق من التحميل المتعدد الوسائط في Spanner (اختياري)
في ما يلي مثال على الناتج في واجهة المستخدم لـ test_photo1.
- افتح Google Cloud Console Spanner.
- اختَر المثيل:
Survivor Network - اختَر قاعدة بياناتك:
graph-db - في الشريط الجانبي الأيمن، انقر على Spanner Studio
👉 في Spanner Studio، يمكنك الاستعلام عن البيانات الجديدة:
SELECT
s.name AS Survivor,
s.role AS Role,
b.name AS Biome,
r.name AS FoundResource,
s.created_at
FROM Survivors s
LEFT JOIN SurvivorInBiome sib ON s.survivor_id = sib.survivor_id
LEFT JOIN Biomes b ON sib.biome_id = b.biome_id
LEFT JOIN SurvivorFoundResource sfr ON s.survivor_id = sfr.survivor_id
LEFT JOIN Resources r ON sfr.resource_id = r.resource_id
ORDER BY s.created_at DESC;
يمكننا التحقق من ذلك من خلال رؤية النتيجة أدناه:

12. ☕️ [اختياري] "بنك الذاكرة" مع Agent Engine
1. طريقة عمل ميزة "الذاكرة"
يستخدم النظام نهج الذاكرة المزدوجة للتعامل مع كل من السياق الفوري والتعلّم على المدى الطويل.

2. ما هي مواضيع الذكريات؟
تحدّد مواضيع الذاكرة فئات المعلومات التي يجب أن يتذكّرها الوكيل في جميع المحادثات. يمكنك اعتبارها خزائن ملفات لأنواع مختلفة من تفضيلات المستخدم.
الموضوعان:
search_preferences: طريقة البحث المفضّلة لدى المستخدم- هل يفضّلون البحث عن الكلمات الرئيسية أو البحث الدلالي؟
- ما هي المهارات/المناطق الأحيائية التي يبحثون عنها غالبًا؟
- مثال على الذاكرة: "يفضّل المستخدم البحث الدلالي عن المهارات الطبية"
urgent_needs_context: الأزمات التي يتتبّعها- ما هي الموارد التي تتم مراقبتها؟
- مَن هم الناجون الذين يشعرون بالقلق بشأنهم؟
- مثال على تذكُّر معلومة: "يتتبّع المستخدم النقص في الأدوية في المخيم الشمالي"
3- إعداد مواضيع الذكريات
تحدّد مواضيع الذاكرة المخصّصة ما يجب أن يتذكّره الوكيل. ويتم ضبطها عند نشر Agent Engine.
👉💻 في الوحدة الطرفية، افتح الملف في محرِّر Cloud Shell من خلال تشغيل:
cloudshell edit ~/way-back-home/level_2/backend/deploy_agent.py
سيؤدي ذلك إلى فتح ~/way-back-home/level_2/backend/deploy_agent.py في المحرِّر.
نحدّد عناصر MemoryTopic البنية لتوجيه النموذج اللغوي الكبير بشأن المعلومات التي يجب استخراجها وحفظها.
👉في الملف deploy_agent.py، استبدِل # TODO: SET_UP_TOPIC بما يلي:
# backend/deploy_agent.py
custom_topics = [
# Topic 1: Survivor Search Preferences
MemoryTopic(
custom_memory_topic=CustomMemoryTopic(
label="search_preferences",
description="""Extract the user's preferences for how they search for survivors. Include:
- Preferred search methods (keyword, semantic, direct lookup)
- Common filters used (biome, role, status)
- Specific skills they value or frequently look for
- Geographic areas of interest (e.g., "forest biome", "mountain outpost")
Example: "User prefers semantic search for finding similar skills."
Example: "User frequently checks for survivors in the Swamp Biome."
""",
)
),
# Topic 2: Urgent Needs Context
MemoryTopic(
custom_memory_topic=CustomMemoryTopic(
label="urgent_needs_context",
description="""Track the user's focus on urgent needs and resource shortages. Include:
- Specific resources they are monitoring (food, medicine, ammo)
- Critical situations they are tracking
- Survivors they are particularly concerned about
Example: "User is monitoring the medicine shortage in the Northern Camp."
Example: "User is looking for a doctor for the injured survivors."
""",
)
)
]
4. التكامل مع وكلاء الذكاء الاصطناعي
يجب أن يكون رمز الوكيل على عِلم بـ "بنك الذاكرة" لحفظ المعلومات واستردادها.
👉💻 في الوحدة الطرفية، افتح الملف في محرِّر Cloud Shell من خلال تشغيل:
cloudshell edit ~/way-back-home/level_2/backend/agent/agent.py
سيؤدي ذلك إلى فتح ~/way-back-home/level_2/backend/agent/agent.py في المحرِّر.
إنشاء الوكلاء
عند إنشاء الوكيل، نمرّر after_agent_callback لضمان حفظ الجلسات في الذاكرة بعد التفاعلات. تعمل الدالة add_session_to_memory بشكل غير متزامن لتجنُّب إبطاء الردّ في المحادثة.
👉في الملف agent.py، ابحث عن التعليق # TODO: REPLACE_ADD_SESSION_MEMORY، واستبدِل هذا السطر بأكمله بالرمز التالي:
async def add_session_to_memory(
callback_context: CallbackContext
) -> Optional[types.Content]:
"""Automatically save completed sessions to memory bank in the background"""
if hasattr(callback_context, "_invocation_context"):
invocation_context = callback_context._invocation_context
if invocation_context.memory_service:
# Use create_task to run this in the background without blocking the response
asyncio.create_task(
invocation_context.memory_service.add_session_to_memory(
invocation_context.session
)
)
logger.info("Scheduled session save to memory bank in background")
الحفظ في الخلفية
👉في الملف agent.py، ابحث عن التعليق # TODO: REPLACE_ADD_MEMORY_BANK_TOOL، واستبدِل هذا السطر بأكمله بالرمز التالي:
if USE_MEMORY_BANK:
agent_tools.append(PreloadMemoryTool())
👉في الملف agent.py، ابحث عن التعليق # TODO: REPLACE_ADD_CALLBACK، واستبدِل هذا السطر بأكمله بالرمز التالي:
after_agent_callback=add_session_to_memory if USE_MEMORY_BANK else None
إعداد Vertex AI Session Service
👉💻 في الوحدة الطرفية، افتح الملف chat.py في محرِّر Cloud Shell من خلال تنفيذ الأمر التالي:
cloudshell edit ~/way-back-home/level_2/backend/api/routes/chat.py
👉في ملف chat.py، ابحث عن التعليق # TODO: REPLACE_VERTEXAI_SERVICES، واستبدِل هذا السطر بأكمله بالرمز التالي:
session_service = VertexAiSessionService(
project=project_id,
location=location,
agent_engine_id=agent_engine_id
)
memory_service = VertexAiMemoryBankService(
project=project_id,
location=location,
agent_engine_id=agent_engine_id
)
13. ☕️ [اختياري] ربط الوكيل بـ Agent Engine
1. الإعداد والنشر
قبل اختبار ميزات الذاكرة، عليك نشر الوكيل مع مواضيع الذاكرة الجديدة والتأكّد من ضبط بيئتك بشكل صحيح.
لقد قدّمنا نصًا برمجيًا مناسبًا للتعامل مع هذه العملية.
تشغيل نص النشر البرمجي
👉💻 في الوحدة الطرفية، شغِّل النص البرمجي للنشر:
cd ~/way-back-home/level_2
./deploy_and_update_env.sh
ينفّذ هذا النص البرمجي الإجراءات التالية:
- يتم تشغيل
backend/deploy_agent.pyلتسجيل الوكيل ومواضيع الذاكرة في Vertex AI. - يتم تسجيل رقم تعريف محرّك الوكيل الجديد.
- يتم تعديل ملف
.envتلقائيًا باستخدامAGENT_ENGINE_ID. - يجب التأكّد من ضبط
USE_MEMORY_BANK=TRUEفي ملف.env.
[!IMPORTANT] إذا أجريت تغييرات على custom_topics في deploy_agent.py، عليك إعادة تشغيل هذا النص البرمجي لتعديل Agent Engine.
التحقّق من Memory Bank
يمكنك الآن التحقّق من أنّ ذاكرة الوكيل تعمل من خلال تعليمه أحد الإعدادات المفضّلة والتحقّق مما إذا كان سيحتفظ به في جميع الجلسات.
الخطوة الأولى: فتح التطبيق
افتح التطبيق مرة أخرى باتّباع التعليمات التالية: إذا كان التطبيق السابق لا يزال قيد التشغيل، يمكنك إنهاؤه بالضغط على Ctrls+C.
👉💻 بدء استخدام التطبيق:
cd ~/way-back-home/level_2/
./start_app.sh
👉 انقر على Local: http://localhost:5173/ من الوحدة الطرفية.
الخطوة الثانية: اختبار Memory Bank مع نص
في واجهة المحادثة، أخبِر الوكيل عن سياقك المحدّد:
"I'm planning a medical rescue mission in the mountains. I need survivors with first aid and climbing skills."
👉 انتظِر لمدة 30 ثانية تقريبًا حتى تتم معالجة الذكرى في الخلفية.
الخطوة الثالثة: بدء جلسة جديدة
أعِد تحميل الصفحة لمحو سجلّ المحادثة الحالية (الذاكرة القصيرة المدى).
اطرح سؤالاً يعتمد على السياق الذي قدّمته سابقًا:
"What kind of missions am I interested in?"
الردّ المتوقَّع:
"استنادًا إلى محادثاتك السابقة، أنت مهتم بما يلي:
- مهام الإنقاذ الطبي
- العمليات في الجبال أو على ارتفاعات عالية
- المهارات المطلوبة: الإسعافات الأولية والتسلّق
هل تريد مني العثور على ناجين يستوفون هذه المعايير؟"
الخطوة الرابعة: اختبار مع تحميل صورة
حمِّل صورة واطرح السؤال التالي:
remember this
يمكنك اختيار أي من الصور هنا أو صورتك الخاصة وتحميلها إلى واجهة المستخدم:
الخطوة الخامسة: التحقّق في Vertex AI Agent Engine
انتقِل إلى Google Cloud Console Agent Engine
- تأكَّد من اختيار المشروع من أداة اختيار المشاريع في أعلى يمين الصفحة:

- تحقَّق من محرك الوكيل الذي نشرته للتو من الأمر السابق
use_memory_bank.sh:
انقر على محرك الوكيل الذي أنشأته للتو. - انقر على علامة التبويب
Memoriesفي هذا الوكيل الذي تم نشره، ويمكنك الاطّلاع على كل الذاكرة هنا.
👉💻 عند الانتهاء من الاختبار، انقر على "Ctrl + C" في الوحدة الطرفية لإنهاء العملية.
🎉 تهانينا! لقد ربطت قاعدة الذاكرة بوكيلك.
14. ☕️ [اختياري] النشر على Cloud Run
1. تشغيل نص النشر البرمجي
👉💻 شغِّل نص النشر البرمجي:
cd ~/way-back-home/level_2
./deploy_cloud_run.sh
بعد نشر التطبيق بنجاح، سيظهر لك عنوان URL الخاص به. 
👉💻 قبل الحصول على عنوان URL، امنح الإذن من خلال تشغيل:
source .env && gcloud run services add-iam-policy-binding survivor-frontend --region $REGION --member=allUsers --role=roles/run.invoker && gcloud run services add-iam-policy-binding survivor-backend --region $REGION --member=allUsers --role=roles/run.invoker
انتقِل إلى عنوان URL المنشور، وسيظهر لك تطبيقك مباشرةً هناك.
2. فهم مسار الإنشاء
يحدّد ملف cloudbuild.yaml الخطوات المتسلسلة التالية:
- Backend Build: ينشئ صورة Docker من
backend/Dockerfile. - Backend Deploy: لنشر حاوية الخلفية على Cloud Run.
- التقاط عنوان URL: يحصل على عنوان URL الجديد للخلفية.
- Frontend Build:
- يتم تثبيت التبعيات.
- ينشئ تطبيق React، ويُدخل
VITE_API_URL=.
- Frontend Image: لإنشاء نسخة Docker من
frontend/Dockerfile(تجميع مواد العرض الثابتة) - Frontend Deploy: لنشر حاوية الواجهة الأمامية
3- التحقّق من عملية النشر
بعد اكتمال عملية الإنشاء (راجِع رابط السجلّات الذي يوفّره النص البرمجي)، يمكنك التحقّق مما يلي:
- انتقِل إلى وحدة تحكّم Cloud Run.
- ابحث عن خدمة "
survivor-frontend". - انقر على عنوان URL لفتح التطبيق.
- أدخِل طلب بحث للتأكّد من أنّ الواجهة الأمامية يمكنها التواصل مع الواجهة الخلفية.
(اختياري) 4. النشر اليدوي
إذا كنت تفضّل تنفيذ الأوامر يدويًا أو فهم العملية بشكل أفضل، إليك كيفية استخدام cloudbuild.yaml مباشرةً.
جارٍ كتابة "cloudbuild.yaml"
يخبر ملف cloudbuild.yaml خدمة Google Cloud Build بالخطوات التي يجب تنفيذها.
- steps: قائمة بالإجراءات المتسلسلة يتم تنفيذ كل خطوة في حاوية (مثل
dockerأوgcloudأوnodeأوbash). - substitutions: المتغيّرات التي يمكن تمريرها في وقت الإنشاء (مثل
$_REGION). - workspace: دليل مشترك يمكن للخطوات من خلاله مشاركة الملفات (مثل طريقة مشاركة
backend_url.txt).
تشغيل عملية النشر
للنشر يدويًا بدون النص البرمجي، استخدِم الأمر gcloud builds submit. يجب تمرير متغيّرات الاستبدال المطلوبة.
# Load your env vars first or replace these values manually
export PROJECT_ID=your-project-id
export REGION=us-central1
gcloud builds submit --config cloudbuild.yaml \
--project "$PROJECT_ID" \
--substitutions _REGION="us-central1",_GOOGLE_API_KEY="",_AGENT_ENGINE_ID="your-agent-id",_USE_MEMORY_BANK="TRUE",_GOOGLE_GENAI_USE_VERTEXAI="TRUE"
15. الخاتمة
1. ما أنشأته
✅ قاعدة بيانات الرسم البياني: Spanner مع العُقد (الناجون والمهارات) والحواف (العلاقات)
✅ البحث بالذكاء الاصطناعي: البحث بالكلمات الرئيسية والدلالي والمختلط باستخدام التضمينات
✅ مسار المعالجة المتعدّد النماذج: استخراج الكيانات من الصور/الفيديوهات باستخدام Gemini
✅ نظام الوكلاء المتعدّدين: سير عمل منسَّق باستخدام ADK
✅ بنك الذاكرة: تخصيص طويل الأمد باستخدام Vertex AI
✅ نشر الإنتاج: Cloud Run + Agent Engine
2. ملخّص البنية

3- الدروس الرئيسية المستفادة
- Graph RAG: يجمع بين بنية قاعدة بيانات الرسم البياني والتضمينات الدلالية لإجراء بحث ذكي
- أنماط الوكلاء المتعدّدين: مسارات متسلسلة لمهام سير العمل المعقّدة والمتعدّدة الخطوات
- الذكاء الاصطناعي المتعدد الوسائط: استخراج البيانات المنظَّمة من الوسائط غير المنظَّمة (الصور/الفيديو)
- الوكلاء الذين يحفظون الحالة: تتيح ميزة Memory Bank التخصيص في جميع الجلسات
4. محتوى ورشة العمل
- Level0: التعريف عن نفسك
- Level1: تحديد الموقع الجغرافي
- Level2 This One: إنشاء وكيل ذكاء اصطناعي متعدد الوسائط باستخدام Graph RAG وADK وMemory Bank
- Level3: إنشاء وكيل بث ثنائي الاتجاه باستخدام ADK
- Level4: نظام مباشر ثنائي الاتجاه متعدّد الوكلاء
- Level5: بنية مستندة إلى الأحداث باستخدام Google ADK وA2A وKafka