تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

إنشاء منشئ اختبارات باستخدام الذكاء الاصطناعي التوليدي وCloud Run

1. مقدمة

في هذا الدرس التطبيقي، ستُنشئ خدمة ويب لإنشاء اختبارات معلومات عامة ودمجها في تطبيق ممتع وفعّال. ستستخدم لغة برمجة مختلفة عن اللغة التي استخدمتها من قبل: اللغة الإنجليزية.

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

ستُنشئ طلبًا يُنشئ اختبار معلومات عامة وفقًا لمجموعة من المعايير.
ستنشئ تطبيق ويب بسيطًا وتتأكّد من أنّه يعمل على النحو المتوقّع في بيئة التطوير.
سيكون عليك إضافة منطق إلى تطبيق الويب بشكل تدريجي لتحويله إلى خادم واجهة برمجة تطبيقات ينشئ الاختبارات وفقًا لمجموعة من مَعلمات الإدخال.
سترى مدى سهولة نشر خدمة إنشاء الاختبارات على السحابة الإلكترونية باستخدام Google Cloud Run.
أخيرًا، ستقوم بتهيئة تطبيق حقيقي ( quizaic.com) لاستخدام خدمة إنشاء الاختبارات التي تم نشرها وستتمكن من تشغيل اختبارات مباشرة بناءً على النتيجة.

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

كيفية إنشاء طلب مستند إلى نموذج لنموذج لغوي كبير (LLM)
كيفية إنشاء تطبيق خادم ويب بسيط بلغة Python
كيفية إضافة ميزة "التعلم الآلي على مستوى اللغة" من Google إلى تطبيق الويب
كيفية نشر تطبيقك على السحابة الإلكترونية ليتمكّن أي مستخدم من تجربة تطبيقك الجديد
كيفية دمج أداة إنشاء الاختبارات في تطبيق أكبر

المتطلبات

متصفّح الويب Chrome
حساب Google
مشروع على Cloud تم تفعيل الفوترة فيه

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

2. ضبط إعدادات الجهاز

يتناول هذا القسم كل ما عليك فعله للبدء في هذا الدرس التطبيقي.

إعداد بيئة ذاتية

سجِّل الدخول إلى Google Cloud Console وأنشئ مشروعًا جديدًا أو أعِد استخدام مشروع حالي. إذا لم يكن لديك حساب على Gmail أو Google Workspace، عليك إنشاء حساب.

اسم المشروع هو الاسم المعروض للمشاركين في هذا المشروع. وهي سلسلة أحرف لا تستخدمها واجهات برمجة تطبيقات Google. ويمكنك تعديلها في أي وقت.
يكون رقم تعريف المشروع فريدًا في جميع مشاريع Google Cloud وغير قابل للتغيير (لا يمكن تغييره بعد تحديده). تنشئ Cloud Console سلسلة فريدة تلقائيًا، لذا لا تهمّك عادةً. في معظم الدروس التطبيقية حول الترميز، يجب الرجوع إلى رقم تعريف المشروع (الذي يتم تحديده عادةً على أنّه PROJECT_ID). وإذا لم يعجبك رقم التعريف الذي تم إنشاؤه، يمكنك إنشاء رقم تعريف عشوائي آخر. يمكنك بدلاً من ذلك تجربة عنوانك الخاص لمعرفة ما إذا كان متاحًا. ولا يمكن تغييره بعد هذه الخطوة ويبقى ساريًا طوال مدة المشروع.
لمعلوماتك، هناك قيمة ثالثة، وهي رقم المشروع، الذي تستخدمه بعض واجهات برمجة التطبيقات. اطّلِع على مزيد من المعلومات حول هذه القيم الثلاث في المستندات.

بعد ذلك، عليك تفعيل الفوترة في Cloud Console لاستخدام الموارد/واجهات برمجة التطبيقات في Cloud. لن يؤدي إكمال هذا الدرس التطبيقي حول الترميز إلى فرض أي تكاليف، إن وُجدت. لإيقاف الموارد لتجنُّب تحصيل رسوم بعد انتهاء هذا الدليل التعليمي، يمكنك حذف الموارد التي أنشأتها أو حذف المشروع. المستخدمون الجدد في Google Cloud مؤهّلون للاستفادة من برنامج الفترة التجريبية المجانية التي تبلغ قيمتها 300 دولار أمريكي.

ابدأ Cloud Shell.

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

تفعيل Cloud Shell

من Cloud Console، انقر على تفعيل Cloud Shell .

