عرض Gemma 3 باستخدام vLLM على Cloud Run

1. مقدمة

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

سيوضّح لك هذا الدرس العملي كيفية التغلّب على هذه التحديات. سنستخدم أداتَين رئيسيتَين:

1. vLLM: يمكن اعتبارها محركًا فائق السرعة للنماذج اللغوية الكبيرة. ويجعل نماذجك تعمل بكفاءة أكبر بكثير، إذ يمكنها التعامل مع المزيد من الطلبات في الوقت نفسه وتقليل استخدام الذاكرة.
2. ‫Google Cloud Run: هذه هي منصة Google بدون خادم. إنّها رائعة لنشر التطبيقات لأنّها تتعامل مع جميع عمليات التوسيع نيابةً عنك، بدءًا من صفر مستخدم إلى آلاف المستخدمين، ثم العودة إلى العدد الأصلي. والأفضل من ذلك، أنّ Cloud Run يتيح الآن استخدام وحدات معالجة الرسومات (GPU)، وهي ضرورية لاستضافة النماذج اللغوية الكبيرة.

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

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

• كيفية اختيار حجم النموذج المناسب ومتغيره المناسب للعرض
• كيفية إعداد vLLM لعرض نقاط نهاية متوافقة مع واجهة برمجة التطبيقات من OpenAI
• كيفية إنشاء حاوية لخادم vLLM باستخدام Docker
• كيفية إرسال صورة الحاوية إلى Google Artifact Registry
• كيفية نشر الحاوية على Cloud Run مع تسريع وحدة معالجة الرسومات
• كيفية اختبار النموذج الذي تم نشره

المتطلبات**:**

• متصفّح، مثل Chrome، للوصول إلى "وحدة تحكّم Google Cloud"
• اتصال موثوق بالإنترنت
• مشروع Google Cloud تم تفعيل الفوترة فيه
• رمز دخول Hugging Face (يمكنك إنشاء رمز هنا إذا لم يكن لديك رمز بعد)
• معرفة أساسية بلغة Python وDocker وواجهة سطر الأوامر
• عقل فضولي وحرص على التعلّم

2. قبل البدء

إعداد مشروع Google Cloud

يتطلّب هذا الدرس العملي مشروعًا على Google Cloud مع حساب فوترة نشط.

• بالنسبة إلى الجلسات التي يقودها مدرّب: إذا كنت في صف، سيقدّم لك المدرّب معلومات المشروع والفوترة اللازمة. اتّبِع التعليمات التي يقدّمها لك المعلّم لإكمال عملية الإعداد.
• للمتعلّمين المستقلين: إذا كنت ستنفّذ هذه الخطوات بنفسك، عليك إعداد مشروع جديد وتفعيل حساب فوترة تجريبي. يُرجى اتّباع الخطوات أدناه للبدء.
• افتح نافذة تصفّح متخفي من خلال الضغط على (Ctrl + Shift + N أو Cmd + Shift + N).
• الانتقال إلى بوابة تحصيل القيمة هذه من نافذة التصفّح المتخفي
• تسجيل الدخول والحصول على حساب فوترة تجريبي باستخدام حسابك الشخصي على Gmail
• اتّبِع التعليمات الواردة في هذه المجموعة من الشرائح لإكمال عملية الإعداد.

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

ضبط Cloud Shell

لنبدأ الآن بإعداد Cloud Shell، وهي واجهة سطر أوامر سهلة الاستخدام مضمّنة مباشرةً في Google Cloud Console.

تشغيل Cloud Shell

في أعلى يسار Google Cloud Console، سيظهر لك رمز يشبه نافذة طرفية (>_). انقر عليه لتفعيل Cloud Shell.

تفويض الوصول

إذا طُلب منك ذلك، انقر على تفويض لمنح Cloud Shell الأذونات اللازمة للتفاعل مع مشروعك على Google Cloud.

تأكيد رقم تعريف المشروع

انظر إلى Project ID في الوحدة الطرفية. سيكون مكتوبًا باللون الأصفر كما هو موضّح في الصورة أدناه. تأكَّد من أنّه المعرّف نفسه الذي سجّلته عند إنشاء المشروع.

إذا تم عرض Project ID بشكلٍ صحيح في الجهاز، انتقِل إلى خطوة تفعيل واجهات برمجة التطبيقات اللازمة.

معرّف المشروع الصحيح (إذا لزم الأمر)

إذا كان Project ID غير صحيح أو لا يظهر على الإطلاق، استخدِم هذا الأمر لإصلاحه. احرص على استبدال النص your-project-id بـ Project ID الصحيح قبل تنفيذ الأمر.

