vLLM 依赖管理：从 20 个文件到 1 个 requirements 的正确选择路径

vLLM 依赖管理从 20 个文件到 1 个 requirements 的正确选择路径【免费下载链接】vllmA high-throughput and memory-efficient inference and serving engine for LLMs项目地址: https://gitcode.com/GitHub_Trending/vl/vllm凌晨两点新 A100 机器上一条pip install -r requirements/cuda.txt跑起了服务。一开 JSON 结构化输出却报No module named xgrammar同事机器上同版本却一切正常。排查半天才发现那台机器是旧镜像依赖早就齐了。vLLM 的 requirements 目录里躺着 20 个文件看起来是一堆版本号选错一个就是版本地狱。读完这篇你能在 30 秒内判断自己的环境该装哪个文件以及每个版本号为什么这么钉。全景requirements 目录如何分层requirements 目录按场景而非包名拆分基础层全平台共用每个硬件适配文件一行继承基础层后补上自己的 torch 与 kernel 栈功能扩展层再按开发、测试场景叠加。基础层common.txt 钉了什么、为什么这一层解决模型加载、API 服务、结构化输出缺什么就少什么的问题。50 来个公共包钉法分三种只给下限如pydantic 2.12.0再加上限如fastapi 0.133.0, 0.137.0以及条件依赖根据运行平台自动切换只在列出的架构上安装。前两种管版本上下限第三种管装不装。依赖约束为什么这么钉fastapi 0.133.0, 0.137.00.133 起支持 Starlette 1.0上限规避路由树变更破坏 handler 覆盖starlette 1.0.11.0.1 修复 Host 头注入漏洞protobuf 5.29.6 加一串 ! 排除6.30 至 6.33 区间多个版本有兼容问题逐一跳过xgrammar 0.2.1, 1.0.0限架构只在 x86_64/aarch64 等可编译架构安装条件依赖跳过其余平台safetensors 0.6.20.6.0 起才支持 MXFP4/MXFP6 dtypetransformers 5.10.4模型结构与权重加载的下限新模型依赖新版能力xgrammar 0.2.1, 1.0.0; platform_machine x86_64 or platform_machine aarch64 or ...分号后面就是条件依赖的标记pip 命中架构才装否则静默跳过。所以非 x86 机器上缺结构化输出组件不是错误是设计如此。protobuf 那一行是全文件最长的排除列表原因写在注释里多个中间版本有 gRPC 兼容问题只能逐个跳过。硬件适配层每种硅片选自己的 torch这一层解决同一份 Python 代码、五种底层栈的问题。每个文件第一行都是-r common.txt继承基础层再钉本硬件的 torch 和 kernel 栈。torch 是全文件最大的变量NVIDIA 环境严格钉死 2.13.0因为 flashinfer、CUTLASS DSL 等 kernel 包都是对着这个版本编译测试的浮动升级会悄悄换掉 ABI。文件硬件关键钉版钉版原因cuda.txtNVIDIA GPUtorch2.13.0flashinfer-python0.6.17kernel 栈均按 2.13.0 编译验证cpu.txtCPU onlytorch2.13.0cpucpu 后缀防止误装 CUDA 运行库rocm.txtAMD GPUgRPC 两包同钉 1.78.0两个 gRPC 库版本必须互相一致tpu.txtTPUtpu-inference0.27.0 rayTPU 运行时是成套方案xpu.txtIntel GPUtriton3.7.2xpuXPU 专属 Triton 构建不在 PyPI⚠️ torch 的卫星包torchvision、torchaudio、torchcodec必须和 torch 一起升级cuda.txt 的注释原话就是 must be updated alongside torch。torch2.13.0 torchvision0.28.0 # must be updated alongside torchcpu.txt 把 torch 拆成两行x86_64、aarch64、s390x 走 cpu 构建macOS 和 PowerPC 用普通 2.13.0。这是基础层条件依赖思想的复用——只是把标记从装不装挪到了装哪个版本。功能扩展层按场景才装这一层解决别逼所有人背全套工具的问题。dev.txt 本身只有 2 行引用 lint.txtpre-commit 风格检查和 test/cuda.txt文件里还有句注释别直接往我身上加依赖改我引用的那 2 个文件。test/cuda.txt 不是手写约束文件是锁定文件lock file由 uv 生成每个包标注精确版本和被谁引入作用是让本地与 CI 的测试环境逐字节一致。kv_connectors.txt 面向分布式 KV 缓存场景依赖 lmcache、nixl、mooncakeROCm 另有一份 kv_connectors_rocm.txt。docs.txt 同样是 uv 锁与主环境隔离专门构建文档站。test/ 目录下还有按硬件拆分的测试变体与 nightly PyTorch 验证文件用于提前验证下一代 PyTorch 的兼容性。文件作用备注dev.txt开发工具链等于 lint test/cuda.txt 两份引用test/cuda.txt测试环境锁定uv 生成版本与来源全标注kv_connectors.txtKV 缓存连接器lmcache nixl mooncakedocs.txt文档站锁定独立环境不影响推理环境按硬件选安装命令对号入座复制对应命令即可。生产环境如果是 NVIDIA GPU 生产环境 →pip install -r requirements/cuda.txt文件内已声明 flashinfer 的 wheel 源pip 会自动解析不用手动加 index如果是 AMD ROCm 环境 →pip install -r requirements/rocm.txttorch 版本跟随 ROCm 官方流程文件内不硬钉如果无 GPU只做功能验证 →pip install -r requirements/cpu.txtx86_64 自动选 cpu 构建如果是 TPU 集群 →pip install -r requirements/tpu.txtray 与 tpu-inference 成套引入如果需要 KV 缓存卸载或分布式缓存 → 追加pip install -r requirements/kv_connectors.txtROCm 用 kv_connectors_rocm.txt开发环境如果要贡献源码 →pip install -r requirements/dev.txt一次性拿到 pre-commit 风格检查与完整测试锁即完整开发环境测试环境如果要跑全量测试或复现 CI →pip install -r requirements/test/cuda.txt直接装锁文件环境与 CI 完全一致、可复现三个高频依赖坑flashinfer 单包安装失败 症状Could not find a version that satisfies the requirement flashinfer-python0.6.17 根因该包已不在 PyPI只在官方 wheel 源 ✅ 解法pip install -r requirements/cuda.txt 验证pip show flashinfer-pythontorch 卫星包版本错位 症状导入时报 undefined symbol 或版本不匹配告警 根因卫星包被手动装到了与 torch 不同的版本 ✅ 解法pip install torch2.13.0 torchvision0.28.0 torchaudio2.11.0 验证python -c import torch, torchvision; print(torch.__version__)改了本地代码行为却不变 症状修改 vllm 源码后运行行为完全没变化 根因环境装的是发布 wheel 而非本地源码 ✅ 解法pip uninstall vllm pip install -e . 验证python -c import vllm; print(vllm.__file__)确认指向源码目录依赖管理的下一步uv 化的锁定方案已经落到文档与测试docs.txt、test/cuda.txt 都是 uv 生成的锁未来很可能一条uv sync直接搭好任意硬件的完整环境。建议每次升级 vLLM 前 diff 一次 requirements/ 目录重点盯 torch 的钉版变化——那是依赖升级里最大的风险源。 本文随 vLLM 主分支 requirements/ 目录更新节奏维护升级前过一遍钉版对照表。【免费下载链接】vllmA high-throughput and memory-efficient inference and serving engine for LLMs项目地址: https://gitcode.com/GitHub_Trending/vl/vllm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考