إذا كانت هذه هي المرة الأولى التي تبدأ فيها Cloud Shell، ستظهر لك شاشة وسيطة توضّح ماهيتها. إذا ظهرت لك شاشة وسيطة، انقر على متابعة.

من المفترَض أن تستغرق عملية إدارة الحسابات والاتصال بخدمة Cloud Shell بضع دقائق فقط.

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

بعد الاتصال بـ Cloud Shell، من المفترض أن تظهر لك رسالة تفيد بأنّه تم مصادقة حسابك وأنّه تم ضبط المشروع على معرّف مشروعك.

نفِّذ الأمر التالي في Cloud Shell لتأكيد مصادقة حسابك:

gcloud auth list

ناتج الأمر

 Credentialed Accounts
ACTIVE  ACCOUNT
*       <my_account>@<my_domain.com>

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

شغّل الأمر التالي في Cloud Shell للتأكد من معرفة الأمر gcloud بمشروعك:

gcloud config list project

مخرجات الأمر

[core]
project = <PROJECT_ID>

إذا لم يكن كذلك، يمكنك تعيينه من خلال هذا الأمر:

gcloud config set project <PROJECT_ID>

ناتج الأمر

Updated property [core/project].

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

في الخطوات اللاحقة، سترى الأماكن التي تكون فيها هذه الخدمات مطلوبة (والأسباب)، ولكن في الوقت الحالي، يمكنك تنفيذ هذا الأمر لمنح مشروعك إذن الوصول إلى Cloud Build وArtifact Registry وVertex AI وCloud Run:

gcloud services enable cloudbuild.googleapis.com        \
                       artifactregistry.googleapis.com  \
                       aiplatform.googleapis.com        \
                       run.googleapis.com

من المفترض أن تؤدي هذه الخطوة إلى ظهور رسالة تفيد بنجاح العملية على النحو التالي:

Operation "operations/acf.cc11852d-40af-47ad-9d59-477a12847c9e" finished successfully.

3- طلب المعلومات - البرمجة بلغة طبيعية

سنبدأ بتعلم كيفية تطوير طلب لنموذج لغوي كبير. انتقِل إلى Google Cloud Console > Vertex AI > Vertex AI Studio (اللغة). من المفترض أن تظهر لك صفحة بالشكل التالي:

ضمن Generate Text، انقر على الزر Text Prompt. في مربّع الحوار التالي، أدخِل طلبًا تعتقد أنّه قد يكون فعّالاً لإنشاء اختبار معلومات عامة وفقًا للمتطلبات التالية:

الموضوع: تاريخ العالم
عدد الأسئلة: 5
مستوى الصعوبة: متوسط
اللغة: الإنجليزية

انقر على الزر "إرسال" للاطّلاع على النتيجة.

كما هو موضّح في لقطة الشاشة التالية، تتيح لك اللوحة اليمنى اختيار النموذج الذي تريد استخدامه وضبط بعض الإعدادات:

تتوفر الإعدادات التالية:

المنطقة هي المكان الذي يجب أن يتم فيه تنفيذ طلب إنشاء المحتوى.
يختار النموذج النموذج اللغوي الكبير الذي تريد استخدامه. في هذا الدليل التعليمي حول الرموز البرمجية، استخدِم الإصدار "gemini-1.0-pro-001".
يتحكّم خيار "درجة الحرارة" في درجة العشوائية عند اختيار الرمز المميّز. تكون درجات الحرارة المنخفضة مناسبة للطلبات التي تتوقّع الحصول على ردّ صحيح أو صحيح، في حين يمكن أن تؤدي درجات الحرارة المرتفعة إلى نتائج أكثر تنوعًا أو غير متوقّعة.
يحدِّد الحدّ الأقصى للرموز المميّزة الحدّ الأقصى للكمية التي يمكن أن يتم عرضها من طلب واحد. يتكون الرمز المميّز من أربعة أحرف تقريبًا. القيمة التلقائية هي 1024.
يغيّر Top-k طريقة اختيار النموذج للرموز لعرضها. إذا كان عدد العناصر في أعلى مجموعة هو 1، يعني ذلك أنّ العنصر المحدّد هو الأكثر احتمالًا من بين جميع العناصر في مفردات النموذج (يُعرف ذلك أيضًا باسم الترميز الجشع)، في حين أنّ عدد العناصر في أعلى مجموعة هو 3 يعني أنّ العنصر التالي يتم اختياره من بين العناصر الثلاثة الأكثر احتمالًا (باستخدام درجة الحرارة). القيمة التلقائية لعدد أهمّ k منتج هي 40.
يغيّر الجزء العلوي p طريقة اختيار النموذج للرموز المميّزة للمخرجات. يتم اختيار الرموز من الأكثر احتمالًا إلى الأقل إلى أن يصبح مجموع احتمالاتها مساويًا لقيمة top-p.
الحد الأقصى لعدد الردود هو الحد الأقصى لعدد الردود المستندة إلى النماذج التي يتم إنشاؤها لكل طلب.
تسلسل الإيقاف هو سلسلة من الأحرف (بما في ذلك المسافات) التي تتوقف عن إنشاء الردود إذا صادفها النموذج.
يحدد البث المباشر الردود ما إذا كان يجب طباعة الردود عند إنشائها أو حفظها، ويتم عرضها عند اكتمالها.
يضبط حدّ الأمان من الفلتر مدى احتمالية ظهور ردود قد تكون ضارة.

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

