1. 簡介
大型語言模型 (LLM) 正在改變我們建構智慧型應用程式的方式。但要讓這些強大的模型準備好在現實世界中使用，可能很棘手。這類模型需要大量運算能力，尤其是顯示卡 (GPU)，以及能同時處理多項要求的智慧方式。此外，您希望降低成本，並確保應用程式順暢運作，不會發生延遲。
本程式碼研究室將說明如何解決這些難題！我們會使用兩項重要工具：
- vLLM：可將其視為 LLM 的超快速引擎。這項功能可大幅提升模型執行效率，一次處理更多要求，並減少記憶體用量。
- Google Cloud Run：這是 Google 的無伺服器平台。這項服務非常適合部署應用程式，因為它會為您處理所有資源調度作業，從零位使用者到數千位使用者，再回到零位使用者，都能輕鬆應付。最重要的是，Cloud Run 現在支援 GPU，這是託管 LLM 的必要條件！
結合使用 vLLM 和 Cloud Run，就能以強大、彈性且符合成本效益的方式，提供 LLM 服務。在本指南中，您將部署開放模型，並以標準網頁 API 的形式提供。
學習內容：
- 如何選擇適當的模型大小和變體來放送廣告。
- 如何設定 vLLM，以提供與 OpenAI 相容的 API 端點。
- 如何使用 Docker 將 vLLM 伺服器容器化。
- 如何將容器映像檔推送到 Google Artifact Registry。
- 如何將容器部署至 Cloud Run，並啟用 GPU 加速功能。
- 如何測試已部署的模型。
事前準備：
- 用來存取 Google Cloud 控制台的瀏覽器，例如 Chrome
- 穩定的網路連線
- 啟用計費功能的 Google Cloud 專案
- Hugging Face 存取權杖 (如果還沒有，請在這裡建立)
- 對 Python、Docker 和指令列介面有基本的瞭解
- 好奇心和學習意願
2. 事前準備
設定 Google Cloud 專案
本程式碼研究室需要具備有效帳單帳戶的 Google Cloud 專案。
- 講師主導的課程：如果您在教室中，講師會提供必要的專案和帳單資訊。按照老師的指示完成設定。
- 獨立學習者：如果您是獨立學習者，請設定新專案並啟用試用帳單帳戶。如要開始使用，請按照下列步驟操作。
- 按下 Ctrl + Shift + N 鍵或 Cmd + Shift + N 鍵，開啟無痕視窗
- 從無痕視窗前往兌換入口網站
- 使用個人 Gmail 帳戶登入，取得試用帳單帳戶
- 按照這份簡報中的操作說明完成設定
設定 Cloud Shell
接著設定 Cloud Shell，這是 Google Cloud 控制台內建的實用指令列介面。
啟動 Cloud Shell
在 Google Cloud 控制台的右上角，你會看到類似終端機的圖示 (>_)。點選該圖示即可啟用 Cloud Shell。
授權存取
如果系統提示您授權，請按一下「授權」，授予 Cloud Shell 與 Google Cloud 專案互動的必要權限。
驗證專案 ID
查看終端機中的 Project ID。如下圖所示，這段文字會以黃色顯示。確認這是您建立專案時記錄的 ID。
如果終端機中正確反映 Project ID，請繼續進行「啟用必要的 API」步驟。
正確的專案 ID (如有需要)
如果 Project ID 錯誤或未完整顯示，請使用這個指令修正。請務必先將 your-project-id 文字替換為正確的 Project ID，再執行指令。
gcloud config set project your-project-id
啟用必要的 API
如要使用 Cloud Run 等 Google Cloud 服務，請先為專案啟用對應的 API。在 Cloud Shell 中執行下列指令，啟用本 Codelab 的必要服務：
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 支援的所有模型，請按這裡。
現在，讓我們來瞭解 Gemma 3，這是 Google 最新推出的開放式大型語言模型 (LLM) 系列。Gemma 3 共有四種不同規模，複雜程度以參數衡量：10 億、40 億、120 億和 270 億。
每種尺寸都有兩大類型：
- 基礎 (預先訓練) 版本：這是從大量資料中學習的基礎模型。
- 經過指令微調的版本：這個版本經過進一步微調，可更瞭解及遵循特定指令或命令。
較大的模型 (40 億、120 億和 270 億個參數) 屬於多模態，可解讀及處理圖片和文字。不過，最小的 10 億參數變體只專注於文字。
在本程式碼研究室中，我們將使用 10 億個變體的 Gemma 3：gemma-3-1b-it。使用較小的模型也有助於瞭解如何運用有限資源，這對於降低成本及確保應用程式在雲端順暢運作至關重要。
4. 環境變數和密鑰
建立環境檔案
繼續操作前，建議您將本程式碼研究室中使用的所有設定集中管理。如要開始使用，請開啟終端機並按照下列步驟操作：
- 為這個專案建立新資料夾。
- 前往新建立的資料夾。
- 在這個資料夾中建立空白的 .env 檔案 (這個檔案稍後會保存環境變數)
執行這些步驟的指令如下：
mkdir vllm-gemma3
cd vllm-gemma3
touch .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 模型設有使用限制，因此您必須先詳閱並接受條款及細則，才能使用。前往 Hugging Face Hub 上的 Gamma3 模型資訊卡，並確認條款及細則。
取得 Hugging Face 存取權杖後，請前往 Secret Manager 頁面，然後按照這些操作說明建立密鑰
- 前往 Google Cloud 控制台
- 從左上方的下拉式選單列選取專案
- 在搜尋列中搜尋「Secret Manager」，然後點選顯示的該選項
在 Secret Manager 頁面中：
- 按一下「+Create Secret」(+建立密鑰) 按鈕，
- 填寫下列資訊：
- 名稱：HF_TOKEN
- 密鑰值：<your_hf_access_token>
- 完成後，按一下「建立密鑰」按鈕。
您現在應該已在 Google Cloud Secret Manager 中，將 Hugging Face 存取權杖設為密鑰。
您可以在終端機中執行下列指令，從 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. 在 Artifact Registry 建立 Docker 存放區
我們將在 Artifact Registry 中建立 Docker 存放區，用於推送建構的映像檔。在終端機中執行下列指令：
gcloud artifacts repositories create ${AR_REPO_NAME} \
--repository-format docker \
--location ${REGION}
2. 儲存模型
根據 GPU 最佳做法文件，您可以將 ML 模型儲存在容器映像檔中，或從 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 控制台中的建構詳細資料連結。完成後，容器映像檔就會出現在 Artifact Registry 存放區中，隨時可供部署。
7. 測試服務
在終端機中執行下列指令來建立 Proxy，以便在 localhost 中存取服務：
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 相容的 API。
- 使用 Docker 安全地將 vLLM 伺服器和模型權重容器化。
- 將容器映像檔推送至 Google Artifact Registry。
- 將 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