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

مستوى البرمجة: متقدّم
المدة: 30 دقيقة
نوع المشروع: دالة مخصّصة

نظرة عامة

دالة مخصّصة للتحقّق من صحة المعلومات في "جداول بيانات Google" يمكن استخدامها كمشروع مرتبط بتطبيق Apps Script يستند إلى وكيل Vertex AI ونموذج Gemini.

يوضّح هذا النموذج كيف يمكنك استخدام نوعَين فعّالَين من موارد الذكاء الاصطناعي مباشرةً في جداول بيانات Google:

1. وكلاء الذكاء الاصطناعي لإمكانات الاستدلال المعقّدة والمتعدّدة الخطوات والمتعدّدة الأدوات باستخدام وكلاء ADK الذين تم نشرهم في Vertex AI Agent Engine
2. نماذج الذكاء الاصطناعي لفهم المحتوى بشكل متقدّم وإنشاء المحتوى وتلخيصه باستخدام نماذج Gemini من Vertex AI

الأهداف

• فهم ما يفعله الحلّ
• فهم طريقة تنفيذ الحلّ
• فعِّل وكيل Vertex AI.
• إعداد النص البرمجي
• شغِّل النص البرمجي.

لمحة عن هذا الحل

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

• الاستخدام:
  • =FACT_CHECK("Your statement here") للحصول على ناتج موجز وملخّص.
  • =FACT_CHECK("Your statement here", "Your output formatting instructions here") لتنسيق إخراج محدّد.
• الاستدلال: LLM Auditor ADK AI Agent (نموذج Python)
• تنسيق الإخراج: نموذج Gemini

يطلب هذا الحلّ واجهات Vertex AI REST API باستخدام UrlFetchApp.

الهندسة المعمارية

يوضّح الرسم البياني التالي بنية موارد Google Workspace وGoogle Cloud التي تستخدمها الدالة المخصّصة.

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

لاستخدام هذا النموذج، يجب استيفاء المتطلبات الأساسية التالية:

• حساب Google (قد تتطلّب حسابات Google Workspace موافقة المشرف).

• متصفّح ويب يمكنه الوصول إلى الإنترنت

• المتطلبات الأساسية لوكيل LLM Auditor ADK

  • ‫Python 3.11 والإصدارات الأحدث: لتثبيت هذا الإصدار، اتّبِع التعليمات الواردة على موقع Python الإلكتروني الرسمي.
  • Python Poetry: لتثبيت هذه الأداة، اتّبِع التعليمات الواردة على موقع Poetry الإلكتروني الرسمي.
  • ‫Google Cloud CLI: للتثبيت، اتّبِع التعليمات الواردة على موقع Google Cloud الإلكتروني الرسمي.

إعداد البيئة

يوضّح هذا القسم كيفية إنشاء مشروع على Google Cloud وإعداده.

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

Google Cloud Console

1. في Google Cloud Console، انتقِل إلى "القائمة" > المشرف وإدارة الهوية وإمكانية الوصول > إنشاء مشروع.

   الانتقال إلى صفحة "إنشاء مشروع"

2. في حقل اسم المشروع، أدخِل اسمًا وصفيًا لمشروعك.

   اختياري: لتعديل رقم تعريف المشروع، انقر على تعديل. لا يمكن تغيير رقم تعريف المشروع بعد إنشائه، لذا اختَر رقم تعريف يلبي احتياجاتك طوال مدة المشروع.

3. في حقل الموقع الجغرافي، انقر على تصفّح لعرض المواقع الجغرافية المحتملة لمشروعك. بعد ذلك، انقر على اختيار.
   تنبيه: يتعذّر العثور على مؤسستك على Google Workspace؟
   هذا يعني أنّك لست مسجّلاً الدخول إلى حساب Google Workspace. لا تتوفّر بعض الميزات الموضّحة في مستندات مطوّري Google Workspace إلا للمشاريع المرتبطة بمؤسسة.
4. انقر على إنشاء. تنتقل وحدة تحكّم Google Cloud إلى صفحة "لوحة البيانات" ويتم إنشاء مشروعك في غضون بضع دقائق.

gcloud CLI

في إحدى بيئات التطوير التالية، يمكنك الوصول إلى واجهة سطر الأوامر (CLI) في Google Cloud (gcloud):