يتم التعبير عن الاختبارات في هذا المختبر على أنّها مصفوفة من العناصر، حيث يحتوي كل عنصر على سؤال، وعلى مصفوفة من الردود المحتملة لهذا السؤال، وعلى إجابة صحيحة. في ما يلي ترميز JSON للاختبارات في هذا الاختبار:

[
    {
        "question": "Who was the first person to walk on the moon?",
          "responses": [
              "Neil Armstrong",
              "Buzz Aldrin",
              "Michael Collins",
              "Yuri Gagarin"
           ],
           "correct": "Neil Armstrong"
    },
    {
        "question": "What was the name of the war that took place between the British and the French in North America from 1754 to 1763??",
          "responses": [
              "The French and Indian War",
              "The Seven Years' War",
              "The War of the Austrian Succession",
              "The Great War"
           ],
           "correct": "The French and Indian War"
    },

    ...
]

تحقَّق ممّا إذا كان بإمكانك تعديل الطلب لإخراج الاختبار الآن بتنسيق JSON المطلوب.

حدِّد التنسيق الدقيق الذي تبحث عنه بالكلمات (مثلاً الجملة المائلة أعلاه).
أدرِج في طلبك مثالاً على تنسيق JSON المطلوب.

بعد أن يصبح لديك طلب لإنشاء الاختبارات وفقًا للمواصفات المطلوبة، انقر على الزر GET CODE في أعلى يسار الصفحة للاطّلاع على رمز لغة Python الذي يمكنك استخدامه لإرسال طلبك آليًا إلى Vertex AI LLM. إذا كنت مهتمًا باستخدام لغة برمجة أخرى غير Python، يمكنك الاطّلاع على https://cloud.google.com/vertex-ai/docs/samples?text=generative.

4. إنشاء خادم ويب بسيط

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

ابدأ بالنقر على الزر Open Editor في أعلى لوحة Cloud Shell. يظهر الإجراء على النحو التالي:

ستنتقل بعد ذلك إلى بيئة تطوير متكاملة مشابهة لـ Visual Studio Code، حيث يمكنك إنشاء المشاريع وتعديل الرمز المصدر وتشغيل برامجك وما إلى ذلك.

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

يمكنك التبديل بين "المحرِّر" و"وحدة التحكّم في المحطة الطرفية" من خلال النقر على الزرَّين Open Editor وOpen Terminal على التوالي. جرِّب التبديل بين هاتين البيئتَين الآن.

بعد ذلك، أنشئ مجلدًا لتخزين عملك في هذا المختبر، وذلك بالنقر على زر إضافة مجلد وإدخال quiz-generator والضغط على مفتاح Enter. سيتم إنشاء جميع الملفات في هذا المجلد وتنفيذ جميع الأعمال في Cloud Shell.

أنشئ الآن ملفًا بتنسيق requirements.txt. يُعلم هذا الإجراء بايثون بالمكتبات التي يعتمد عليها تطبيقك. في تطبيق الويب البسيط هذا، ستستخدم وحدة Python شائعة لإنشاء خوادم ويب تُسمى Flask, مكتبة برامج google-cloud-aiplatform، وإطار عمل لخادم الويب يُسمى gunicorn. في لوحة التنقّل في الملفات، انقر بزر الماوس الأيمن على مجلد quiz-generator واختَر عنصر القائمة New file، على النحو التالي:

عندما يُطلب منك إدخال اسم الملف الجديد، أدخِل requirements.txt واضغط على مفتاح Enter. تأكَّد من أنّ الملف الجديد ينتهي به المطاف في مجلد مشروع quiz-generator.

الصِق السطور التالية في الملف الجديد لتحديد أنّ تطبيقك يعتمد على حزمة flask في Python وخادم الويب gunicorn ومكتبة العميل google-cloud-aiplatform، بالإضافة إلى الإصدارات المرتبطة بكل منها.

flask==3.0.0
gunicorn==21.2.0
google-cloud-aiplatform==1.47.0

لست بحاجة إلى حفظ هذا الملف صراحةً لأنّ "محرر السحابة الإلكترونية" سيحفظ التغييرات تلقائيًا نيابةً عنك.

باستخدام الأسلوب نفسه، أنشئ ملفًا جديدًا آخر باسم main.py. سيكون هذا هو ملف المصدر الرئيسي (والوحيد) لتطبيقك بتنسيق Python. يُرجى التأكّد مرة أخرى من أنّ الملف الجديد قد تم نقله إلى مجلد quiz-generator.

أدخِل الرمز التالي في هذا الملف:

from flask import Flask
import os

app = Flask(__name__)  # Create a Flask object.
PORT = os.environ.get("PORT")  # Get PORT setting from environment.
if not PORT:
    PORT = 8080

# The app.route decorator routes any GET requests sent to the root path
# to this function, which responds with a "Hello world!" HTML document.
@app.route("/", methods=["GET"])
def say_hello():
    html = "<h1>Hello world!</h1>"
    return html

# This code ensures that your Flask app is started and listens for
# incoming connections on the local interface and port 8080.
if __name__ == "__main__":
    app.run(host="0.0.0.0", port=PORT)

عُد مرة أخرى إلى الوحدة الطرفية ثم انتقِل إلى مجلد المشروع باستخدام الأمر التالي:

cd quiz-generator

شغِّل الأمر التالي لتثبيت التبعيات في مشروعك:

pip3 install -r requirements.txt

بعد تثبيت التبعيات، من المفترض أن يظهر لك ناتج ينتهي على النحو التالي:

Successfully installed flask-3.0.0

الآن، يمكنك تشغيل تطبيقك من خلال تنفيذ هذا الأمر في الوحدة الطرفية:

flask --app main.py --debug run --port 8080

في هذه المرحلة، يتم تشغيل تطبيقك على الجهاز الافتراضي المخصّص لجلسة Cloud Shell. تتضمّن Cloud Shell آلية وكيل تتيح لك الوصول إلى خوادم الويب (مثل الخادم الذي بدأته للتو) التي تعمل على جهازك الافتراضي من أي مكان على الإنترنت العالمي.

انقر على الزر web preview ثم على عنصر القائمة Preview on Port 8080 على النحو التالي:

سيؤدي ذلك إلى فتح علامة تبويب في متصفّح الويب للانتقال إلى تطبيقك الذي يعمل، ومن المفترض أن يظهر على النحو التالي:

5- إضافة طريقة إنشاء باستخدام تحليل المَعلمات

نريد الآن توفير إمكانية إدخال طريقة جديدة تُسمى generate. ويمكنك إجراء ذلك من خلال إضافة عبارة استيراد لمعالجة طلب HTTP وتعديل المسار الرئيسي لتحليل هذا الطلب وطباعة المعلمات، كما يلي:

from flask import Flask
from flask import request                       #<-CHANGED
import os

app = Flask(__name__)  # Create a Flask object.
PORT = os.environ.get("PORT")  # Get PORT setting from environment.
if not PORT:
    PORT = 8080

# The app.route decorator routes any GET requests sent to the /generate
# path to this function, which responds with "Generating:" followed by
# the body of the request.
@app.route("/", methods=["GET"])                #<-CHANGED
def generate():                                 #<-CHANGED
    params = request.args.to_dict()             #<-CHANGED
    html = f"<h1>Quiz Generator</h1>"           #<-CHANGED
    for param in params:                        #<-CHANGED
        html += f"<br>{param}={params[param]}"  #<-CHANGED
    return html                                 #<-CHANGED

# This code ensures that your Flask app is started and listens for
# incoming connections on the local interface and port 8080.
if __name__ == "__main__":
    app.run(host="0.0.0.0", port=PORT)

