CS329s 机器学习模型部署教程

警告： 按照本教程中的步骤操作可能会产生费用（Google Cloud 是一项付费服务），请务必关闭不再使用的 Google Cloud 服务，以避免产生额外费用。

感谢： Mark Douthwaite 的精彩机器学习与软件工程博客、Lj Miranda 关于数据科学家软件工程工具的优秀文章、以及 Chip Huyen 和 Ashik Shafi 对本教程初稿提供的宝贵反馈。

本教程包含哪些内容？

与 CS329s 机器学习模型部署教程 配套的代码和文件。

• 观看 YouTube 上的视频教程
• 查阅 幻灯片
• 获取 模型训练代码

开始前需要准备什么？

• 一个 Google Cloud 账户 和一个 Google Cloud 项目
• 已安装 Google Cloud SDK（gcloud CLI 工具）
• 训练好的 机器学习模型，我们的应用使用了一个基于 Food101 数据集 中多种食物类别的图像分类模型。
• 已安装 Docker

再次警告： 使用 Google Cloud 服务需要付费。如果您没有免费额度（首次注册可获得 300 美元），则会产生费用。完成操作后，请删除并关闭相关资源，以避免产生额外费用。

最终会得到什么？

如果您按照以下步骤顺利完成，最终将获得一个由 Streamlit 提供支持的 Web 应用程序（Food Vision 🍔👁），用于对食物图像进行分类（如果您愿意，还可以将其部署到 Google Cloud 上）。

我们的应用在本地运行时，对一张冰淇淋图片进行预测（使用部署在 Google Cloud 上的机器学习模型）：

好的，我准备好了，该如何使用呢？

我们将分三个部分来完成这个任务：

1. 让应用运行起来（在本地机器上运行 Streamlit）
2. 将机器学习模型部署到 AI Platform（让 Google Cloud 托管我们的模型）
3. 将应用部署到 App Engine（让我们的应用上线）

1. 让应用运行起来

1. 克隆此仓库

git clone https://github.com/mrdbourke/cs329s-ml-deployment-tutorial

2. 进入 food-vision 目录

cd food-vision

3. 创建并激活虚拟环境（您可以随意命名，我将其命名为 “env”）

pip install virtualenv
virtualenv <ENV-NAME>
source <ENV-NAME>/bin/activate

4. 安装所需依赖项（Streamlit、TensorFlow 等）

pip install -r requirements.txt

5. 启动 Streamlit 并运行 app.py

streamlit run app.py

执行上述命令后，您应该会看到如下界面：

这就是我们正在开发的 Food Vision 🍔👁 应用程序。

6. 尝试上传一张图片（例如 food-images/ 文件夹中的图片，如 ice_cream.jpeg），它应该能够成功加载。

7. 注意，当您向应用上传图片时，会出现一个“Predict”按钮，点击它看看会发生什么。

8. 此时应用会崩溃，因为它试图联系 Google Cloud Platform (GCP) 以获取机器学习模型，但可能由于以下原因导致失败：

• 无法找到模型（API 调用错误或模型不存在）
• 无法使用现有模型，因为凭据错误（如下所示）

这其实是一件好事！这意味着我们的应用正在尝试与 GCP 进行通信（通过 food-vision/app.py 和 food-vision/utils.py 中的函数）。

接下来，让我们学习如何在 GCP 上托管模型。

2. 在 GCP 上托管机器学习模型

如何解决这个错误？（Streamlit 无法访问您的模型）

要解决这个问题，我们需要准备以下几样东西：

• 一个训练好的机器学习模型（适合我们的问题，我们将把它上传到 Google Storage）
• 一个 Google Storage 存储桶（用于存放我们的训练好的模型）
• 一个托管在 Google AI Platform 上的模型（我们将存储桶中的模型与此处关联）
• 用于访问 Google AI Platform 上托管模型的服务账号密钥

下面我们将逐一介绍如何实现上述目标。