• Cloud Shell: لتفعيل Cloud Shell واستخدام وحدة طرفية على الإنترنت مع إعداد واجهة سطر الأوامر gcloud مسبقًا
  تفعيل Cloud Shell
• Local Shell: لاستخدام بيئة تطوير محلية، عليك تثبيت وإعداد gcloud CLI.
  لإنشاء مشروع على Google Cloud، استخدِم الأمر gcloud projects create:

  gcloud projects create PROJECT_ID

  استبدِل PROJECT_ID بضبط رقم تعريف المشروع الذي تريد إنشاءه.

تفعيل الفوترة لمشروع Cloud

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

Google Cloud Console

1. في Google Cloud Console، انتقِل إلى الفوترة. انقر على القائمة > الفوترة > مشاريعي.

   الانتقال إلى "الفوترة لمشاريعي"

2. في اختيار مؤسسة، اختَر المؤسسة المرتبطة بمشروعك على Google Cloud.
3. في صف المشروع، افتح قائمة الإجراءات ()، وانقر على تغيير الفوترة، ثم اختَر حساب Cloud Billing.
4. انقر على ضبط الحساب.

gcloud CLI

1. لعرض قائمة بحسابات الفوترة المتاحة، نفِّذ الأمر التالي:

   gcloud billing accounts list

2. ربط حساب فوترة بمشروع على Google Cloud:

   gcloud billing projects link PROJECT_ID --billing-account=BILLING_ACCOUNT_ID

   غيِّر القيم في السلسلة على الشكل التالي:

   • PROJECT_ID هو معرّف المشروع الخاص بالمشروع على السحابة الإلكترونية الذي تريد تفعيل الفوترة فيه.
   • ‫BILLING_ACCOUNT_ID هو معرّف حساب الفوترة الذي سيتم ربطه بمشروع Google Cloud.

تفعيل واجهة برمجة التطبيقات Vertex AI API

Google Cloud Console

1. في Google Cloud Console، فعِّل Vertex AI API.

   تفعيل واجهات برمجة التطبيقات

2. تأكَّد من أنّك بصدد تفعيل واجهة برمجة التطبيقات Vertex AI API في مشروع Cloud الصحيح، ثم انقر على التالي.

3. تأكَّد من تفعيل واجهة برمجة التطبيقات الصحيحة، ثم انقر على تفعيل.

gcloud CLI

1. إذا لزم الأمر، اضبط مشروع Cloud الحالي على المشروع الذي أنشأته باستخدام الأمر gcloud config set project:

   gcloud config set project PROJECT_ID

   استبدِل PROJECT_ID بمعرّف المشروع لمشروع Cloud الذي أنشأته.

2. فعِّل واجهة برمجة التطبيقات Vertex AI API باستخدام الأمر gcloud services enable:

   gcloud services enable aiplatform.googleapis.com

إنشاء حساب خدمة في Google Cloud Console

أنشِئ حساب خدمة جديدًا بالدور Vertex AI User باتّباع الخطوات التالية:

Google Cloud Console

1. في Google Cloud Console، انتقِل إلى "القائمة" > المشرف وإدارة الهوية وإمكانية الوصول > حسابات الخدمة.

   الانتقال إلى "حسابات الخدمة"

2. انقر على إنشاء حساب خدمة.
3. املأ تفاصيل حساب الخدمة، ثم انقر على إنشاء ومتابعة.
   ملاحظة: تنشئ Google تلقائيًا معرّفًا فريدًا لحساب الخدمة. إذا أردت تغيير المعرّف، عدِّله في حقل معرّف حساب الخدمة.
4. اختياري: يمكنك إسناد أدوار إلى حساب الخدمة لمنحه إذن الوصول إلى موارد مشروعك على Google Cloud. لمزيد من التفاصيل، يُرجى الرجوع إلى منح إذن الوصول إلى الموارد وتغييره وإبطاله.
5. انقر على متابعة.
6. اختياري: أدخِل المستخدمين أو المجموعات التي يمكنها إدارة حساب الخدمة هذا وتنفيذ إجراءات فيه. لمزيد من التفاصيل، يُرجى الاطّلاع على إدارة انتحال هوية حساب الخدمة.
7. انقر على تم. دوِّن عنوان البريد الإلكتروني لحساب الخدمة.