يمكنك الآن إعادة تحميل علامة تبويب متصفّح الويب للاطّلاع على النتائج. من المفترض أن يظهر لك هذه المرة "أداة إنشاء الاختبارات"، بالإضافة إلى مَعلمة طلب بحث تمت إضافتها تلقائيًا إلى عنوان URL (authuser). جرِّب إضافة مَعلمتَين إضافيتَين من خلال إلحاق السلسلة "`&param1=val1&param2=val2`" بنهاية عنوان URL في شريط عناوين المتصفّح، وأعِد تحميل الصفحة، ومن المفترض أن يظهر لك ما يلي:

بعد أن اطّلعنا على كيفية إرسال مَعلمات طلب البحث وتحليلها في عنوان URL، سنضيف إمكانية استخدام المَعلمات المحدّدة التي سنريد إرسالها إلى أداة إنشاء الاختبارات، وهي كما يلي:

topic - موضوع الاختبار المطلوب
num_q - عدد الأسئلة المطلوبة
diff - مستوى الصعوبة المطلوب (سهل أو متوسط أو صعب)
lang - لغة الاختبار المطلوبة

from flask import Flask
from flask import request
import os

# Default quiz settings  #<-CHANGED
TOPIC = "History"        #<-CHANGED
NUM_Q = "5"              #<-CHANGED
DIFF = "intermediate"    #<-CHANGED
LANG = "English"         #<-CHANGED

app = Flask(__name__)  # Create a Flask object.
PORT = os.environ.get("PORT")  # Get PORT setting from environment.
if not PORT:
    PORT = 8080

# This function takes a dictionary, a name, and a default value.
# If the name exists as a key in the dictionary, the corresponding
# value is returned. Otherwise, the default value is returned.
def check(args, name, default):  #<-CHANGED
    if name in args:             #<-CHANGED
        return args[name]        #<-CHANGED
    return default               #<-CHANGED

# The app.route decorator routes any GET requests sent to the /generate
# path to this function, which responds with "Generating:" followed by
# the body of the request.
@app.route("/", methods=["GET"])
# This function generates a quiz using Vertex AI.
def generate():
    args = request.args.to_dict()        #<-CHANGED
    topic = check(args, "topic", TOPIC)  #<-CHANGED
    num_q = check(args, "num_q", NUM_Q)  #<-CHANGED
    diff = check(args, "diff", DIFF)     #<-CHANGED
    lang = check(args, "lang", LANG)     #<-CHANGED
    html = f"""
        <h1>Quiz Generator</h1><br>
        {topic=}<br>
        {num_q=}<br>
        {diff=}<br>
        {lang=}"""                       #<-CHANGED
    return html

# This code ensures that your Flask app is started and listens for
# incoming connections on the local interface and port 8080.
if __name__ == "__main__":
    app.run(host="0.0.0.0", port=PORT)

أعِد الآن تحميل علامة التبويب الحالية لمتصفّح الويب للاطّلاع على النتائج. من المفترض أن تظهر لك صفحة ويب مشابهة لما يلي:

جرِّب تغيير عنوان URL لضبط قيم للمَعلمات المختلفة. على سبيل المثال، حاوِل استخدام اللاحقة "?authuser=0&topic=Literature&num_q=10&diff=easy&lang=French" في نهاية عنوان URL في شريط العناوين:

6- إضافة طلبك وتنسيقه

بعد ذلك، سنضيف إمكانية استخدام المَعلمات المحدّدة التي سنريد إرسالها إلى أداة إنشاء الاختبارات، وهي كما يلي:

topic - موضوع الاختبار المطلوب
num_q - عدد الأسئلة المطلوبة
diff - مستوى الصعوبة المطلوب (سهل أو متوسط أو صعب)
lang - لغة الاختبار المطلوبة

انسخ الطلب الذي أنشأته باستخدام Vertex Generative AI Studio في خطوة سابقة، ولكن غيِّر القيم الثابتة للموضوع وعدد الأسئلة ومستوى الصعوبة باستخدام السلاسل التالية:

{topic}
{num_q}
{diff}
{lang}

from flask import Flask
from flask import request
import os

# Default quiz settings
TOPIC = "History"
NUM_Q = 5
DIFF = "intermediate"
LANG = "English"

PROMPT = """
Generate a quiz according to the following specifications:

- topic: {topic}
- num_q: {num_q}
- diff:  {diff}
- lang:  {lang}

Output should be (only) an unquoted json array of objects with keys:
"Question", "responses", and "correct".

"""  #<-CHANGED

app = Flask(__name__)  # Create a Flask object.
PORT = os.environ.get("PORT")  # Get PORT setting from environment.
if not PORT:
    PORT = 8080