1. 要训练一个机器学习模型并将其保存为 SavedModel 格式（此格式为 TensorFlow 特定格式，PyTorch 用户请根据自身需求调整），可以按照 model_training.ipynb 中的步骤进行操作。

2. 一旦我们有了 SavedModel，就可以将其上传到 Google Storage，但在上传之前，我们需要先 创建一个 Google Storage 存储桶（存储桶相当于云端的硬盘）。

您可以随意为存储桶命名（例如 my_cool_bucket_name）。建议将数据存储在离您最近的区域，或者您所在地区允许存储数据的区域（如果不确定，可以选择在美国存储）。

3. 创建好存储桶后，我们可以将模型复制到该存储桶中（参考 Google Cloud Storage 文档）。

## 在 Colab 中将模型上传到 Google Storage ##

# 授权 Colab 并初始化 gcloud（在提示时输入相应信息）
from google.colab import auth
auth.authenticate_user()
!curl https://sdk.cloud.google.com | bash
!gcloud init

# 将 SavedModel 上传到 Google Cloud Storage 存储桶
!gsutil cp -r <YOUR_MODEL_PATH> <YOUR_GOOGLE_STORAGE_BUCKET>

4. 将存储桶中的模型连接到 AI Platform（这将使我们的模型可以通过 API 调用访问。如果你不清楚什么是 API 调用，可以把它想象成一个函数，可以从互联网上的任何地方触发我们的模型）

• 不喜欢在 Google Cloud 控制台中点击操作？你也可以在命令行上使用 gcloud 在 AI Platform 上创建模型：
• 在 AI Platform 上创建模型（选择离你最近或希望模型被访问的区域）：
• 一旦你在 AI Platform 上有了模型（如上所示），你需要创建一个与你的模型训练内容相匹配的模型版本（例如，如果你的模型是用 TensorFlow 训练的，就选择 TensorFlow）：
• 然后将你的模型版本链接到 Google Cloud Storage 中的已训练模型：

5. 创建一个用于访问 AI Platform 的服务账号（GCP 非常注重权限管理，这是为了保护你的应用安全）

• 你需要创建一个具有“ML Engine Developer”角色权限的服务账号

6. 一旦你有了活跃的服务账号，创建并下载其密钥（密钥将以 .JSON 文件的形式提供）

• 🔑 注意： 服务账号密钥会授予对你的 GCP 账号的访问权限，请务必妥善保管此文件（例如，将 *.json 添加到 .gitignore 文件中，以免意外将其提交到 GitHub）

7. 更新以下变量：

• 在 app.py 中，将现有的 GCP 密钥路径替换为你的密钥路径：

# Google Cloud 服务会在你的应用运行时查找这些环境变量

# 旧
os.environ["GOOGLE_APPLICATION_CREDENTIALS"] = "daniels-dl-playground-4edbcb2e6e37.json"

# 新
os.environ["GOOGLE_APPLICATION_CREDENTIALS"] = "<PATH_TO_YOUR_KEY>"

• 在 app.py 中，将 GCP 项目和区域替换为你自己的 GCP 项目和区域：

# 旧
PROJECT = "daniels-dl-playground"
REGION = "us-central1" 

# 新
PROJECT = "<YOUR_GCP_PROJECT_NAME>"
REGION = "<YOUR_GCP_REGION>"

• 在 utils.py 中，将 "model_1" 的 "model_name" 键替换为你的模型名称：

# 旧
classes_and_models = {
    "model_1": {
        "classes": base_classes,
        "model_name": "efficientnet_model_1_10_classes" 
    }
 }

# 新
classes_and_models = {
    "model_1": {
        "classes": base_classes,
        "model_name": "<YOUR_AI_PLATFORM_MODEL_NAME>" 
    }
}

8. 再次运行应用，看看是否正常工作（按 R 键刷新 Streamlit 应用程序，或刷新页面，然后重新上传一张图片并点击“预测”按钮）

3. 将整个应用部署到 GCP