gcloud CLI

1. أنشئ حساب الخدمة:

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
     --display-name="SERVICE_ACCOUNT_NAME"

2. اختياري: يمكنك إسناد أدوار إلى حساب الخدمة لمنحه إذن الوصول إلى موارد مشروعك على Google Cloud. لمزيد من التفاصيل، يُرجى الرجوع إلى منح إذن الوصول إلى الموارد وتغييره وإبطاله.

يظهر حساب الخدمة في صفحة حساب الخدمة. بعد ذلك، أنشئ مفتاحًا خاصًا لحساب الخدمة.

إنشاء مفتاح خاص

تحذير: يستخدم هذا المثال مفتاح حساب خدمة تم تصديره لتسهيل العملية. لا يُنصح بتصدير مفتاح خاص في بيئة الإنتاج لأنّه لا يجب تخزينه في مكان غير آمن، مثل نظام التحكّم بالمصادر.

لمزيد من المعلومات حول عمليات التنفيذ الآمنة لحسابات الخدمة وأفضل الممارسات، يُرجى الاطّلاع على اختيار الوقت المناسب لاستخدام حسابات الخدمة.

لإنشاء مفتاح خاص لحساب الخدمة وتنزيله، اتّبِع الخطوات التالية:

1. في Google Cloud Console، انتقِل إلى "القائمة" > المشرف وإدارة الهوية وإمكانية الوصول > حسابات الخدمة.

   الانتقال إلى "حسابات الخدمة"

2. اختَر حساب الخدمة.
3. انقر على المفاتيح > إضافة مفتاح > إنشاء مفتاح جديد.
4. اختَر JSON، ثمّ انقر على إنشاء.

   يتم إنشاء زوج المفتاح العام/الخاص وتنزيله على جهازك كملف جديد. احفظ ملف JSON الذي تم تنزيله باسم credentials.json في دليل العمل. هذا الملف هو النسخة الوحيدة من هذا المفتاح. للحصول على معلومات عن طريقة التخزين الآمن للمفتاح، راجِع إدارة مفاتيح حساب الخدمة.

5. انقر على إغلاق (Close).

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

نشر وكيل الذكاء الاصطناعي الخاص بأداة LLM Auditor ADK

1. إذا لم يسبق لك إجراء ذلك، عليك إثبات ملكية حسابك على Google Cloud وإعداد Google Cloud CLI لاستخدام مشروعك على Google Cloud.

   gcloud auth application-default login
   gcloud config set project PROJECT_ID
   gcloud auth application-default set-quota-project PROJECT_ID

   استبدِل PROJECT_ID بمعرّف مشروع Cloud الذي أنشأته.

2. تنزيل مستودع GitHub هذا

   تنزيل

3. في بيئة التطوير المحلية المفضّلة لديك، استخرِج ملف الأرشيف الذي تم تنزيله وافتح الدليل adk-samples/python/agents/llm-auditor.

   unzip adk-samples-main.zip
   cd adk-samples-main/python/agents/llm-auditor

4. أنشئ حزمة جديدة في Cloud Storage مخصّصة لعامل ADK.

   gcloud storage buckets create gs://CLOUD_STORAGE_BUCKET_NAME --project=PROJECT_ID --location=PROJECT_LOCATION

   غيِّر القيم في السلسلة على الشكل التالي:

   1. استبدِل CLOUD_STORAGE_BUCKET_NAME باسم حزمة فريد تريد استخدامه.
   2. PROJECT_ID مع رقم تعريف مشروع السحابة الإلكترونية الذي أنشأته.
   3. استبدِل PROJECT_LOCATION بموقع مشروع Cloud الذي أنشأته.

5. اضبط متغيرات البيئة التالية:

   export GOOGLE_GENAI_USE_VERTEXAI=true
   export GOOGLE_CLOUD_PROJECT=PROJECT_ID
   export GOOGLE_CLOUD_LOCATION=PROJECT_LOCATION
   export GOOGLE_CLOUD_STORAGE_BUCKET=CLOUD_STORAGE_BUCKET_NAME

   غيِّر القيم في السلسلة على الشكل التالي:

   1. استبدِل CLOUD_STORAGE_BUCKET_NAME باسم الحزمة التي أنشأتها.
   2. PROJECT_ID مع رقم تعريف مشروع السحابة الإلكترونية الذي أنشأته.
   3. استبدِل PROJECT_LOCATION بموقع مشروع Cloud الذي أنشأته.

