# 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 实测 [![Gitee Star](https://gitee.com/kill-life/vllm-learn/badge/star.svg?theme=dark)](https://gitee.com/kill-life/vllm-learn/stargazers) [![Gitee Fork](https://gitee.com/kill-life/vllm-learn/badge/fork.svg?theme=dark)](https://gitee.com/kill-life/vllm-learn/members) ![vLLM](https://img.shields.io/badge/vLLM-v0.34.0-blueviolet) ![CUDA](https://img.shields.io/badge/CUDA-13.0-76b900) ![Python](https://img.shields.io/badge/Python-3.12-3776ab) ![License](https://img.shields.io/badge/License-Apache--2.0-blue)
--- ## 概述 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)。