gcloud config set project your-project-id

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

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

gcloud services enable run.googleapis.com
gcloud services enable cloudbuild.googleapis.com
gcloud services enable secretmanager.googleapis.com
gcloud services enable artifactregistry.googleapis.com

3- اختيار النموذج المناسب

يمكنك العثور على العديد من النماذج المفتوحة على مواقع إلكترونية مثل Hugging Face Hub وKaggle. عندما تريد استخدام أحد هذه النماذج على خدمة مثل Google Cloud Run، عليك اختيار نموذج يتناسب مع الموارد المتوفرة لديك (أي وحدة معالجة الرسومات NVIDIA L4).

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

من المهم أيضًا التحقّق مما إذا كان النموذج المطلوب متوافقًا مع أداة العرض (vLLM في هذه الحالة). يمكنك الاطّلاع هنا على جميع النماذج المتوافقة مع vLLM.

لنستكشف الآن Gemma 3، وهي أحدث مجموعة من النماذج اللغوية الكبيرة (LLM) المتاحة للجميع من Google. تتوفّر Gemma 3 بأربعة أحجام مختلفة استنادًا إلى مدى تعقيدها، ويتم قياسها بالمَعلمات: مليار و4 مليارات و12 مليارًا و27 مليارًا.

لكل من هذه الأحجام، ستجد نوعَين رئيسيَّين:

• الإصدار الأساسي (المدرَّب مسبقًا): هذا هو النموذج الأساسي الذي تعلّم من كمية هائلة من البيانات.
• إصدار معدَّل وفقًا للتعليمات: تم تحسين هذا الإصدار بشكل أكبر لفهم تعليمات أو أوامر معيّنة واتّباعها بشكل أفضل.

النماذج الأكبر حجمًا (4 مليارات و12 مليار و27 مليار مَعلَمة) هي متعددة الوسائط، ما يعني أنّه يمكنها فهم الصور والنصوص والتعامل معها. ومع ذلك، يركّز أصغر نوع من أنواع المعلمات التي تبلغ مليار معلمة على النص فقط.

في هذا الدرس العملي، سنستخدم مليار متغير من Gemma 3: gemma-3-1b-it. يساعدك استخدام نموذج أصغر أيضًا في تعلُّم كيفية العمل بموارد محدودة، وهو أمر مهم للحفاظ على انخفاض التكاليف وضمان تشغيل تطبيقك بسلاسة على السحابة الإلكترونية.

4. متغيرات البيئة والأسرار

إنشاء ملف بيئة

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

1. أنشئ مجلدًا جديدًا لهذا المشروع.
2. انتقِل إلى المجلد الذي تم إنشاؤه حديثًا.
3. أنشئ ملف ‎.env فارغًا داخل هذا المجلد (سيحتوي هذا الملف لاحقًا على متغيرات البيئة).

في ما يلي الأمر اللازم لتنفيذ هذه الخطوات:

mkdir vllm-gemma3
cd vllm-gemma3
touch .env

ملاحظة: إذا لم تكن معتادًا على استخدام أدوات سطر الأوامر مثل vim أو nano، يمكنك استخدام محرّر Cloud Code من خلال النقر على الزر فتح المحرّر.

يمكنك الاطّلاع على ملف .env من خلال تفعيل الخيار المحرّر > عرض > تبديل الملفات المخفية.

بعد ذلك، انسخ المتغيّرات المدرَجة أدناه والصِقها في ملف ‎.env الذي أنشأته للتو. تذكَّر استبدال قيم العناصر النائبة (your_project_id وyour_region) بمعلومات مشروعك المحدّدة. على سبيل المثال (PROJECT_ID=unique-ai-project وREGION=us-central1)

PROJECT_ID=your_project_id
REGION=your_region

MODEL_PROVIDER=google
MODEL_VARIANT=gemma-3-1b-it
MODEL_NAME=${MODEL_PROVIDER}/${MODEL_VARIANT}

AR_REPO_NAME=vllm-gemma3-repo
SERVICE_NAME=${MODEL_VARIANT}-service
IMAGE_NAME=${REGION}-docker.pkg.dev/${PROJECT_ID}/${AR_REPO_NAME}/${SERVICE_NAME}

SERVICE_ACC_NAME=${SERVICE_NAME}-sa
SERVICE_ACC_EMAIL=${SERVICE_ACC_NAME}@${PROJECT_ID}.iam.gserviceaccount.com

بعد تعديل ملف.env وحفظه، اكتب هذا الأمر لتحميل متغيرات البيئة هذه إلى جلسة الوحدة الطرفية:

source .env

