استخدام "أداة البحث عن الملفات" من Google Gemini لإنشاء الردود المستندة إلى الاسترجاع والإنشاء (RAG)

1. مقدمة

يوضّح لك هذا الدرس العملي كيفية استخدام ميزة "البحث عن الملفات" في Gemini لتفعيل ميزة "الاسترجاع والإنشاء" في تطبيقك المستند إلى الذكاء الاصطناعي الوكيل. ستستخدم "بحث الملفات في Gemini" لاستيعاب مستنداتك وفهرستها بدون الحاجة إلى الاهتمام بتفاصيل تقسيم المحتوى إلى أجزاء أو التضمين أو قاعدة بيانات المتّجهات.

ما ستتعرّف عليه

أساسيات RAG وأسباب حاجتنا إليها
ما هي ميزة "البحث عن الملفات" في Gemini ومزاياها؟
كيفية إنشاء "متجر بحث الملفات"
كيفية تحميل ملفاتك المخصّصة إلى "متجر بحث الملفات"
كيفية استخدام أداة "البحث عن الملفات" من Gemini للتوليد المعزّز بالاسترجاع
مزايا استخدام "حزمة تطوير البرامج لوكيل Google" (ADK)
كيفية استخدام "أداة البحث عن الملفات" من Gemini في حلّ مستند إلى وكيل تم إنشاؤه باستخدام "حزمة تطوير التطبيقات"
كيفية استخدام أداة "البحث عن الملفات" من Gemini إلى جانب أدوات Google "الأصلية"، مثل "بحث Google"

المهام التي ستنفّذها

أنشئ مشروعًا على Google Cloud وأعِدّ بيئة التطوير.
إنشاء وكيل بسيط يستند إلى Gemini باستخدام حزمة تطوير البرامج (SDK) من Google للذكاء الاصطناعي التوليدي (ولكن بدون ADK) ولديه القدرة على استخدام "بحث Google"، ولكن بدون إمكانية استرجاع المعلومات.
أن يثبت عدم قدرته على تقديم معلومات دقيقة وعالية الجودة بشأن المعلومات المخصّصة
أنشئ ورقة ملاحظات Jupyter (يمكنك تشغيلها محليًا أو على Google Colab مثلاً) لإنشاء وإدارة مستودع "بحث الملفات" في Gemini.
استخدِم دفتر الملاحظات لتحميل محتوى مخصّص إلى "متجر البحث عن الملفات".
أنشئ وكيلًا يتضمّن "متجر بحث الملفات"، وأثبِت أنّه قادر على تقديم ردود أفضل.
تحويل وكيلنا "الأساسي" الأوّلي إلى وكيل ADK، مع أداة "بحث Google"
اختبِر الوكيل باستخدام واجهة مستخدم الويب الخاصة بـ ADK.
دمج "مستودع بحث الملفات" في وكيل ADK، باستخدام نمط "الوكيل كأداة" للسماح لنا باستخدام "أداة بحث الملفات" إلى جانب "أداة بحث Google"

2. ما هو التوليد المعزّز بالاسترجاع (RAG) وسبب الحاجة إليه؟

حسنًا التوليد المعزّز بالاسترجاع

إذا كنت تقرأ هذا المقال، من المحتمل أنّك تعرف ما هو، ولكن لنلخّصه سريعًا، تحسّبًا لأي طارئ. تتسم النماذج اللغوية الكبيرة (مثل Gemini) بالذكاء، ولكنها تعاني من بعض المشاكل:

معلومات قديمة دائمًا: لا تعرف هذه النماذج سوى ما تعلّمته أثناء التدريب.
لا تعرف كل شيء: صحيح أنّ النماذج ضخمة، ولكنّها ليست مطلقة المعرفة.
لا تعرف هذه النماذج معلوماتك الخاصة: لديها معرفة واسعة، ولكنّها لم تقرأ مستنداتك الداخلية أو مدوّناتك أو تذاكر Jira.

