🔥  GitHub 上顶级 ML 仓库之一

课程内容

学习如何将机器学习与软件工程相结合，以设计、开发、部署并迭代生产级（production-grade）的机器学习应用。

• 课程网站：https://madewithml.com/
• 代码仓库：GokuMohandas/Made-With-ML

概览

在本课程中，我们将从实验阶段（设计 + 开发）过渡到生产阶段（部署 + 迭代）。我们会通过迭代的方式，逐步引入构建一个可靠生产系统所需的各个组件。

  务必观看下方视频，快速了解我们将要构建的内容。

• 💡 第一性原理（First principles）：在直接写代码之前，我们先从第一性原理出发，深入理解每一个机器学习概念。
• 💻 最佳实践（Best practices）：在开发和部署机器学习模型的过程中，贯彻软件工程的最佳实践。
• 📈 可扩展性（Scale）：无需学习全新语言，即可轻松在 Python 中扩展机器学习工作负载（数据处理、训练、调参、服务等）。
• ⚙️ MLOps：在构建端到端机器学习系统的过程中，集成 MLOps 组件（如实验跟踪、测试、模型服务、任务编排等）。
• 🚀 从开发到生产（Dev to Prod）：学习如何在不更改代码或基础设施管理的前提下，快速且可靠地将模型从开发环境迁移到生产环境。
• 🐙 CI/CD：学习如何构建成熟的持续集成/持续部署（CI/CD）工作流，以模块化方式持续训练和部署更优模型，并可与任意技术栈集成。

目标受众

机器学习并非一个独立的行业，而是一种强大的数据思维方式，并非仅限于某一类人群。

• 👩‍💻 所有开发者：无论是软件/基础设施工程师还是数据科学家，机器学习正日益成为你所开发产品中的关键组成部分。
• 👩‍🎓 应届毕业生：学习业界所需的实用技能，弥合大学课程与行业实际需求之间的差距。
• 👩‍💼 产品经理/管理者：希望打下技术基础，从而能够构建由机器学习驱动的卓越（且可靠）产品。

环境设置

请务必访问课程网站，以获取对本仓库内容更详细的分步讲解。以下各节均提供本地笔记本电脑和 Anyscale 集群两种操作说明，请根据你的使用环境点击 ► 下拉菜单进行切换（默认显示 Anyscale 的说明）。如果你想通过 Anyscale 学习本课程，我们将为你提供结构化内容、计算资源（GPU） 和社区支持，助你在一天内掌握全部内容。欢迎报名参加我们的下一期实时课程 → 立即注册！

集群设置

首先，我们需要配置集群的环境和计算资源。

- Workspace name: `madewithml`
- Project: `madewithml`
- Cluster environment name: `madewithml-cluster-env`
# 勾选 `Select from saved configurations`
- Compute config: `madewithml-cluster-compute-g5.4xlarge`

Git 设置

请按以下步骤创建一个新仓库：Create a new repository → 仓库名称设为 Made-With-ML → 勾选 Add a README file（非常重要，这会自动创建 main 分支）→ 点击 Create repository（滚动到底部）

现在我们可以克隆包含所有代码的仓库了：

git clone https://github.com/GokuMohandas/Made-With-ML.git .

凭据配置

touch .env

# Inside .env
GITHUB_USERNAME="CHANGE_THIS_TO_YOUR_USERNAME"  # ← 请修改为你自己的用户名

source .env

虚拟环境（Virtual environment）

export PYTHONPATH=$PYTHONPATH:$PWD
python3 -m venv venv  # 推荐使用 Python 3.10
source venv/bin/activate  # Windows 上使用：venv\Scripts\activate
python3 -m pip install --upgrade pip setuptools wheel
python3 -m pip install -r requirements.txt
pre-commit install
pre-commit autoupdate

export PYTHONPATH=$PYTHONPATH:$PWD
pre-commit install
pre-commit autoupdate

Notebook

首先通过 Jupyter Notebook 进行交互式探索，逐步了解核心的机器学习工作负载（workloads）。

# 启动 notebook
jupyter lab notebooks/madewithml.ipynb

脚本（Scripts）

