LLaMA-Factory和python版本的兼容性问题解决

引言

笔者今天在电脑上安装下LLaMA-Factory做下本地的模型调优。
从github上拉取代码git clone https://github.com/hiyouga/LLaMA-Factory.git.
pycharm建立工程,按照官网指导如下:
LLaMA-Factory 安装

在安装 LLaMA-Factory 之前，请确保您安装了下列依赖:

运行以下指令以安装 LLaMA-Factory 及其依赖:

git clone --depth 1 https://github.com/hiyouga/LLaMA-Factory.git cd
LLaMA-Factory pip install -e “.[torch,metrics]”
如果出现环境冲突，请尝试使用
pip install --no-deps -e . 解决

一、碰到问题

在pycharm的终端平台上，输入 pip install -e “.[torch,metrics]”

详细报错如下：

Windows PowerShell
版权所有（C） Microsoft Corporation。保留所有权利。安装最新的 PowerShell，了解新功能和改进！https://aka.ms/PSWindowsPS E:\study\ai\tuning\LLaMA-Factory> pip install -e ".[torch,metrics]"
Obtaining file:///E:/study/ai/tuning/LLaMA-FactoryInstalling build dependencies ... doneChecking if build backend supports build_editable ... doneGetting requirements to build editable ... donePreparing editable metadata (pyproject.toml) ... done
Collecting transformers!=4.46.*,!=4.47.*,!=4.48.0,!=4.52.0,<=4.52.4,>=4.45.0 (from llamafactory==0.9.3.dev0)Using cached transformers-4.52.4-py3-none-any.whl.metadata (38 kB)
Collecting datasets<=3.6.0,>=2.16.0 (from llamafactory==0.9.3.dev0)Using cached datasets-3.6.0-py3-none-any.whl.metadata (19 kB)
Collecting accelerate<=1.7.0,>=0.34.0 (from llamafactory==0.9.3.dev0)Using cached accelerate-1.7.0-py3-none-any.whl.metadata (19 kB)
Collecting peft<=0.15.2,>=0.14.0 (from llamafactory==0.9.3.dev0)Using cached peft-0.15.2-py3-none-any.whl.metadata (13 kB)
Collecting trl<=0.9.6,>=0.8.6 (from llamafactory==0.9.3.dev0)Using cached trl-0.9.6-py3-none-any.whl.metadata (12 kB)
Collecting tokenizers<=0.21.1,>=0.19.0 (from llamafactory==0.9.3.dev0)Using cached tokenizers-0.21.1-cp39-abi3-win_amd64.whl.metadata (6.9 kB)
Collecting gradio<=5.31.0,>=4.38.0 (from llamafactory==0.9.3.dev0)Using cached gradio-5.31.0-py3-none-any.whl.metadata (16 kB)
Collecting scipy (from llamafactory==0.9.3.dev0)Downloading scipy-1.15.3-cp313-cp313-win_amd64.whl.metadata (60 kB)
Collecting einops (from llamafactory==0.9.3.dev0)Using cached einops-0.8.1-py3-none-any.whl.metadata (13 kB)
Collecting sentencepiece (from llamafactory==0.9.3.dev0)Downloading sentencepiece-0.2.0.tar.gz (2.6 MB)━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 2.6/2.6 MB 5.8 MB/s eta 0:00:00Installing build dependencies ... doneGetting requirements to build wheel ... errorerror: subprocess-exited-with-error× Getting requirements to build wheel did not run successfully.│ exit code: 1╰─> [48 lines of output]Traceback (most recent call last):File "D:\install\Python313\Lib\site-packages\pip\_vendor\pyproject_hooks\_in_process\_in_process.py", line 389, in <module>main()~~~~^^File "D:\install\Python313\Lib\site-packages\pip\_vendor\pyproject_hooks\_in_process\_in_process.py", line 373, in mainjson_out["return_val"] = hook(**hook_input["kwargs"])~~~~^^^^^^^^^^^^^^^^^^^^^^^^File "D:\install\Python313\Lib\site-packages\pip\_vendor\pyproject_hooks\_in_process\_in_process.py", line 143, in get_requires_for_build_wheelreturn hook(config_settings)File "C:\Users\opfly\AppData\Local\Temp\pip-build-env-sv4axyrq\overlay\Lib\site-packages\setuptools\build_meta.py", line 331, in get_requires_for_build_wheelreturn self._get_build_requires(config_settings, requirements=[])~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^File "C:\Users\opfly\AppData\Local\Temp\pip-build-env-sv4axyrq\overlay\Lib\site-packages\setuptools\build_meta.py", line 301, in _get_build_requiresself.run_setup()~~~~~~~~~~~~~~^^File "C:\Users\opfly\AppData\Local\Temp\pip-build-env-sv4axyrq\overlay\Lib\site-packages\setuptools\build_meta.py", line 512, in run_setupsuper().run_setup(setup_script=setup_script)~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^File "C:\Users\opfly\AppData\Local\Temp\pip-build-env-sv4axyrq\overlay\Lib\site-packages\setuptools\build_meta.py", line 317, in run_setupexec(code, locals())~~~~^^^^^^^^^^^^^^^^File "<string>", line 128, in <module>File "D:\install\Python313\Lib\subprocess.py", line 414, in check_callretcode = call(*popenargs, **kwargs)File "D:\install\Python313\Lib\subprocess.py", line 395, in callwith Popen(*popenargs, **kwargs) as p:~~~~~^^^^^^^^^^^^^^^^^^^^^^File "D:\install\Python313\Lib\subprocess.py", line 1039, in __init__self._execute_child(args, executable, preexec_fn, close_fds,~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^pass_fds, cwd, env,^^^^^^^^^^^^^^^^^^^...<5 lines>...gid, gids, uid, umask,^^^^^^^^^^^^^^^^^^^^^^start_new_session, process_group)^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^File "D:\install\Python313\Lib\subprocess.py", line 1551, in _execute_childhp, ht, pid, tid = _winapi.CreateProcess(executable, args,~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^# no special security^^^^^^^^^^^^^^^^^^^^^...<4 lines>...cwd,^^^^startupinfo)^^^^^^^^^^^^FileNotFoundError: [WinError 2] 系统找不到指定的文件。[end of output]note: This error originates from a subprocess, and is likely not a problem with pip.[notice] A new release of pip is available: 25.0.1 -> 25.1.1
[notice] To update, run: D:\install\Python313\python.exe -m pip install --upgrade pip
error: subprocess-exited-with-error× Getting requirements to build wheel did not run successfully.
│ exit code: 1
╰─> See above for output.note: This error originates from a subprocess, and is likely not a problem with pip.

从错误信息来看，安装过程中在处理 sentencepiece 依赖时遇到了问题。

二、错误分析

以下是可能导致该错误的原因和解决方法：
1.Python 版本不兼容：
您正在使用的是较新的 Python 3.13，而一些依赖库可能尚未完全支持此版本。
2.系统缺少必要的构建工具：
安装某些 Python 包（尤其是需要编译的包）时，如果没有安装 C/C++ 编译器或相关的构建工具，会导致构建失败。
3.网络问题或缓存问题：
虽然 sentencepiece 的源码已经下载成功，但在构建过程中可能因为网络或缓存导致子进程调用失败，再次安装还有这个问题，这个基本排除。
4.路径问题：Windows 系统中路径过长或包含特殊字符也可能导致此类问题。

三、解决办法

由于笔者电脑里安装了python3的各种版本呢，而3.13是最近一次的安装，需要回滚到3.10再次看看。

从日志中看到，当前安装时候用的python版本是python3.13，按照分析的思路，先更换成python3.10再次运行，成功安装。

根据llamafactory-cli.exe version 验证命令和git版本管理的的追溯，可以看到本次安装的LLaMA-Factory的tag版本。

四、结论

LLaMA-Factory的模型微调工具，在版本 LLaMA Factory, version 0.9.3.dev0，至少还是需要python3.10的，高版本的可能面临版本冲突导致无法正常安装。