لذلك، عندما تطرح سؤالاً على نموذج لا يعرف إجابته، ستحصل عادةً على إجابة غير صحيحة أو حتى من تأليفه. في كثير من الأحيان، سيقدّم النموذج هذه الإجابة غير الصحيحة بثقة. وهذا ما نشير إليه باسم التهيّؤ.

أحد الحلول هو تضمين معلوماتنا الخاصة مباشرةً في سياق المحادثة. لا بأس بذلك إذا كانت كمية المعلومات صغيرة، ولكن يصبح الأمر مشكلة بسرعة عندما يكون لديك الكثير من المعلومات. على وجه التحديد، يؤدي ذلك إلى المشاكل التالية:

وقت الاستجابة: استجابات أبطأ فأبطأ من النموذج
تدهور الإشارات، المعروف أيضًا باسم "الضياع في المنتصف": يحدث عندما يعجز النموذج عن فرز البيانات ذات الصلة من البيانات غير المرغوب فيها. يتجاهل النموذج الكثير من السياق.
التكلفة: لأنّ الرموز المميزة تتطلّب دفع المال.
استنفاد نافذة السياق: في هذه الحالة، لن ينفّذ Gemini طلباتك.

الطريقة الأكثر فعالية لمعالجة هذه المشكلة هي استخدام RAG. إنّها ببساطة عملية البحث عن المعلومات ذات الصلة من مصادر البيانات الخاصة بك (باستخدام المطابقة الدلالية) وتزويد النموذج بأجزاء ذات صلة من هذه البيانات إلى جانب سؤالك. فهو يربط النموذج بواقعك.

تعمل هذه العملية من خلال استيراد بيانات خارجية، وتقسيم البيانات إلى أجزاء، وتحويل البيانات إلى تضمينات متجهة، ثم تخزين هذه التضمينات وفهرستها في قاعدة بيانات متجهة مناسبة.

لذا، لتنفيذ RAG، علينا عادةً الاهتمام بما يلي:

إنشاء قاعدة بيانات متّجهات (مثل Pinecone أو Weaviate أو Postgres مع pgvector).
كتابة نص برمجي لتقسيم المستندات (مثل ملفات PDF أو Markdown أو أي تنسيق آخر)
إنشاء تضمينات (متجهات) لهذه الأجزاء باستخدام نموذج تضمين
تخزين المتجهات في قاعدة بيانات المتجهات

لكنّ الأصدقاء لا يسمحون لبعضهم البعض بالإفراط في التفكير في الأمور. ماذا لو أخبرتك أنّ هناك طريقة أسهل؟

3- المتطلبات الأساسية

إنشاء مشروع على Google Cloud

يجب أن يكون لديك مشروع على Google Cloud لتنفيذ هذا الدرس العملي. يمكنك استخدام مشروع حالي أو إنشاء مشروع جديد.

تأكَّد من تفعيل الفوترة في مشروعك. راجِع هذا الدليل لمعرفة كيفية التحقّق من حالة الفوترة لمشاريعك.

يُرجى العلم أنّه من غير المتوقّع أن تتكبّد أي تكلفة مقابل إكمال هذا الدرس العملي. في الحد الأقصى، ستكون بضعة سنتات.

يمكنك الآن إعداد مشروعك. سأنتظر.

استنساخ مستودع العرض التوضيحي

لقد أنشأتُ مستودعًا يتضمّن محتوًى إرشاديًا لهذا الدرس التطبيقي حول الترميز. ستحتاج إليه.

نفِّذ الأوامر التالية من الوحدة الطرفية أو من الوحدة الطرفية المدمجة في محرّر Cloud Shell من Google. تتوفّر في Cloud Shell وأداة التعديل الخاصة به جميع الأوامر التي تحتاج إليها مثبّتة مسبقًا، كما أنّ كل شيء يعمل "بدون أي إعدادات إضافية".

git clone https://github.com/derailed-dash/gemini-file-search-demo
cd gemini-file-search-demo