接下来，我们将使用符合软件工程最佳实践（如测试、文档、日志记录、服务部署、版本控制等）的干净 Python 脚本来执行相同的工作负载。我们在 notebook 中实现的代码将被重构为以下脚本：

madewithml
├── config.py
├── data.py
├── evaluate.py
├── models.py
├── predict.py
├── serve.py
├── train.py
├── tune.py
└── utils.py

注意：请根据你的系统资源调整以下命令中的 --num-workers、--cpu-per-worker 和 --gpu-per-worker 参数值。例如，如果你在本地笔记本电脑上运行，一个合理的配置是 --num-workers 6 --cpu-per-worker 1 --gpu-per-worker 0。

训练（Training）

export EXPERIMENT_NAME="llm"
export DATASET_LOC="https://raw.githubusercontent.com/GokuMohandas/Made-With-ML/main/datasets/dataset.csv"
export TRAIN_LOOP_CONFIG='{"dropout_p": 0.5, "lr": 1e-4, "lr_factor": 0.8, "lr_patience": 3}'
python madewithml/train.py \
    --experiment-name "$EXPERIMENT_NAME" \
    --dataset-loc "$DATASET_LOC" \
    --train-loop-config "$TRAIN_LOOP_CONFIG" \
    --num-workers 1 \
    --cpu-per-worker 3 \
    --gpu-per-worker 1 \
    --num-epochs 10 \
    --batch-size 256 \
    --results-fp results/training_results.json

调优（Tuning）

export EXPERIMENT_NAME="llm"
export DATASET_LOC="https://raw.githubusercontent.com/GokuMohandas/Made-With-ML/main/datasets/dataset.csv"
export TRAIN_LOOP_CONFIG='{"dropout_p": 0.5, "lr": 1e-4, "lr_factor": 0.8, "lr_patience": 3}'
export INITIAL_PARAMS="[{\"train_loop_config\": $TRAIN_LOOP_CONFIG}]"
python madewithml/tune.py \
    --experiment-name "$EXPERIMENT_NAME" \
    --dataset-loc "$DATASET_LOC" \
    --initial-params "$INITIAL_PARAMS" \
    --num-runs 2 \
    --num-workers 1 \
    --cpu-per-worker 3 \
    --gpu-per-worker 1 \
    --num-epochs 10 \
    --batch-size 256 \
    --results-fp results/tuning_results.json

实验跟踪（Experiment tracking）

我们将使用 MLflow 来跟踪实验、存储模型，并通过 MLflow Tracking UI 查看实验结果。目前我们将实验保存在本地目录中，但在实际生产环境中，我们会使用一个中心化的位置来存储所有实验数据。你可以轻松且低成本地搭建自己的 MLflow 服务器供团队成员使用，也可以选择托管解决方案，例如 Weights & Biases、Comet 等。

export MODEL_REGISTRY=$(python -c "from madewithml import config; print(config.MODEL_REGISTRY)")
mlflow server -h 0.0.0.0 -p 8080 --backend-store-uri $MODEL_REGISTRY

APP_PORT=8080
echo https://$APP_PORT-port-$ANYSCALE_SESSION_DOMAIN

评估（Evaluation）

export EXPERIMENT_NAME="llm"
export RUN_ID=$(python madewithml/predict.py get-best-run-id --experiment-name $EXPERIMENT_NAME --metric val_loss --mode ASC)
export HOLDOUT_LOC="https://raw.githubusercontent.com/GokuMohandas/Made-With-ML/main/datasets/holdout.csv"
python madewithml/evaluate.py \
    --run-id $RUN_ID \
    --dataset-loc $HOLDOUT_LOC \
    --results-fp results/evaluation_results.json

