企业官网建设流程全解析

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

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

0. 准备目录并克隆源码

cd/root/autodl-tmpmkdir-pmfocdmfogitclone https://gitcode.com/gh_mirrors/vl/vllm.gitcdvllm

也可以使用 GitHub 官方仓库：

gitclone https://github.com/vllm-project/vllm.gitcdvllm

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

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

普通安装：

uv pipinstall.

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

.venv/site-packages/vllm/

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

可编辑安装：

uv pipinstall-e.

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

也就是说：

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

这种方式非常适合：

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

一句话总结：

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

2. 是否必须 clone vLLM 源码？

必须 clone。

因为：

uv pipinstall-e.

这里的.表示当前目录。

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

pyproject.toml setup.py vllm/

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

pipinstallvllm

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

3. 创建 uv 虚拟环境

在 vLLM 源码根目录下执行：

uv venv--python3.12--seed--managed-pythonsource.venv/bin/activate

Windows 环境激活方式：

.venv\Scripts\activate

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

(vllm)

4. 切换到指定 vLLM 版本

gitcheckout 4765f0f189fd0cd032a79da37ba427c3ba60ec33

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

source.venv/bin/activate

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

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

exportUV_CACHE_DIR=/root/autodl-tmp/uv-cacheexportTMPDIR=/root/autodl-tmp/tmpexportUV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simpleexportVLLM_PRECOMPILED_WHEEL_VARIANT=cu129exportVLLM_MAIN_CUDA_VERSION=12.9

然后执行可编辑安装：

VLLM_USE_PRECOMPILED=1uv pipinstall-e.--torch-backend=auto-v

参数说明：

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

6. 确认安装成功

执行：

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

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

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

重点看第二行。

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

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

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

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

uv pipinstalldebugpy modelscope

其中：

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

8. 下载国内模型

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

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

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

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

9. 编写测试脚本

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

hello.py

内容如下：

# SPDX-License-Identifier: Apache-2.0# SPDX-FileCopyrightText: Copyright contributors to the vLLM projectfromvllmimportLLM,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,)defmain():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)foroutputinoutputs:prompt=output.prompt generated_text=output.outputs[0].textprint(f"Prompt:{prompt!r}")print(f"Output:{generated_text!r}")print("-"*60)if__name__=="__main__":main()

10. 运行测试脚本

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

cd/root/autodl-tmp/mfo/vllmsource.venv/bin/activate

执行：

python hello.py

示例命令行状态：

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

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

11. PyCharm 远程连接调试

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

核心思路是：

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

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

3. 项目路径选择 vLLM 源码目录：

/root/autodl-tmp/mfo/vllm

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

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

12. 常用检查命令

查看当前 Python 路径：

whichpython

查看 vLLM 实际导入路径：

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

查看虚拟环境中的包：

uv pip list

确认 CUDA 是否可用：

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

13. 总结

完整流程如下：

cd/root/autodl-tmpmkdir-pmfocdmfogitclone https://gitcode.com/gh_mirrors/vl/vllm.gitcdvllmgitcheckout 4765f0f189fd0cd032a79da37ba427c3ba60ec33 uv venv--python3.12--seed--managed-pythonsource.venv/bin/activateexportUV_CACHE_DIR=/root/autodl-tmp/uv-cacheexportTMPDIR=/root/autodl-tmp/tmpexportUV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simpleexportVLLM_PRECOMPILED_WHEEL_VARIANT=cu129exportVLLM_MAIN_CUDA_VERSION=12.9VLLM_USE_PRECOMPILED=1uv pipinstall-e.--torch-backend=auto-vuv pipinstalldebugpy modelscope modelscope download\--modelQwen/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__指向源码目录：

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

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