问题描述

在 Linux 系统中部署 LLaMa-Factory 时，使用 llamafactory-cli webui 启动 WebUI 时可能遇到虚拟环境 Python 路径引用错误，导致服务无法正常访问。

常见错误原因

1. 虚拟环境未正确激活或路径未正确配置
2. Python 解释器路径在脚本中被硬编码而未动态获取
3. 系统环境变量未正确传递到子进程

解决方法

检查虚拟环境激活状态 确保在运行命令前已激活虚拟环境：

source venv/bin/activate

验证 Python 路径是否正确指向虚拟环境：

which python

修改启动脚本 查找 llamafactory-cli 脚本（通常位于虚拟环境的 bin 目录），确保使用环境变量动态获取 Python 路径：

#!/usr/bin/env python3

而非硬编码路径如：

#!/path/to/python

重建虚拟环境 如果路径问题持续存在，尝试重建虚拟环境：

python -m venv --clear venv
source venv/bin/activate
pip install -r requirements.txt

检查环境变量传递 确保 WebUI 子进程继承了正确的环境变量，可以临时导出变量测试：

export PYTHONPATH=$(pwd):$PYTHONPATH
llamafactory-cli webui

权限问题处理 确保脚本和虚拟环境有可执行权限：

chmod +x venv/bin/llamafactory-cli
chmod +x venv/bin/python

调试技巧

1. 在脚本开头添加调试信息打印环境变量：

import os
print("PYTHONPATH:", os.environ.get('PYTHONPATH'))
print("PATH:", os.environ.get('PATH'))

1. 使用 strace 跟踪系统调用：

strace -f -e trace=file llamafactory-cli webui

备选方案

如果问题仍未解决，可以尝试直接运行底层命令绕过 CLI：

python -m llamafactory.webui