تعرض هذه الشجرة المجلدات والملفات الرئيسية في المستودع:

gemini-file-search-demo/
├── app/
│   ├── basic_agent_adk/        # Agent with Google Search, using ADK framework
│   │   └── agent.py
│   ├── rag_agent_adk/          # Agent with Google Search and File Search, using ADK framework
│   │   ├── agent.py            
│   │   └── tools_custom.py      
│   ├── sdk_agent.py            # Agent using GenAI SDK (no ADK) with Google Search tool
│   └── sdk_rag_agent.py        # Agent using GenAI SDK (no ADK) with Gemini File Search tool
├── data/
│   └── story.md                # Sample story with "bespoke content" to use with Gemini File Search Store
├── notebooks/
│   └── file_search_store.ipynb # Jupyter notebook for creating and managing Gemini File Search Store
│
├── .env.template               # Template for environment variables - make a copy as .env
├── Makefile                    # Makefile for `make` commands
├── pyproject.toml              # Project configuration and dependencies
└── README.md                   # This file

افتح هذا المجلد في "محرِّر Cloud Shell" أو في المحرِّر المفضّل لديك. (هل جرّبت Antigravity بعد؟ إذا لم يسبق لك تجربتها، ننصحك بتجربتها الآن.)

يحتوي المستودع على قصة نموذجية بعنوان "The Wormhole Incursion" في الملف data/story.md. لقد شاركتُ في كتابة هذه الأغنية مع Gemini. تدور أحداثها حول القائد "دازبو" وسرب سفنه الفضائية الذكية. (استلهمت بعض الأفكار من لعبة Elite Dangerous). تعمل هذه القصة كـ "قاعدة معرفة مخصّصة"، إذ تحتوي على حقائق معيّنة لا يعرفها Gemini، ولا يمكنه البحث عنها باستخدام "بحث Google".

إعداد بيئة التطوير

لتسهيل الأمر، قدّمتُ Makefile لتبسيط العديد من الأوامر التي عليك تنفيذها. بدلاً من تذكُّر أوامر معيّنة، يمكنك ببساطة تنفيذ أمر مثل make <target>. ومع ذلك، لا تتوفّر make إلا في بيئات Linux أو MacOS أو WSL. إذا كنت تستخدم نظام التشغيل Windows (بدون WSL)، عليك تنفيذ الأوامر الكاملة التي تحتوي عليها أهداف make.

# Install dependencies with make
make install

# If you don't have make...
uv sync --extra jupyter

إليك الشكل الذي يظهر عند تشغيل make install في "محرّر Cloud Shell":

إنشاء مفتاح واجهة Gemini API

لاستخدام Gemini Developer API (الذي نحتاج إليه من أجل استخدام "أداة البحث عن الملفات" في Gemini)، يجب أن يكون لديك مفتاح Gemini API. أسهل طريقة للحصول على مفتاح واجهة برمجة تطبيقات هي استخدام Google AI Studio، الذي يوفّر واجهة سهلة الاستخدام للحصول على مفاتيح واجهة برمجة التطبيقات لمشاريعك على Google Cloud. يمكنك الاطّلاع على هذا الدليل لمعرفة الخطوات المحدّدة.

بعد إنشاء مفتاح واجهة برمجة التطبيقات، انسَخه واحتفِظ به في مكان آمن.

عليك الآن ضبط مفتاح واجهة برمجة التطبيقات هذا كمتغيّر بيئي. يمكننا إجراء ذلك باستخدام ملف .env. انسخ .env.example المضمّن كملف جديد باسم .env. يجب أن يظهر الملف على النحو التالي:

export GEMINI_API_KEY="your-api-key"
export MODEL="gemini-2.5-flash"
export STORE_NAME="demo-file-store"

استبدِل your-api-key بمفتاح واجهة برمجة التطبيقات الفعلي. من المفترض أن يظهر الآن على النحو التالي:

الآن، تأكَّد من تحميل متغيرات البيئة. يمكنك إجراء ذلك من خلال تنفيذ الأمر التالي:

source .env

4. The Basic Agent

أولاً، لنحدّد خط الأساس. سنستخدم حزمة تطوير البرامج (SDK) google-genai الأولية لتشغيل وكيل بسيط.

الرمز

ألقِ نظرة على app/sdk_agent.py. وهي عملية تنفيذ بسيطة تتضمّن ما يلي:

تنشئ هذه السمة مثيلاً من genai.Client.
تفعّل هذه السياسة أداة "google_search".
انتهيت! لا يتوفّر التوليد المعزّز بالاسترجاع.

ألقِ نظرة على الرمز وتأكَّد من فهمك لوظيفته.

تشغيل التطبيق

# With make
make sdk-agent

# Without make
uv run python app/sdk_agent.py

لنطرح عليه سؤالاً عامًا:

> What is the stock price of Google?

يجب أن يجيب بشكل صحيح باستخدام "بحث Google" للعثور على السعر الحالي:

والآن، لنطرح سؤالاً لا يعرف كيفية الإجابة عنه. ويجب أن يكون الوكيل قد قرأ قصتنا.

> Who pilots the 'Too Many Pies' ship?

يجب أن يفشل أو حتى أن يقدّم إجابات من نسج الخيال. لنطّلع على ما يلي:

وكما هو متوقّع، لم يتمكّن النموذج من الإجابة عن السؤال. فهي لا تفهم ما نقوله!

الآن، اكتب quit للخروج من الوكيل.

5- شرح حول ميزة "البحث عن الملفات" في Gemini

تجمع ميزة "البحث عن الملفات" في Gemini بين عنصرَين أساسيَين:

نظام استرجاع مستندات من قاعدة بيانات خارجية (RAG) مُدار بالكامل: يمكنك تقديم مجموعة من الملفات، ويتولّى "بحث الملفات في Gemini" تقسيم الملفات وتضمينها وتخزينها وفهرسة المتجهات نيابةً عنك.
"أداة" بالمعنى الاصطلاحي للوكيل: يمكنك ببساطة إضافة أداة "بحث الملفات" في Gemini كأداة في تعريف الوكيل، وتوجيه الأداة إلى "متجر بحث الملفات".

لكن الأهم من ذلك هو أنّ هذه الميزة مضمّنة في Gemini API نفسه. وهذا يعني أنّك لست بحاجة إلى تفعيل أي واجهات برمجة تطبيقات إضافية أو نشر أي منتجات منفصلة لاستخدامها. لذا، فإنّها out-of-the-box.

ميزات "البحث عن الملفات" في Gemini

في ما يلي بعض ميزاته:

يتم إخفاء تفاصيل تقسيم المحتوى وتضمينه وتخزينه وفهرسته عنك كمطوّر. وهذا يعني أنّه ليس عليك معرفة (أو الاهتمام) بنموذج التضمين (وهو Gemini Embeddings، بالمناسبة)، أو مكان تخزين المتجهات الناتجة. لست بحاجة إلى اتخاذ أي قرارات بشأن قاعدة بيانات المتجهات.
وهو يتوافق مع عدد كبير من أنواع المستندات الجاهزة للاستخدام. بما في ذلك، على سبيل المثال لا الحصر: PDF وDOCX وExcel وSQL وJSON ودفاتر ملاحظات Jupyter وHTML وMarkdown وCSV وحتى ملفات zip. يمكنك الاطّلاع على القائمة الكاملة هنا. لذا، إذا أردت مثلاً أن يستند وكيلك إلى ملفات PDF تحتوي على نصوص وصور وجداول، لن تحتاج إلى إجراء أي معالجة مسبقة لملفات PDF هذه. ما عليك سوى تحميل ملفات PDF الأولية، وسيتولّى Gemini الباقي.
يمكننا إضافة بيانات وصفية مخصّصة إلى أي ملف يتم تحميله. يمكن أن يكون ذلك مفيدًا جدًا لتصفية الملفات التي نريد أن تستخدمها الأداة لاحقًا، وذلك في وقت التشغيل.

