[Bug]: 直接调用虚拟环境中的 vllm 时无法找到 ninja

快速结论：该报错通常发生在未激活虚拟环境、直接调用虚拟环境内 bin/vllm 可执行文件时，导致子进程无法找到同一环境中的 ninja。优先排查方式是先激活虚拟环境再启动服务，或检查环境内 ninja 的可执行路径是否被 PATH 正确继承。

适用环境：vLLM（已确认）；操作系统、Python、CUDA、显卡版本在 Issue 讨论中未提供明确证据，不补写。

最快修复方案：暂无确认的一步修复方案。Issue 中验证过的直接方式是“先激活虚拟环境，再运行 vllm serve”，该方式可正常启动。

注意事项：激活虚拟环境后启动正常，说明 ninja 本体安装无问题；问题更可能出现在 vLLM 初始化子进程时的 PATH 继承或环境变量解析逻辑上，当前尚未有代码层面的修复补丁被确认。

问题场景

在虚拟环境中已安装 ninja，但用户未激活该虚拟环境，而是直接调用虚拟环境路径下的 bin/vllm serve 启动服务。vLLM 服务初始化时产生的子进程找不到同一虚拟环境中的 ninja，导致启动失败。若先激活虚拟环境再执行同一命令，则可以正常启动。

报错原文

服务初始化失败，并报告找不到 ninja（ninja not found / No such file or directory）

原因分析

可能原因：直接调用 bin/vllm 时，可执行文件所依赖的 PATH 环境变量并未自动包含虚拟环境自身（例如 venv/bin 目录）。vLLM 在服务初始化阶段以子进程方式调用 ninja（例如用于编译或构建算子），该子进程继承的是父进程（即当前 shell）的环境变量，而非虚拟环境激活后的环境变量。由于未激活虚拟环境，PATH 中未包含虚拟环境的 bin 目录，因此即使 ninja 已通过 pip 安装在该虚拟环境中，子进程仍然找不到它。激活虚拟环境后，PATH 被正确修改，问题解决。

另一可能原因：vLLM 的启动脚本内部依赖 sys.executable 或解析可执行文件路径来构造子进程环境时存在缺陷，导致继承了非预期的 PATH。但此点仅属推测，Issue 中并未提供代码级确认。

环境排查

确认虚拟环境中 ninja 是否已安装：venv/bin/pip show ninja
检查直接调用时的 PATH 是否包含虚拟环境路径，例如执行 echo $PATH 对比输入 venv/bin/vllm serve 前后的差异。
确认 ninja 可执行文件实际存在：ls -l venv/bin/ninja
如可能，确认 vLLM 构建过程中是否使用了 --no-build-isolation 之类的编译选项。

解决步骤

首选（已验证）：先激活虚拟环境，再运行 vllm serve。例如：source venv/bin/activate，然后执行 vllm serve。Issue 中确认此方式可以正常启动。
可优先尝试：若需要不激活环境直接调用，可在启动命令前手动将虚拟环境的 bin 目录加入 PATH：PATH="/path/to/venv/bin:$PATH" /path/to/venv/bin/vllm serve，使子进程能够继承包含 ninja 的 PATH（此方案为逻辑推导，尚未在 Issue 中验证，但可优先尝试）。
可优先尝试：检查调用 vllm 的命令或外层封装脚本是否重置了 PATH 或 PYTHONPATH；若有，请将其改为在完整继承环境变量的基础上追加虚拟环境路径。
如以上方式均无效，建议在 vLLM 的启动逻辑中自行在初始化阶段导入 ninja 前显式检查 shutil.which('ninja')，若为 None 则打印提示“请先激活虚拟环境”后退出，以保证用户能明确了解失败原因（此方案为 Issue 中提出的期望行为，尚未落地实现）。

验证方法

执行 vllm serve 命令后，观察服务初始化阶段是否仍有子进程报错“找不到 ninja”。若服务能够进入加载模型或监听端口阶段，则说明问题已解决。另一种快速验证方式是在未激活虚拟环境时运行 PATH="/path/to/venv/bin:$PATH" /path/to/venv/bin/vllm serve，若能正常启动也可作为问题解决的依据。