vLLM 源码可编辑模式安装与调试记录

本文记录如何在 AutoDL 环境中 clone vLLM 源码，并使用 uv pip install -e . 以可编辑模式安装，方便后续源码调试和二次开发。

0. 准备目录并克隆源码

bash 复制代码

cd /root/autodl-tmp
mkdir -p mfo
cd mfo

git clone https://gitcode.com/gh_mirrors/vl/vllm.git
cd vllm

也可以使用 GitHub 官方仓库：

bash 复制代码

git clone https://github.com/vllm-project/vllm.git
cd vllm

1. 什么是源码可编辑模式？

uv pip install -e . 中的 -e 表示 editable，也就是可编辑模式 / 开发模式。

普通安装：

bash 复制代码

uv pip install .

普通安装会把代码复制到虚拟环境的 site-packages 目录中，例如：

bash 复制代码

.venv/site-packages/vllm/

这种方式下，如果你修改本地源码，修改不会立刻生效，通常需要重新安装。

可编辑安装：

bash 复制代码

uv pip install -e .

可编辑安装不会复制源码，而是在 site-packages 中建立一个指向本地源码目录的链接。

也就是说：

text 复制代码

修改本地 vLLM 源码 -> 保存 -> 立即生效

这种方式非常适合：

二次开发
源码调试
阅读和修改 vLLM 内部逻辑
使用 PyCharm / VS Code 断点调试

一句话总结：

可编辑模式就是把本地源码直接挂载到 Python 环境里，改源码后无需重新安装。

2. 是否必须 clone vLLM 源码？

必须 clone。

因为：

bash 复制代码

uv pip install -e .

这里的 . 表示当前目录。

当前目录必须是 vLLM 的源码根目录，并且里面需要有：

text 复制代码

pyproject.toml
setup.py
vllm/

如果只是通过下面命令安装：

bash 复制代码

pip install vllm

那只是从 PyPI 安装了发布包，并没有完整源码目录，因此不能使用 -e . 做源码开发。

3. 创建 uv 虚拟环境

在 vLLM 源码根目录下执行：

bash 复制代码

uv venv --python 3.12 --seed --managed-python
source .venv/bin/activate

Windows 环境激活方式：

bash 复制代码

.venv\Scripts\activate

激活后，终端前面通常会出现类似：

bash 复制代码

(vllm)

4. 切换到指定 vLLM 版本

bash 复制代码

git checkout 4765f0f189fd0cd032a79da37ba427c3ba60ec33

再次确认虚拟环境已激活：

bash 复制代码

source .venv/bin/activate

5. 配置环境变量并安装依赖

为了加速下载，并使用预编译 CUDA wheel，可以配置以下环境变量：

bash 复制代码

export UV_CACHE_DIR=/root/autodl-tmp/uv-cache
export TMPDIR=/root/autodl-tmp/tmp
export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
export VLLM_PRECOMPILED_WHEEL_VARIANT=cu129
export VLLM_MAIN_CUDA_VERSION=12.9

然后执行可编辑安装：

bash 复制代码

VLLM_USE_PRECOMPILED=1 uv pip install -e . --torch-backend=auto -v

参数说明：

VLLM_USE_PRECOMPILED=1：使用 vLLM 预编译包，避免本地完整编译
uv pip install -e .：以可编辑模式安装当前源码
--torch-backend=auto：自动选择合适的 PyTorch 后端
-v：输出更详细的安装日志

6. 确认安装成功

执行：

bash 复制代码

python -c "import sys, vllm; print(sys.executable); print(vllm.__file__)"

如果输出类似下面这样，说明安装正确：

bash 复制代码

/root/autodl-tmp/mfo/vllm/.venv/bin/python
/root/autodl-tmp/mfo/vllm/vllm/__init__.py

重点看第二行。

如果 vllm.__file__ 指向的是源码目录：

bash 复制代码

/root/autodl-tmp/mfo/vllm/vllm/__init__.py

就说明当前环境使用的是本地源码，而不是复制到 site-packages 里的普通安装版本。

7. 安装调试和模型下载工具

bash 复制代码

uv pip install debugpy modelscope

其中：

debugpy：用于 PyCharm / VS Code 远程调试
modelscope：用于从国内 ModelScope 下载模型

8. 下载国内模型