مكان تخزين البيانات

تحميل بعض الملفات أخذت "أداة البحث عن الملفات" من Gemini هذه الملفات، وأنشأت منها أجزاءً، ثم أنشأت منها تضمينات، ووضعتها... في مكان ما. ولكن أين؟

الحلّ هو متجر البحث عن الملفات. هذه حاوية مُدارة بالكامل لعمليات التضمين. لست بحاجة إلى معرفة (أو الاهتمام) بكيفية تنفيذ ذلك في الخلفية. كل ما عليك فعله هو إنشاء ملف واحد (برمجيًا) ثم تحميل ملفاتك إليه.

إنّه رخيص!

تخزين عمليات التضمين وطلبها مجاني. وبالتالي، يمكنك تخزين التضمينات للمدة التي تريدها بدون دفع أي رسوم مقابل ذلك.

في الواقع، الشيء الوحيد الذي تدفع مقابله هو إنشاء التضمينات عند التحميل/الفهرسة. في وقت كتابة هذا المقال، تبلغ تكلفة ذلك 0.15 دولار أمريكي لكل مليون رمز مميز. هذا رخيص جدًا.

6. كيف نستخدم ميزة "البحث عن الملفات" في Gemini؟

هناك مرحلتان:

إنشاء التضمينات وتخزينها في "مستودع البحث عن الملفات"
إرسال طلب بحث إلى "مستودع بحث الملفات" من وكيلك

المرحلة 1: استخدام Jupyter Notebook لإنشاء متجر بحث عن ملفات Gemini وإدارته

هذه المرحلة هي ما عليك تنفيذه في البداية، ثم كلما أردت تعديل المتجر. على سبيل المثال، عندما يكون لديك مستندات جديدة تريد إضافتها أو عندما تتغير المستندات المصدر.

هذه المرحلة ليست شيئًا عليك تضمينه في تطبيقك المستند إلى وكيل الذي تم نشره. بالتأكيد، يمكنك ذلك إذا أردت. على سبيل المثال، إذا كنت تريد إنشاء نوع من واجهة المستخدم للمشرفين على تطبيقك المستند إلى الوكلاء. ولكن غالبًا ما يكون من المناسب تمامًا أن يكون لديك جزء من الرمز البرمجي الذي تنفّذه عند الطلب. وما هي إحدى الطرق الرائعة لتشغيل هذا الرمز عند الطلب؟ دفتر ملاحظات Jupyter

The Notebook

افتح الملف notebooks/file_search_store.ipynb في المحرِّر. إذا طُلب منك تثبيت أي إضافات Jupyter VS Code، يُرجى المتابعة وتنفيذ ذلك.

إذا فتحناه في "محرِّر Cloud Shell"، سيظهر على النحو التالي:

لننفّذها خليةً خليةً. ابدأ بتنفيذ الخلية Setup مع عمليات الاستيراد المطلوبة. إذا لم يسبق لك تشغيل دفتر ملاحظات، سيُطلب منك تثبيت الإضافات المطلوبة. يمكنك إجراء ذلك. سيُطلب منك بعد ذلك اختيار نواة. انقر على "Python environments..." ثم على الحزمة المحلية .venv التي ثبّتناها عند تشغيل make install سابقًا:

بعد ذلك:

نفِّذ الخلية على الجهاز فقط لجلب متغيرات البيئة.
نفِّذ الخلية "إعداد العميل" لإعداد عميل الذكاء الاصطناعي التوليدي من Gemini.
نفِّذ الخلية "استرداد المتجر" باستخدام الدالة المساعدة لاسترداد "متجر البحث عن الملفات" في Gemini حسب الاسم.

الآن، نحن جاهزون لإنشاء المتجر.

