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.gitcdvllm1. 什么是源码可编辑模式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/activateWindows 环境激活方式.venv\Scripts\activate激活后终端前面通常会出现类似(vllm)4. 切换到指定 vLLM 版本gitcheckout 4765f0f189fd0cd032a79da37ba427c3ba60ec33再次确认虚拟环境已激活source.venv/bin/activate5. 配置环境变量并安装依赖为了加速下载并使用预编译 CUDA wheel可以配置以下环境变量exportUV_CACHE_DIR/root/autodl-tmp/uv-cacheexportTMPDIR/root/autodl-tmp/tmpexportUV_INDEX_URLhttps://pypi.tuna.tsinghua.edu.cn/simpleexportVLLM_PRECOMPILED_WHEEL_VARIANTcu129exportVLLM_MAIN_CUDA_VERSION12.9然后执行可编辑安装VLLM_USE_PRECOMPILED1uv pipinstall-e.--torch-backendauto-v参数说明VLLM_USE_PRECOMPILED1使用 vLLM 预编译包避免本地完整编译uv pip install -e .以可编辑模式安装当前源码--torch-backendauto自动选择合适的 PyTorch 后端-v输出更详细的安装日志6. 确认安装成功执行python-cimport 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-Instruct9. 编写测试脚本在 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_paramsSamplingParams(temperature0.8,top_p0.95,)defmain():llmLLM(model/root/autodl-tmp/models/Qwen2.5-0.5B-Instruct,trust_remote_codeTrue,)print(\nxcy:\n-*60)outputsllm.generate(prompts,sampling_params)print(\nGenerated Outputs:\n-*60)foroutputinoutputs:promptoutput.prompt generated_textoutput.outputs[0].textprint(fPrompt:{prompt!r})print(fOutput:{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)rootautodl-container-11hz88zfkm-31078a3e:~/autodl-tmp/mfo/vllm# python hello.py如果能正常输出生成结果说明 vLLM 源码环境和模型加载都已经成功。11. PyCharm 远程连接调试后续可以使用 PyCharm 连接 AutoDL 服务器进行远程调试。核心思路是PyCharm 配置远程 SSH InterpreterPython 解释器选择/root/autodl-tmp/mfo/vllm/.venv/bin/python项目路径选择 vLLM 源码目录/root/autodl-tmp/mfo/vllm在源码中打断点使用hello.py作为入口脚本运行调试因为当前 vLLM 是通过uv pip install -e .可编辑模式安装的所以 PyCharm 中修改源码后不需要重新安装 vLLM重新运行脚本即可生效。12. 常用检查命令查看当前 Python 路径whichpython查看 vLLM 实际导入路径python-cimport vllm; print(vllm.__file__)查看虚拟环境中的包uv pip list确认 CUDA 是否可用python-cimport 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_URLhttps://pypi.tuna.tsinghua.edu.cn/simpleexportVLLM_PRECOMPILED_WHEEL_VARIANTcu129exportVLLM_MAIN_CUDA_VERSION12.9VLLM_USE_PRECOMPILED1uv pipinstall-e.--torch-backendauto-vuv pipinstalldebugpy modelscope modelscope download\--modelQwen/Qwen2.5-0.5B-Instruct\--local_dir/root/autodl-tmp/models/Qwen2.5-0.5B-Instruct python-cimport sys, vllm; print(sys.executable); print(vllm.__file__)python hello.py只要vllm.__file__指向源码目录/root/autodl-tmp/mfo/vllm/vllm/__init__.py就说明可编辑模式安装成功。
vLLM 源码可编辑模式安装与调试记录
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.gitcdvllm1. 什么是源码可编辑模式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/activateWindows 环境激活方式.venv\Scripts\activate激活后终端前面通常会出现类似(vllm)4. 切换到指定 vLLM 版本gitcheckout 4765f0f189fd0cd032a79da37ba427c3ba60ec33再次确认虚拟环境已激活source.venv/bin/activate5. 配置环境变量并安装依赖为了加速下载并使用预编译 CUDA wheel可以配置以下环境变量exportUV_CACHE_DIR/root/autodl-tmp/uv-cacheexportTMPDIR/root/autodl-tmp/tmpexportUV_INDEX_URLhttps://pypi.tuna.tsinghua.edu.cn/simpleexportVLLM_PRECOMPILED_WHEEL_VARIANTcu129exportVLLM_MAIN_CUDA_VERSION12.9然后执行可编辑安装VLLM_USE_PRECOMPILED1uv pipinstall-e.--torch-backendauto-v参数说明VLLM_USE_PRECOMPILED1使用 vLLM 预编译包避免本地完整编译uv pip install -e .以可编辑模式安装当前源码--torch-backendauto自动选择合适的 PyTorch 后端-v输出更详细的安装日志6. 确认安装成功执行python-cimport 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-Instruct9. 编写测试脚本在 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_paramsSamplingParams(temperature0.8,top_p0.95,)defmain():llmLLM(model/root/autodl-tmp/models/Qwen2.5-0.5B-Instruct,trust_remote_codeTrue,)print(\nxcy:\n-*60)outputsllm.generate(prompts,sampling_params)print(\nGenerated Outputs:\n-*60)foroutputinoutputs:promptoutput.prompt generated_textoutput.outputs[0].textprint(fPrompt:{prompt!r})print(fOutput:{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)rootautodl-container-11hz88zfkm-31078a3e:~/autodl-tmp/mfo/vllm# python hello.py如果能正常输出生成结果说明 vLLM 源码环境和模型加载都已经成功。11. PyCharm 远程连接调试后续可以使用 PyCharm 连接 AutoDL 服务器进行远程调试。核心思路是PyCharm 配置远程 SSH InterpreterPython 解释器选择/root/autodl-tmp/mfo/vllm/.venv/bin/python项目路径选择 vLLM 源码目录/root/autodl-tmp/mfo/vllm在源码中打断点使用hello.py作为入口脚本运行调试因为当前 vLLM 是通过uv pip install -e .可编辑模式安装的所以 PyCharm 中修改源码后不需要重新安装 vLLM重新运行脚本即可生效。12. 常用检查命令查看当前 Python 路径whichpython查看 vLLM 实际导入路径python-cimport vllm; print(vllm.__file__)查看虚拟环境中的包uv pip list确认 CUDA 是否可用python-cimport 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_URLhttps://pypi.tuna.tsinghua.edu.cn/simpleexportVLLM_PRECOMPILED_WHEEL_VARIANTcu129exportVLLM_MAIN_CUDA_VERSION12.9VLLM_USE_PRECOMPILED1uv pipinstall-e.--torch-backendauto-vuv pipinstalldebugpy modelscope modelscope download\--modelQwen/Qwen2.5-0.5B-Instruct\--local_dir/root/autodl-tmp/models/Qwen2.5-0.5B-Instruct python-cimport sys, vllm; print(sys.executable); print(vllm.__file__)python hello.py只要vllm.__file__指向源码目录/root/autodl-tmp/mfo/vllm/vllm/__init__.py就说明可编辑模式安装成功。