{
  "timestamp": "June 09, 2023 09:26:18 AM",
  "run_id": "6149e3fec8d24f1492d4a4cabd5c06f6",
  "overall": {
    "precision": 0.9076136428670714,
    "recall": 0.9057591623036649,
    "f1": 0.9046792827719773,
    "num_samples": 191.0
  },
...

推理（Inference）

export EXPERIMENT_NAME="llm"
export RUN_ID=$(python madewithml/predict.py get-best-run-id --experiment-name $EXPERIMENT_NAME --metric val_loss --mode ASC)
python madewithml/predict.py predict \
    --run-id $RUN_ID \
    --title "Transfer learning with transformers" \
    --description "Using transformers for transfer learning on text classification tasks."

[{
  "prediction": [
    "natural-language-processing"
  ],
  "probabilities": {
    "computer-vision": 0.0009767753,
    "mlops": 0.0008223939,
    "natural-language-processing": 0.99762577,
    "other": 0.000575123
  }
}]

部署（Serving）

# 启动
ray start --head

# 设置
export EXPERIMENT_NAME="llm"
export RUN_ID=$(python madewithml/predict.py get-best-run-id --experiment-name $EXPERIMENT_NAME --metric val_loss --mode ASC)
python madewithml/serve.py --run_id $RUN_ID

# 通过 Python 调用
import json
import requests
title = "Transfer learning with transformers"
description = "Using transformers for transfer learning on text classification tasks."
json_data = json.dumps({"title": title, "description": description})
requests.post("http://127.0.0.1:8000/predict", data=json_data).json()

ray stop  # 关闭

# 设置
export EXPERIMENT_NAME="llm"
export RUN_ID=$(python madewithml/predict.py get-best-run-id --experiment-name $EXPERIMENT_NAME --metric val_loss --mode ASC)
python madewithml/serve.py --run_id $RUN_ID

# 通过 Python 调用
import json
import requests
title = "Transfer learning with transformers"
description = "Using transformers for transfer learning on text classification tasks."
json_data = json.dumps({"title": title, "description": description})
requests.post("http://127.0.0.1:8000/predict", data=json_data).json()

测试（Testing）

# 代码测试
python3 -m pytest tests/code --verbose --disable-warnings

# 数据测试
export DATASET_LOC="https://raw.githubusercontent.com/GokuMohandas/Made-With-ML/main/datasets/dataset.csv"
pytest --dataset-loc=$DATASET_LOC tests/data --verbose --disable-warnings

# 模型测试
export EXPERIMENT_NAME="llm"
export RUN_ID=$(python madewithml/predict.py get-best-run-id --experiment-name $EXPERIMENT_NAME --metric val_loss --mode ASC)
pytest --run-id=$RUN_ID tests/model --verbose --disable-warnings

# 覆盖率测试
python3 -m pytest tests/code --cov madewithml --cov-report html --disable-warnings  # HTML 报告
python3 -m pytest tests/code --cov madewithml --cov-report term --disable-warnings  # 终端报告

生产环境（Production）

从这一步开始，若要将我们的应用程序部署到生产环境，我们需要使用 Anyscale，或者使用你自行管理的 云虚拟机（cloud VM） / 本地集群（on-prem cluster）（需配合 Ray）。如果不在 Anyscale 上，命令会略有不同（参见 文档），但核心概念是一致的。

如果你不想自己搭建所有这些基础设施，我们强烈推荐你加入我们即将推出的 实时课程（live cohort）{:target="_blank"}。我们将为你提供一个已配置好全部基础设施的环境，让你可以专注于机器学习本身。

认证（Authentication）

如果你使用的是 Anyscale Workspaces，以下凭据会自动为你设置。在 Workspaces 中，你无需显式设置这些凭据；但如果你在本地或 Anyscale Jobs 和 Services 配置范围之外的集群上运行，则需要手动设置。

export ANYSCALE_HOST=https://console.anyscale.com
export ANYSCALE_CLI_TOKEN=$YOUR_CLI_TOKEN  # 从 Anyscale 凭据页面获取

集群环境（Cluster environment）

集群环境决定了我们的工作负载将在何处执行（操作系统、依赖项等）。我们已经为你创建了这个 集群环境，但你也可以按如下方式自行创建或更新：

export CLUSTER_ENV_NAME="madewithml-cluster-env"
anyscale cluster-env build deploy/cluster_env.yaml --name $CLUSTER_ENV_NAME

计算配置（Compute configuration）

计算配置决定了我们的工作负载将在何种资源上执行。我们已经为你创建了这个 计算配置，但你也可以按如下方式自行创建：

export CLUSTER_COMPUTE_NAME="madewithml-cluster-compute-g5.4xlarge"
anyscale cluster-compute create deploy/cluster_compute.yaml --name $CLUSTER_COMPUTE_NAME

Anyscale Jobs

现在我们已准备好执行机器学习工作负载。我们选择将所有任务合并到一个 Job 中，但也可以为每个任务（训练、评估等）分别创建 Job。首先，编辑 workloads.yaml 文件中的 $GITHUB_USERNAME 占位符：

runtime_env:
  working_dir: .
  upload_path: s3://madewithml/$GITHUB_USERNAME/jobs  # <--- 修改为你的 GitHub 用户名（区分大小写）
  env_vars:
    GITHUB_USERNAME: $GITHUB_USERNAME  # <--- 修改为你的 GitHub 用户名（区分大小写）

此处的 runtime_env 表示应将当前 working_dir 上传至 S3 存储桶，以便执行 Anyscale Job 时所有工作节点都能访问代码。GITHUB_USERNAME 用于后续将工作负载的结果保存到 S3，以便之后检索（例如用于部署服务）。

现在我们可以提交 Job 来执行机器学习工作负载了：

anyscale job submit deploy/jobs/workloads.yaml

Anyscale Services

在机器学习工作负载执行完成后，我们就可以将模型部署到生产环境了。与 Anyscale Jobs 的配置类似，请确保修改 serve_model.yaml 中的 $GITHUB_USERNAME：

ray_serve_config:
  import_path: deploy.services.serve_model:entrypoint
  runtime_env:
    working_dir: .
    upload_path: s3://madewithml/$GITHUB_USERNAME/services  # <--- 修改为你的 GitHub 用户名（区分大小写）
    env_vars:
      GITHUB_USERNAME: $GITHUB_USERNAME  # <--- 修改为你的 GitHub 用户名（区分大小写）

现在我们可以启动服务了：

# 部署服务
anyscale service rollout -f deploy/services/serve_model.yaml

# 查询服务
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $SECRET_TOKEN" -d '{
  "title": "Transfer learning with transformers",
  "description": "Using transformers for transfer learning on text classification tasks."
}' $SERVICE_ENDPOINT/predict/

