LLaMAFactory WebUI 启动无反应问题解决：pyarrow 导致 Windows fatal exception: access violation

一、问题背景

最近在腾讯云 Windows 服务器上部署 LLaMAFactory，用于大模型微调实验。环境基本信息如下：

• 系统：腾讯云 Windows Server
• 操作方式：远程桌面连接
• Python：3.11
• CUDA：12.2
• PyTorch：2.5.1
• LLaMAFactory：本地源码安装
• 启动命令：

llamafactory-cli webui

正常情况下，执行该命令后应该启动 Gradio WebUI，并在终端输出类似：

Running on local URL: http://0.0.0.0:7860

但是我的问题是：输入命令后，鼠标转圈两次，终端没有任何报错，也没有任何输出，随后直接回到命令行，可以继续输入下一条命令。

也就是说，现象类似：

(llama) C:\Users\Administrator\LlamaFactory>llamafactory-cli webui

(llama) C:\Users\Administrator\LlamaFactory>

一开始看起来像是 WebUI 没有启动，或者端口、防火墙、Gradio 出了问题，但实际根因不是这些。

---

二、最初排查方向

最开始怀疑过几个方向：

1. 是否没有安装 Node.js

后来确认 LLaMAFactory 的 WebUI 是基于 Gradio 的 Python Web 应用，正常使用并不需要单独安装 Node.js。

所以这个问题和 Node.js 无关。

2. 是否是腾讯云端口没有开放

因为是在腾讯云 Windows 服务器上运行，所以也怀疑过安全组、防火墙或者 7860 端口没有放行。

于是单独测试 Gradio：

python -u -c "import gradio as gr; print('gradio import ok', gr.__version__, flush=True); demo=gr.Interface(lambda x:x, 'text', 'text'); print('before launch', flush=True); demo.launch(server_name='0.0.0.0', server_port=7860, inbrowser=False)"

输出如下：

gradio import ok 5.50.0
before launch
* Running on local URL:  http://0.0.0.0:7860
* To create a public link, set `share=True` in `launch()`.

这说明 Gradio 本身可以正常启动，7860 端口也能监听，所以问题不在腾讯云端口，也不在 Gradio。

3. 是否是 conda 环境路径错误

继续检查命令路径：

where llamafactory-cli
where python
python -c "import sys; print(sys.executable)"
python -c "import llamafactory; print(llamafactory.__file__)"

输出显示 llamafactory-cli 和 python 都来自当前 conda 环境，LLaMAFactory 也指向当前源码目录：

C:\ProgramData\miniconda3\envs\llama\Scripts\llamafactory-cli.exe
C:\ProgramData\miniconda3\envs\llama\python.exe
C:\Users\Administrator\LlamaFactory\src\llamafactory\__init__.py

所以也不是环境路径问题。

---

三、定位真正报错

因为 llamafactory-cli webui 没有任何输出，所以需要绕过启动入口，直接手动导入 WebUI 模块，并开启 faulthandler：

python -u -X faulthandler -c "import torch; print('1 torch ok', torch.__version__, torch.cuda.is_available(), flush=True); import gradio; print('2 gradio ok', gradio.__version__, flush=True); import transformers; print('3 transformers ok', transformers.__version__, flush=True); import peft; print('4 peft ok', peft.__version__, flush=True); from llamafactory.webui.interface import create_ui; print('5 create_ui import ok', flush=True); demo=create_ui(); print('6 ui created ok', flush=True); demo.queue().launch(server_name='0.0.0.0', server_port=7860, inbrowser=False)"

执行后输出：

1 torch ok 2.5.1 True
2 gradio ok 5.50.0
3 transformers ok 4.56.2
4 peft ok 0.18.1
Windows fatal exception: access violation

关键错误是：

Windows fatal exception: access violation

继续看调用栈，可以看到问题发生在：

site-packages\pyarrow\__init__.py
site-packages\pandas\compat\pyarrow.py
site-packages\datasets\__init__.py
llamafactory\data\data_utils.py
llamafactory\webui\interface.py

也就是说，LLaMAFactory WebUI 在导入数据相关模块时，会导入 datasets，而 datasets 又会导入 pandas 和 pyarrow。最终是 pyarrow 在 Windows 环境下发生了 C/C++ 层面的崩溃，导致 Python 进程直接退出。

这也是为什么终端没有 Python Traceback，而是表现为“鼠标转圈两次，然后什么都没有”。

---

四、问题原因

根因是：

pyarrow 版本在当前 Windows + conda + Python 3.11 环境下不稳定，导入时触发 access violation，导致 Python 解释器直接崩溃。

我当时环境中相关包版本比较新，例如：

numpy      2.x
pandas     2.3.x
pyarrow    24.x
datasets   4.x