这里以 Qwen2.5-0.5B-Instruct 为例：

bash 复制代码

modelscope download \
  --model Qwen/Qwen2.5-0.5B-Instruct \
  --local_dir /root/autodl-tmp/models/Qwen2.5-0.5B-Instruct

下载完成后，模型路径为：

bash 复制代码

/root/autodl-tmp/models/Qwen2.5-0.5B-Instruct

9. 编写测试脚本

在 vLLM 源码根目录下新建文件：

bash 复制代码

hello.py

内容如下：

python 复制代码

# SPDX-License-Identifier: Apache-2.0
# SPDX-FileCopyrightText: Copyright contributors to the vLLM project

from vllm import LLM, SamplingParams

prompts = [
    "Hello, my name is",
    "The president of the United States is",
    "The capital of France is",
    "The future of AI is",
]

sampling_params = SamplingParams(
    temperature=0.8,
    top_p=0.95,
)


def main():
    llm = LLM(
        model="/root/autodl-tmp/models/Qwen2.5-0.5B-Instruct",
        trust_remote_code=True,
    )

    print("\nxcy:\n" + "-" * 60)

    outputs = llm.generate(prompts, sampling_params)

    print("\nGenerated Outputs:\n" + "-" * 60)

    for output in outputs:
        prompt = output.prompt
        generated_text = output.outputs[0].text

        print(f"Prompt:    {prompt!r}")
        print(f"Output:    {generated_text!r}")
        print("-" * 60)


if __name__ == "__main__":
    main()

10. 运行测试脚本

确保当前在 vLLM 源码目录，并且虚拟环境已激活：

bash 复制代码

cd /root/autodl-tmp/mfo/vllm
source .venv/bin/activate

执行：

bash 复制代码

python hello.py

示例命令行状态：

bash 复制代码

(vllm) (base) root@autodl-container-11hz88zfkm-31078a3e:~/autodl-tmp/mfo/vllm# python hello.py

如果能正常输出生成结果，说明 vLLM 源码环境和模型加载都已经成功。

11. PyCharm 远程连接调试

后续可以使用 PyCharm 连接 AutoDL 服务器进行远程调试。

核心思路是：

PyCharm 配置远程 SSH Interpreter
Python 解释器选择：

bash 复制代码

/root/autodl-tmp/mfo/vllm/.venv/bin/python

bash 复制代码

/root/autodl-tmp/mfo/vllm

在源码中打断点
使用 hello.py 作为入口脚本运行调试

因为当前 vLLM 是通过 uv pip install -e . 可编辑模式安装的，所以 PyCharm 中修改源码后，不需要重新安装 vLLM，重新运行脚本即可生效。

12. 常用检查命令

查看当前 Python 路径：

bash 复制代码

which python

查看 vLLM 实际导入路径：

bash 复制代码

python -c "import vllm; print(vllm.__file__)"

查看虚拟环境中的包：

bash 复制代码

uv pip list

确认 CUDA 是否可用：

bash 复制代码

python -c "import torch; print(torch.cuda.is_available()); print(torch.version.cuda)"

13. 总结

完整流程如下：

bash 复制代码

cd /root/autodl-tmp
mkdir -p mfo
cd mfo

git clone https://gitcode.com/gh_mirrors/vl/vllm.git
cd vllm

git checkout 4765f0f189fd0cd032a79da37ba427c3ba60ec33

uv venv --python 3.12 --seed --managed-python
source .venv/bin/activate

export UV_CACHE_DIR=/root/autodl-tmp/uv-cache
export TMPDIR=/root/autodl-tmp/tmp
export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
export VLLM_PRECOMPILED_WHEEL_VARIANT=cu129
export VLLM_MAIN_CUDA_VERSION=12.9

VLLM_USE_PRECOMPILED=1 uv pip install -e . --torch-backend=auto -v

uv pip install debugpy modelscope

modelscope download \
  --model Qwen/Qwen2.5-0.5B-Instruct \
  --local_dir /root/autodl-tmp/models/Qwen2.5-0.5B-Instruct

python -c "import sys, vllm; print(sys.executable); print(vllm.__file__)"

python hello.py

只要 vllm.__file__ 指向源码目录：

bash 复制代码

/root/autodl-tmp/mfo/vllm/vllm/__init__.py

就说明可编辑模式安装成功。