好吧，我已经修复了权限错误，那我该如何部署我的模型/应用呢？

很高兴你这么问……

1. 运行 make gcloud-deploy……等待 5–10 分钟，你的应用就会部署到 App Engine 上（前提是你已经启用了 App Engine API）。

……这样就完成了！

但是等等，运行 make gcloud-deploy 会发生什么？

当你运行 make gcloud-deploy 时，Makefile 中的 gcloud-deploy 命令（位于 food-vision/Makefile）会被触发。

实际上，make gcloud-deploy 是以下命令的别名：

gcloud app deploy app.yaml

这就是 gcloud 的一种方式，用来告诉 Google Cloud：“嘿，Google Cloud，请开始执行必要的步骤，将我们本地运行的应用程序（food-vision/app.py）部署到 App Engine 上。”

为此，gcloud app deploy 命令会执行以下操作：

• 我们的应用程序会被放入由 food-vision/Dockerfile 定义的 Docker 容器中（可以将 Docker 容器想象成一个盒子，里面包含了我们在本地运行的应用程序以及它运行所需的一切。一旦进入容器，只要 Docker 可用，这个容器就可以在任何地方运行，并且应该能够正常工作；而 Dockerfile 则定义了如何创建这个容器）。
• 当 Docker 容器创建完成后，它就变成了一个 Docker 镜像（听起来可能有点复杂，但你可以把 Docker 镜像理解为不可变的 Docker 容器，也就是说，当我们把它移动到其他地方时，它的内容不会改变）。
• 接着，Docker 镜像会被上传到 Google Container Registry (GCR)，这是 Google 用于托管 Docker 镜像的地方。
• 一旦我们的 Docker 镜像被托管在 GCR 上，它就会被部署到一个 App Engine 实例上（可以把它想象成一台类似于我们本地电脑的在线计算机，其他人也可以访问它）。
• App Engine 实例是由 food-vision/app.yaml 中的指令定义的。如果你查看这个文件，会发现它非常简单，只有两行：

runtime: custom # 我们希望运行自定义的 Docker 容器
env: flex # 我们希望 App Engine 具有灵活性，能够安装 requirements.txt 中列出的各种依赖项

听起来步骤很多，对吧？

确实如此，但只要你对每一步都多加练习，就会逐渐明白其中每一步背后都有其特定的原因。

如果所有步骤都成功执行，你应该能够在 App Engine 上看到你的应用正在运行，网址类似于：

http://<YOUR_PROJECT_NAME>.ue.r.appspot.com/

这看起来应该和我们在本地运行的应用完全一致！

拆解 food-vision

food-vision 目录下的所有文件分别有什么作用？

我们的 food-vision 目录 里包含许多文件，初次看到时可能会让人感到困惑。下面为每个文件简要说明：

• .dockerignore - 在构建 Docker 容器时需要忽略的文件或文件夹（类似于 .gitignore 在提交代码时指定要忽略的文件和文件夹）。
• Dockerfile - 定义如何创建我们的 Docker 容器（一个包含应用运行所需一切的“盒子”）的指令。
• Makefile - 一个便捷的脚本，用于在命令行中执行诸如 make gcloud-deploy 等命令，从而简化复杂操作（这样我们就不必每次都手动输入长命令了；更多信息请参阅 什么是 Makefile？）。
• SessionState.py - 一个 Python 脚本，帮助我们的 Streamlit 应用在点击按钮时保持状态（不会重置所有内容），详情可参见 Streamlit 论坛。
• app.py - 我们的 Food Vision 👁🍔 应用，基于 Streamlit 构建。
• app.yaml - 指定当我们部署应用时，App Engine 应该创建哪种类型的实例。
• requirements.txt - 运行 app.py 所需的所有依赖项。
• utils.py - 在 app.py 中使用的辅助函数，避免主程序过于庞大。

你的应用还可能在哪些地方出错

在教程中（见 1:32:31 处），我们看到已部署的应用远非完美，并且指出了几个可能导致应用崩溃的地方，但还有一个需要注意：

