1. مقدمه
مدل های زبان بزرگ (LLM) نحوه ساخت برنامه های هوشمند را تغییر می دهند. اما آماده کردن این مدل های قدرتمند برای استفاده در دنیای واقعی می تواند دشوار باشد. آنها به قدرت محاسباتی زیادی، به‌ویژه کارت‌های گرافیک (GPU) و روش‌های هوشمندانه برای رسیدگی به بسیاری از درخواست‌ها در یک زمان نیاز دارند. به علاوه، شما می خواهید هزینه ها را کاهش دهید و برنامه خود را بدون تاخیر اجرا کنید.
این Codelab به شما نشان می دهد که چگونه با این چالش ها مقابله کنید! ما از دو ابزار کلیدی استفاده خواهیم کرد:
- vLLM : به این به عنوان یک موتور فوق سریع برای LLM فکر کنید. این باعث می‌شود مدل‌های شما کارآمدتر اجرا شوند، درخواست‌های بیشتری را به‌طور هم‌زمان مدیریت کنند و استفاده از حافظه را کاهش دهند.
- Google Cloud Run : این پلتفرم بدون سرور گوگل است. برای استقرار برنامه‌ها فوق‌العاده است، زیرا همه مقیاس‌ها را برای شما مدیریت می‌کند – از صفر تا هزاران کاربر، و دوباره به عقب برمی‌گردید. بهترین از همه، Cloud Run اکنون از پردازنده‌های گرافیکی پشتیبانی می‌کند ، که برای میزبانی LLM ضروری هستند!
vLLM و Cloud Run با هم یک راه قدرتمند، انعطاف پذیر و مقرون به صرفه برای ارائه خدمات به LLM های شما ارائه می دهند. در این راهنما، شما یک مدل باز را مستقر خواهید کرد و آن را به عنوان یک وب API استاندارد در دسترس قرار خواهید داد.
آنچه یاد خواهید گرفت **:**
- نحوه انتخاب سایز و نوع مدل مناسب برای سرو
- نحوه راه اندازی vLLM برای ارائه نقاط پایانی API سازگار با OpenAI.
- نحوه کانتینریزه کردن سرور vLLM با Docker.
- چگونه تصویر ظرف خود را به رجیستری مصنوع Google فشار دهید.
- نحوه استقرار کانتینر در Cloud Run با شتاب GPU.
- چگونه مدل مستقر شده خود را آزمایش کنیم.
آنچه شما نیاز دارید **:**
- مرورگری مانند کروم برای دسترسی به کنسول ابری گوگل
- یک اتصال اینترنتی قابل اعتماد
- یک پروژه Google Cloud با فعال کردن صورتحساب
- یک نشانه دسترسی به چهره در آغوش گرفته (اگر هنوز آن را ندارید، یکی را در اینجا ایجاد کنید)
- آشنایی اولیه با پایتون، داکر و رابط خط فرمان
- ذهن کنجکاو و اشتیاق به یادگیری
2. قبل از شروع
پروژه Google Cloud را راه اندازی کنید
این آزمایشگاه کد به یک پروژه Google Cloud با یک حساب صورتحساب فعال نیاز دارد.
- برای جلسات تحت رهبری مربی: اگر در کلاس درس هستید، مربی شما اطلاعات پروژه و صورتحساب لازم را در اختیار شما قرار می دهد. دستورالعمل های مربی خود را برای تکمیل تنظیمات دنبال کنید..
- برای زبان آموزان مستقل: اگر این کار را به تنهایی انجام می دهید، باید یک پروژه جدید راه اندازی کنید و یک حساب صورتحساب آزمایشی را فعال کنید. لطفاً برای شروع مراحل زیر را دنبال کنید.
- با فشار دادن ( Ctrl + Shift + N یا Cmd + Shift + N ) یک پنجره ناشناس باز کنید.
- از پنجره حالت ناشناس به این پورتال رستگاری بروید
- وارد شوید و با حساب شخصی جیمیل خود یک حساب صورتحساب آزمایشی دریافت کنید
- برای تکمیل تنظیمات، دستورالعمل‌های این دک را دنبال کنید
Cloud Shell را پیکربندی کنید
اکنون بیایید Cloud Shell را راه‌اندازی کنیم، یک رابط خط فرمان مفید مستقیماً در Google Cloud Console.
Cloud Shell را راه اندازی کنید
در گوشه سمت راست بالای Google Cloud Console ، نمادی را خواهید دید که شبیه ترمینال است ( >_ ). روی آن کلیک کنید تا Cloud Shell فعال شود.
مجوز دسترسی
اگر از شما خواسته شد، روی مجوز کلیک کنید تا به Cloud Shell مجوزهای لازم برای تعامل با پروژه Google Cloud شما اعطا شود.
شناسه پروژه را تأیید کنید
به Project ID در ترمینال خود نگاه کنید. مطابق تصویر زیر با رنگ زرد نوشته خواهد شد. مطمئن شوید که همان شناسه ای است که هنگام ایجاد پروژه ثبت کرده اید.
اگر Project ID به درستی در ترمینال منعکس شده است، به مرحله فعال کردن API های ضروری بروید.
شناسه پروژه صحیح (در صورت نیاز)
اگر Project ID اشتباه است یا به طور کامل نشان داده نمی شود، از این دستور برای رفع آن استفاده کنید. حتماً قبل از اجرای دستور، متن your-project-id با Project ID صحیح خود جایگزین کنید.
gcloud config set project your-project-id
API های لازم را فعال کنید
برای استفاده از سرویس‌های Google Cloud مانند Cloud Run، ابتدا باید API مربوطه آنها را برای پروژه خود فعال کنید. برای فعال کردن سرویس های لازم برای این Codelab دستورات زیر را در 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 GPU) مناسب باشد.
فراتر از اندازه، به یاد داشته باشید که آنچه را که مدل واقعا می تواند انجام دهد را در نظر بگیرید. مدل ها همه یکسان نیستند. هر کدام مزایا و معایب خاص خود را دارند. برای مثال، برخی از مدل‌ها می‌توانند انواع مختلفی از ورودی‌ها را مدیریت کنند (مانند تصاویر و متن – معروف به قابلیت‌های چندوجهی)، در حالی که برخی دیگر می‌توانند اطلاعات بیشتری را به‌طور هم‌زمان به خاطر بسپارند و پردازش کنند (به این معنی که پنجره‌های زمینه بزرگ‌تری دارند). اغلب، مدل های بزرگتر دارای قابلیت های پیشرفته تری مانند فراخوانی تابع و تفکر هستند .
همچنین مهم است که بررسی کنید آیا مدل مورد نظر شما توسط ابزار سرویس (در این مورد vLLM) پشتیبانی می شود یا خیر. می‌توانید تمام مدل‌هایی که توسط vLLM پشتیبانی می‌شوند را در اینجا بررسی کنید.
اکنون، بیایید جما 3 را بررسی کنیم، که جدیدترین خانواده Google از مدل‌های زبان بزرگ (LLM) است. جما 3 بر اساس پیچیدگی آنها در چهار مقیاس مختلف ارائه می شود که در پارامترهای 1 میلیارد، 4 میلیارد، 12 میلیارد و 27 میلیارد اندازه گیری می شود.
برای هر یک از این اندازه ها، دو نوع اصلی پیدا خواهید کرد:
- نسخه پایه (از پیش آموزش داده شده): این مدل پایه ای است که از حجم عظیمی از داده ها آموخته شده است.
- یک نسخه تنظیم‌شده توسط دستورالعمل: این نسخه برای درک بهتر و پیروی از دستورالعمل‌ها یا دستورات خاص، بیشتر اصلاح شده است.
مدل های بزرگتر (4 میلیارد، 12 میلیارد و 27 میلیارد پارامتر) چند وجهی هستند، به این معنی که می توانند هم تصاویر و هم متن را درک کنند و با آنها کار کنند. با این حال، کوچکترین نوع پارامتر 1 میلیاردی، تنها بر روی متن متمرکز است.
برای این Codelab، از 1 میلیارد نوع Gemma 3 استفاده خواهیم کرد: gemma-3-1b-it . استفاده از یک مدل کوچکتر همچنین به شما کمک می کند تا نحوه کار با منابع محدود را یاد بگیرید، که برای پایین نگه داشتن هزینه ها و اطمینان از اجرای روان برنامه شما در فضای ابری مهم است.
4. متغیرهای محیطی و اسرار
یک فایل محیطی ایجاد کنید
قبل از ادامه، این یک تمرین خوب است که تمام تنظیماتی را که در سراسر این Codelab استفاده می‌کنید در یک مکان داشته باشید. برای شروع، ترمینال خود را باز کنید این مراحل را انجام دهید:
- یک پوشه جدید برای این پروژه ایجاد کنید .
- به پوشه ای که به تازگی ایجاد شده است بروید.
- یک فایل env خالی در این پوشه ایجاد کنید (این فایل بعداً متغیرهای محیط شما را نگه می‌دارد)
در اینجا دستور انجام این مراحل آمده است:
mkdir vllm-gemma3
cd vllm-gemma3
touch .env
در مرحله بعد، متغیرهای فهرست شده در زیر را کپی کنید و آنها را در فایل .env که به تازگی ایجاد کرده اید قرار دهید. به یاد داشته باشید که مقادیر متغیر مکان ( your_project_id و your_region ) را با اطلاعات پروژه خاص خود جایگزین کنید. برای مثال ( PROJECT_ID=unique-ai-project and 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 On Hugging Face Hub بروید و شرایط و ضوابط را بپذیرید.
هنگامی که نشانه دسترسی به چهره را در آغوش گرفتید، به صفحه Secret Manager بروید و با دنبال کردن این دستورالعمل ها یک راز ایجاد کنید
- به Google Cloud Console بروید
- پروژه را از نوار کشویی بالا سمت چپ انتخاب کنید
- Search Secret Manager را در نوار جستجو جستجو کنید و پس از ظاهر شدن روی آن گزینه کلیک کنید
وقتی در آن صفحه مدیر مخفی هستید:
- روی دکمه +Create Secret کلیک کنید،
- این اطلاعات را پر کنید:
- نام : HF_TOKEN
- ارزش مخفی : <your_hf_access_token>
- پس از اتمام کار، روی دکمه Create Secret کلیک کنید.
اکنون باید نشانه دسترسی Hugging Face را به عنوان یک راز در Google Cloud Secret Manager داشته باشید.
شما می توانید با اجرای دستور زیر در ترمینال دسترسی خود را به راز آزمایش کنید، این دستور آن را از Secret Manager بازیابی می کند:
gcloud secrets versions access latest --secret=HF_TOKEN
باید مشاهده کنید که Token Access شما بازیابی شده و در پنجره ترمینال نشان داده می شود.
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. یک تصویر در رجیستری مصنوع ایجاد کنید
این مرحله شامل ایجاد یک تصویر Docker است که شامل وزن مدل و یک vLLM از پیش نصب شده است.
1. یک مخزن docker در Artifact Registry ایجاد کنید
بیایید یک مخزن Docker در Artifact Registry برای فشار دادن تصاویر ساخته شده شما ایجاد کنیم. دستور زیر را در ترمینال اجرا کنید:
gcloud artifacts repositories create ${AR_REPO_NAME} \
--repository-format docker \
--location ${REGION}
2. ذخیره سازی مدل
بر اساس مستندات بهترین شیوه های GPU ، می توانید مدل های ML را در تصاویر کانتینر ذخیره کنید یا بارگیری آنها را از فضای ذخیره سازی ابری بهینه کنید . البته هر رویکردی مزایا و معایب خاص خود را دارد. برای کسب اطلاعات بیشتر در مورد آنها می توانید اسناد را مطالعه کنید. برای سادگی، ما فقط مدل را در تصویر ظرف ذخیره می کنیم.
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 دنبال کنید. پس از اتمام، تصویر کانتینر در مخزن 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. نتیجه گیری
تبریک می گویم! شما این Codelab را با موفقیت تکمیل کردید. شما یاد گرفتید که چگونه:
- اندازه مدل مناسب را برای استقرار هدف انتخاب کنید.
- vLLM را برای ارائه یک API سازگار با OpenAI تنظیم کنید.
- سرور vLLM را ایمن کنید و وزن ها را با Docker مدل کنید.
- یک تصویر ظرف را به رجیستری مصنوع Google فشار دهید.
- یک سرویس تسریع شده توسط GPU را در 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