Week 0 · 环境与工具链

目标：周末两天内能在云上 GPU 跑通 vllm serve，并提交一个空白 commit 的 fork PR 走通流程。

这一节不教 AI，只解决"我连环境都跑不起来"这个最劝退的问题。 vLLM 有 C++/CUDA 部分，新手最容易栽在这。读完这页后你应该有： 一份能复现的 Python 环境、一台能开关的云 GPU、一个 fork 好的 vLLM、和一次成功跑通的对话推理。 全程预算控制在 $5 以内。

01硬件实情核对

02本地环境（Mac / Linux 都行）

2.1 工具版本

# Python 3.11 (vLLM 当前支持 3.9-3.12，3.11 最稳)
python --version    # → Python 3.11.x

# uv 是最快的 Python 包管理器，强推（比 pip 快 10-100×）
curl -LsSf https://astral.sh/uv/install.sh | sh

# git 配好用户名 / SSH key
git config --global user.name "WeishuZ"
git config --global user.email "你的邮箱"
ssh-keygen -t ed25519 -C "你的邮箱"        # 然后把 ~/.ssh/id_ed25519.pub 加到 GitHub

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)

# 同步上游 main
git fetch upstream
git checkout main
git merge upstream/main
git push origin main

2.3 安装（本地 CPU-only 模式）

在 Mac 上你不能编译 CUDA 部分，但可以装 CPU 版用来跑 Python 测试和读代码：

uv venv --python 3.11
source .venv/bin/activate

# 方案 A · CPU-only wheel (适合阅读代码 + 单测)
VLLM_TARGET_DEVICE=cpu pip install -e . \
  --extra-index-url https://download.pytorch.org/whl/cpu

# 方案 B · 只装 dev deps，不 build C++（最快，只能读代码不能 run）
pip install -r requirements/dev.txt

# 验证 (方案 A 才行)
python -c "import vllm; print(vllm.__version__)"

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

# 常见报错快速修
ruff check --fix              # 自动修可修的
mypy vllm/                    # 类型问题，手动修
typos                         # 错别字

2.5 IDE 配置（可选但强推）

用 VSCode + Cursor / IntelliJ，配几个插件让阅读速度翻倍：

• Python (Microsoft) + Pylance · 跳转到定义、查类型
• CUDA C++ · 高亮 .cu 文件
• Git Lens · 看每行的 blame，知道这行代码"为什么被加进来"——读 vLLM 历史变更必备
• Project Manager · vLLM + 你的 fork + mini-vLLM 切换

03云上 GPU：第一次跑通

下面以 RunPod 为例（其他 provider 类似）。跟着做，全程不超过 30 分钟。

3.1 开机

1. RunPod → Deploy → 选 Community Cloud → A10 24GB（spot $0.20–0.30/h）。
2. 镜像：runpod/pytorch:2.4.0-py3.11-cuda12.4.1-devel-ubuntu22.04。
3. 磁盘：50GB volume 够（模型 ~14GB + 代码 + 缓存）。
4. SSH 启用，开 port 8000（vLLM 默认）。
5. 点 Deploy → 30 秒后 SSH 上去。

3.2 装 vLLM

# 在 pod 内
git clone https://github.com/WeishuZ/vllm.git
cd vllm

# 选项 A · 用官方 wheel（推荐，省得 build CUDA）
pip install vllm

# 选项 B · 从源 build（你要改 C++/CUDA 代码时用）
pip install -e . --verbose

# 验证
python -c "import vllm; print(vllm.__version__)"
nvidia-smi                         # 看 GPU 状态

3.3 第一次推理

# 起 OpenAI-compatible server
vllm serve meta-llama/Llama-3.1-8B-Instruct \
  --max-model-len 4096 \
  --gpu-memory-utilization 0.85

# 第一次跑：下载模型 ~14GB，要 2-3 分钟（用了 HF cache 后秒级）
# 等到看到 "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"}]
  }'

GPU KV cache size: X tokens
Maximum concurrency for Y tokens per request: Z.NNx

3.4 下机习惯

# 退出 server (Ctrl-C)，commit 任何改动
git add -A && git commit -m "wip: notes" && git push

# 立刻在 RunPod 控制台 Stop pod
# 不 stop 一直按时计费！

04故障排查矩阵

常见症状 → 最可能原因 → 排查步骤：

05本地开发循环

如果你完全本地开发，下面这套 loop 最高效：

┌──────────────────┐    ┌──────────────────┐    ┌──────────────────┐
│ Mac: 编辑代码    │ →  │ git push to fork │ →  │ pod: pull + 验证 │
│ (vim / cursor)   │    │ (1s)             │    │ (10s)            │
└──────────────────┘    └──────────────────┘    └──────────────────┘
       ↑                                                  │
       └──────────────────  iterate  ────────────────────┘

或者直接 VSCode Remote SSH 进 pod 改代码——简单粗暴，所有 IDE 体验都在 pod 上。

5.1 VSCode Remote SSH 极简设置

# 本地 ~/.ssh/config
Host runpod
    HostName ssh.runpod.io
    Port 12345          # 看 pod console 给的端口
    User root
    IdentityFile ~/.ssh/id_ed25519
    LocalForward 8000 localhost:8000   # 本地能 curl pod 的 server

# VSCode 装 Remote-SSH 扩展
# Command Palette → Remote-SSH: Connect to Host... → runpod

这样在 Mac 上 curl http://localhost:8000/... 就直接打到 pod 的 vLLM server，因为端口被 forward。

06走通第一个 PR 流程（保底 PR）

Month 1 的 KPI 是"第一个 merged PR"，无论多小都行。 Week 0 末尾就先跑一遍 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 标签贴上
# 注意 DCO 签署：commit message 末尾要有 "Signed-off-by: Your Name "
# 用 git commit -s 自动加

6.1 Reviewer 期望的最低标准

• PR 标题前缀：[Doc] · [Bugfix] · [Core] · [Kernel] · [Hardware][AMD]。看一眼最近 10 个 merged PR 学风格。
• 描述里至少写："改了什么 / 为什么改 / 怎么验证"。模板就在 .github/PULL_REQUEST_TEMPLATE.md。
• CI 必须全绿。pre-commit 红的话回去本地 pre-commit run --all-files 修。
• 第一次提 PR 会被要求签 DCO（Developer Certificate of Origin），照 bot 提示来：git rebase --signoff。
• 非 trivial PR 通常要测试。看 tests/ 目录类似 case 的写法。

6.2 PR 卡 review 怎么办

• 5 天没人看 → 礼貌 ping 一次：@reviewer-name PTAL when you have a moment, thanks!
• 10 天还没看 → 到 vLLM 官方 Slack 的 #vllm-dev 频道发链接
• 不要纠结一个 PR 卡住——同时推进下一个，多个 PR 并行

07HuggingFace cache 与磁盘

HF model cache 默认在 ~/.cache/huggingface/，大文件多。两个建议：

1. cache 放在 volume 上，不要放在容器内（pod 关机会丢）：

   export HF_HOME=/workspace/.hf_cache
   mkdir -p $HF_HOME

2. 用 hf_transfer 加速下载：

   pip install hf_transfer
   export HF_HUB_ENABLE_HF_TRANSFER=1
   # 下载 Llama 8B 从 ~3 分钟 → ~30 秒

08本页自检