نفِّذ خلية "إنشاء المتجر (مرة واحدة)" لإنشاء المتجر. يجب إجراء ذلك مرة واحدة فقط. إذا تم تشغيل الرمز بنجاح، من المفترض أن تظهر لك الرسالة "Created store: fileSearchStores/<someid>"
نفِّذ الخلية "عرض المتجر" للاطّلاع على محتوى المتجر. في هذه المرحلة، من المفترض أن تلاحظ أنّه يحتوي على 0 مستند.

رائع! لدينا الآن متجر "بحث الملفات" من Gemini جاهز للاستخدام.

تحميل البيانات

نريد تحميل data/story.md إلى المتجر. فعليك إجراء ما يلي:

نفِّذ الخلية التي تحدّد مسار التحميل. يشير ذلك إلى مجلد data/.
شغِّل الخلية التالية التي تنشئ دوال مساعدة لتحميل الملفات إلى المتجر. يُرجى العِلم أنّ الرمز البرمجي في هذه الخلية يستخدم أيضًا Gemini لاستخراج البيانات الوصفية من كل ملف تم تحميله. نأخذ هذه القيم المستخرَجة ونخزّنها كبيانات وصفية مخصّصة في المتجر. (ليس عليك إجراء ذلك، ولكنّه إجراء مفيد).
نفِّذ الخلية لتحميل الملف. يُرجى العِلم أنّه إذا سبق أن حمّلنا ملفًا بالاسم نفسه، سيحذف دفتر الملاحظات أولاً الإصدار الحالي قبل تحميل الإصدار الجديد. من المفترض أن تظهر لك رسالة تشير إلى أنّه تم تحميل الملف.

المرحلة 2: تنفيذ ميزة "البحث عن الملفات" المستندة إلى الاسترجاع والإنشاء (RAG) في Gemini في "الوكيل"

لقد أنشأنا متجر "بحث الملفات" من Gemini وحمّلنا قصتنا إليه. حان الوقت الآن لاستخدام أداة File Search Store في الوكيل. لننشئ وكيلاً جديدًا يستخدم "مخزن البحث عن الملفات" بدلاً من "بحث Google". ألقِ نظرة على app/sdk_rag_agent.py.

أول ما يجب ملاحظته هو أنّنا نفّذنا دالة لاسترداد متجرنا من خلال تمرير اسم المتجر:

def get_store(client: genai.Client, store_name: str) -> types.FileSearchStore | None:
    """Retrieve a store by display name"""
    try:
        for a_store in client.file_search_stores.list():
            if a_store.display_name == store_name:
                return a_store
    except Exception as e:
        logger.error(f"Error listing stores: {e}")
    return None

بعد إنشاء المتجر، يصبح استخدامه بسيطًا مثل إرفاقه كأداة بالوكيل، كما يلي:

   file_search_tool = types.Tool(file_search=types.FileSearch(file_search_store_names=[store.name]))

تشغيل وكيل التوليد المعزّز بالاسترجاع

نطلقها على النحو التالي:

make sdk-rag-agent

# Or, without make:
uv run python app/sdk_rag_agent.py

لنطرح السؤال الذي لم يتمكّن الموظف السابق من الإجابة عنه:

> Who pilots the 'Too Many Pies' ship?

وما هو الردّ؟

تم الإجراء بنجاح. يمكننا أن نرى من الردّ ما يلي:

تم استخدام مستودع الملفات للإجابة عن السؤال.
تم العثور على 5 أجزاء ذات صلة.
الإجابة صحيحة تمامًا.

اكتب quit لإغلاق الوكيل.

7. تحويل وكلائنا لاستخدام "حزمة تطوير التطبيقات"

