llm-inference

一个开箱即用的大模型推理工程学习环境。开机 5 分钟，就能在 JupyterLab 里跟着交互式教程，把「部署 → 监控 → 压测 → 量化 → 双引擎对决」全流程亲手做一遍。

配套开源教程仓库（十周图文笔记 + 全部实机数据 + 可复现脚本）：github.com/cypggs/llm-inference-mastery

镜像介绍

本镜像是一套完整的「LLM 推理工程师」实战教学环境，基于真实企业级推理栈构建，适合：

• 想从"会调 API"成长为推理系统工程师的开发者
• 需要为公司做模型部署 / 推理降本决策的工程师
• 准备推理方向面试的求职者

镜像内所有教程基于第一性原理展开：先用纸笔推导理论上限，再用真实 GPU 实测验证。例如手算 KV Cache 容量与 vLLM 实测误差仅 0.7%，让学习者建立扎实的工程直觉。

学习路线参考开源项目 patchy631/time-to-first-token（CC BY 4.0）的十周路线图，全部实验已在真实 GPU 上跑通并附实测数据。

功能特性

双推理引擎

• vLLM 0.28.0：OpenAI 兼容服务，已开启前缀缓存 / chunked prefill / CUDA Graph
• SGLang 0.5.19：RadixAttention 前缀复用引擎，可与 vLLM 做同模型正面对决实验

监控与压测全家桶

• Prometheus 3.14 + Grafana 13.2：已配置抓取 vLLM 全部 98 个指标，预置官方 12 面板 Dashboard（TTFT / ITL / 吞吐 / 队列深度 / KV Cache 水位）
• GuideLLM + 自研压测脚本：开环速率扫描 + 闭环并发扫描，找到系统拐点

7 个交互式教程 Notebook（JupyterLab 打开即学）

教程	内容
Week 1	心智模型：Roofline / 算术强度交互计算
Week 2	vLLM 部署 Qwen2.5-7B，实测验证理论上限
Week 3	用 PromQL 查询真实监控数据
Week 4	vLLM vs SGLang 前缀缓存对决（3360 token 共享前缀实测）
Week 5	GuideLLM 压测找系统拐点（含完整实测数据）
Week 6	FP8 在线量化三笔账：速度 ×1.58 / KV 池 +30% / 质量无损
Week 7	投机解码实测：98.6% 接受率仍减速的经典负结果案例

AI 编码助手 pi agent

• 已接入本地 Qwen2.5-7B 模型（vLLM / SGLang 双通道注册），终端里直接 pi 即可用本地模型驱动的 AI 编码助手

使用教程

第一步：一键启动全部服务

bash /workspace/start_monitoring.sh

该脚本自动启动 vLLM（:8000）+ Prometheus（:9090）+ Grafana（:3000），并打印全部访问入口。

第二步：打开 JupyterLab 学习

通过平台控制台的软件入口打开 JupyterLab，进入 workspace/ 目录，从 week01_mental_model.ipynb 开始按顺序学习，内核选择 py312。

第三步（可选）：监控面板

开放 3000 端口后访问 Grafana（admin / admin），左侧 Dashboards → vLLM，即可看到 TTFT、字间延迟、吞吐、KV Cache 水位等 12 个实时面板。

第四步（可选）：双引擎对决

bash /workspace/start_sglang.sh        # SGLang 起在 :8001
python3 /workspace/prefix_faceoff.py --url http://localhost:8001 --name SGLang

常用脚本一览

脚本	作用
start_monitoring.sh	一键启动 vLLM + 监控栈（幂等，可重复执行）
start_sglang.sh	启动 SGLang（:8001，含工具调用解析器）
run_guidellm.sh	GuideLLM 开环速率扫描
concurrency_sweep.py	闭环并发扫描（1→128 找拐点）
prefix_faceoff.py	前缀缓存对决测试

环境验证

本镜像在 RTX 5090（32GB） 上制作并完成全部实验验证，实测关键数据：

• 单流 decode 速度 104 tok/s（理论上限 118 tok/s 的 88%）
• KV Cache 池 253,056 token（与手算误差 0.7%）
• 并发 1→64，总吞吐 100 → 5317 tok/s（×53），单用户速度仅降 13%
• FP8 在线量化：单流 ×1.58，KV 池 +30%

建议 GPU：RTX 5090 / 4090（24GB+）即可完美运行；更大显存（A100 / H100，80GB）可挑战 1000 并发压测。

模型说明：教程默认使用平台共享模型库的 /model/ModelScope/Qwen/Qwen2.5-7B-Instruct。若实例所在区域无该共享盘，请先下载模型至本地，并修改各启动脚本中的模型路径。

常见问题

Q：vLLM 和 SGLang 能同时运行吗？

可以，但注意显存分配：vLLM 默认占用 90% 显存，SGLang 脚本已配置 40%。建议对决实验顺序进行（先测一边再测另一边），数据更干净。

Q：启动 vLLM 报 flashinfer 版本错误？

镜像已内置 FLASHINFER_DISABLE_VERSION_CHECK=1 绕过，使用 start_monitoring.sh 启动即可，无需手动处理。

Q：pi agent 怎么用？

终端直接输入 pi 即可，默认模型为本机 vLLM 服务的 Qwen2.5-7B；输入 /model 可切换到 SGLang 通道（sglang-local）。

Q：教程的实机数据在哪里？

Notebook 内嵌了全部实测输出与图表；原始压测数据和十周图文笔记见开源仓库 github.com/cypggs/llm-inference-mastery，欢迎 star 和 issue 交流。