# 回滚（回退到服务的先前版本）
anyscale service rollback -f $SERVICE_CONFIG --name $SERVICE_NAME

# 终止服务
anyscale service terminate --name $SERVICE_NAME

CI/CD（持续集成/持续部署）

我们不会在每次修改代码后都手动部署应用程序。相反，我们将使用 GitHub Actions 来自动化这一流程！

1. 创建一个新的 GitHub 分支来保存我们的更改并执行 CI/CD 工作负载：

git remote set-url origin https://github.com/$GITHUB_USERNAME/Made-With-ML.git  # <-- 将此处替换为你的用户名
git checkout -b dev

2. 我们首先需要将必要的凭据添加到 GitHub 仓库的 /settings/secrets/actions 页面中。

export ANYSCALE_HOST=https://console.anyscale.com
export ANYSCALE_CLI_TOKEN=$YOUR_CLI_TOKEN  # 从 https://console.anyscale.com/o/madewithml/credentials 获取

3. 现在我们可以修改代码（不要在 main 分支上），并将更改推送到 GitHub。但为了将代码推送到 GitHub，我们需要先使用凭据进行身份验证：

git config --global user.name $GITHUB_USERNAME  # <-- 将此处替换为你的用户名
git config --global user.email you@example.com  # <-- 将此处替换为你的邮箱
git add .
git commit -m ""  # <-- 将此处替换为你的提交信息
git push origin dev

此时系统会提示你输入用户名和密码（个人访问令牌）。请按以下步骤获取个人访问令牌：新建 GitHub 个人访问令牌 → 输入名称 → 勾选 repo 和 workflow 权限 → 点击 Generate token（向下滚动）→ 复制生成的令牌，并在提示输入密码时粘贴该令牌。

