1. Pengantar
Model Bahasa Besar (LLM) mengubah cara kita membangun aplikasi pintar. Namun, menyiapkan model canggih ini untuk digunakan di dunia nyata bisa jadi rumit. Mereka memerlukan banyak daya komputasi, terutama kartu grafis (GPU), dan cara cerdas untuk menangani banyak permintaan sekaligus. Selain itu, Anda ingin menekan biaya dan menjalankan aplikasi dengan lancar tanpa penundaan.
Codelab ini akan menunjukkan cara mengatasi tantangan ini. Kita akan menggunakan dua alat utama:
- vLLM: Anggap ini sebagai mesin super cepat untuk LLM. Hal ini membuat model Anda berjalan jauh lebih efisien, menangani lebih banyak permintaan sekaligus, dan mengurangi penggunaan memori.
- Google Cloud Run: Ini adalah platform serverless Google. Fitur ini sangat bagus untuk men-deploy aplikasi karena menangani semua penskalaan untuk Anda – dari nol pengguna hingga ribuan, dan kembali lagi. Terlebih lagi, Cloud Run kini mendukung GPU, yang penting untuk menghosting LLM.
Bersama-sama, vLLM dan Cloud Run menawarkan cara yang efektif, fleksibel, dan hemat biaya untuk menayangkan LLM Anda. Dalam panduan ini, Anda akan men-deploy model terbuka, sehingga tersedia sebagai API web standar.
Yang akan Anda pelajari**:**
- Cara memilih ukuran dan varian model yang tepat untuk penayangan.
- Cara menyiapkan vLLM untuk menayangkan endpoint API yang kompatibel dengan OpenAI.
- Cara memasukkan server vLLM ke dalam container dengan Docker.
- Cara mengirim image container Anda ke Google Artifact Registry.
- Cara men-deploy container ke Cloud Run dengan akselerasi GPU.
- Cara menguji model yang di-deploy.
Yang akan Anda butuhkan**:**
- Browser, seperti Chrome, untuk mengakses Konsol Google Cloud
- Koneksi internet yang andal
- Project Google Cloud dengan penagihan diaktifkan
- Token Akses Hugging Face (buat di sini jika Anda belum memilikinya)
- Pemahaman dasar tentang Python, Docker, dan antarmuka command line
- Pikiran yang ingin tahu dan semangat untuk belajar
2. Sebelum Memulai
Menyiapkan Project Google Cloud
Codelab ini memerlukan Project Google Cloud dengan akun penagihan yang aktif.
- Untuk sesi yang dipandu instruktur: Jika Anda berada di ruang kelas, instruktur akan memberi Anda informasi project dan penagihan yang diperlukan. Ikuti petunjuk dari instruktur Anda untuk menyelesaikan penyiapan.
- Untuk pelajar mandiri: Jika Anda melakukannya sendiri, Anda harus menyiapkan project baru dan mengaktifkan akun penagihan uji coba. Ikuti langkah-langkah di bawah ini untuk memulai.
- Buka jendela samaran dengan menekan (Ctrl + Shift + N atau Cmd + Shift + N)
- Buka portal penukaran ini dari jendela samaran
- Login dan dapatkan akun penagihan uji coba dengan akun Gmail pribadi Anda
- Ikuti petunjuk dari slide ini untuk menyelesaikan penyiapan
Mengonfigurasi Cloud Shell
Sekarang, mari kita siapkan Cloud Shell, antarmuka command line praktis langsung di dalam Konsol Google Cloud.
Luncurkan Cloud Shell
Di pojok kanan atas Konsol Google Cloud, Anda akan melihat ikon yang terlihat seperti terminal (>_). Klik ikon tersebut untuk mengaktifkan Cloud Shell.
Izinkan Akses
Jika diminta, klik Authorize untuk memberikan izin yang diperlukan kepada Cloud Shell agar dapat berinteraksi dengan project Google Cloud Anda.
Verifikasi Project ID
Lihat Project ID di terminal Anda. Kata tersebut akan ditulis dengan warna kuning seperti yang ditunjukkan pada gambar di bawah. Pastikan ID tersebut sama dengan yang Anda catat saat membuat project.
Jika Project ID ditampilkan dengan benar di terminal, lanjutkan ke langkah Aktifkan API yang diperlukan.
Project ID yang Benar (jika diperlukan)
Jika Project ID salah atau tidak muncul sama sekali, gunakan perintah ini untuk memperbaikinya. Pastikan untuk mengganti teks your-project-id dengan Project ID yang benar sebelum menjalankan perintah.
gcloud config set project your-project-id
Aktifkan API yang diperlukan
Untuk menggunakan layanan Google Cloud seperti Cloud Run, Anda harus mengaktifkan API masing-masing untuk project Anda terlebih dahulu. Jalankan perintah berikut di Cloud Shell untuk mengaktifkan layanan yang diperlukan untuk Codelab ini:
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. Memilih model yang tepat
Anda dapat menemukan banyak model terbuka di situs seperti Hugging Face Hub dan Kaggle. Saat ingin menggunakan salah satu model ini di layanan seperti Google Cloud Run, Anda harus memilih model yang sesuai dengan resource yang Anda miliki (yaitu GPU NVIDIA L4).
Selain ukuran, ingatlah untuk mempertimbangkan apa yang sebenarnya dapat dilakukan model. Model tidak semuanya sama; masing-masing memiliki kelebihan dan kekurangan. Misalnya, beberapa model dapat menangani berbagai jenis input (seperti gambar dan teks – yang dikenal sebagai kemampuan multimodal), sementara model lainnya dapat mengingat dan memproses lebih banyak informasi sekaligus (artinya, model tersebut memiliki jendela konteks yang lebih besar). Sering kali, model yang lebih besar akan memiliki kemampuan yang lebih canggih seperti panggilan fungsi dan pemikiran.
Penting juga untuk memeriksa apakah model yang Anda inginkan didukung oleh alat penayangan (vLLM dalam kasus ini). Anda dapat memeriksa semua model yang didukung oleh vLLM di sini.
Sekarang, mari kita pelajari Gemma 3, yang merupakan lini Model Bahasa Besar (LLM) terbaru Google yang tersedia secara terbuka. Gemma 3 hadir dalam empat skala berbeda berdasarkan kompleksitasnya, yang diukur dalam parameter: 1 miliar, 4 miliar, 12 miliar, dan 27 miliar.
Untuk setiap ukuran ini, Anda akan menemukan dua jenis utama:
- Versi dasar (terlatih): Ini adalah model dasar yang telah mempelajari sejumlah besar data.
- Versi yang dioptimalkan untuk mengikuti perintah: Versi ini telah dioptimalkan lebih lanjut untuk lebih memahami dan mengikuti petunjuk atau perintah tertentu.
Model yang lebih besar (4 miliar, 12 miliar, dan 27 miliar parameter) bersifat multimodal, yang berarti model tersebut dapat memahami dan bekerja dengan gambar dan teks. Namun, varian 1 miliar parameter terkecil hanya berfokus pada teks.
Untuk Codelab ini, kita akan menggunakan 1 miliar varian Gemma 3: gemma-3-1b-it. Menggunakan model yang lebih kecil juga membantu Anda mempelajari cara bekerja dengan resource terbatas, yang penting untuk menekan biaya dan memastikan aplikasi Anda berjalan lancar di cloud.
4. Variabel Lingkungan & Secret
Membuat file lingkungan
Sebelum melanjutkan, sebaiknya semua konfigurasi yang akan Anda gunakan di seluruh Codelab ini berada di satu tempat. Untuk memulai, buka terminal Anda dan lakukan langkah-langkah berikut:
- Buat folder baru untuk project ini.
- Buka folder yang baru dibuat.
- Buat file .env kosong dalam folder ini (file ini akan menyimpan variabel lingkungan Anda nanti)
Berikut perintah untuk melakukan langkah-langkah tersebut:
mkdir vllm-gemma3
cd vllm-gemma3
touch .env
Selanjutnya, salin variabel yang tercantum di bawah dan tempelkan ke file.env yang baru saja Anda buat. Jangan lupa mengganti nilai placeholder (your_project_id dan your_region) dengan informasi project spesifik Anda. Misalnya (PROJECT_ID=unique-ai-project dan 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
Setelah file.env diedit dan disimpan, ketik perintah ini untuk memuat variabel lingkungan tersebut ke dalam sesi terminal:
source .env
Anda dapat menguji apakah variabel berhasil dimuat atau tidak dengan mengulang salah satu variabel. Contoh:
echo $SERVICE_NAME
Jika Anda mendapatkan nilai yang sama dengan yang Anda tetapkan dalam .env file, berarti variabel berhasil dimuat.
Menyimpan secret di Secret Manager
Untuk data sensitif apa pun, termasuk kode akses, kredensial, dan sandi, sebaiknya gunakan secret manager.
Sebelum menggunakan model Gemma 3, Anda harus menyetujui persyaratan dan ketentuan terlebih dahulu, karena model ini bersifat tertutup. Buka Kartu Model Gamma3 di Hub Hugging Face dan setujui persyaratan dan ketentuan.
Setelah Anda memiliki Token Akses Hugging Face, buka halaman Secret Manager dan buat secret dengan mengikuti petunjuk berikut
- Buka Konsol Google Cloud
- Pilih project dari menu drop-down di kiri atas
- Cari Secret Manager di kotak penelusuran dan klik opsi tersebut saat muncul
Saat Anda berada di halaman Secret Manager:
- Klik tombol +Buat Secret,
- Isi informasi berikut:
- Name: HF_TOKEN
- Secret Value: <your_hf_access_token>
- Klik tombol Buat Secret setelah Anda selesai.
Sekarang Anda akan memiliki Token Akses Hugging Face sebagai secret di Google Cloud Secret Manager.
Anda dapat menguji akses ke secret dengan menjalankan perintah di bawah di terminal. Perintah tersebut akan mengambilnya dari Secret Manager:
gcloud secrets versions access latest --secret=HF_TOKEN
Anda akan melihat Token Akses Anda diambil dan ditampilkan di jendela terminal.
5. Membuat akun layanan
Untuk meningkatkan keamanan dan mengelola akses secara efektif dalam setelan produksi, layanan harus beroperasi di bawah akun layanan khusus yang dibatasi secara ketat untuk izin yang diperlukan bagi tugas tertentu.
Jalankan perintah ini untuk membuat akun layanan
gcloud iam service-accounts create $SERVICE_ACC_NAME --display-name='Cloud Run vLLM Model Serving SA'
Perintah berikut melampirkan izin yang diperlukan
gcloud secrets add-iam-policy-binding HF_TOKEN \
--member="serviceAccount:${SERVICE_ACC_EMAIL}" \
--role="roles/secretmanager.secretAccessor"
6. Membuat Image di Artifact Registry
Langkah ini melibatkan pembuatan image Docker yang mencakup bobot model dan vLLM yang telah diinstal sebelumnya.
1. Buat repositori Docker di Artifact Registry
Mari kita buat repositori Docker di Artifact Registry untuk mengirim image yang telah Anda buat. Jalankan perintah berikut di terminal:
gcloud artifacts repositories create ${AR_REPO_NAME} \
--repository-format docker \
--location ${REGION}
2. Menyimpan model
Berdasarkan dokumentasi praktik terbaik GPU, Anda dapat menyimpan model ML di dalam image container atau mengoptimalkan pemuatannya dari Cloud Storage. Tentu saja, setiap pendekatan memiliki pro dan kontra masing-masing. Anda dapat membaca dokumentasi untuk mempelajari lebih lanjut. Untuk mempermudah, kita hanya akan menyimpan model di image container.
3. Membuat file Docker
Buat file bernama Dockerfile dan salin konten di bawah ke dalamnya:
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. Buat file cloudbuild.yaml
Selanjutnya, buat file bernama cloudbuild.yaml di direktori yang sama. File ini menentukan langkah-langkah yang harus diikuti Cloud Build. Salin dan tempel konten berikut ke 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. Kirimkan build ke Cloud Build
Salin dan tempel kode berikut, lalu jalankan di terminal:
gcloud builds submit . \
--config=cloudbuild.yaml \
--region=${REGION} \
--substitutions=_MODEL_NAME=${MODEL_NAME},_IMAGE_NAME=${IMAGE_NAME}
Perintah ini mengupload kode Anda (Dockerfile dan cloudbuild.yaml), meneruskan variabel shell sebagai penggantian (_MODEL_NAME dan _IMAGE_NAME), serta memulai build.
Cloud Build kini akan mengeksekusi langkah-langkah yang ditentukan dalam cloudbuild.yaml. Anda dapat mengikuti log di terminal atau dengan mengklik link ke detail build di Cloud Console. Setelah selesai, image container akan tersedia di repositori Artifact Registry Anda, siap untuk di-deploy.
7. Menguji layanan
Jalankan perintah berikut di terminal untuk membuat proxy, sehingga Anda dapat mengakses layanan saat berjalan di localhost:
gcloud run services proxy ${SERVICE_NAME} --region ${REGION}
Di jendela terminal baru, jalankan perintah curl ini di terminal untuk menguji koneksi
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
}'
Jika Anda melihat output yang mirip seperti di bawah ini:
{"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. Kesimpulan
Selamat! Anda berhasil menyelesaikan Codelab ini. Anda telah mempelajari cara:
- Pilih ukuran model yang sesuai untuk deployment target.
- Siapkan vLLM untuk menayangkan API yang kompatibel dengan OpenAI.
- Masukkan server vLLM dan bobot model ke dalam container dengan aman menggunakan Docker.
- Kirim image container ke Google Artifact Registry.
- Men-deploy layanan yang diakselerasi GPU ke Cloud Run.
- Menguji model yang di-deploy dan diautentikasi.
Jangan ragu untuk mempelajari cara men-deploy model menarik lainnya seperti Llama, Mistral, atau Qwen untuk melanjutkan perjalanan belajar Anda.
9. Pembersihan
Untuk menghindari tagihan di masa mendatang, Anda harus menghapus resource yang Anda buat. Jalankan perintah berikut untuk membersihkan project Anda.
1. Hapus layanan Cloud Run:
gcloud run services delete ${SERVICE_NAME} --region=${REGION} --quiet
2. Hapus repositori Artifact Registry:
gcloud artifacts repositories delete ${AR_REPO_NAME} --location=${REGION} --quiet
3. Hapus akun layanan:
gcloud iam service-accounts delete ${SERVICE_ACC_EMAIL} --quiet
4. Hapus secret dari Secret Manager:
gcloud secrets delete HF_TOKEN --quiet