يمكنك اختبار ما إذا كان قد تم تحميل المتغيّرات بنجاح أم لا عن طريق عرض أحد المتغيّرات. على سبيل المثال:

echo $SERVICE_NAME

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

تخزين مفتاح سري في Secret Manager

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

قبل استخدام نماذج Gemma 3، يجب أولاً الإقرار بالأحكام والشروط، لأنّها محمية. يُرجى الانتقال إلى بطاقة نموذج Gamma3 على منصة Hugging Face Hub والموافقة على الأحكام والشروط.

ملاحظة: إذا لم يكن لديك رمز مميّز للوصول إلى Hugging Face، يمكنك إنشاء رمز هنا. ستحتاج إليه في الخطوات اللاحقة.

بعد الحصول على رمز الوصول إلى Hugging Face، انتقِل إلى صفحة Secret Manager وأنشئ سرًا باتّباع هذه التعليمات

• الانتقال إلى Google Cloud Console
• اختَر المشروع من شريط القائمة المنسدلة في أعلى يمين الصفحة
• ابحث عن Secret Manager في شريط البحث وانقر على هذا الخيار عند ظهوره.

عندما تكون في صفحة Secret Manager:

• انقر على الزر +إنشاء رمز سرّي.
• أدخِل المعلومات التالية:
• الاسم: HF_TOKEN
• قيمة المفتاح السرّي: <your_hf_access_token>
• انقر على الزر إنشاء سر عند الانتهاء.

يجب أن يكون لديك الآن رمز الوصول إلى Hugging Face كبيانات سرية على Google Cloud Secret Manager.

يمكنك اختبار إمكانية الوصول إلى كلمة المرور السرية من خلال تنفيذ الأمر أدناه في الوحدة الطرفية، وسيؤدي هذا الأمر إلى استردادها من Secret Manager:

gcloud secrets versions access latest --secret=HF_TOKEN

من المفترض أن يظهر لك رمز الدخول الذي تم استرداده في نافذة الوحدة الطرفية.

5- إنشاء حساب خدمة

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

نفِّذ هذا الأمر لإنشاء حساب خدمة

gcloud iam service-accounts create $SERVICE_ACC_NAME --display-name='Cloud Run vLLM Model Serving SA'

يربط الأمر التالي الإذن اللازم

gcloud secrets add-iam-policy-binding HF_TOKEN \
  --member="serviceAccount:${SERVICE_ACC_EMAIL}" \
  --role="roles/secretmanager.secretAccessor"

6. إنشاء صورة على Artifact Registry

تتضمّن هذه الخطوة إنشاء صورة Docker تتضمّن أوزان النموذج وvLLM مثبّتة مسبقًا.

1. إنشاء مستودع Docker على Artifact Registry

لننشئ مستودع Docker في Artifact Registry لنقل الصور التي تم إنشاؤها. نفِّذ الأمر التالي في الوحدة الطرفية:

gcloud artifacts repositories create ${AR_REPO_NAME} \
  --repository-format docker \
  --location ${REGION}

2- تخزين النموذج

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

3- إنشاء ملف Docker

أنشئ ملفًا باسم Dockerfile وانسخ المحتوى أدناه إليه:

FROM vllm/vllm-openai:v0.9.0

ARG MODEL_NAME
ARG HF_TOKEN

ENV HF_HOME=/model-cache
ENV MODEL_NAME=${MODEL_NAME}

# Use the HF_TOKEN argument to log in and download the model
RUN huggingface-cli login --token ${HF_TOKEN} && \
    huggingface-cli download ${MODEL_NAME}

ENV HF_HUB_OFFLINE=1

EXPOSE 8080

ENTRYPOINT python3 -m vllm.entrypoints.openai.api_server \
    --port ${PORT:-8080} \
    --model ${MODEL_NAME} \
    --gpu-memory-utilization 0.90 \
    ${MAX_MODEL_LEN:+--max-model-len "$MAX_MODEL_LEN"}

4. إنشاء ملف cloudbuild.yaml

بعد ذلك، أنشِئ ملفًا باسم cloudbuild.yaml في الدليل نفسه. يحدّد هذا الملف الخطوات التي يجب أن تتّبعها Cloud Build. انسخ المحتوى التالي والصقه في ملف cloudbuild.yaml:

steps:
- name: 'gcr.io/cloud-builders/docker'
  entrypoint: 'bash'
  args:
  - '-c'
  - |
    docker build \
      --build-arg MODEL_NAME=${_MODEL_NAME} \
      --build-arg HF_TOKEN=$$HF_TOKEN_SECRET \
      -t ${_IMAGE_NAME} .
  secretEnv: ['HF_TOKEN_SECRET']