حزمة تطوير الوكلاء (ADK) من Google هي حزمة تطوير برامج (SDK) وإطار عمل نمطي مفتوح المصدر يتيح للمطوّرين إنشاء وكلاء وأنظمة قائمة على الوكلاء. ويتيح لنا إنشاء أنظمة تستند إلى عدّة وكلاء وتنظيمها بسهولة. على الرغم من أنّ ADK محسّن للعمل مع Gemini ومنظومة Google المتكاملة، إلا أنّه لا يعتمد على نموذج معيّن ولا على طريقة نشر معيّنة، وهو مصمّم ليتوافق مع أُطر العمل الأخرى. إذا لم يسبق لك استخدام "حزمة تطوير التطبيقات لنظام Android"، يمكنك الانتقال إلى مستندات "حزمة تطوير التطبيقات لنظام Android" لمعرفة المزيد.

وكيل ADK الأساسي مع "بحث Google"

ألقِ نظرة على app/basic_agent_adk/agent.py. في نموذج الرمز البرمجي هذا، يمكنك ملاحظة أنّنا نفّذنا في الواقع وكيلَين:

root_agent يتعامل مع التفاعل مع المستخدم، وهو المكان الذي قدّمنا فيه تعليمات النظام الرئيسية.
SearchAgent منفصل يستخدم google.adk.tools.google_search كأداة

يستخدم root_agent في الواقع SearchAgent كأداة، ويتم تنفيذ ذلك باستخدام السطر التالي:

   tools=[AgentTool(agent=search_agent)],

يبدو طلب النظام الخاص بالوكيل الرئيسي على النحو التالي:

You are a helpful AI assistant designed to provide accurate and useful information.
If you don't know the answer, use the SearchAgent to perform a Google search.
Do not attempt to search more than ONCE.
If the search yields no relevant results or returns unrelated content, you MUST immediately respond with: "I could not find any information about that."
Do NOT retry the search with different terms. Do NOT ask for clarification. FAIL FAST.

تجربة "الوكيل"

توفر "حزمة تطوير التطبيقات" عددًا من الواجهات الجاهزة للاستخدام للسماح للمطوّرين باختبار وكلاء "حزمة تطوير التطبيقات". إحدى هذه الواجهات هي واجهة مستخدم الويب. يتيح لنا ذلك اختبار برامجنا في المتصفّح، بدون الحاجة إلى كتابة سطر واحد من رمز واجهة المستخدم.

يمكننا تشغيل هذه الواجهة من خلال تنفيذ ما يلي:

make adk-playground

# Or, without make:
uv run adk web app --port 8501 --reload_agents

يُرجى العِلم أنّ الأمر يوجّه أداة adk web إلى المجلد app، حيث ستعثر تلقائيًا على أيّ وكلاء ADK ينفّذون root_agent. لنجرّب ذلك:

بعد بضع ثوانٍ، يصبح التطبيق جاهزًا. إذا كنت تنفّذ الرمز برمجيًا على جهازك، ما عليك سوى توجيه المتصفح إلى http://127.0.0.1:8501. إذا كنت تستخدم Cloud Shell Editor، انقر على معاينة الويب، وغيِّر المنفذ إلى 8501:

عندما تظهر واجهة المستخدم، انقر على basic_agent_adk من القائمة المنسدلة، ثم يمكنك طرح أسئلة على الذكاء الاصطناعي:

كل الأمور جيدة حتى الآن تعرض واجهة المستخدم على الويب أيضًا الوقت الذي يفوّض فيه الوكيل الرئيسي SearchAgent. هذه ميزة مفيدة جدًا.

والآن، لنطرح عليه سؤالنا الذي يتطلّب معرفة قصتنا:

جرِّب هذه الميزة بنفسك. من المفترض أن تلاحظ أنّه يتعذّر تنفيذه بسرعة، تمامًا كما هو مطلوب.

دمج "مخزن البحث عن الملفات" في وكيل ADK

الآن، سنجمع كل ذلك معًا. سنشغّل وكيل ADK يمكنه استخدام كلّ من "متجر البحث عن الملفات" و"بحث Google". ألقِ نظرة على الرمز في app/rag_agent_adk/agent.py.

تشبه التعليمة البرمجية المثال السابق، ولكن مع بعض الاختلافات الأساسية:

لدينا وكيل رئيسي ينسّق عمل وكيلَين متخصصَين:
RagAgent: خبير المعرفة المخصّص - باستخدام "متجر البحث عن الملفات" في Gemini
SearchAgent: خبير المعرفة العامة - يستخدم "بحث Google"
بما أنّ حزمة ADK لا تتضمّن برنامج تضمين مدمجًا لـ FileSearch حتى الآن، نستخدم فئة برنامج تضمين مخصّصة FileSearchTool لتضمين أداة FileSearch، التي تُدرِج إعداد file_search_store_names في طلب النموذج المنخفض المستوى. تم تنفيذ ذلك في النص البرمجي المنفصل app/rag_agent_adk/tools_custom.py.

هناك أيضًا نقطة يجب الانتباه إليها. في وقت كتابة هذا المستند، لا يمكنك استخدام أداة GoogleSearch الأصلية وأداة FileSearch في الطلب نفسه إلى الوكيل نفسه. إذا حاولت ذلك، ستظهر لك رسالة خطأ على النحو التالي:

ERROR - حدث خطأ: 400 INVALID_ARGUMENT. {‎'error': {‎'code': 400, ‎'message': ‎'Search as a tool and file search tool are not supported together', ‎'status': ‎'INVALID_ARGUMENT'}}

الخطأ: 400 INVALID_ARGUMENT. {‎'error': {‎'code': 400, ‎'message': ‎'Search as a tool and file search tool are not supported together', ‎'status': ‎'INVALID_ARGUMENT'}}

الحلّ هو تنفيذ الوكيلَين المتخصّصَين كوكيلَين فرعيَين منفصلَين، وتمريرهما إلى الوكيل الرئيسي باستخدام نمط "الوكيل كأداة". والأهم من ذلك، أنّ تعليمات النظام الخاصة بالعامل الأساسي تقدّم إرشادات واضحة جدًا لاستخدام RagAgent أولاً:

أنت مساعد مستند إلى الذكاء الاصطناعي ومصمّم لتقديم معلومات دقيقة ومفيدة.

يمكنك التواصل مع وكيلَين متخصصَين:

‫RagAgent: للحصول على معلومات مخصّصة من قاعدة المعلومات الداخلية
‫SearchAgent: للحصول على معلومات عامة من "بحث Google"

جرِّب RagAgent دائمًا أولاً. إذا لم يؤدِّ ذلك إلى الحصول على إجابة مفيدة، جرِّب استخدام SearchAgent.

الاختبار النهائي

شغِّل واجهة مستخدم الويب الخاصة بـ ADK كما كان من قبل:

make adk-playground

# Or, without make:
uv run adk web app --port 8501 --reload_agents

في هذه المرة، اختَر rag_agent_adk في واجهة المستخدم. لنطّلِع على مثال عملي:

يمكننا أن نرى أنّها تختار الوكيل الفرعي المناسب استنادًا إلى السؤال.

8. الخاتمة

تهانينا على إكمال هذا الدرس التطبيقي حول الترميز.

لقد انتقلت من نص برمجي بسيط إلى نظام متعدّد الوكلاء مزوّد بإمكانية "التوليد المعزّز بالاسترجاع"، وكل ذلك بدون سطر واحد من رمز التضمين وبدون الحاجة إلى تنفيذ قاعدة بيانات متجهة.

لقد تبيّن لنا ما يلي:

Gemini File Search هو حلّ مُدار لعملية الاسترجاع المستند إلى البحث الدلالي (RAG) يوفّر الوقت ويحافظ على تركيزك.
تمنحنا مجموعة أدوات المطوّرين (ADK) البنية التي نحتاج إليها للتطبيقات المعقّدة التي تستخدم عدة وكلاء، وتوفّر للمطوّرين الراحة من خلال واجهات مثل واجهة مستخدم الويب.
يحلّ نمط "Agent-as-a-Tool" مشاكل توافق الأدوات.

نأمل أن تكون هذه التجربة العملية مفيدة لك. إلى اللقاء!