# VllmLearn
**Repository Path**: kill-life/vllm-learn
## Basic Information
- **Project Name**: VllmLearn
- **Description**: Vllm学习仓库
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-19
- **Last Updated**: 2026-11-19
## Categories & Tags
**Categories**: Uncategorized
**Tags**: vllm, cuda, Docker, inference
## README
# VllmLearn
**从「跑起来」到「读懂源码」的 vLLM 深度学习工作台**
22 篇体系化中文教程 · 浏览器内源码探索器 · 一键 Docker 编排 · 结论全部来自双 RTX 3090 实测
[](https://gitee.com/kill-life/vllm-learn/stargazers)
[](https://gitee.com/kill-life/vllm-learn/members)




---
## 概述
VllmLearn 是一套可以直接运行起来的 vLLM 学习环境。执行 `docker compose up -d` 后,一个容器里同时启动 vLLM 服务(v0.34.0,OpenAI 兼容 API)和自研的浏览器探索器 vllm-explorer,配套 22 篇中文教程与 7 个可运行实验。
它解决的是学 vLLM 时三个具体问题:
- 概念讲完看不到对应数据——PagedAttention、前缀缓存、连续批处理这些机制,在教程里只能靠想象;
- 源码找不到入口——vLLM 代码量大,不知道从哪个文件读起;
- 教程里的数字没法验证——参数默认值、吞吐/TTFT、显存占用,大多是别人的机器和别人的版本。
在本项目中,每读完一个概念,都可以在浏览器里查看本机实例的实时指标、点开对应源码、发出真实请求,并运行实验脚本复现教程中的数字。教程覆盖从镜像选型与 Docker 部署,到 Prefill/Decode 本质、GPU 与指标原理、PagedAttention 与前缀缓存、双卡并行、结构化输出与工具调用、推测解码、量化、多模态、思考模型、嵌入与 RAG,最后到 v0.34 的引擎特性、参数默认值与部署实践。
---
## 本教程优势
- **讲原理时能看本机数据**:讲 PagedAttention,直接在 explorer 里看 KV 池水位、块利用率、前缀缓存命中数的实时曲线,再点开 `block_manager` 源码对照。
- **双卡不只讲参数**:给出双 3090 上 TP=1 与 TP=2 的吞吐、TTFT 对照,以及 NCCL 共享内存、无 NVLink 的实测与踩坑记录。
- **参数标注默认值与关键设计**:Extensible KV cache 的分配方式、block size 对前缀缓存的影响、工具调用解析器的选择、`max_tokens` 的输出上限语义,都给出默认值与判断依据。
- **数字可复现**:每个结论都附本机复现命令;`scripts/smoke-test.sh` 7 步验证、`bench-example.sh` 压测、`workspace/experiments/` 7 个实验都能直接重跑。
- **默认部署即可用**:已处理实际踩过的坑——`--served-model-name` 决定客户端 model id、`--enable-auto-tool-choice --tool-call-parser qwen3_xml` 让工具调用生效、MTP 推测解码默认开启(实测 C=1 +83%、C=16 +40%)、端口默认对局域网开放,装完即可被其他机器调用。
- **阅读、源码、调试在同一界面**:explorer 内置 24 篇文档阅读器、源码跳转、全文搜索、API 调试与容器内交互式终端,不用在编辑器和终端之间来回切。
---
## 组成
| 组件 | 内容 | 规模 |
|---|---|---|
| [`docs/`](docs/) | 22 篇编号教程 + 2 个附录 + 学习地图 | 约 14.3 万字 |
| [`tools/vllm-explorer/`](tools/vllm-explorer/) | 自研浏览器探索器,跑在 vLLM 容器内,14 个路由视图 | 1.3k Python + 3.0k JS + 0.7k CSS |
| [`docker/`](docker/) | 单容器同时跑 vLLM 服务与 explorer,默认监听 0.0.0.0 | 1 个 compose 文件 |
| [`scripts/`](scripts/) | 环境自检 / 模型软链接 / 冒烟测试 / 压测示例 | 4 个脚本 |
| [`workspace/`](workspace/experiments/) | 挂载进容器的实验代码,宿主机改完容器内立即生效 | 7 个实验 |
| [`site/`](site/) | 教程站点构建产物(mkdocs-material),可直接用于 Gitee Pages | 72 个文件 |
---
## 架构
```text
宿主机 容器 vllm-learn (gpus: all)
┌──────────────────────────────────────┐ ┌────────────────────────────────────────────┐
│ docker/.env │ │ entrypoint.sh │
│ ├─ VLLM_IMAGE / VLLM_MODEL │ │ ├─ python3 /opt/vllm-explorer/app.py │
│ ├─ VLLM_EXTRA_ARGS │ │ │ └─ :8080 ← 浏览器 <本机IP>:18082 │
│ └─ HOST_MODELS_DIR ─────────────┐ │ │ └─ vllm serve ... --host 0.0.0.0 :8000 │
│ │ │ │ ├─ OpenAI 兼容 API │
│ workspace/ ──────────────────────┼──┼──▶│ └─ /metrics · /server_info · 开发端点 │
│ ├─ experiments/*.py │ │ │ │
│ └─ models/qwen3.5-4B ──软链接──▶│ │ │ 挂载: │
│ │ │ │ /vllm-workspace/learn ← workspace/ │
│ 真实权重目录 ◀─── 同路径只读挂载 ─┘ │ │ /vllm-workspace/learn-docs ← docs/ │
│ │ │ /opt/vllm-explorer ← tools/ │
│ docs/ ──────────────────────────────┼──▶│ $HOST_MODELS_DIR (相同绝对路径, :ro) │
└──────────────────────────────────────┘ └────────────────────────────────────────────┘
│
explorer ───────────────┘
├─ 概览 / GPU / 实时 LIVE 曲线
├─ 文件与源码浏览(带行号、语法高亮、Markdown 渲染)
├─ 全文搜索(vLLM 源码,支持 glob)
├─ API 实验台(含 SSE 流式渲染)
└─ 架构可视化(由本机 server_info 驱动)
```
**关键设计**:模型权重通过 `workspace/models/` 里的软链接引用,软链接目标必须**以相同绝对路径**只读挂进容器,否则容器内链接悬空 —— 这就是 `HOST_MODELS_DIR` 存在的原因。
---
## 快速开始
### 前置条件
| 项目 | 要求 | 说明 |
|---|---|---|
| GPU | NVIDIA,显存 ≥ 16GB(本项目实测 2×RTX 3090 24GB) | CUDA 13 镜像要求 Ampere 及以上(sm_80+) |
| 驱动 | ≥ 580(CUDA 13.0 镜像) | 跑 `bash scripts/check-env.sh` 自动判定 |
| Docker | Docker 24+ 与 Compose v2 | 需要 `nvidia-container-toolkit`(`gpus: all` 语法) |
| 磁盘 | 镜像约 36GB + 模型权重 | 4B 模型约 8.8GB(bf16) |
| 系统 | Linux(路径与软链接依赖 Linux 语义) | 本项目在 Ubuntu 24.04 实测 |
### 三步启动
```bash
# 0. 环境自检(可选):检测 GPU / 驱动 / Docker / 本地镜像并给出镜像选型建议
bash scripts/check-env.sh
# 1. 准备配置
cp .env.example docker/.env
# · 用本地权重:在 docker/.env 里设置 HOST_MODELS_DIR=/path/to/models
# · 用在线权重:把 VLLM_MODEL 改成 HF 名称,如 VLLM_MODEL=Qwen/Qwen3-1.7B
# 2. 启动(vLLM 服务 + explorer 在同一容器)
cd docker && docker compose up -d
docker compose logs -f # 等待 "Application startup complete"
# 3. 冒烟测试(健康检查 → 模型列表 → 对话 → 结构化输出 → 前缀缓存 → 工具调用 → 推测解码)
cd .. && bash scripts/smoke-test.sh
```
期望输出(节选):
```text
[·] 1/7 健康检查 GET /health
[✓] health OK
[·] 2/7 模型列表 GET /v1/models → qwen3.5-4B
[·] 3/7 OpenAI 兼容对话 /v1/chat/completions
[✓] chat OK
...
[✓] 5/7 前缀缓存命中(第二次请求的 cached token 显著增大)
[✓] 6/7 工具调用 OK(parser 与模型匹配)
[✓] 7/7 推测解码 OK(MTP 草稿被接受)
```
### 打开入口
| 入口 | 本机地址 | 局域网地址 | 用途 |
|---|---|---|---|
| vllm-explorer | | `http://<本机IP>:18082` | 教程阅读 + 源码浏览 + API 实验 + 容器内终端 + GPU/KV 观测 |
| vLLM API | | `http://<本机IP>:8000` | OpenAI 兼容接口(`/v1/chat/completions` 等) |
| Swagger | | `http://<本机IP>:8000/docs` | vLLM 自带交互式文档 |
| 教程站点(可选) | | `http://<本机IP>:18083` | nginx 托管的静态站点,见「文档站」 |
端口**默认监听 `0.0.0.0`**,同一局域网的其他机器直接用上面第二列地址即可调用模型。查本机内网 IP:
```bash
ip -4 addr show scope global | awk '{print $2, $4}' | grep -v docker
```
只想本机访问时,把 `docker/docker-compose.yml` 的端口映射改回 `127.0.0.1:8000:8000` / `127.0.0.1:18082:8080`。
> **暴露到局域网时的安全提醒**:explorer 能浏览容器文件、vLLM 默认未开 api-key。建议在 `docker/.env` 设 `EXPLORER_TOKEN`(浏览器首访 `http://<本机IP>:18082/?token=密钥` 即记住令牌),并在需要鉴权时给 `VLLM_EXTRA_ARGS` 追加 `--api-key <密钥>`。
---
## 教程地图
按学习顺序组织,与 `mkdocs.yml` 导航一致。
### 第一段:跑起来
| # | 教程 | 内容 |
|---|---|---|
| 00 | [快速开始(镜像选型)](docs/00-quick-start.md) | 三层关系(驱动/CUDA/镜像)、本机盘点、最小可用启动 |
| 01 | [全景与核心概念](docs/01-overview.md) | vLLM 定位、OpenAI 兼容双入口、硬件覆盖、版本演进 |
| 02 | [总体架构](docs/02-architecture.md) | EngineCore / Scheduler / KV Cache / Worker 分层 |
| 03 | [Docker 部署实战](docs/03-docker-deployment.md) | compose 逐行解读、权重挂载、端口与健康检查 |
### 第二段:本质与硬件
| # | 教程 | 内容 |
|---|---|---|
| 15 | [大模型推理的本质](docs/15-inference-essentials.md) | prefill/decode 两阶段、算术强度、显存带宽瓶颈 |
| 16 | [GPU 运行原理(3090 实测)](docs/16-gpu-primer.md) | SM/Tensor Core/显存带宽实测、算力与容量账本 |
| 17 | [推理服务指标手册](docs/17-metrics-handbook.md) | TTFT/TPOT/ITL/吞吐、P50-P99、指标之间的因果链 |
### 第三段:吃透原理
| # | 教程 | 内容 |
|---|---|---|
| 04 | [引擎参数全解](docs/04-server-args.md) | 参数分类、默认值出处、当前版本的关键设计 |
| 05 | [请求的一生(源码走读)](docs/05-request-lifecycle.md) | 从 HTTP 到 Scheduler 再到 Tokenizer/Worker 的完整链路 |
| 06 | [PagedAttention 与前缀缓存](docs/06-paged-attention.md) | 分页 KV 管理、块分配、前缀缓存命中实测 |
| 07 | [双卡并行 TP/PP/DP/EP](docs/07-multi-gpu-parallel.md) | 四种并行切分、双 3090 实测与 NCCL 踩坑 |
### 第四段:高阶能力
| # | 教程 | 内容 |
|---|---|---|
| 08 | [结构化输出](docs/08-structured-output.md) | `response_format` / guided_json / regex / choice 与工具调用 |
| 09 | [推测解码全景](docs/09-speculative-decoding.md) | draft 模型、EAGLE3、MTP、接受率与加速比账本 |
| 18 | [多模态推理原理](docs/18-multimodal-deep-dive.md) | 图像 token 化、视觉编码器与调度影响 |
| 19 | [思考模型与思考预算](docs/19-thinking-models.md) | reasoning parser、思考预算控制、长输出对服务的影响 |
| 10 | [量化部署](docs/10-quantization.md) | FP8/INT4/AWQ/GPTQ、精度与吞吐权衡、sm_86 支持边界 |
| 11 | [离线 LLM API](docs/11-offline-llm-api.md) | `LLM`/`SamplingParams`、批量异构、与在线服务差异 |
| 12 | [压测观测与生产化](docs/12-benchmarking.md) | `vllm bench serve`、阶梯并发摸底、生产化检查单 |
| 13 | [高阶专题](docs/13-advanced-topics.md) | LoRA、`/sleep` 显存换出、权重热更新、开发端点 |
| 20 | [嵌入与重排模型(JEV 实战)](docs/20-embedding-models.md) | Jina Embeddings V5 部署 + 本地 RAG 最小闭环 |
### 第五段:版本与查阅
| 文档 | 内容 |
|---|---|
| [21 v0.34 特性与参数全解](docs/21-v034-features.md) | 执行引擎、KV cache、推测解码、API 面、参数速查与本机实测 |
| [14 FAQ 与踩坑手册](docs/14-faq.md) | 启动失败、显存不足、端口冲突、驱动不匹配等 |
| [附录 A · 源码阅读路线图](docs/appendix-a-source-map.md) | 从入口文件到核心模块的推荐阅读顺序 |
| [附录 B · 多模态与 API 生态](docs/appendix-b-multimodal-and-apis.md) | embeddings / rerank / responses 等端点速查 |
---
## vllm-explorer
自研浏览器工作台,纯 Python + 原生 JS,**无前端构建步骤**,跑在 vLLM 容器内(`/opt/vllm-explorer`)。
| 页面 | 能力 |
|---|---|
| 概览 | 服务健康、版本、GPU 状态、当前模型配置 |
| 学习地图 | 24 篇文档(22 教程 + 2 附录)内置阅读器,进度记录在浏览器本地 |
| 文件 / 源码 | 浏览容器内任意目录,带行号与语法高亮;Markdown 直接渲染 |
| 全文搜索 | 对 vLLM 源码 grep,支持 glob 过滤 |
| API 实验台 | 代理 `/v1/*`,支持 SSE 流式渲染与 token 速率统计 |
| 终端 | 容器内交互式 bash(PTY over WebSocket + xterm.js),可跑 `nvidia-smi` / `htop` / `vim` 等全屏程序,窗口尺寸与浏览器同步 |
| 指标 / 仪表盘 | `/metrics` 解读、KV 池水位、吞吐曲线 |
| 可视化 | 由本机真实 `server_info` 驱动的执行流程与调度器模拟 |
| 系统 | 环境变量、版本、磁盘、pip 包清单 |
安全边界:**终端页可执行任意命令**(等同于 `docker exec -it vllm-learn bash`,以 root 运行),其余页面为只读观测。设置容器环境变量 `EXPLORER_TOKEN` 可启用访问令牌(浏览器首访 `/?token=密钥` 自动记住,WebSocket 终端同样校验);端口默认监听 `0.0.0.0`,局域网可达,**公网暴露前必须加令牌并配合防火墙**。
---
## 目录结构
```text
VllmLearn/
├── README.md
├── mkdocs.yml # 教程站点配置(mkdocs-material)
├── .env.example # Docker 环境变量模板(复制为 docker/.env)
├── docs/ # ★ 22 篇教程 + 2 附录 + 学习地图
├── site/ # 站点构建产物(可直接用于 Gitee Pages)
├── docker/
│ ├── docker-compose.yml # vLLM 服务 + explorer 同容器编排
│ ├── docker-compose.docs.yml # 教程站点静态部署(nginx,可选)
│ └── nginx-docs.conf # 站点 gzip / 缓存 / 404 配置
├── tools/
│ └── vllm-explorer/ # ★ 浏览器探索器(app.py / viz.py / static/)
├── scripts/
│ ├── check-env.sh # GPU/驱动/Docker/镜像选型自检
│ ├── link-model.sh # 本地权重软链接
│ ├── smoke-test.sh # 7 步冒烟测试(含工具调用与 MTP)
│ └── bench-example.sh # vllm bench serve 压测示例
└── workspace/
├── models/ # 权重软链接目录(权重本体不入库)
└── experiments/ # 7 个可运行实验
```
---
## 配置参考
`docker/.env` 由 `.env.example` 复制而来,全部变量均有默认值:
| 变量 | 默认值 | 说明 |
|---|---|---|
| `VLLM_IMAGE` | `vllm/vllm-openai:v0.34.0` | 官方 CUDA 13.0 构建;仅此一种构建,驱动需 ≥580 |
| `VLLM_MODEL` | `/vllm-workspace/learn/models/qwen3.5-4B` | 容器内路径,或 HF 名称(如 `Qwen/Qwen3-8B`) |
| `VLLM_EXTRA_ARGS` | `--served-model-name qwen3.5-4B --enable-auto-tool-choice --tool-call-parser qwen3_xml --speculative-config '{"method":"mtp","num_speculative_tokens":2}' --max-model-len 32768 --enable-prefix-caching` | 透传给 `vllm serve`;`--served-model-name` 决定 model id,`qwen3_xml` 与本机模型输出格式匹配(写 `hermes` 会 `tool_calls=null`),`--speculative-config` 为 MTP 推测解码(去掉即关闭);一般**不设** `--gpu-memory-utilization`(Extensible KV cache 按实际空闲显存分配) |
| `HOST_MODELS_DIR` | `/opt/vllm-models` | 宿主机权重目录,以**相同绝对路径**只读挂进容器 |
| `HF_ENDPOINT` | `https://hf-mirror.com` | 国内下载加速;已禁用 `hf_xet` 以免绕过镜像 |
| `VLLM_CACHE_ROOT` | `/root/.cache/vllm` | torch.compile / CUDA Graph 缓存,避免重启重编译 |
| `VLLM_SERVER_DEV_MODE` | `1` | 打开 `/server_info`、`/sleep`、`/start_profile` 等;**生产务必改 0** |
| `TZ` | `Asia/Shanghai` | 容器时区 |
`EXPLORER_TOKEN` 默认留空(不鉴权),compose 已透传:在 `docker/.env` 中取消 `.env.example` 里对应注释并填入密钥即可启用(浏览器首访 `/?token=密钥` 自动记住)。
---
## 常用命令
```bash
cd docker
docker compose up -d # 启动
docker compose down # 停止(保留缓存卷)
docker compose logs -f vllm # 跟踪日志
docker compose exec vllm bash # 进容器
docker compose ps # 看健康状态
# 换模型(本地权重)
cd .. && bash scripts/link-model.sh qwen3.5-9B /path/to/models/qwen3.5-9B
# 然后编辑 docker/.env:VLLM_MODEL=/vllm-workspace/learn/models/qwen3.5-9B
# 双卡:VLLM_EXTRA_ARGS 追加 --tensor-parallel-size 2
bash scripts/smoke-test.sh # 7 步冒烟(含工具调用与 MTP)
bash scripts/bench-example.sh # 压测示例(容器内执行)
bash scripts/check-env.sh # 环境自检
# 教程站点(独立编排,可单独起停)
docker compose -f docker-compose.docs.yml up -d # http://127.0.0.1:18083
docker compose -f docker-compose.docs.yml down
```
运行时实验:
```bash
cd docker && docker compose exec vllm bash
python3 /vllm-workspace/learn/experiments/01_hello_vllm.py
VLLM_TP=2 python3 /vllm-workspace/learn/experiments/05_offline_batch.py
```
---
## 实测环境
| 项目 | 实测情况 |
|---|---|
| GPU | 2 × NVIDIA RTX 3090(Ampere,sm_86,各 24GB) |
| 驱动 | 580.178.04(`nvidia-smi` 报告支持到 CUDA 13.0) |
| 镜像 | `vllm/vllm-openai:v0.34.0`(python 3.12 / torch 2.14.0+cu130) |
| 系统 | Ubuntu 24.04 LTS,Docker 29.x + Compose v2 |
| 默认模型 | 本地 `qwen3.5-4B`(bf16,约 8.8GB) |
教程里的行号、文件名、参数默认值均以 **vLLM v0.34.0** 为准,跨版本请以 release notes 校正。
---
## 文档站
`docs/` 用 [mkdocs-material](https://squidfunk.github.io/mkdocs-material/) 构建,产物 `site/` 已随仓库提交:
```bash
pip install mkdocs mkdocs-material
mkdocs serve -a 127.0.0.1:18999 # 开发预览(热重载,避开 vLLM 的 8000)
mkdocs build --clean # 重新生成 site/(改完 docs/ 后请重新构建再提交)
```
流程图用 mermaid 写(```` ```mermaid ```` 代码块):`mermaid.js` 已 vendor 到 `docs/javascripts/`,Material 检测到 `window.mermaid` 已存在就不再回源 unpkg,内网/离线也能渲染;`docs/stylesheets/mermaid.css` 把图放宽到 1100px 并居中,避免宽图被 688px 的正文栏压到看不清。explorer 的教程阅读器用的是同一份 Markdown,服务端把 mermaid 块原样输出、浏览器端渲染(宽图保留原尺寸并横向滚动)。
**本地部署(nginx,适合长期运行/局域网分享)**:
```bash
cd docker
docker compose -f docker-compose.docs.yml up -d # http://127.0.0.1:18083
docker compose -f docker-compose.docs.yml logs -f # 看访问日志
```
容器以只读方式挂载 `site/`,根目录 `mkdocs build --clean` 后刷新即生效,无需重启容器。已开启 gzip(搜索索引 368KB → 106KB)、主题资源 30 天 immutable 缓存、HTML/JSON 5 分钟短缓存,并提供自定义 404 页。端口默认监听 `0.0.0.0`,局域网访问 `http://<本机IP>:18083`;只允许本机时改回 `127.0.0.1:18083:80`。
**发布到 Gitee Pages**:仓库 → 服务 → Gitee Pages,部署分支选 `main`,部署目录填 `site`。注意 Gitee Pages 需要实名认证,且每次更新 `site/` 后需手动点「更新」。
---
## 常见问题
| 现象 | 定位 |
|---|---|
| 容器起来了但模型加载失败 | `docker compose logs -f` 找 `HOST_MODELS_DIR` 是否指向真实权重;软链接目标是否以相同路径挂进容器 |
| `CUDA out of memory` | 降 `--gpu-memory-utilization`、降 `--max-model-len`、确认没有别的进程占卡 |
| 宿主机 `curl 127.0.0.1:8000` 不通 | 容器内必须 `--host 0.0.0.0`;端口映射是否被改 |
| explorer 打不开 | 默认监听 0.0.0.0,确认端口映射未被改回 `127.0.0.1`;`docker compose ps` 看容器健康状态;explorer 崩溃不影响 vLLM 主服务 |
| 驱动太旧、镜像起不来 | `bash scripts/check-env.sh` 会给镜像 tag 建议 |
完整清单见 [14 · FAQ 与踩坑手册](docs/14-faq.md)。