images:
- '${_IMAGE_NAME}'

availableSecrets:
  secretManager:
  - versionName: projects/${PROJECT_ID}/secrets/HF_TOKEN/versions/latest
    env: 'HF_TOKEN_SECRET'

5- إرسال الإصدار إلى Cloud Build

انسخ الرمز التالي والصقه ونفِّذه في الوحدة الطرفية:

gcloud builds submit . \
    --config=cloudbuild.yaml \
    --region=${REGION} \
    --substitutions=_MODEL_NAME=${MODEL_NAME},_IMAGE_NAME=${IMAGE_NAME}

يحمّل هذا الأمر الرمز (Dockerfile وcloudbuild.yaml)، ويمرّر متغيّرات الصدفة كبدائل (_MODEL_NAME و_IMAGE_NAME)، ويبدأ عملية الإنشاء.

ستنفّذ Cloud Build الآن الخطوات المحدّدة في cloudbuild.yaml. يمكنك تتبُّع السجلات في نافذة الأوامر أو من خلال النقر على رابط تفاصيل الإصدار في Cloud Console. بعد اكتمال العملية، ستتوفّر صورة الحاوية في مستودع Artifact Registry، وستكون جاهزة للنشر.

7. اختبار الخدمة

شغِّل الأمر التالي في الوحدة الطرفية لإنشاء خادم وكيل، حتى تتمكّن من الوصول إلى الخدمة أثناء تشغيلها في المضيف المحلي:

gcloud run services proxy ${SERVICE_NAME} --region ${REGION}

في نافذة وحدة طرفية جديدة، شغِّل الأمر curl التالي في الوحدة الطرفية لاختبار الاتصال

curl -X POST http://localhost:8080/v1/completions \
-H "Authorization: Bearer $(gcloud auth print-identity-token)" \
-H "Content-Type: application/json" \
-d '{
  "model": "google/gemma-3-1b-it",
  "prompt": "Cloud Run is a ",
  "max_tokens": 128,
  "temperature": 0.90
}'

إذا ظهرت لك نتيجة مشابهة لما يلي:

{"id":"cmpl-e96d05d2893d42939c1780d44233defa","object":"text_completion","created":1746870778,"model":"google/gemma-3-1b-it","choices":[{"index":0,"text":"100% managed Kubernetes service. It's a great option for many use cases.\n\nHere's a breakdown of key features and considerations:\n\n* **Managed Kubernetes:**  This means Google handles the underlying infrastructure, including scaling, patching, and maintenance.  You don't need to worry about managing Kubernetes clusters.\n* **Serverless:**  You only pay for the compute time your application actually uses.  No charges when your code isn't running.\n* **Scalability:**  Cloud Run automatically scales your application based on demand. You can easily scale up or down to handle fluctuating traffic.\n*","logprobs":null,"finish_reason":"length","stop_reason":null,"prompt_logprobs":null}],"usage":{"prompt_tokens":6,"total_tokens":134,"completion_tokens":128,"prompt_tokens_details":null}}

8. الخاتمة

تهانينا! لقد أكملت هذا الدرس التطبيقي بنجاح. لقد تعلّمت كيفية:

• اختَر حجم نموذج مناسبًا لعملية نشر مستهدَفة.
• إعداد vLLM لعرض واجهة برمجة تطبيقات متوافقة مع OpenAI
• يمكنك إنشاء حاوية آمنة لخادم vLLM وأوزان النموذج باستخدام Docker.
• إرسال صورة حاوية إلى Google Artifact Registry
• نشر خدمة مسرَّعة بواسطة وحدة معالجة الرسومات على Cloud Run
• اختبار نموذج تمّت المصادقة عليه ونشره

يمكنك استكشاف طرق نشر نماذج أخرى رائعة مثل Llama أو Mistral أو Qwen لمواصلة رحلتك التعليمية.

9- تنظيف

لتجنُّب تكبُّد رسوم مستقبلية، من المهم حذف الموارد التي أنشأتها. نفِّذ الأوامر التالية لتنظيف مشروعك.

1. احذف خدمة Cloud Run:

gcloud run services delete ${SERVICE_NAME} --region=${REGION} --quiet

2- احذف مستودع Artifact Registry:

gcloud artifacts repositories delete ${AR_REPO_NAME} --location=${REGION} --quiet

3. احذف حساب الخدمة باتّباع الخطوات التالية:

gcloud iam service-accounts delete ${SERVICE_ACC_EMAIL} --quiet

4. احذف المفتاح السرّي من Secret Manager:

gcloud secrets delete HF_TOKEN --quiet