这些包本身不是一定有问题，但在 Windows 云服务器环境中，pyarrow 这类带有底层 C++ 扩展的库，一旦二进制兼容性出现问题，就可能不是普通 Python 报错，而是直接进程崩溃。

因此，pip check 可能显示：

No broken requirements found

但这只能说明 Python 包依赖关系没有冲突，不能说明底层二进制库一定能正常运行。

---

五、最终解决方法

最终通过卸载并降级 pyarrow / pandas / numpy / datasets 解决。

先卸载：

pip uninstall -y pyarrow pandas numpy datasets

然后安装稳定版本：

pip install --no-cache-dir ^
"numpy==1.26.4" ^
"pandas==2.2.3" ^
"pyarrow==17.0.0" ^
"datasets==3.2.0"

如果使用的是 PowerShell，可以改成：

pip install --no-cache-dir `
"numpy==1.26.4" `
"pandas==2.2.3" `
"pyarrow==17.0.0" `
"datasets==3.2.0"

安装完成后，先测试这几个包是否能正常导入：

python -c "import pyarrow; print('pyarrow ok', pyarrow.__version__)"
python -c "import pandas; print('pandas ok', pandas.__version__)"
python -c "import datasets; print('datasets ok', datasets.__version__)"

如果都能正常输出版本号，再启动 LLaMAFactory WebUI：

llamafactory-cli webui

或者指定 Gradio 监听地址和端口：

set DISABLE_VERSION_CHECK=1
set GRADIO_SERVER_NAME=0.0.0.0
set GRADIO_SERVER_PORT=7860

llamafactory-cli webui

之后 WebUI 就可以正常启动了。

---

六、为什么这个问题不好排查

这个问题比较坑的地方在于：

1. 终端没有普通 Python 报错

普通 Python 包错误一般会显示：

ModuleNotFoundError
ImportError
RuntimeError

但是这次是：

Windows fatal exception: access violation

这属于底层二进制扩展崩溃，Python 解释器会直接退出。

所以表面现象就是命令一闪而过，没有任何提示。

2. pip check 不一定能发现问题

我执行过：

pip check

结果是：

No broken requirements found.

说明依赖声明没有冲突，但 pyarrow 的底层动态库仍然可能在导入时崩溃。

3. 很容易误判为 Gradio 或云服务器端口问题

因为命令是：

llamafactory-cli webui

所以第一反应很容易怀疑是 WebUI、端口、防火墙或腾讯云安全组问题。

但单独测试 Gradio 后发现 Gradio 是正常的，真正的问题发生在 LLaMAFactory WebUI 导入 datasets -> pandas -> pyarrow 的过程中。

---

七、建议的排查流程

如果你也遇到类似问题，可以按下面顺序排查。

1. 检查 LLaMAFactory 命令路径

where llamafactory-cli
where python
python -c "import sys; print(sys.executable)"
python -c "import llamafactory; print(llamafactory.__file__)"

确认都指向当前 conda 环境。

2. 测试 Gradio 是否正常

python -u -c "import gradio as gr; print('gradio import ok', gr.__version__, flush=True); demo=gr.Interface(lambda x:x, 'text', 'text'); print('before launch', flush=True); demo.launch(server_name='0.0.0.0', server_port=7860, inbrowser=False)"

如果 Gradio 能启动，说明端口和 Gradio 本身大概率没问题。

3. 测试 pyarrow / pandas / datasets

python -c "import pyarrow; print(pyarrow.__version__)"
python -c "import pandas; print(pandas.__version__)"
python -c "import datasets; print(datasets.__version__)"

如果这里发生静默退出或 access violation，问题基本就定位到了。

4. 使用 faulthandler 查看底层崩溃位置

python -u -X faulthandler -c "from llamafactory.webui.interface import create_ui; print('import ok'); demo=create_ui(); print('ui ok')"

如果看到 pyarrow、pandas、datasets 相关调用栈，就可以优先处理这些包。

---

八、总结

这次问题的最终表现是：

llamafactory-cli webui 执行后没有任何反应，鼠标转圈后直接回到命令行

最终原因是：

pyarrow 在 Windows 环境中导入时发生 access violation，导致 Python 进程直接崩溃

最终解决方法是：

pip uninstall -y pyarrow pandas numpy datasets

pip install --no-cache-dir ^
"numpy==1.26.4" ^
"pandas==2.2.3" ^
"pyarrow==17.0.0" ^
"datasets==3.2.0"

解决后，LLaMAFactory WebUI 可以正常启动。

这类问题的关键不是反复重装 LLaMAFactory，而是要先判断：

• Gradio 能不能单独启动；
• llamafactory-cli 是否指向当前 conda 环境；
• pyarrow / pandas / datasets 是否能正常导入；
• 是否存在 Windows fatal exception 这类底层崩溃。

如果遇到 LLaMAFactory WebUI 静默退出，可以优先检查 pyarrow，尤其是在 Windows 服务器环境下。