6. تثبيت وكيل ADK ونشره من بيئة افتراضية

   python3 -m venv myenv
   source myenv/bin/activate
   poetry install --with deployment
   python3 deployment/deploy.py --create

7. استرداد رقم تعريف الوكيل، ستحتاج إليه لاحقًا لإعداد الدالة المخصّصة

   python3 deployment/deploy.py --list

مراجعة نموذج الرمز البرمجي

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

عرض على GitHub

إنشاء وإعداد جدول بيانات جديد

1. انقر على الزر التالي لإنشاء نسخة كاملة من نموذج جدول بيانات Google Sheets، بما في ذلك مشروع نص برمجي في Apps Script مرتبط بالحاوية.

   نسخ جدول بيانات Google

2. في جدول البيانات الذي تم إنشاؤه حديثًا، انتقِل إلى الإضافات > برمجة تطبيقات Google.

3. في مشروع Apps Script، انتقِل إلى إعدادات المشروع، وانقر على تعديل خصائص البرنامج النصي، ثم انقر على إضافة خاصية برنامج نصي لإضافة خصائص البرنامج النصي التالية:

   1. استبدِل LOCATION بموقع مشروع Google Cloud الذي تم إنشاؤه في الخطوات السابقة، مثل us-central1.
   2. GEMINI_MODEL_ID مع نموذج Gemini الذي تريد استخدامه، مثل gemini-2.5-flash-lite
   3. استبدِل REASONING_ENGINE_ID برقم تعريف وكيل LLM Auditor ADK الذي تم نشره في الخطوات السابقة، مثل 1234567890.
   4. استبدِل SERVICE_ACCOUNT_KEY بمفتاح JSON من حساب الخدمة الذي تم تنزيله في الخطوات السابقة، مثل { ... }.

4. انقر على حفظ مواقع النص البرمجي.

اختبار الدالة المخصّصة

1. انتقِل إلى جدول البيانات الذي تم إنشاؤه حديثًا.
2. تغيير العبارات في العمود A
3. يتم تنفيذ الصيغ في العمود B ثم عرض نتائج التحقّق من صحة الأخبار.

تَنظيم

لتجنُّب تحمّل رسوم في حسابك على Google Cloud مقابل الموارد المستخدَمة في هذا البرنامج التعليمي، ننصحك بحذف مشروع Cloud.

تنبيه: يؤدي حذف مشروع إلى ما يلي:

• يتم حذف كل المحتوى في المشروع. إذا كنت قد استخدمت مشروعًا حاليًا لهذا البرنامج التعليمي، سيؤدي حذفه إلى حذف أي عمل آخر أنجزته في المشروع.
• فقدان أرقام تعريف المشاريع المخصّصة: عند إنشاء هذا المشروع، ربما أنشأت معرّف مشروع مخصّصًا تريد استخدامه في المستقبل. للحفاظ على عناوين URL التي تستخدم رقم تعريف المشروع، مثل عنوان URL على appspot.com، احذف الموارد المحدّدة داخل المشروع بدلاً من حذف المشروع بأكمله.

إذا كنت تخطّط لاستكشاف العديد من البرامج التعليمية وأدلة البدء السريع، يمكن أن يساعدك إعادة استخدام المشاريع في تجنُّب تجاوز حدود حصة المشاريع.

1. في Google Cloud Console، انتقِل إلى صفحة إدارة الموارد. انقر على القائمة > إدارة الهوية وإمكانية الوصول والمشرف > إدارة الموارد.

   الانتقال إلى "إدارة الموارد"

2. في قائمة المشاريع، اختَر المشروع الذي تريد حذفه، ثم انقر على حذف .
3. في مربّع الحوار، اكتب رقم تعريف المشروع، ثم انقر على إيقاف لحذف المشروع.

الخطوات التالية

• الدوال المخصّصة في "جداول بيانات Google"
• توسيع نطاق "جداول بيانات Google"