4. 接下来，我们可以从该分支向 main 分支发起 Pull Request（PR），这将触发 workloads workflow。如果工作流（Anyscale Jobs）成功运行，它会直接在 PR 中添加包含训练和评估结果的评论。

5. 如果我们对结果满意，就可以将 PR 合并到 main 分支。这将触发 serve workflow，从而将我们的新服务部署到生产环境！

持续学习（Continual learning）

有了用于部署应用程序的 CI/CD 工作流后，我们现在可以专注于持续改进模型。在此基础上，我们可以轻松扩展，例如连接定时任务（cron）、数据管道、通过监控检测到的数据漂移、在线评估等。我们还可以轻松添加更多上下文信息，例如在 PR 中直接比较任意实验与当前生产环境中的模型效果等。

常见问题（FAQ）

Jupyter Notebook 内核（kernels）

在配置 Jupyter Notebook 内核时遇到问题？默认情况下，Jupyter 会使用我们虚拟环境中的内核，但我们也可以手动将其添加到 Jupyter：

python3 -m ipykernel install --user --name=venv

现在我们可以打开一个 Notebook → 点击顶部菜单栏的 Kernel（内核）→ Change Kernel（更换内核）→ 选择 venv。如果以后想删除这个内核，可以执行以下命令：

jupyter kernelspec list
jupyter kernelspec uninstall venv

Made-With-ML 快速上手指南

环境准备

• 操作系统：Linux / macOS / Windows（推荐 Linux 或 macOS）
• Python 版本：强烈推荐使用 Python 3.10
• 依赖工具：
  • git
  • pip
  • 推荐使用 pyenv（macOS/Linux）或 pyenv-win（Windows）管理 Python 版本
• 可选加速：如在国内，建议配置 PyPI 镜像源（如清华源）以加速依赖安装：

  pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
  

安装步骤

1. 克隆代码库

git clone https://github.com/GokuMohandas/Made-With-ML.git .

2. 配置环境变量

touch .env

编辑 .env 文件，填入你的 GitHub 用户名：

GITHUB_USERNAME="你的GitHub用户名"

然后加载环境变量：

source .env

3. 创建并激活虚拟环境（本地开发）

如果你使用 Anyscale 平台，此步可跳过。

export PYTHONPATH=$PYTHONPATH:$PWD
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
python3 -m pip install --upgrade pip setuptools wheel
python3 -m pip install -r requirements.txt
pre-commit install
pre-commit autoupdate

基本使用

方式一：交互式 Notebook（快速体验）

jupyter lab notebooks/madewithml.ipynb

打开后按顺序运行单元格，即可交互式体验数据处理、训练、调优等核心 ML 工作流。

方式二：命令行脚本（生产就绪实践）

训练模型（示例）

export EXPERIMENT_NAME="llm"
export DATASET_LOC="https://raw.githubusercontent.com/GokuMohandas/Made-With-ML/main/datasets/dataset.csv"
export TRAIN_LOOP_CONFIG='{"dropout_p": 0.5, "lr": 1e-4, "lr_factor": 0.8, "lr_patience": 3}'
python madewithml/train.py \
    --experiment-name "$EXPERIMENT_NAME" \
    --dataset-loc "$DATASET_LOC" \
    --train-loop-config "$TRAIN_LOOP_CONFIG" \
    --num-workers 1 \
    --cpu-per-worker 3 \
    --gpu-per-worker 0 \  # 若无 GPU，请设为 0
    --num-epochs 10 \
    --batch-size 256 \
    --results-fp results/training_results.json

注意：根据你的机器资源调整 --num-workers、--cpu-per-worker 和 --gpu-per-worker 参数。普通笔记本建议设置 --num-workers 4 --cpu-per-worker 1 --gpu-per-worker 0。

启动实验跟踪（MLflow）

export MODEL_REGISTRY=$(python -c "from madewithml import config; print(config.MODEL_REGISTRY)")
mlflow server -h 0.0.0.0 -p 8080 --backend-store-uri $MODEL_REGISTRY

启动后访问 http://localhost:8080 查看实验记录与模型版本。

现在你已准备好开始构建端到端的机器学习系统！更多内容请访问课程官网：https://madewithml.com/