1. 简介
大语言模型 (LLM) 正在改变我们构建智能应用的方式。不过，要让这些强大的模型准备好在现实世界中投入使用，可能非常棘手。它们需要强大的计算能力，尤其是显卡 (GPU)，以及能够同时处理大量请求的智能方式。此外，您还希望降低费用，并确保应用顺畅运行，不会出现延迟。
本 Codelab 将向您展示如何应对这些挑战！我们将使用两个关键工具：
- vLLM：可将其视为 LLM 的超快引擎。这样一来，模型运行效率会大大提高，可以同时处理更多请求，并减少内存使用量。
- Google Cloud Run：这是 Google 的无服务器平台。它非常适合部署应用，因为它可以为您处理所有扩缩事宜，从零用户到数千用户，再到零用户。最重要的是，Cloud Run 现在支持 GPU，这对于托管 LLM 至关重要！
vLLM 和 Cloud Run 结合使用，可提供强大、灵活且经济高效的 LLM 服务。在本指南中，您将部署一个开放模型，使其可作为标准 Web API 使用。
学习内容**：**
- 如何选择合适的模型大小和变体以进行服务。
- 如何设置 vLLM 以提供与 OpenAI 兼容的 API 端点。
- 如何使用 Docker 对 vLLM 服务器进行容器化。
- 如何将容器映像推送到 Google Artifact Registry。
- 如何将容器部署到支持 GPU 加速的 Cloud Run。
- 如何测试已部署的模型。
所需条件**：**
- 浏览器（例如 Chrome），用于访问 Google Cloud 控制台
- 可靠的互联网连接
- 启用了结算功能的 Google Cloud 项目
- Hugging Face 访问令牌（如果您还没有，请点击此处创建一个）
- 基本熟悉 Python、Docker 和命令行界面
- 好奇心和学习热情
2. 准备工作
设置 Google Cloud 项目
此 Codelab 需要具有有效结算账号的 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 与您在创建项目时记录的 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 亿参数变体仅专注于文本。
在本 Codelab 中，我们将使用 10 亿参数的 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 和 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 中存储 Secret
对于任何敏感数据（包括访问代码、凭据和密码），建议使用 Secret 管理器。
在使用 Gemma 3 模型之前，您必须先确认相关条款及条件，因为这些模型是受限的。前往 Hugging Face Hub 上的 Gamma3 模型卡片，并接受相关条款及条件。
获得 Hugging Face 访问令牌后，前往 Secret Manager 页面，然后按照以下说明创建 Secret
- 前往 Google Cloud 控制台
- 从左上角的下拉菜单中选择项目
- 在搜索栏中搜索 Secret Manager，并在该选项显示时点击它
当您位于 Secret Manager 页面时：
- 点击 + 创建 Secret 按钮，
- 填写以下信息：
- 名称：HF_TOKEN
- 密钥值：<your_hf_access_token>
- 完成后，点击创建 Secret 按钮。
现在，您应该已在 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 上创建映像
此步骤涉及创建一个包含模型权重和预安装 vLLM 的 Docker 映像。
1. 在 Artifact Registry 上创建 Docker 代码库
我们将在 Artifact Registry 中创建一个 Docker 代码库，用于推送您构建的映像。在终端运行以下命令：
gcloud artifacts repositories create ${AR_REPO_NAME} \
--repository-format docker \
--location ${REGION}
2. 存储模型
根据 GPU 最佳实践文档，您可以将机器学习模型存储在容器映像中或优化从 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）、将您的 shell 变量作为替换项（_MODEL_NAME 和 _IMAGE_NAME）传递，并开始 build。
Cloud Build 现在将执行 cloudbuild.yaml 中定义的步骤。您可以在终端中跟踪日志，也可以点击 Cloud 控制台中指向 build 详细信息的链接。完成后，容器映像将显示在您的 Artifact Registry 代码库中，可供部署。
7. 测试服务
在终端中运行以下命令以创建代理，以便您在 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. 总结
恭喜！您已成功完成此 Codelab。您已学习了：
- 为目标部署选择合适的模型大小。
- 设置 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 中删除 Secret：
gcloud secrets delete HF_TOKEN --quiet