# This function takes a dictionary, a name, and a default value.
# If the name exists as a key in the dictionary, the corresponding
# value is returned. Otherwise, the default value is returned.
def check(args, name, default):
    if name in args:
        return args[name]
    return default

# The app.route decorator routes any GET requests sent to the /generate
# path to this function, which responds with "Generating:" followed by
# the body of the request.
@app.route("/", methods=["GET"])
# This function generates a quiz using Vertex AI.
def generate():
    args = request.args.to_dict()
    topic = check(args, "topic", TOPIC)
    num_q = check(args, "num_q", NUM_Q)
    diff = check(args, "diff", DIFF)
    lang = check(args, "lang", LANG)
    prompt = PROMPT.format(topic=topic, num_q=num_q, diff=diff, lang=lang)  #<-CHANGED 
    html = f"<h1>Prompt:</h1><br><pre>{prompt}</pre>"                       #<-CHANGED
    return html

# This code ensures that your Flask app is started and listens for
# incoming connections on the local interface and port 8080.
if __name__ == "__main__":
    app.run(host="0.0.0.0", port=PORT)

حاوِل تعديل عنوان URL لتغيير المَعلمات الأربعة.

7- إضافة مكتبة تطبيقات Vertex AI

أصبحنا الآن جاهزين لاستخدام مكتبة برامج Python لواجهة برمجة التطبيقات Vertex AI لإنشاء الاختبار. سيؤدي ذلك إلى التشغيل الآلي للطلب التفاعلي الذي أجريته في الخطوة 3 ومنح خدمة إنشاء المحتوى إمكانية الوصول الآلي إلى إمكانات نموذج اللغة الكبيرة من Google. عدِّل ملف main.py على النحو التالي:

تأكَّد من استبدال "YOUR_PROJECT" برقم تعريف مشروعك الفعلي.

from flask import Flask
from flask import request
from flask import Response                                          #<-CHANGED
import os

import vertexai    
from vertexai.generative_models import GenerativeModel  #<-CHANGED

# Default quiz settings
TOPIC = "History"
NUM_Q = 5
DIFF = "intermediate"
LANG = "English"
MODEL = "gemini-1.0-pro"  #<-CHANGED

PROMPT = """
Generate a quiz according to the following specifications:

- topic: {topic}
- num_q: {num_q}
- diff:  {diff}
- lang:  {lang}

Output should be (only) an unquoted json array of objects with keys "question", "responses", and "correct".

"""

app = Flask(__name__)  # Create a Flask object.
PORT = os.environ.get("PORT")  # Get PORT setting from environment.
if not PORT:
    PORT = 8080

# Initialize Vertex AI access.
vertexai.init(project="YOUR_PROJECT", location="us-central1")  #<-CHANGED
parameters = {                                                 #<-CHANGED
    "candidate_count": 1,                                      #<-CHANGED
    "max_output_tokens": 1024,                                 #<-CHANGED
    "temperature": 0.5,                                        #<-CHANGED
    "top_p": 0.8,                                              #<-CHANGED
    "top_k": 40,                                               #<-CHANGED
}                                                              #<-CHANGED
model = GenerativeModel(MODEL)             #<-CHANGED

# This function takes a dictionary, a name, and a default value.
# If the name exists as a key in the dictionary, the corresponding
# value is returned. Otherwise, the default value is returned.
def check(args, name, default):
    if name in args:
        return args[name]
    return default

# The app.route decorator routes any GET requests sent to the /generate
# path to this function, which responds with "Generating:" followed by
# the body of the request.
@app.route("/", methods=["GET"])
# This function generates a quiz using Vertex AI.
def generate():
    args = request.args.to_dict()
    topic = check(args, "topic", TOPIC)
    num_q = check(args, "num_q", NUM_Q)
    diff = check(args, "diff", DIFF)
    lang = check(args, "lang", LANG)
    prompt = PROMPT.format(topic=topic, num_q=num_q, diff=diff, lang=lang)
    response = model.generate_content(prompt, generation_config=parameters)  #<-CHANGED
    print(f"Response from Model: {response.text}")           #<-CHANGED
    html = f"{response.text}"                                #<-CHANGED
    return Response(html, mimetype="application/json")       #<-CHANGED

# This code ensures that your Flask app is started and listens for
# incoming connections on the local interface and port 8080.
if __name__ == "__main__":
    app.run(host="0.0.0.0", port=PORT)

