企业官网建设流程全解析

vLLM requirements 依赖管理：多版本文件怎么选、版本冲突怎么排完整指南

【免费下载链接】vllmA high-throughput and memory-efficient inference and serving engine for LLMs项目地址: https://gitcode.com/GitHub_Trending/vl/vllm

pip install -r requirements/cuda.txt跑到一半弹出ERROR: Cannot install vllm because these package versions have conflicting dependencies，手动把 torch 卸了重装，import vllm又报No module named 'flashinfer'。折腾三遍的根源都一样：vLLM 的依赖不是一套文件，requirements/目录里按硬件拆成了 10 多个文件，装错文件、或者只改单个包的版本，冲突几乎是必然的。

说白了，vLLM（高吞吐 LLM 推理引擎）用"分层 requirements"管理依赖：requirements/common.txt放 50 多个所有平台共享的包，硬件文件（cuda.txt / cpu.txt / rocm.txt 等）第一行就是-r common.txt，装上硬件文件时基础依赖自动带进来。你唯一要做对的事是选对硬件文件，并且整份安装、不要动单个包的版本。

读完能拿到这些能力：

• 根据硬件条件（NVIDIA / AMD / CPU / TPU / XPU）选对 requirements 文件
• 看懂-r引用链和 uv 生成的锁文件，分清"手写文件"和"自动生成文件"
• 排查 torch 与 torchaudio/torchvision 版本不匹配的报错
• 定位 FlashInfer 装不上、protobuf 被 6.x 顶包这类高频冲突
• 知道开发、文档、KV 连接器各自该装哪份清单

🗺️ 全局地图：requirements 目录 12 个文件一览

继承关系一张图：基础层 → 硬件层 → 工具链层，箭头表示-r引用。

🚀 生产部署（NVIDIA GPU）：装 cuda.txt

什么时候用它：机器有 NVIDIA GPU、跑vllm serve对外提供推理服务。

requirements/cuda.txt的关键版本绑定关系：

pip install -r requirements/cuda.txt

⚠️ 硬绑定一：torch 2.13.0 ↔ torchaudio 2.11.0 ↔ torchvision 0.28.0 强耦合，只单独升级 torch 会在加载多模态 processor 时炸掉。 ⚠️ 硬绑定二：FlashInfer 版本要求与项目 Dockerfile 同步更新；flashinfer-cubin自 0.6.14 起不再发 PyPI，cuda.txt 里的--extra-index-url行删不得。

🖥️ 无 GPU 开发调试：装 cpu.txt

什么时候用它：笔记本改代码、跑单测，或目标服务器只有 CPU。

requirements/cpu.txt按platform_machine分叉：

⚠️torch==2.13.0+cpu这种本地版本标签只能从 PyTorch 官方 CPU wheel 源解析。如果机器是 x86_64 却装了带+cu1xx的 torch 再叠 cpu.txt，pip 会把 torch 卸了重装，顺带可能带走依赖它的包——这是"装了三遍都没跑起来"的常见剧本。

🎮 AMD / TPU / Intel：rocm.txt、tpu.txt、xpu.txt

什么时候用它：ROCm 的 AMD GPU 集群、TPU Pod、Intel 数据中心 GPU 部署。

三个文件的差异集中在"加速器专属包"和"额外 wheel 源"：

⚠️ rocm.txt 里 grpcio 与 grpcio-reflection 都钉死在 1.78.0，注释明说"gRPC 库版本必须彼此一致"。只升级其中一个，KV 传输相关功能会静默失败。

🛠️ 开发、文档与 KV 连接器：dev.txt、docs.in、kv_connectors.txt

什么时候用它：要给项目提 PR、本地构建文档、或启用分布式 KV 缓存连接器。

• dev.txt只有两行实质内容：-r lint.txt和-r test/cuda.txt，文件头注释写着"不要直接往 dev.txt 加东西"。test/cuda.txt是 uv 自动生成的 1400+ 行锁文件，每个包下面都有# via ...注释说明它被谁引用。
• docs.txt同样是 uv 编译产物，真正的入口是docs.in：

uv pip compile requirements/docs.in -o requirements/docs.txt \ --python-platform x86_64-manylinux_2_28 --python-version 3.12 pip install -r requirements/docs.txt

• kv_connectors.txt体量很小：lmcache >= 0.3.9、nixl 1.3.2、mooncake-transfer-engine >= 0.3.12，配合tools/install_gdrcopy.sh一类的安装脚本使用。

⚠️ 两份 uv 锁文件（test/cuda.txt、docs.txt）头部都带编译命令，改依赖请改.in源文件后重新 compile，直接手改锁文件会在下次 CI 被覆盖回去。

💥 踩坑速查

坑 1：FlashInfer 找不到可用版本

症状：ERROR: Could not find a version that satisfies the requirement flashinfer-cubin==0.6.17

根因：cubin 包 0.6.14 起已撤下 PyPI，只留在 flashinfer 官方源，单独pip install flashinfer-python不会带这个源。

pip install -r requirements/cuda.txt # 整份装，源信息在文件第 16 行

坑 2：protobuf 被顶到 6.x

症状：装完import vllm报AttributeError: module 'google.protobuf' ...，pip show protobuf是 6.x

根因：common.txt 里 protobuf 排除了 6.30~6.33 一整段（CVE-2026-0994），手动装别的库时依赖解析器会把它升到 6.x。

pip install "protobuf>=5.29.6,<6.30.0"

坑 3：xgrammar / llguidance 在冷门架构装不上

症状：ERROR: Could not find a version that satisfies the requirement xgrammar

根因：这两个包在 common.txt 里带platform_machine条件（仅 x86_64/aarch64/arm64/s390x/ppc64le），riscv64 等架构没有 wheel。

pip install -r requirements/cpu.txt # 条件依赖自动跳过，别单独硬装

📌 一页纸速查

🔖 收藏提示：升级 vLLM 时先 diffrequirements/cuda.txt的 torch 版本行和requirements/test/下的锁文件，版本漂移基本都藏在这两处。

下一步

把requirements/目录加进你的关注列表，每次拉新 tag 先对比cuda.txt与rocm.txt的 torch 行；遇到解析冲突，直接打开对应锁文件头部的 uv 编译命令复现一遍，比盲猜版本快得多。

【免费下载链接】vllmA high-throughput and memory-efficient inference and serving engine for LLMs项目地址: https://gitcode.com/GitHub_Trending/vl/vllm