Week 0 · 环境与工具链
目标：周末两天内能在云上 GPU 跑通 vllm serve，并提交一个空白 commit 的 fork PR 走通流程。
这一节不教 AI，只解决"我连环境都跑不起来"这个最劝退的问题。 vLLM 有 C++/CUDA 部分，新手最容易栽在这。读完这页后你应该有： 一份能复现的 Python 环境、一台能开关的云 GPU、一个 fork 好的 vLLM、和一次成功跑通的对话推理。
驱动问题
Apple Silicon Mac 上能真的学 vLLM 吗？还是必须先开云？
先猜，再看答案
能学，能贡献，不能跑大模型推理。
- Mac 上可以：读代码、跑 Python 部分的单测（vLLM 有大量 CPU-only 测试）、写 mini-vLLM、写 blog。
- Mac 上不行：跑 CUDA kernel、benchmark、用 7B+ 模型测延迟。这些必须上云。
- 实际节奏：90% 时间本地、10% 时间云上验证。云 GPU 按需开关，每月 $30–80 完全够。
01硬件实情核对
| 场景 | 最低 | 推荐 | 预算 |
|---|---|---|---|
| 读代码 / 跑 CPU 单测 / 写 blog | 任意笔记本 | 16GB RAM Mac/PC | $0 |
| 跑 7B fp16 推理 (验证) | A10 24GB (~$0.4/h) | A100 40GB | $30–80/月 |
| 跑 benchmark / 多并发压测 | A100 40GB | A100 80GB | $80–200/月 |
| 多卡 TP/PP 实验 (Month 4+) | 2× A10 | 2× A100 | $200+/月 |
| 训练 / 大模型微调 | 这不在本路径里。要做就单独申请实习或学校 cluster。 | ||
💡 GPU 怎么选 provider
都支持按秒计费 + 镜像快照。规则：每次开机最多 2 小时，下机前 push 代码 + 关机。
02本地环境（Mac / Linux 都行）
2.1 工具版本
# Python 3.11 (vLLM 当前支持 3.9-3.12，3.11 最稳)
python --version # → Python 3.11.x
# uv 是最快的 Python 包管理器，强推
curl -LsSf https://astral.sh/uv/install.sh | sh
# git 配好用户名 / SSH key
git config --global user.name "WeishuZ"
git config --global user.email "myludus@outlook.com"
2.2 Fork 并 clone vLLM
第一件事：到 vllm-project/vllm 点 fork。然后：
# 你的 fork
git clone git@github.com:WeishuZ/vllm.git
cd vllm
# 加 upstream remote，方便日后 sync 主仓
git remote add upstream https://github.com/vllm-project/vllm.git
git remote -v
# origin git@github.com:WeishuZ/vllm.git (fetch/push)
# upstream https://github.com/vllm-project/vllm.git (fetch/push)
2.3 安装（本地 CPU-only 模式）
在 Mac 上你不能编译 CUDA 部分，但可以装 CPU 版用来跑 Python 测试和读代码：
uv venv --python 3.11
source .venv/bin/activate
# vLLM 提供 CPU-only wheel（适合 Mac 阅读和单测）
VLLM_TARGET_DEVICE=cpu pip install -e . --extra-index-url https://download.pytorch.org/whl/cpu
# 或者只装 dev deps 不 build C++ 部分（更快，只能读代码不能 run）
pip install -r requirements/dev.txt
⚠ 编译易踩坑
vLLM 的 setup.py 会调 CMake 编译 C++/CUDA 部分。在 Mac 上首次 build 容易挂 —— 报错很正常。先 跳过 build，纯读源码，等上云再 build。
具体 build 文档：docs.vllm.ai/installation
2.4 pre-commit hooks
vLLM reviewer 看到没过 lint 的 PR 会直接关。装上 pre-commit，每次 commit 自动跑 ruff / mypy / typos：
pip install pre-commit
pre-commit install
pre-commit run --all-files # 第一次跑会慢，之后只检查 diff
03云上 GPU：第一次跑通
下面以 RunPod 为例（其他 provider 类似）。跟着做，全程不超过 30 分钟。
3.1 开机
- RunPod → Deploy → 选 Community Cloud → A10 24GB（spot $0.20–0.30/h）。
- 镜像：
runpod/pytorch:2.4.0-py3.11-cuda12.4.1-devel-ubuntu22.04。 - 磁盘：50GB volume 够（模型 ~14GB + 代码 + 缓存）。
- SSH 启用，开 port 8000。
- 点 Deploy → 30 秒后 SSH 上去。
3.2 装 vLLM
# 在 pod 内
git clone https://github.com/WeishuZ/vllm.git
cd vllm
# 用官方 wheel 装最新稳定版（推荐，省得 build CUDA）
pip install vllm
# 验证
python -c "import vllm; print(vllm.__version__)"
3.3 第一次推理
# 起 OpenAI-compatible server
vllm serve meta-llama/Llama-3.1-8B-Instruct \
--max-model-len 4096 \
--gpu-memory-utilization 0.85
# 等到看到 "Application startup complete." 约 60-90 秒
# 在另一个终端：
curl http://localhost:8000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "meta-llama/Llama-3.1-8B-Instruct",
"messages": [{"role": "user", "content": "用一句话解释 PagedAttention"}]
}'
✓ 这一步成功 = Week 0 已完成 70%
你现在有一台能 serve LLM 的机器。立刻看一下日志 —— vLLM 会打印它分配了多少 KV blocks、block size 多少。
这些数字将在 Month 2 里被你彻底理解。
3.4 下机习惯
# 退出 server，commit 任何改动
git add -A && git commit -m "wip: notes" && git push
# 立刻在 RunPod 控制台 Stop pod
# 不 stop 一直按时计费！
⚠ 账单事故
忘关 GPU 是最常见的破产事故。建议：
- 设手机闹钟 90 分钟提醒。
- RunPod 账户里设 spending limit（$50/月硬限）。
- 把 stop 操作写成 shell alias
alias byepod='runpodctl stop pod $POD_ID'。
04走通第一个 PR 流程（保底 PR）
Month 1 的 KPI 是"第一个 merged PR"，无论多小都行。 Week 0 末尾就先跑一遍 PR 流程，把陌生感消掉。
行动
vllm/docs/
打开 vLLM 文档目录，找一个 typo / 措辞不清 / 链接失效。有，几乎一定有。
把它修了，提一个 docs-only PR。
# 在 fork 里
git checkout -b docs/fix-typo
# 改 docs/source/xxx.md
git add docs/source/xxx.md
git commit -m "docs: fix typo in xxx"
git push -u origin docs/fix-typo
# 然后到 GitHub UI 提 PR，目标是 vllm-project/vllm:main
# 等 CI 跑完（约 10 分钟），把 reviewer 标签贴上
Reviewer 期望的最低标准
- PR 标题前缀：
docs:/[Bugfix]/[Core]/[Kernel]。看一眼最近 10 个 merged PR 学风格。 - 描述里至少写："改了什么 / 为什么改 / 怎么验证"。
- CI 必须全绿。pre-commit 红的话回去本地
pre-commit run --all-files修。 - 第一次提 PR 会被要求签 DCO，照 bot 提示来即可。
05选填：本地开发循环
如果你完全本地开发，下面这套 loop 最高效：
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│ Mac: 编辑代码 │ → │ git push to fork │ → │ pod: pull + 验证 │
│ (vim / cursor) │ │ (1s) │ │ (10s) │
└──────────────────┘ └──────────────────┘ └──────────────────┘
↑ │
└────────────────── iterate ────────────────────┘把 pod 当远程 runner。本地代码、远程执行。
或者直接 VSCode Remote SSH 进 pod 改代码，简单粗暴。