أعِد الآن تحميل علامة التبويب الحالية لمتصفّح الويب للاطّلاع على النتائج. يُرجى العِلم أنّ هذا الإجراء قد يستغرق عدة ثوانٍ لأنّك بصدد تقديم طلب بحث متقدم عن النصوص الآن. من المفترض أن تظهر لك صفحة ويب مشابهة لما يلي:

جرِّب تغيير عنوان URL لطلب موضوع اختبار وعدد أسئلة ومستوى صعوبة مختلفين.

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

8. إلى السحابة الإلكترونية

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

التشغيل الموثوق: يمكنك الحصول على ميزة التسامح التلقائي مع الأخطاء في حال تعطُّل جهاز الكمبيوتر الذي يشغّل تطبيقك.
يتطور تلقائيًا - سيواكب تطبيقك مستويات هائلة من الزيارات، ويقلل تلقائيًا من تأثيره عند عدم استخدامه.
تقليل التكاليف إلى أدنى حدّ، وذلك من خلال عدم تحصيل رسوم منك مقابل الموارد التي لا تستخدمها، بل يتم تحصيل رسوم منك فقط مقابل الموارد المستخدَمة أثناء الاستجابة للزيارات
يمكن الوصول إليها من خلال اسم نطاق مخصّص: يمكنك الاستفادة من حلّ بنقرة واحدة لمنح اسم نطاق مخصّص لخدمتك
وقت استجابة ممتاز - عمليات التشغيل على البارد سريعة الاستجابة بشكل معقول ولكن يمكنك تحسين ذلك من خلال تحديد تهيئة الحد الأدنى للمثيل
أن تتيح التشفير التام بين الأطراف باستخدام أمان الويب العادي من خلال طبقة المقابس الآمنة/طبقة النقل الآمنة: عند نشر خدمة، يمكنك الحصول على التشفير العادي للويب والشهادات المطلوبة ذات الصلة مجانًا وبشكل تلقائي

من خلال نشر تطبيقك على Google Cloud Run، يمكنك الحصول على كل ما سبق والمزيد. الحاوية هي المكوّن الأساسي لمشاركة تطبيقك مع Cloud Run.

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

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

نشر تطبيقك على Cloud Run

‫Cloud Run هي خدمة إقليمية، ما يعني أنّ البنية الأساسية التي تشغّل خدمات Cloud Run موجودة في منطقة معيّنة وتدير Google هذه البنية الأساسية لتكون متاحة بشكلٍ مكرّر في جميع المناطق ضمن تلك المنطقة. للتبسيط، سنستخدم في هذا الدرس التطبيقي المنطقة us-central1 التي تمّ ضبطها بشكلٍ ثابت.

سنستخدم أداة تسمى Buildpack لإنشاء حاويتك تلقائيًا. أنشئ ملفًا جديدًا باسم Procfile في "محرر السحابة الإلكترونية" وأدخِل سطر النص التالي:

web: gunicorn --bind :$PORT --workers 1 --threads 8 --timeout 0 main:app

يُستخدم هذا الإجراء لإعلام نظام حِزم الإنشاء بكيفية تشغيل تطبيقك في الحاوية التي تم إنشاؤها تلقائيًا. بعد ذلك، نفِّذ الأمر التالي في وحدة Cloud Shell الطرفية (من دليل quiz-generator نفسه) :

gcloud run deploy quiz-generator  \
    --source .                    \
    --region us-central1          \
    --allow-unauthenticated

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

انتظِر بضع لحظات حتى تكتمل عملية النشر. عند نجاح الأمر gcloud، يعرض عنوان URL للخدمة الجديدة:

Building using Buildpacks and deploying container to Cloud Run service [quiz-generator] in project [YOUR_PROJECT] region [YOUR_REGION]
OK Building and deploying new service... Done.                                                                          
  OK Creating Container Repository...                                                                                   
  OK Uploading sources...                                                                                               
  OK Building Container... Logs are available at [https://console.cloud.google.com/cloud-build/builds/0cf1383f-35db-412d
  -a973-557d5e2cd4a4?project=780573810218].                                                                             
  OK Creating Revision...                                                                                               
  OK Routing traffic...                                                                                                 
  OK Setting IAM Policy...                                                                                              
Done.                                                                                                                   
Service [quiz-generator] revision [quiz-generator-00001-xnr] has been deployed and is serving 100 percent of traffic.
Service URL: https://quiz-generator-co24gukjmq-uc.a.run.app