默认应用（克隆仓库后得到的版本）支持 3 种模型：

• 模型 1：来自 Food101 的 10 类食物。
• 模型 2：同样来自 Food101 的 11 类食物。
• 模型 3：Food101 的 11 类食物加上 1 类“非食物”类别（来自 ImageNet 的随机图像）。

这些模型都可以通过 model_training.ipynb 进行训练。然而，如果你拥有全部 3 种模型，当你在侧边栏中选择除模型 1 之外的其他选项时，应用就会崩溃（应用至少需要一种模型才能运行）。

拓展学习

我在哪里可以学到这些知识？

正如你可以用不同的层结构构建无限种深度学习神经网络一样，我们在这里所做的只是使用 Google Cloud 部署机器学习模型或应用的一种方式（其他云服务也有类似的功能）。

如果你想深入了解 Google Cloud，我推荐 Google 的 Qwiklabs。在这里，你可以针对不同场景免费获得使用 Google Cloud 的实战经验。

如果你想进一步了解软件工程与机器学习的交叉领域，可以参考以下博客：

• LJ Miranda 的 作为研究人员如何提升软件工程技能
• Mark Douthwaite 的 软件工程与机器学习博客

关于教程中提到的“数据飞轮”概念，可以观看 Josh Tobin 的演讲 机器学习基础设施栈中的缺失一环。

扩展建议

我该如何扩展这个应用？

CI/CD - 在开始构建和发布软件时，你会经常听到这个词。它代表“持续集成/持续交付”。我的理解是：假设你对应用做了一些更改，并希望立即推送给用户，那么你可以使用像 GitHub Actions 这样的服务来监控 GitHub 仓库中的变化。一旦某个分支发生更改，GitHub Actions 就会执行与我们在此处类似的操作，自动重新部署你的（更新后的）应用。

• Mark Douthwaite 写过一篇关于 使用 GitHub Actions 实现 CI/CD 的优秀文章。

将所有操作代码化！ - 在部署应用时，我们大量使用了 Google Cloud 控制台进行点击操作。但实际上，你可以使用 gcloud SDK 来完成所有这些步骤，这意味着你可以将整个流程自动化，从而大大减少手动操作！

有问题吗？

请发起 讨论 或发送邮件至 daniel@mrdbourke.com。

CS329s 机器学习模型部署快速上手指南

本指南基于斯坦福 CS329s 课程教程，帮助你构建一个基于 Streamlit 的 Web 应用（Food Vision），并将训练好的机器学习模型部署到 Google Cloud Platform (GCP) 上进行推理。

⚠️ 费用警告：本教程涉及 Google Cloud 付费服务。新用户通常有 $300 免费额度，但请务必在使用完毕后删除资源并关闭服务，以免产生意外费用。

1. 环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows (WSL2 推荐)。
• Google Cloud 账号：已注册并创建一个 Google Cloud Project。
• Google Cloud SDK：已安装 gcloud 命令行工具。
  • 安装指南：Google Cloud SDK Install
  • 国内提示：如果下载缓慢，可尝试配置代理或使用国内镜像源加速 Python 包安装。
• Docker：已安装并运行 Docker Desktop 或 Docker Engine。
  • 安装指南：Get Docker
• Python 环境：建议 Python 3.8+。
• 预训练模型：本教程使用基于 Food101 数据集训练的图像分类模型（TensorFlow SavedModel 格式）。你可以直接使用仓库提供的 model_training.ipynb 进行训练。

2. 安装步骤

第一步：克隆项目并设置虚拟环境

# 1. 克隆仓库
git clone https://github.com/mrdbourke/cs329s-ml-deployment-tutorial

# 2. 进入项目目录
cd food-vision

# 3. 创建并激活虚拟环境 (以 'env' 为例)
pip install virtualenv
virtualenv env
source env/bin/activate  # Windows 用户请使用: env\Scripts\activate

