1. 项目概述为什么是 Ubuntu Conda vLLM 这套组合vLLM 是当前大模型推理部署绕不开的一个名字。它通过 PagedAttention 显存管理、连续批处理、CUDA Graph 等机制把单卡部署大模型的吞吐能力拉高了一个量级。很多人第一次接触 vLLM 是在云服务器上或者本地工作站上系统一多半是 Ubuntu因为 NVIDIA 的驱动、CUDA 生态、Docker 支持在 Linux 下最省心。而 Conda 则是 Python 环境管理的标配用来隔离不同项目的 Python 版本和依赖包避免把系统 Python 搞得一团糟。你如果问我“ubuntu conda 安装vllm”这件事值不值得写一篇教程我的答案是值得而且坑不少。虽然 vLLM 官方给了一条pip install vllm的最简路径但实际部署时你会遇到 CUDA 版本不匹配、Python 版本过新、显存分配不合理、模型下载慢、甚至国产加速卡不支持某些模型类型等一系列问题。这篇文章把我实际踩过的坑和验证过的步骤完整记录下来适合三类读者刚接触大模型部署、想在本地或服务器上用 vLLM 跑起来 Qwen、Llama 这类开源模型的人准备把 vLLM 接入生产环境、需要做推理服务选型的人以及正在用国产加速卡比如昇腾 910B做适配、想搞明白 vLLM 能力边界的人。先说结论在 Ubuntu 上用 Conda 装 vLLM核心就三件事。第一把 Python 版本锁在 3.10 附近别用最新的 Python 3.12/3.13第二确保 CUDA 版本和 PyTorch 版本互相匹配不要让 vLLM 自己去跟一个不兼容的 torch 打架第三学会用conda create隔离环境出了问题直接删环境重来比折腾系统 Python 快得多。这三件事做好了安装过程基本不会有什么意外。2. 安装前必须想清楚的几件事2.1 先确认你的显卡和 CUDA 版本vLLM 是一个对硬件环境非常敏感的项目。它的预编译 wheel 包是绑定特定 CUDA 版本的所以你不能盲目地pip install vllm然后祈祷它能跑。我见过太多人卡在这一步PyTorch 装的是 CUDA 11.8 的版本vLLM 最新版却要求 CUDA 12.x结果一启动就报CUDA error: no kernel image available。所以在动手之前先执行nvidia-smi看三样东西GPU 型号、显存大小、驱动支持的 CUDA 版本。vLLM 目前官方预编译包主要基于 CUDA 12.1 和 12.4你需要确保驱动版本够新建议 535 以上。如果你还在用 GTX 10 系、20 系的旧卡或者显卡驱动停留在 470、525 这种老版本建议先把驱动升级到 535 以上再继续。不仅是 vLLM新版 PyTorch 对驱动版本也有要求驱动太老会直接导致所有 CUDA 相关的包报错。2.2 Python 版本选择直接决定你能不能装上这是 Conda 方案最核心的优势你可以精确控制 Python 版本。vLLM 对 Python 版本的支持范围比较保守0.8.x 版本官方支持 Python 3.9 到 3.12但我实际测试下来Python 3.10 和 3.11 最稳。Python 3.12 在部分旧版本 vLLM 上会出现依赖编译失败的问题Python 3.9 则太老有些新版本依赖已经不维护了。所以我的建议是创建虚拟环境时直接指定python3.10。不是 3.11不是 3.12就是 3.10。原因很简单vLLM 的依赖生态里很多 C 扩展比如 xformers、flash-attn对 Python 3.10 的预编译支持最齐全遇到问题最少。虽然 3.11 现在也基本没问题但没必要为了求新给自己找麻烦。2.3 Conda 换源别在下载上浪费时间国内网络环境下直接用官方源创建 Conda 环境可能会慢到怀疑人生。conda create -n vllm python3.10这一条命令可能要等十分钟以上因为要解析和下载大量依赖。我建议在安装完 Miniconda 之后立刻换源把 conda 的 channel 指向清华源或阿里源。这里有个细节值得注意Conda 换源和 pip 换源是两件事。Conda 的源配置在~/.condarc文件里pip 的源配置在~/.pip/pip.conf或~/.config/pip/pip.conf。两个都要换因为 vLLM 的安装过程会同时用到 conda 和 pip。特别是 pip 源如果还是默认的 PyPI下载 PyTorch 这种几个 GB 的包会非常痛苦。3. 核心细节解析与实操要点3.1 安装 Miniconda 的完整过程如果你的机器上还没有 Conda第一步是装 Miniconda 而不是 Anaconda。Anaconda 预装了太多用不到的包体积大、依赖杂对服务器环境来说完全是负担。Miniconda 只有几十 MB需要什么装什么。安装过程很简单但是有个细节我要专门说一下安装完 Miniconda 之后一定要执行conda init bash或者重新登录 shell否则你会遇到一个非常经典的问题——conda: command not found。这个问题的原因通常是安装时选择了“不自动加入 PATH”或者干脆忘了重新加载 shell 配置。# 下载 Miniconda 安装脚本 wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh # 执行安装-b 表示静默安装-p 指定安装路径 bash Miniconda3-latest-Linux-x86_64.sh -b -p $HOME/miniconda3 # 初始化 shell 配置 $HOME/miniconda3/bin/conda init bash # 重新加载配置 source ~/.bashrc装完之后可以验证一下conda --version能正常输出版本号就说明 Conda 已经可用了。这里再提一个细节如果你用的是 zsh 而不是 bash记得把conda init bash换成conda init zsh否则同样会遇到conda: command not found。3.2 Conda 换源和 pip 换源安装完 Miniconda 后第一件事永远是换源。写~/.condarc文件把默认通道替换成国内镜像channels: - defaults show_channel_urls: true default_channels: - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/r - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/msys2 custom_channels: conda-forge: https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud pytorch: https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloudpip 的源配置在~/.pip/pip.conf[global] index-url https://mirrors.aliyun.com/pypi/simple/ trusted-host mirrors.aliyun.com换完源以后建议执行conda clean -i清一下索引缓存然后conda update conda -y把 Conda 本身更新到最新版。这一步很多人会跳过但我遇到过旧版 Conda 在解析某些新依赖时出现奇怪的报错更新之后就好了。3.3 创建独立的 vllm 虚拟环境接下来是创建虚拟环境。为什么强调用虚拟环境因为 vLLM 的依赖非常重它会安装特定版本的 torch、transformers、tokenizers、fastapi 等一堆包这些包的版本要求跟其他项目经常冲突。如果你把所有东西装到 base 环境里早晚会出事。conda create -n vllm python3.10 -y conda activate vllm这里有一个非常常见的坑输入conda activate vllm时系统提示CommandNotFoundError: Your shell has not been properly configured to use conda activate或者直接报conda error: run conda init before conda activate。这个报错的原因很简单——安装完 Miniconda 后conda init没有正确执行或者执行完没有重新加载 shell。解决办法也很简单再跑一次conda init bash source ~/.bashrc然后重新开一个终端窗口。3.4 vLLM 版本与 PyTorch 版本对照在真正安装 vLLM 之前我建议你先看一眼 vLLM 官方文档里的版本兼容表。简单说几条关键信息vLLM 0.6.x 及更早版本对应 PyTorch 2.1-2.2Python 支持到 3.11。vLLM 0.7.x/0.8.x对应 PyTorch 2.5Python 支持到 3.12但推荐 3.10/3.11。vLLM 0.9.x目前最新系列性能优化更多但对 CUDA 版本要求更高需要 CUDA 12.4 才能获得完整支持。我的建议是如果你是新部署直接装最新版 vLLM 就好pip install -U vllm会自动拉取匹配的 PyTorch 版本。如果你是要复现别人的项目那就必须以项目要求为准锁定 vLLM 版本不要装最新版。我遇到过不止一次某个项目的代码用的是 vLLM 0.4.2 的 API结果用户直接装了 0.8.x启动服务时各种参数不兼容最后只能重装环境。4. 实操过程与核心环节实现4.1 安装 vLLM 的三条路我推荐哪条现在环境已经准备好了正式安装 vLLM 有三条路pip install vllm直接装预编译包、源码编译安装、用 Docker 镜像。我按推荐程度排序讲一下。第一条路pip 安装预编译包。这是最推荐的方式尤其适合生产环境。一条命令搞定不需要编译不需要等半小时。官方会为 PyPI 发布预编译的 wheel 包基于 CUDA 12.x装完直接能用。唯一要注意的是你机器的 CUDA 版本要和 wheel 包的版本对上。pip install -U vllm如果你想安装特定版本pip install vllm0.8.3第二条路源码编译。适合以下情况你需要改 vLLM 源码、你需要适配特定 GPU比如昇腾、寒武纪等国产卡或者你用的 CUDA 版本没有对应的预编译包。源码编译比较痛苦需要提前装好 CUDA toolkit、gcc、cmake编译时间从二十分钟到两个小时不等。除非有必要否则不建议走这条路。第三条路Docker。这也是我实际生产环境推荐的方式。vLLM 官方提供了现成的 Docker 镜像把 CUDA、Python、vLLM 全都打包好了不需要自己装 Conda。命令大概是docker pull vllm/vllm-openai:latest docker run --runtime nvidia --gpus all \ -v ~/.cache/huggingface:/root/.cache/huggingface \ -p 8000:8000 \ --ipchost \ vllm/vllm-openai:latest \ --model Qwen/Qwen2.5-7B-Instruct但既然你选择 Conda 方案说明你想在宿主机上直接管理环境可能是为了调试方便或者不想引入 Docker 的复杂性。没问题pip 安装就够了。4.2 验证安装是否成功安装完 vLLM第一件事是验证能不能正常导入python -c import vllm; print(vllm.__version__)如果报错常见的是 CUDA 相关的ImportError: libcublas.so.12: cannot open shared object file或No module named torch._C。前者说明 CUDA 库路径没配好需要检查LD_LIBRARY_PATH后者说明 PyTorch 没装好需要重装匹配 CUDA 版本的 PyTorch。还可以用nvidia-smi检查显存状态然后跑一个小模型做冒烟测试。我会用 Qwen2.5-0.5B-Instruct 这种极小模型试因为它下载快、显存占用低能快速验证整条链路是否通。等确认通了再换大模型。4.3 用 Qwen3-8B 做一次真实部署装完环境总得跑一个真实模型验证下效果。我以 Qwen3-8B 为例讲一下启动命令和参数选择。首先下载模型。我强烈建议先用modelscope或huggingface-cli把模型下载到本地目录再让 vLLM 从本地路径加载模型。直接从 HuggingFace 在线加载不是不行但模型下载过程中一旦断网整个服务会卡住而且每次启动都要检查文件完整性非常浪费时间。# 安装 modelscope pip install modelscope # 下载模型到本地 modelscope download --model Qwen/Qwen3-8B --local_dir ./models/Qwen3-8B然后启动 vLLM 服务python -m vllm.entrypoints.openai.api_server \ --model ./models/Qwen3-8B \ --served-model-name Qwen3-8B \ --tensor-parallel-size 1 \ --gpu-memory-utilization 0.9 \ --max-model-len 8192 \ --port 8000几个参数我逐个解释一下。--tensor-parallel-size张量并行数。单卡就写 1多卡就写卡数比如 2 张 A100 写 2。这个参数决定了模型如何在多卡之间切分。--gpu-memory-utilizationGPU 显存利用率上限0.9 表示允许使用 90% 的显存。这个参数很关键如果设置太高模型加载时可能 OOM设置太低留给 KV Cache 的空间就小并发能力会下降。一般建议单卡部署时设 0.85-0.95生产环境从 0.9 起步观察显存峰值再调。--max-model-len最大序列长度。这里有一个新手很容易踩的坑如果你设置得太大比如 32768vLLM 会为每个序列预分配显存导致 KV Cache 可用空间变小并发吞吐下降。Qwen3-8B 支持 128K 上下文但实际业务不一定需要那么大按需设置即可。8K 或 16K 对大多数业务场景足够用了。启动后终端会输出一段日志包括 GPU 信息、模型加载耗时、KV Cache 大小、最大并发数等。如果日志最后出现Application startup complete说明服务已经成功启动。这时候可以用 curl 测试一下接口curl -X POST http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: Qwen3-8B, messages: [{role: user, content: 你好介绍一下你自己}], max_tokens: 256, temperature: 0.7 }能正常返回 JSON 响应里面包含模型生成的内容就说明整条链路已经通了。4.4 关于 --enforce-eager 的影响很多人在启动 vLLM 时纠结要不要加--enforce-eager这个参数。搜索热度也高我在这里说清楚。默认情况下vLLM 会启用 CUDA Graph 来加速推理。CUDA Graph 的原理是把一小段 GPU 计算流程预先捕获并固化减少 CPU 与 GPU 之间的调度开销。这能让推理速度提升不少但代价是启动时要额外分配显存用于捕获 CUDA Graph 的输入输出缓存某些 GPU 架构或驱动版本下 CUDA Graph 捕获会失败或报错。--enforce-eager的作用就是强制关闭 CUDA Graph改用 Eager 模式。它的影响有三个启动时间变短因为省去了 CUDA Graph 捕获阶段。显存占用略低但推理吞吐下降实测在 5%-15% 左右模型越大、并发越高差距越明显。兼容性变好很多 CUDA Graph 捕获失败的问题可以通过加这个参数规避。所以在开发调试阶段加--enforce-eager没问题能快速跑通链路。但在生产环境我建议还是去掉这个参数让 CUDA Graph 正常工作换取更高的吞吐。如果确实遇到了 CUDA Graph 相关报错再考虑用--enforce-eager兜底而不是从一开始就牺牲性能。4.5 生产环境部署的 Docker 补充思路虽然这篇文章主要讲 Conda 方案但如果你最终要上生产环境我还是建议看一下 Docker 方案。原因很简单Conda 环境是为“这台机器”准备的换一台机器就要重新来一遍Docker 把整个运行时环境固化成了镜像开发、测试、生产保持一致这也是现在大模型推理服务的主流做法。# docker-compose.yml 示例 services: vllm: image: vllm/vllm-openai:latest runtime: nvidia environment: - HUGGINGFACE_HUB_CACHE/models - NVIDIA_VISIBLE_DEVICESall volumes: - ./models:/models - ~/.cache/huggingface:/root/.cache/huggingface ports: - 8000:8000 command: --model /models/Qwen3-8B --served-model-name Qwen3-8B --gpu-memory-utilization 0.9 --max-model-len 8192 ipc: host关于 Docker说三个要点--ipchost要加上否则某些 PyTorch 版本在多进程场景下会报共享内存不足模型文件一定要挂载到宿主机目录缓存否则每次重启容器都要重新拉模型runtime: nvidia是 NVIDIA Container Toolkit 的写法需要提前在宿主机装好。5. 常见问题与排查技巧实录5.1 找不到 conda 可执行文件这个问题在搜索热词里排名非常靠前而且大部分时候是无意间踩的坑。如果你执行conda命令提示command not found按这个顺序排查确认 Miniconda 安装路径通常是$HOME/miniconda3或/opt/miniconda3。检查~/.bashrc末尾有没有 conda 初始化的代码块。如果没有执行$HOME/miniconda3/bin/conda init bash。重新登录终端或source ~/.bashrc。还有一个小概率情况你安装时用了-b静默参数且指定了非默认路径但 shell 配置里写的还是默认路径。这种直接手动改~/.bashrc里的路径即可。5.2 conda activate 报“run conda init before conda activate”这个问题我在前面提到过这里再展开说一下。它的本质是Conda 4.4 版本引入了新的conda activate机制这个机制依赖 shell 初始化而初始化是通过conda init完成的。如果你装完 Miniconda 后没有执行conda init或者执行后没有重新加载 shell就会看到这个报错。# 复原步骤 conda init bash source ~/.bashrc # 或者干脆重新登录 ssh需要注意conda init需要在已经能使用conda命令的前提下执行。如果你现在连conda都用不了先找到 conda 可执行文件的绝对路径去执行这个命令比如/root/miniconda3/bin/conda init bash。5.3 安装时提示 CUDA 版本不匹配vLLM 安装最常见的报错是CUDA_HOME相关的问题或者运行时报no kernel image is available for execution on the device。后者通常意味着你下载的 PyTorch/vLLM 编译时用的 CUDA 版本比驱动支持的 CUDA 版本更高。解决办法就是先升级驱动别想着靠软件层绕过。驱动版本对应的 CUDA 版本必须高于或等于 PyTorch/vLLM 需要的 CUDA 版本。检查方法nvidia-smi输出的右上角能看到驱动支持的最大 CUDA 版本。如果显示 12.4那么 PyTorch 选 CUDA 12.1/12.4 的版本都可以如果显示 11.8 甚至更低那就只能找老版本的 vLLM 和 PyTorch 了。5.4 vLLM 不支持 embedding 向量模型和 reranker 模型这个问题的来源是热词里的“昇腾910b-a2服务器上不能通过vllm启动embedding向量和reranker模型吗”。直接回答vLLM 官方并不支持 embedding 向量模型和 reranker 模型这不是昇腾的问题在任何 GPU 上都是如此。原因要从 vLLM 的架构设计说起。vLLM 的核心优化目标是自回归生成式大模型LLM它通过 PagedAttention 和连续的 KV Cache 管理来优化生成过程。而 embedding 模型和 reranker 模型不做自回归生成不产生 KV Cache它们的计算模式是“一次性前向传播拿到向量”——这跟 vLLM 的调度器、显存管理器是两套逻辑。vLLM 团队把精力集中在生成式模型上对 embedding 和 reranker 的支持优先级非常低目前也只在接口层面做过有限的尝试。如果你确实需要部署 embedding 和 reranker 模型替代方案有几个用text-embeddings-inferenceTEI这个专用服务它对 BERT 类模型和向量检索场景优化很好用FlagEmbedding加 FastAPI 自己封装一个服务或者直接用sentence-transformers在 Python 进程里加载模型性能满足中小规模场景。如果你是在昇腾 910B 上跑 vLLM需要装vllm-ascend插件。昇腾的 CANN 软件栈跟 CUDA 完全不同vLLM 官方的主线代码不支持昇腾必须通过vllm-ascend这个适配层来跑。但即使是vllm-ascend也同样是只支持生成式模型不支持 embedding 和 reranker。这一点要提前跟业务方说清楚免得部署到一半才发现方案做不了。5.5 模型加载慢、下载卡住如果你在服务器上第一次跑 vLLM会发现模型下载和加载占了很长时间。解决方法我之前提过先用modelscope或hf download把模型下到本地再用本地路径加载。这里再补充一个细节HuggingFace 的缓存目录是~/.cache/huggingface/hubmodelscope 的缓存目录是~/.cache/modelscope。如果你用两种工具下载过同一个模型磁盘上会有两份文件白白浪费空间。建议所有模型统一用 modelscope 下载到项目目录下的models/文件夹管理最清晰。5.6 一张速查表现象可能原因解决办法conda: command not foundMiniconda 未加入 PATH执行 conda 所在路径的conda init并source ~/.bashrcrun conda init before conda activate未执行 conda init 或未重新加载 shell执行conda init bash source ~/.bashrcCUDA error: no kernel image驱动版本低于 PyTorch/vLLM 所需 CUDA 版本升级 NVIDIA 驱动到 535启动服务时报共享内存不足Docker 或系统/dev/shm空间太小加--ipchost或--shm-size1g并发高时响应变慢KV Cache 空间不足调低--max-model-len或调高--gpu-memory-utilization模型加载到一半卡住网络问题或磁盘 IO 慢先下载模型到本地再用本地路径加载6. 从开发到生产我的一些实践心得最后分享几个我在实际部署中沉淀下来的习惯希望对你有帮助。第一U 盘式环境管理。每一个新项目都建一个独立的 Conda 环境环境名跟项目名一致。坏处是磁盘占用会多一些好处是项目之间完全隔离删环境随时重来不会影响其他正在跑的服务。我在服务器上维护了七八个 Conda 环境每个环境对应一个业务项目从未出过互相污染的问题。第二先小后大的测试策略。每次装完 vLLM我先用 0.5B 或 1.5B 的小模型跑通接口确认整个链路模型加载、请求转发、返回格式、监控日志都没问题再换正式模型。这一步虽然看起来多花了一点时间但能帮你避开“大模型加载失败但不知道是环境问题还是模型问题”的尴尬排查过程。第三关注 vLLM 的版本变更日志。vLLM 迭代速度极快每个版本都有大量行为变化和接口调整。升级前建议看一眼https://github.com/vllm-project/vllm/releases的 Release Notes重点关注 Breaking Changes别把生产环境贸然升到新版本。我自己就吃过亏0.6.x 升级到 0.7.x 后--api-server相关参数变了服务直接起不来回滚再排查花了不少时间。第四监控指标别只看显存。vLLM 的/metrics端点暴露了 Prometheus 格式的监控指标里面有几个关键指标值得重点关注vllm:num_requests_running正在处理的请求数、vllm:num_requests_waiting等待中的请求数、vllm:gpu_cache_usage_percKV Cache 利用率。特别是最后一个它比单纯的显存占用更能反映系统的真实负载状态。如果gpu_cache_usage_perc长期接近 100%说明 KV Cache 快满了要么调低--max-model-len要么考虑升级到显存更大的卡。第五有条件就把 Conda 方案和 Docker 方案都试一遍。Conda 适合开发调试Docker 适合生产交付。两个方案并不是互斥的你可以先在 Conda 环境里调试模型参数确定最优启动命令后再把同样的命令固化进 Docker Compose 部署到生产。这样既享受了 Conda 的灵活也享受了 Docker 的可移植性。回到最开始的问题在 Ubuntu 上用 Conda 装 vLLM 难吗说实话不难。整个安装链路只要把 Python 版本、CUDA 版本、模型加载这三个环节打通剩下的都是重复劳动。真正花时间的往往不是安装本身而是理解 vLLM 的运行机制和参数权衡。希望这篇博客能帮你少走一些弯路把时间花在真正有价值的事情上。