يمكنك أيضًا استرداد عنوان URL للخدمة باستخدام الأمر التالي:

gcloud run services describe quiz-generator  \
  --region us-central1                       \
  --format "value(status.url)"

من المفترض أن يظهر المحتوى على النحو التالي:

https://quiz-generator-co24gukjmq-uc.a.run.app

هذا الرابط هو عنوان URL مخصّص، مزوّد بأمان بروتوكول أمان طبقة النقل (TLS)، لخدمة Cloud Run. هذا الرابط دائم (ما دامت الخدمة مفعّلة) ويمكن استخدامه في أي مكان على الإنترنت. ولا يستخدم آلية الخادم الوكيل لـ Cloud Shell المذكورة سابقًا، والتي كانت تعتمد على جهاز افتراضي عابر.

انقر على الرمز Service URL المميّز لفتح علامة تبويب في متصفّح الويب للانتقال إلى تطبيقك الذي يعمل. تأكَّد من أنّ النتيجة هي نفسها النتيجة التي رأيتها في بيئة التطوير. تأكَّد أيضًا من أنّه يمكنك تعديل الاختبار الذي تم إنشاؤه من خلال تقديم مَعلمات في نهاية عنوان URL.

تهانينا! يتم تشغيل تطبيقك الآن على السحابة الإلكترونية من Google. بدون الحاجة إلى التفكير في ذلك، يصبح تطبيقك متاحًا للجميع، مع تشفير بروتوكول أمان طبقة النقل (TLS) وتوسيع نطاق التطبيق تلقائيًا لمستويات مدهشة من عدد الزيارات.

9. تجميع كل العناصر معًا

في هذه الخطوة الأخيرة، نحن على استعداد لتشغيل أداة إنشاء الاختبارات كجزء من تطبيق quizaic. يُرجى الانتقال إلى عنوان URL الخاص بتطبيق quizaic وتسجيل الدخول إلى حسابك على Google والانتقال إلى علامة التبويب Create Quiz. اختَر نوع المنشئ Custom، والصق عنوان URL لتشغيل Cloud في حقل عنوان URL، واملأ الحقول الأخرى المطلوبة، ثم أرسِل النموذج.

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

10. تنظيف المحتوى

على الرغم من أنه لا يتم تحصيل رسوم عند استخدام الخدمة عندما لا تكون الخدمة قيد الاستخدام، قد يستمر تحصيل رسوم منك مقابل تخزين صورة الحاوية التي تم إنشاؤها.

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

gcloud config set artifacts/repository cloud-run-source-deploy
gcloud config set artifacts/location us-central1
gcloud artifacts docker images list

# Note image tag for resulting list

gcloud artifacts docker images delete <IMAGE-TAG>

لحذف خدمة Cloud Run، استخدِم الأمر التالي:

gcloud run services delete quiz-generator --region us-central1 --quiet

11. أحسنت.

مبروك، لقد نجحت في إنشاء طلب LLM ونشر خدمة صغيرة على Cloud Run باستخدام هذا الطلب. يمكنك الآن البرمجة بلغة طبيعية ومشاركة إبداعاتك مع العالم!

أودّ أن أطرح عليك سؤالاً مهمًا:

بعد تشغيل تطبيقك في بيئة المطوّر، كم عدد أسطر التعليمات البرمجية التي كان عليك تعديلها لنشره على السحابة الإلكترونية، مع جميع السمات المناسبة للإنتاج التي يوفّرها Cloud Run؟

الإجابة هي صفر بالطبع. :)

دروس تطبيقية أخرى حول الترميز يمكنك الاطّلاع عليها...

مستندات مرجعية...

12. الحث على اتخاذ إجراء

إذا أعجبك هذا الدرس التطبيقي حول الترميز ومن المرجّح أن تقضي المزيد من الوقت في استخدام Google Cloud، ننصحك بالانضمام إلى Google Cloud Innovators اليوم.

إنّ برنامج "مبدعو Google Cloud" مجاني ويشمل ما يلي:

المناقشات المباشرة وجلسات "الأسئلة والأجوبة" وجلسات خارطة الطريق للاطّلاع على آخر الأخبار مباشرةً من موظفي Google
آخر أخبار Google Cloud مباشرةً في بريدك الوارد
الشارة الرقمية وخلفية اجتماع الفيديو
500 رصيد للاستفادة من التدريبات التعليمية على "منصة تعزيز المهارات"

انقر هنا للتسجيل.