# 4. 安装依赖 (Streamlit, TensorFlow 等)
# 国内用户建议使用清华或阿里镜像加速
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

第二步：本地运行应用（初步测试）

在配置云端模型之前，先在本地启动应用以验证环境。

streamlit run app.py

• 启动后，浏览器会自动打开应用界面。
• 尝试上传一张图片（例如 food-images/ice_cream.jpeg）。
• 点击 "Predict" 按钮。
• 预期结果：此时应用会报错（无法连接 GCP 或凭证错误）。这是正常的，说明本地应用逻辑正常，接下来需要配置云端模型。

第三步：在 Google Cloud 上托管模型

要修复上述错误，需将模型部署到 GCP AI Platform。

1. 创建 Storage Bucket： 在 Google Cloud Console 中创建一个存储桶（Bucket），用于存放模型文件。

2. 上传模型： 如果你使用 Colab 或已初始化 gcloud 的本地终端，执行以下命令上传 SavedModel：

   # 授权并初始化 (如果在 Colab 中运行)
   # from google.colab import auth
   # auth.authenticate_user()
   # !curl https://sdk.cloud.google.com | bash
   # !gcloud init
   
   # 上传模型到 Storage Bucket
   # 替换 <YOUR_MODEL_PATH> 和 <YOUR_GOOGLE_STORAGE_BUCKET>
   gsutil cp -r <YOUR_MODEL_PATH> <YOUR_GOOGLE_STORAGE_BUCKET>
   

3. 在 AI Platform 创建模型及版本：

   • 在 GCP Console 的 AI Platform > Models 中创建新模型（选择靠近你的区域，如 us-central1）。
   • 创建 Model Version，框架选择 TensorFlow，并链接到上一步上传的 Google Storage 路径。

4. 创建服务账号与密钥：

   • 在 IAM & Admin > Service Accounts 创建新服务账号。
   • 赋予角色：ML Engine Developer。
   • 创建并下载 JSON 密钥文件。
   • 安全提示：切勿将此 JSON 文件提交到 GitHub，请将其添加到 .gitignore。

5. 更新代码配置： 修改 food-vision/app.py 和 food-vision/utils.py 中的配置变量：

   • app.py: 设置凭证路径、项目 ID 和区域

     # Google Cloud Services look for these when your app runs
     
     # 修改为你的密钥文件路径
     os.environ["GOOGLE_APPLICATION_CREDENTIALS"] = "<PATH_TO_YOUR_KEY>.json"
     
     # 修改为你的 GCP 项目名和区域
     PROJECT = "<YOUR_GCP_PROJECT_NAME>"
     REGION = "<YOUR_GCP_REGION>" 
     

   • utils.py: 设置模型名称

     classes_and_models = {
        "model_1": {
            "classes": base_classes,
            # 修改为你在 AI Platform 创建的模型名称
            "model_name": "<YOUR_AI_PLATFORM_MODEL_NAME>" 
        }
     }
     

6. 验证连接： 重新运行 streamlit run app.py，上传图片并点击 "Predict"。如果配置正确，应用将返回预测结果。

3. 基本使用：部署应用到互联网

完成模型配置后，将整个应用部署到 Google App Engine。

1. 确保 App Engine API 已启用： 在 Google Cloud Console 中搜索 "App Engine" 并完成初始化（选择区域）。

2. 执行部署命令： 在项目根目录 (food-vision) 下运行：

   make gcloud-deploy
   

   注：该命令实际上是 gcloud app deploy app.yaml 的别名。它会自动构建 Docker 容器，推送到 Google Container Registry (GCR)，并部署到 App Engine。

3. 访问应用： 部署过程大约需要 5-10 分钟。完成后，终端会显示应用的公网 URL。点击该链接即可在互联网上访问你的 Food Vision 应用。

---

清理资源：实验结束后，请记得在 Google Cloud Console 中删除 App Engine 版本、AI Platform 模型版本、Storage Bucket 以及服务账号，以避免持续扣费。